npm - @qijenchen/design-system - Versions diffs - 0.1.0-beta.145 → 0.1.0-beta.147 - Mend

@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

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 (576) hide show

package/dist/components/Button/button.js CHANGED Viewed

@@ -17,8 +17,12 @@ const buttonVariants = cva(
     // aria-disabled 給語意 + visual,但不 suppress functionality;functionality 由 consumer 阻 e.g.
     // RowDragHandle listeners 只在 canDrag spread)。**故意不加** `aria-disabled:pointer-events-none`
     // — Round 4 RowDragHandle Tooltip flicker fix root cause:aria-disabled buttons 必保 pointer events
-    // 讓 Radix Tooltip pointerenter 通過。HTML `disabled` 保 PE:none(完全 inactive)。
-    "disabled:pointer-events-none",
+    // 讓 Radix Tooltip pointerenter 通過。
+    // 2026-09-29(待辦總帳 N46 停用游標全站掃):原生 `disabled` 原本也掛 `pointer-events-none`(「完全 inactive」),
+    // 結果上面那句 `disabled:cursor-not-allowed` 從來沒生效 —— 沒有指標事件就沒有游標,全站 35 顆停用的 Button 家族
+    //(分頁箭頭 / 輪播箭頭 / AI 面板送出鈕)都是箭頭游標,違反 hit-area-canonical.md「停用的用禁止符號」。
+    // 現在停用不再切掉指標事件;滑過 / 按住的回饋改由各 variant 的 `disabled:hover:` / `disabled:active:` 顯式釘在停用靜止值
+    //(同 aria-disabled 的寫法;原生 disabled 的按鈕本來就不派發 click)。
     // 2026-05-12 fix v2(playwright pixel-quantified verify 抓 opacity=1 不生效):
     // `opacity-disabled` 是 custom Tailwind v4 `@utility`(opacity.css:21),variant prefix
     // `aria-disabled:` 跟 custom @utility 不 compose(`aria-disabled:cursor-not-allowed` 標準
@@ -37,7 +41,15 @@ const buttonVariants = cva(
           "bg-primary text-on-emphasis",
           "hover:bg-primary-hover",
           "active:bg-primary-active",
-          "disabled:bg-disabled disabled:text-fg-disabled disabled:border-transparent"
+          // 開啟中 = 自己的 hover(inline-action.spec.md:26「overlay 開啟 → 同 host hover」)。2026-09-29 待辦總帳 C13:
+          // 七家一手裡沒有任何一家「給部分 variant、獨獨豁免 primary」(Atlassian / Fluent 每個 appearance 含 primary 都給;
+          // Radix / shadcn / MUI / Ant / Carbon 全都不給);DS 早選了「給」,primary / link 缺的只是同一條規則的落地。
+          "data-[state=open]:bg-primary-hover",
+          // aria-disabled 的 hover / active 釘在靜止(button.spec.md「狀態疊加」表 aria-disabled 列:與 disabled 同樣不給互動回饋;
+          // 原生 disabled 與 aria-disabled 都顯式釘住(2026-09-29 前原生 disabled 靠 pointer-events-none,見檔頭);先例 switch.tsx 的 `disabled:…:hover:` 守衛)
+          "aria-disabled:hover:bg-primary aria-disabled:active:bg-primary",
+          "disabled:bg-disabled disabled:text-fg-disabled disabled:border-transparent",
+          "disabled:hover:bg-disabled disabled:active:bg-disabled"
         ],
         secondary: [
           "bg-surface text-primary border-primary",
@@ -46,7 +58,11 @@ const buttonVariants = cva(
           // Overlay trigger active(asChild Popover/DropdownMenu trigger)— 維持 hover 樣式
           // (canonical 對齊 inline-action.spec.md:trigger 維持 host hover 直到 overlay 關閉)
           "data-[state=open]:text-primary-hover data-[state=open]:border-primary-hover",
-          "disabled:bg-transparent disabled:text-fg-disabled disabled:border-border"
+          // aria-disabled 釘住(同 primary 註解);`not-aria-pressed` = 只釘「未按下」的靜止,按下的由 pressed compound 自己釘(避免兩組 (0,3,0) 靠產出順序決勝)
+          "aria-disabled:not-aria-pressed:hover:text-primary aria-disabled:not-aria-pressed:hover:border-primary",
+          "aria-disabled:not-aria-pressed:active:text-primary aria-disabled:not-aria-pressed:active:border-primary",
+          "disabled:bg-transparent disabled:text-fg-disabled disabled:border-border",
+          "disabled:hover:text-fg-disabled disabled:hover:border-border disabled:active:text-fg-disabled disabled:active:border-border"
           // 2026-05-21 v12:Toggle pressed 視覺移到 compoundVariants(variant × pressedTone),
           // 同時支援 emphasis(藍底)/ neutral(灰底)兩 tone。詳 cva.compoundVariants 段。
         ],
@@ -56,7 +72,11 @@ const buttonVariants = cva(
           "active:text-primary-active active:border-primary-active",
           // Overlay trigger active — 維持 hover 樣式(同 secondary 邏輯)
           "data-[state=open]:text-primary-hover data-[state=open]:border-primary-hover",
-          "disabled:bg-transparent disabled:text-fg-disabled disabled:border-border"
+          // aria-disabled 釘住(同 secondary 註解)
+          "aria-disabled:not-aria-pressed:hover:text-foreground aria-disabled:not-aria-pressed:hover:border-border",
+          "aria-disabled:not-aria-pressed:active:text-foreground aria-disabled:not-aria-pressed:active:border-border",
+          "disabled:bg-transparent disabled:text-fg-disabled disabled:border-border",
+          "disabled:hover:text-fg-disabled disabled:hover:border-border disabled:active:text-fg-disabled disabled:active:border-border"
         ],
         text: [
           "bg-transparent text-foreground border-transparent",
@@ -65,13 +85,21 @@ const buttonVariants = cva(
           // Overlay trigger active — 維持 hover 樣式(canonical 2026-05-02 改:hover token,
           // 不另開 selected 4% — 對齊 shadcn/Radix/Material 狀態極簡派,跨 host 一致)
           "data-[state=open]:bg-neutral-hover",
-          "disabled:bg-transparent disabled:text-fg-disabled"
+          // aria-disabled 釘住(同 secondary 註解)
+          "aria-disabled:not-aria-pressed:hover:bg-transparent aria-disabled:not-aria-pressed:active:bg-transparent",
+          "disabled:bg-transparent disabled:text-fg-disabled",
+          "disabled:hover:bg-transparent disabled:hover:text-fg-disabled disabled:active:bg-transparent disabled:active:text-fg-disabled"
         ],
         link: [
           "bg-transparent text-primary border-transparent",
           "hover:text-primary-hover",
           "active:text-primary-active",
-          "disabled:text-fg-disabled"
+          // 開啟中 = 自己的 hover(link 的 hover 只換字色;同 primary 分支註解,2026-09-29 C13)
+          "data-[state=open]:text-primary-hover",
+          // aria-disabled 釘住(同 primary 註解;link 無 pressed 視覺,不需 not-aria-pressed)
+          "aria-disabled:hover:text-primary aria-disabled:active:text-primary",
+          "disabled:text-fg-disabled",
+          "disabled:hover:text-fg-disabled disabled:active:text-fg-disabled"
         ]
       },
       danger: {
@@ -82,7 +110,8 @@ const buttonVariants = cva(
        * 2026-05-21 v12 — pressed visual tone(per user「我認同這一個方向,然後預設emphasis」):
        * emphasis = 淡藍底(toolbar functional toggle / 篩選啟用 / 面板開關 — Figma toolbar /
        *            Linear toolbar / Material ToggleButton 共識)
-       * neutral  = 灰底(sidebar/contextual nav row pressed — Linear / Notion / VS Code Activity Bar 共識)
+       * neutral  = 灰底(**可取消**的切換鈕、要比藍底低一級時;不用於導覽 / 目前頁 —— 那是選中列,
+       *            owner = item-anatomy.spec.md「選中 × 互動疊加」;button.spec.md pressedTone 表,待辦總帳 B5 2026-09-25 更正)
        * 預設 `emphasis` per user directive。實際樣式由 compoundVariants(variant × pressedTone)套用。
        * 只在 secondary / tertiary / text variant 觸發 toggle 視覺;primary / link 無視覺效果。
        */
@@ -105,7 +134,11 @@ const buttonVariants = cva(
         class: [
           "bg-error text-on-emphasis border-transparent",
           "hover:bg-error-hover",
-          "active:bg-error-active"
+          "active:bg-error-active",
+          // 開啟中 = 自己的 hover(同 primary 分支,2026-09-29 C13)
+          "data-[state=open]:bg-error-hover",
+          // aria-disabled 釘在自己的靜止紅(button.spec.md「狀態疊加」表 aria-disabled 列)
+          "aria-disabled:hover:bg-error aria-disabled:active:bg-error"
         ]
       },
       // secondary + danger → 紅框紅字（有確認步驟的危險操作）
@@ -115,7 +148,12 @@ const buttonVariants = cva(
         class: [
           "bg-surface text-error border-error",
           "hover:text-error-hover hover:border-error-hover",
-          "active:text-error-active active:border-error-active"
+          "active:text-error-active active:border-error-active",
+          // 開啟中 = 自己的 hover(error-hover),不是 secondary 的 primary-hover(inline-action.spec.md「overlay 開啟 → 同 host hover」;
+          // button.spec.md「狀態疊加」表開啟中列)。靠 cn()/twMerge 去掉 variant 那組同前綴 class,同本檔 danger 覆寫慣例
+          "data-[state=open]:text-error-hover data-[state=open]:border-error-hover",
+          "aria-disabled:not-aria-pressed:hover:text-error aria-disabled:not-aria-pressed:hover:border-error",
+          "aria-disabled:not-aria-pressed:active:text-error aria-disabled:not-aria-pressed:active:border-error"
         ]
       },
       // text + danger → 紅字，hover 灰底
@@ -125,7 +163,10 @@ const buttonVariants = cva(
         class: [
           "text-error",
           "hover:bg-neutral-hover hover:text-error-hover",
-          "active:bg-neutral-active active:text-error-active"
+          "active:bg-neutral-active active:text-error-active",
+          // 開啟中 = 自己的 hover 配對:底色沿用 text 的 data-[state=open]:bg-neutral-hover,字補上 error-hover(同 secondary+danger 註解)
+          "data-[state=open]:text-error-hover",
+          "aria-disabled:not-aria-pressed:hover:text-error aria-disabled:not-aria-pressed:active:text-error"
         ]
       },
       // ── 2026-05-21 v12 Toggle pressed(variant × pressedTone)──────────────────
@@ -137,28 +178,81 @@ const buttonVariants = cva(
         pressedTone: "emphasis",
         class: [
           "data-[state=on]:bg-primary-subtle data-[state=on]:text-primary data-[state=on]:border-transparent",
-          "data-[state=on]:hover:text-primary-hover",
-          "data-[state=on]:active:text-primary-active",
+          // 按下的 hover / active 只換字(primary-hover / -active),底色與邊框顯式釘住 —— 照 sidebar.tsx
+          // `data-[active=true]:hover:bg-neutral-selected` 寫法,釘住 (0,3,0) > variant 的 hover / active (0,2,0)。
+          // 之前底色只是靠 CSS 產出順序(data-* 排在 hover 之後)才沒被 text 的 neutral-hover 換掉(button.spec.md「狀態疊加」表 pressed × hover / active 列)
+          "data-[state=on]:hover:bg-primary-subtle data-[state=on]:hover:border-transparent data-[state=on]:hover:text-primary-hover",
+          "data-[state=on]:active:bg-primary-subtle data-[state=on]:active:border-transparent data-[state=on]:active:text-primary-active",
           "data-[state=on]:disabled:bg-disabled data-[state=on]:disabled:text-fg-disabled data-[state=on]:disabled:border-transparent",
-          // aria-pressed fallback(Radix overlay trigger override data-state 時仍生效)
+          "data-[state=on]:disabled:hover:bg-disabled data-[state=on]:disabled:hover:text-fg-disabled data-[state=on]:disabled:hover:border-transparent data-[state=on]:disabled:active:bg-disabled data-[state=on]:disabled:active:text-fg-disabled data-[state=on]:disabled:active:border-transparent",
+          // aria-pressed fallback(Radix overlay trigger override data-state 時仍生效)—— 逐條鏡像上方 data-[state=on] 分支
           "aria-pressed:bg-primary-subtle aria-pressed:text-primary aria-pressed:border-transparent",
-          "aria-pressed:hover:text-primary-hover",
+          "aria-pressed:hover:bg-primary-subtle aria-pressed:hover:border-transparent aria-pressed:hover:text-primary-hover",
           // 2026-07-07 補齊第三階:fallback 分支與 data-[state=on] 分支同拼寫(選中之上按壓 = active 階)
-          "aria-pressed:active:text-primary-active"
+          "aria-pressed:active:bg-primary-subtle aria-pressed:active:border-transparent aria-pressed:active:text-primary-active",
+          // pressed + disabled:disabled 視覺優先(button.spec.md「狀態 → disabled」pressed + disabled 條);fallback 分支原本缺這條,鏡像 data-[state=on]:disabled
+          "aria-pressed:disabled:bg-disabled aria-pressed:disabled:text-fg-disabled aria-pressed:disabled:border-transparent",
+          "aria-pressed:disabled:hover:bg-disabled aria-pressed:disabled:hover:text-fg-disabled aria-pressed:disabled:hover:border-transparent aria-pressed:disabled:active:bg-disabled aria-pressed:disabled:active:text-fg-disabled aria-pressed:disabled:active:border-transparent",
+          // 按下的觸發鈕開啟中 = 按下自己的 hover(底色與邊框不動、字 primary-hover),不是 variant 的開啟樣式
+          //(inline-action.spec.md「overlay 開啟 → 同 host hover」;button.spec.md「狀態疊加」表開啟中列)。
+          // Radix 會把 data-state 改寫成 open,所以只走 aria-pressed;(0,3,0) > variant 的 data-[state=open] (0,2,0)
+          "aria-pressed:data-[state=open]:bg-primary-subtle aria-pressed:data-[state=open]:border-transparent aria-pressed:data-[state=open]:text-primary-hover",
+          // 按下 + aria-disabled:hover / active 釘在按下的靜止字色(底色與邊框已由上方釘住)
+          "data-[state=on]:aria-disabled:hover:text-primary data-[state=on]:aria-disabled:active:text-primary",
+          "aria-pressed:aria-disabled:hover:text-primary aria-pressed:aria-disabled:active:text-primary"
         ]
       },
-      // neutral tone:灰底(neutral-selected family)— sidebar/contextual nav pressed
+      // neutral tone:灰底(neutral-selected family)— 可取消的切換鈕;導覽 / 目前頁不用它(選中列規則,item-anatomy.spec.md「選中 × 互動疊加」)
+      // 階梯值 selected → -selected-hover → -selected-active(2→3→4):user 2026-09-25 選「甲：保留，維持 2→3→4 (Recommended)」
+      // (選項由 AI 提供;待辦總帳 B5)。下方開啟中 / aria-disabled 各條都是「跟著本分支的 hover / 靜止 token 走」,改階梯時同一 compound 內一起改。
+      // 2026-09-29(待辦總帳 N7):secondary 從這一組拆出去(下一組)—— 它的靜止底是 `--surface`(「底」),已按下要**疊層**不換底:
+      // 深色 --surface 與 --neutral-selected 都是白 8%,換底後已按下 = 未按下(#1E1E1E = #1E1E1E);tertiary / text 是透明底,換底沒問題。
       {
-        variant: ["secondary", "tertiary", "text"],
+        variant: ["tertiary", "text"],
         pressedTone: "neutral",
         class: [
           "data-[state=on]:bg-neutral-selected data-[state=on]:text-foreground data-[state=on]:border-transparent",
-          "data-[state=on]:hover:bg-neutral-selected-hover",
-          "data-[state=on]:active:bg-neutral-selected-active",
+          // 字與邊框在 hover / active 顯式釘住(secondary / tertiary 的 hover 會把字與框轉 primary;同 emphasis 分支註解)
+          "data-[state=on]:hover:bg-neutral-selected-hover data-[state=on]:hover:text-foreground data-[state=on]:hover:border-transparent",
+          "data-[state=on]:active:bg-neutral-selected-active data-[state=on]:active:text-foreground data-[state=on]:active:border-transparent",
           "data-[state=on]:disabled:bg-transparent data-[state=on]:disabled:text-fg-disabled",
-          // aria-pressed fallback
+          "data-[state=on]:disabled:hover:bg-transparent data-[state=on]:disabled:hover:text-fg-disabled data-[state=on]:disabled:active:bg-transparent data-[state=on]:disabled:active:text-fg-disabled",
+          // aria-pressed fallback —— 逐條鏡像上方 data-[state=on] 分支
           "aria-pressed:bg-neutral-selected aria-pressed:text-foreground aria-pressed:border-transparent",
-          "aria-pressed:hover:bg-neutral-selected-hover"
+          "aria-pressed:hover:bg-neutral-selected-hover aria-pressed:hover:text-foreground aria-pressed:hover:border-transparent",
+          // 補齊第三階(按壓):fallback 原本缺,data-[state=on] 分支與 emphasis 分支都有(同 emphasis 2026-07-07 註解)
+          "aria-pressed:active:bg-neutral-selected-active aria-pressed:active:text-foreground aria-pressed:active:border-transparent",
+          "aria-pressed:disabled:bg-transparent aria-pressed:disabled:text-fg-disabled",
+          "aria-pressed:disabled:hover:bg-transparent aria-pressed:disabled:hover:text-fg-disabled aria-pressed:disabled:active:bg-transparent aria-pressed:disabled:active:text-fg-disabled",
+          // 按下的觸發鈕開啟中 = 按下自己的 hover(neutral-selected-hover),不是 variant 的 neutral-hover / primary-hover(同 emphasis 分支註解)
+          "aria-pressed:data-[state=open]:bg-neutral-selected-hover aria-pressed:data-[state=open]:text-foreground aria-pressed:data-[state=open]:border-transparent",
+          // 按下 + aria-disabled:hover / active 釘在按下的靜止底色
+          "data-[state=on]:aria-disabled:hover:bg-neutral-selected data-[state=on]:aria-disabled:active:bg-neutral-selected",
+          "aria-pressed:aria-disabled:hover:bg-neutral-selected aria-pressed:aria-disabled:active:bg-neutral-selected"
+        ]
+      },
+      // secondary(白底)× neutral:底留 `bg-surface`,已按下三階用疊層 utility(semantic.css `bg-interaction-selected` 家族 =
+      // 把 --neutral-selected / -hover / -active 畫成 background-image,在底色之上、內容之下;配對總則第 2 列「底不換,疊一層」)。
+      // 淺色疊層結果與換底相同(#F5F5F5 / #F0F0F0 / #E8E8E8),深色才分得出來(#303030 / #37 / #3D)。逐條鏡像上一組;
+      // 停用態拿掉疊層(`bg-none`)而不是把底換成透明 —— 白底鈕停用仍是白底。
+      {
+        variant: "secondary",
+        pressedTone: "neutral",
+        class: [
+          // 底寫明 `bg-surface`(與 variant 相同,不換底):疊層是疊在「底」上,hover-own-pair 閘據此判定,不必去別的 compound 找靜止底
+          "data-[state=on]:bg-surface data-[state=on]:bg-interaction-selected data-[state=on]:text-foreground data-[state=on]:border-transparent",
+          "data-[state=on]:hover:bg-interaction-selected-hover data-[state=on]:hover:text-foreground data-[state=on]:hover:border-transparent",
+          "data-[state=on]:active:bg-interaction-selected-active data-[state=on]:active:text-foreground data-[state=on]:active:border-transparent",
+          "data-[state=on]:disabled:bg-none data-[state=on]:disabled:text-fg-disabled",
+          "data-[state=on]:disabled:hover:bg-none data-[state=on]:disabled:hover:text-fg-disabled data-[state=on]:disabled:active:bg-none data-[state=on]:disabled:active:text-fg-disabled",
+          "aria-pressed:bg-surface aria-pressed:bg-interaction-selected aria-pressed:text-foreground aria-pressed:border-transparent",
+          "aria-pressed:hover:bg-interaction-selected-hover aria-pressed:hover:text-foreground aria-pressed:hover:border-transparent",
+          "aria-pressed:active:bg-interaction-selected-active aria-pressed:active:text-foreground aria-pressed:active:border-transparent",
+          "aria-pressed:disabled:bg-none aria-pressed:disabled:text-fg-disabled",
+          "aria-pressed:disabled:hover:bg-none aria-pressed:disabled:hover:text-fg-disabled aria-pressed:disabled:active:bg-none aria-pressed:disabled:active:text-fg-disabled",
+          "aria-pressed:data-[state=open]:bg-interaction-selected-hover aria-pressed:data-[state=open]:text-foreground aria-pressed:data-[state=open]:border-transparent",
+          "data-[state=on]:aria-disabled:hover:bg-interaction-selected data-[state=on]:aria-disabled:active:bg-interaction-selected",
+          "aria-pressed:aria-disabled:hover:bg-interaction-selected aria-pressed:aria-disabled:active:bg-interaction-selected"
         ]
       }
     ],
@@ -258,6 +352,8 @@ const Button = React.forwardRef(
       // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)
       // 弱化 icon hover 一階(item-anatomy.tsx ItemInlineActionButton 同階梯 SSOT)
       dismiss && "text-fg-muted hover:text-fg-secondary",
+      // aria-disabled 的 dismiss hover 釘在 fg-muted(button.spec.md「狀態疊加」表 aria-disabled 列)
+      dismiss && "aria-disabled:hover:text-fg-muted",
       resolvedFullWidth && "w-full"
     );
     const { onClick: slotConsumerOnClick, ...slotRest } = restProps;

package/dist/components/Button/button.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"button.js","sources":["../../../src/components/Button/button.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.\n// code-quality-allow: file-size — foundational composite(Button + iconOnly + danger + loading + asChild + dismiss + pressedTone)— 跨 7 axis variant 集中 SSOT 一處,拆分會 fragment cva variant catalog。當前 528 < cap 800。\nimport * as React from 'react'\nimport { Slot } from '@radix-ui/react-slot'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { useResolvedFieldSize } from '@/design-system/components/Field/field-context'\nimport { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'\n\n/*\n Button — shadcn 風格，橋接設計系統 token\n \n ── Variants ──\n * primary 主要操作，藍底白字\n * secondary 次要品牌操作，藍框藍字；正面 vs 負面並存時用於正面那個\n * tertiary 一般輔助操作，灰框灰字，hover 轉藍（最常用的非主要按鈕）\n * text 無底色無邊框，hover 顯示灰底（工具列、密集 UI）\n * link 外觀像連結的按鈕（本質仍是 button）\n \n ── danger prop ──\n * danger 套用危險色（紅色）；僅 primary / secondary / text 支援（tertiary / link 不支援，見 spec 禁止事項）\n \n <Button variant=\"primary\" danger>永久刪除</Button> → 紅底白字（立即不可逆）\n * <Button variant=\"secondary\" danger>移至垃圾桶</Button> → 紅框紅字（點下去還可反悔）\n \n ── pressed prop（toggle）──\n * pressed Toggle 按下狀態（持續 on/off），寫入 aria-pressed + data-state\n * 僅 secondary / tertiary / text 三個 variant 支援 toggle 視覺：\n * - secondary + pressed → primary-subtle 底、primary 字、透明邊框\n * - tertiary + pressed → primary-subtle 底、primary 字、透明邊框（同 secondary 按下視覺）\n * - text + pressed → primary-subtle 底、primary 字、透明邊框（預設 pressedTone='emphasis'，同 secondary/tertiary 按下視覺）；pressedTone='neutral' 時才走 neutral-selected 灰底\n * primary / link 傳入 pressed 無視覺效果（語意不符）\n \n ── Sizes（預設 md）──\n * xs h-field-xs（24px 固定），不隨 density 縮放\n * sm h-field-sm，md=28px / lg=32px\n * md h-field-md，md=32px / lg=36px ← 預設（跟 Field/Input 對齊）\n * lg h-field-lg，md=36px / lg=40px\n * icon-only 不是獨立尺寸 — 加 iconOnly prop 讓任何尺寸變正方形\n \n ── 內部結構 ──\n * [startIcon?] [label] [badge? + endIcon?]\n \n ── 用法範例 ──\n * <Button startIcon={Plus}>新增</Button>\n * <Button variant=\"tertiary\">取消</Button>\n * <Button variant=\"primary\" danger>永久刪除</Button>\n * <Button variant=\"text\" pressed={isPinned} startIcon={Pin} aria-label=\"釘選\" iconOnly />\n * <Button badge={<Badge count={3} />} endIcon={ChevronDown}>通知</Button>\n * <Button size=\"sm\" iconOnly startIcon={Plus} aria-label=\"新增\" />\n * <Button iconOnly startIcon={Bell} aria-label=\"通知 (3 則)\"\n * overlayBadge={<Badge count={3} />} /> ← badge 自動貼 icon 右上角\n \n ── asChild ──\n * <Button asChild><Link to=\"/home\">回首頁</Link></Button>\n /\nconst buttonVariants = cva(\n [\n 'inline-flex items-center justify-center',\n 'whitespace-nowrap font-medium',\n 'border border-transparent',\n // hover 底色瞬間切換,不做過渡(user 2026-09-10 拍板「第三題改成全部瞬間」;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)\n 'cursor-pointer select-none disabled:cursor-not-allowed aria-disabled:cursor-not-allowed',\n // 2026-05-12 Round 4.5 fix(codex M31 Layer C 抓):`aria-disabled` visual 分支補(per WAI-ARIA APG —\n // aria-disabled 給語意 + visual,但不 suppress functionality;functionality 由 consumer 阻 e.g.\n // RowDragHandle listeners 只在 canDrag spread)。故意不加* `aria-disabled:pointer-events-none`\n // — Round 4 RowDragHandle Tooltip flicker fix root cause:aria-disabled buttons 必保 pointer events\n // 讓 Radix Tooltip pointerenter 通過。HTML `disabled` 保 PE:none(完全 inactive)。\n 'disabled:pointer-events-none',\n // 2026-05-12 fix v2(playwright pixel-quantified verify 抓 opacity=1 不生效):\n // `opacity-disabled` 是 custom Tailwind v4 `@utility`(opacity.css:21),variant prefix\n // `aria-disabled:` 跟 custom @utility 不 compose(`aria-disabled:cursor-not-allowed` 標準\n // utility 能 work,custom 不行)。改 arbitrary value `opacity-[var(--opacity-disabled)]`\n // 繞 custom @utility 限制(Tailwind v4 arbitrary value 直接生 `opacity: var(--opacity-disabled)`)。\n 'aria-disabled:opacity-[var(--opacity-disabled)]',\n 'rounded-md',\n // Defensive:SVG 不被 flex shrink 擠扁(防 inner-area 計算誤差導致 icon 被擠成\n // width<intrinsic 的 asymmetric 顯示)。詳 ICON_ONLY_PX 段 rationale。\n '[&_svg]:shrink-0',\n ],\n {\n variants: {\n variant: {\n primary: [\n 'bg-primary text-on-emphasis',\n 'hover:bg-primary-hover',\n 'active:bg-primary-active',\n 'disabled:bg-disabled disabled:text-fg-disabled disabled:border-transparent',\n ],\n secondary: [\n 'bg-surface text-primary border-primary',\n 'hover:text-primary-hover hover:border-primary-hover',\n 'active:text-primary-active active:border-primary-active',\n // Overlay trigger active(asChild Popover/DropdownMenu trigger)— 維持 hover 樣式\n // (canonical 對齊 inline-action.spec.md:trigger 維持 host hover 直到 overlay 關閉)\n 'data-[state=open]:text-primary-hover data-[state=open]:border-primary-hover',\n 'disabled:bg-transparent disabled:text-fg-disabled disabled:border-border',\n // 2026-05-21 v12:Toggle pressed 視覺移到 compoundVariants(variant × pressedTone),\n // 同時支援 emphasis(藍底)/ neutral(灰底)兩 tone。詳 cva.compoundVariants 段。\n ],\n tertiary: [\n 'bg-surface text-foreground border-border',\n 'hover:text-primary-hover hover:border-primary-hover',\n 'active:text-primary-active active:border-primary-active',\n // Overlay trigger active — 維持 hover 樣式(同 secondary 邏輯)\n 'data-[state=open]:text-primary-hover data-[state=open]:border-primary-hover',\n 'disabled:bg-transparent disabled:text-fg-disabled disabled:border-border',\n ],\n text: [\n 'bg-transparent text-foreground border-transparent',\n 'hover:bg-neutral-hover',\n 'active:bg-neutral-active',\n // Overlay trigger active — 維持 hover 樣式(canonical 2026-05-02 改:hover token,\n // 不另開 selected 4% — 對齊 shadcn/Radix/Material 狀態極簡派,跨 host 一致)\n 'data-[state=open]:bg-neutral-hover',\n 'disabled:bg-transparent disabled:text-fg-disabled',\n ],\n link: [\n 'bg-transparent text-primary border-transparent',\n 'hover:text-primary-hover',\n 'active:text-primary-active',\n 'disabled:text-fg-disabled',\n ],\n },\n danger: {\n true: '', // 實際樣式由 compoundVariants 提供\n },\n /*\n 2026-05-21 v12 — pressed visual tone(per user「我認同這一個方向,然後預設emphasis」):\n * emphasis = 淡藍底(toolbar functional toggle / 篩選啟用 / 面板開關 — Figma toolbar /\n * Linear toolbar / Material ToggleButton 共識)\n * neutral = 灰底(sidebar/contextual nav row pressed — Linear / Notion / VS Code Activity Bar 共識)\n * 預設 `emphasis` per user directive。實際樣式由 compoundVariants(variant × pressedTone)套用。\n * 只在 secondary / tertiary / text variant 觸發 toggle 視覺;primary / link 無視覺效果。\n /\n pressedTone: {\n emphasis: '',\n neutral: '',\n },\n size: {\n xs: 'h-field-xs px-2 text-caption leading-compact gap-0',\n sm: 'h-field-sm px-3 min-w-14 text-body leading-compact gap-1',\n md: 'h-field-md px-3 min-w-16 text-body leading-compact gap-1',\n lg: 'h-field-lg px-3 min-w-20 text-body-lg leading-compact gap-1',\n },\n },\n compoundVariants: [\n // primary + danger → 紅底白字（立即不可逆操作）\n {\n variant: 'primary',\n danger: true,\n class: [\n 'bg-error text-on-emphasis border-transparent',\n 'hover:bg-error-hover',\n 'active:bg-error-active',\n ],\n },\n // secondary + danger → 紅框紅字（有確認步驟的危險操作）\n {\n variant: 'secondary',\n danger: true,\n class: [\n 'bg-surface text-error border-error',\n 'hover:text-error-hover hover:border-error-hover',\n 'active:text-error-active active:border-error-active',\n ],\n },\n // text + danger → 紅字，hover 灰底\n {\n variant: 'text',\n danger: true,\n class: [\n 'text-error',\n 'hover:bg-neutral-hover hover:text-error-hover',\n 'active:bg-neutral-active active:text-error-active',\n ],\n },\n // ── 2026-05-21 v12 Toggle pressed(variant × pressedTone)──────────────────\n // 視覺由 data-[state=on] + aria-pressed(Radix overlay trigger fallback)觸發\n //\n // emphasis tone:藍底(primary-subtle / primary 字)— functional toggle\n {\n variant: ['secondary', 'tertiary', 'text'],\n pressedTone: 'emphasis',\n class: [\n 'data-[state=on]:bg-primary-subtle data-[state=on]:text-primary data-[state=on]:border-transparent',\n 'data-[state=on]:hover:text-primary-hover',\n 'data-[state=on]:active:text-primary-active',\n 'data-[state=on]:disabled:bg-disabled data-[state=on]:disabled:text-fg-disabled data-[state=on]:disabled:border-transparent',\n // aria-pressed fallback(Radix overlay trigger override data-state 時仍生效)\n 'aria-pressed:bg-primary-subtle aria-pressed:text-primary aria-pressed:border-transparent',\n 'aria-pressed:hover:text-primary-hover',\n // 2026-07-07 補齊第三階:fallback 分支與 data-[state=on] 分支同拼寫(選中之上按壓 = active 階)\n 'aria-pressed:active:text-primary-active',\n ],\n },\n // neutral tone:灰底(neutral-selected family)— sidebar/contextual nav pressed\n {\n variant: ['secondary', 'tertiary', 'text'],\n pressedTone: 'neutral',\n class: [\n 'data-[state=on]:bg-neutral-selected data-[state=on]:text-foreground data-[state=on]:border-transparent',\n 'data-[state=on]:hover:bg-neutral-selected-hover',\n 'data-[state=on]:active:bg-neutral-selected-active',\n 'data-[state=on]:disabled:bg-transparent data-[state=on]:disabled:text-fg-disabled',\n // aria-pressed fallback\n 'aria-pressed:bg-neutral-selected aria-pressed:text-foreground aria-pressed:border-transparent',\n 'aria-pressed:hover:bg-neutral-selected-hover',\n ],\n },\n ],\n defaultVariants: {\n // labeled 預設 = tertiary(2026-06-06 從 primary 改;iconOnly 預設 = text,由 resolvedVariant 注入)。\n // 真正預設邏輯在元件內 resolvedVariant(相對指法,免行號漂移);此 cva default 供直接 buttonVariants() 呼叫者一致。\n variant: 'tertiary',\n size: 'md',\n pressedTone: 'emphasis',\n },\n }\n)\n\n// ── ButtonGroup Context ──────────────────────────────────────────────────────\n// ButtonGroup 提供此 context;Button 讀取它注入 fullWidth。\n// Context 放本檔(不放 button-group.tsx)以避免循環 import。\ninterface ButtonGroupContextValue {\n fullWidth?: boolean\n}\n/* @internal — ButtonGroup↔Button 私有 context(fullWidth 注入);consumer 不直接 import,經 <ButtonGroup> 消費。root barrel 排除(subpath 仍可 wrap 後用)。 /\nconst ButtonGroupContext = React.createContext<ButtonGroupContextValue>({})\n\ntype InternalVariant = VariantProps<typeof buttonVariants>['variant']\n\nexport interface ButtonProps\n extends React.ButtonHTMLAttributes<HTMLButtonElement>,\n Omit<VariantProps<typeof buttonVariants>, 'variant' \| 'danger'> {\n /\n 將樣式套用至子元件（e.g. React Router Link）。\n \n ⚠️ icon-only + asChild 警告:當 `iconOnly={true}` 且 `asChild={true}` 時,內建\n * Tooltip wrapper 不啟動(Radix Slot 不接受多 child)。consumer 必須自管 child 的 `aria-label`\n * 給 screen reader,並視需要自行包 `<Tooltip>`(對齊 Polaris / Radix asChild idiom)。\n * Button 不會主動補 tooltip — 否則會破壞 Slot 單 child 規則。\n /\n asChild?: boolean\n /\n 按鈕視覺強調等級。\n * `destructive` / `ghost` 為 shadcn 內部 compat，請勿在應用程式碼中直接使用。\n /\n variant?: 'primary' \| 'secondary' \| 'tertiary' \| 'text' \| 'link'\n /* 套用危險色（紅色）。僅 primary / secondary / text 支援（tertiary / link 不支援，見 spec 禁止事項）。 /\n danger?: boolean\n /\n Toggle 按下狀態（持續 on/off）。設定時 Button 變為 toggle：\n * - 自動寫入 `aria-pressed` + `data-state=\"on\" \| \"off\"`\n * - 樣式由 variant × `pressedTone` 的 compoundVariants 套用\n * - 僅 secondary / tertiary / text 有 toggle 視覺；primary / link 傳入無效果\n \n 不傳此 prop 時 Button 就是一般按鈕，不帶 aria-pressed。\n /\n pressed?: boolean\n /\n Pressed 視覺色調(2026-05-21 v12 加):\n * - `'emphasis'`(預設)→ 淡藍底 / primary 字(對齊 Figma toolbar / Linear toolbar /\n * Material ToggleButton 共識 — toolbar functional toggle / 篩選啟用 / 面板開關)\n * - `'neutral'` → 灰底 / foreground 字(對齊 Linear / Notion / VS Code Activity Bar\n * 共識 — sidebar/contextual nav row pressed)\n \n 僅在 `pressed` 啟用且 variant ∈ {secondary, tertiary, text} 時生效。\n * 跨 toggle context 維持單一 prop API,consumer 視語意選 tone 不另開 variant。\n /\n pressedTone?: 'emphasis' \| 'neutral'\n /* 左側 icon（LucideIcon），最多一個，loading 時自動替換為 spinner /\n startIcon?: LucideIcon\n /* 右側 badge（ReactNode），通常傳入計數指示器 /\n badge?: React.ReactNode\n /\n Overlay badge(iconOnly 專用)。接收 `<Badge>` 元素,Button 內部自動定位在 startIcon 右上角——\n * badge 中心對齊 icon 的 top-right corner(Material BadgedBox / iOS App icon canonical),不是按鈕邊緣。\n * 解決手刻 `relative + absolute -top-1 -right-1` 讓 badge 飄在按鈕 chrome 右上的問題。\n \n 世界級對照:Material BadgedBox、iOS App Icon、Ant Badge wrap icon,badge 相對於視覺重心(icon)。\n * 只在 `iconOnly=true` 時生效;非 iconOnly 時應該用 inline `badge` prop 放 suffix 位置。\n /\n overlayBadge?: React.ReactNode\n /* 右側 icon（LucideIcon），放在 badge 右邊，通常用於 ChevronDown 等方向指示 /\n endIcon?: LucideIcon\n /* Icon-only 模式：移除 padding，變為正方形（必須同時設定 aria-label） /\n iconOnly?: boolean\n /\n Dismiss 視覺類(X close only canonical)。專用於 X(close)icon 的 dismiss 語意 —\n * 「關閉 surface / 忽略訊息」。不適用 Trash / Delete / Clear / Remove 等 destructive / clear 操作。\n \n 自動套用:\n * - `variant=\"text\"`(強制 override 其他 variant)\n * - `iconOnly=true`(強制)\n * - Icon 色 override:`fg-muted` → hover `fg-secondary`(跟 Inline Action dismiss 視覺一致)\n \n 典型 case:Dialog / Sheet / Popover / Alert / Toast / Coachmark 的 chrome corner close X\n * (action group region — corner 可多 action,close 左側加 Separator + refresh / share 等)。\n \n 非 dismiss(不套此 prop):\n * - Trash / Delete → destructive action,Button 用一般 variant 或 Inline Action(按 row size 判)\n * - Clear → 欄位清空,用 Inline Action\n * - Remove → collection 移除,用一般 Button / Inline Action\n \n 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/inline-action.spec.md\n * 「Dismiss canonical — X close only」段。\n /\n dismiss?: boolean\n /* 載入中狀態：startIcon 替換為 spinner，自動 disabled；badge / endIcon 維持顯示以避免 layout shift /\n loading?: boolean\n /* 撐滿父容器寬度 /\n fullWidth?: boolean\n}\n\n// IconOnly 用 padding-free + aspect-square + flex-center 的 Polaris/Atlassian idiom\n// (M17 SSOT 必可傳播 — 取代 4 個 size 的 magic-number 公式):\n// - aspect-square 鎖 width=height(來自 h-field-X)\n// - p-0 移除 px-3 (label 模式) override\n// - flex justify-center items-center(base 已有)→ SVG 自動視覺置中\n// 結果:0 magic number,0 公式,0 border-deduction,任何 size / icon size 都自然正方形。\n// World-class 對照:Polaris + Atlassian iconOnly 走 padding-free 派(Material/Ant 走\n// padding-based)。我們選 padding-free 因 SSOT 性更強(SegmentedControl / Tag dismiss\n// 等 host 全可共用同 utility class,無需各自抄公式)。詳 button.spec.md「iconOnly 鐵律」。\nconst ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst Button = React.forwardRef<HTMLButtonElement, ButtonProps>(\n (\n {\n className,\n variant: variantProp,\n danger: dangerProp,\n size,\n asChild = false,\n startIcon: StartIcon,\n badge,\n overlayBadge,\n endIcon: EndIcon,\n iconOnly = false,\n dismiss = false,\n loading = false,\n fullWidth = false,\n pressed,\n pressedTone, // 2026-06-05 fix(deep-audit P0):原漏 destructure → 落入 ...props 噴到 DOM + 永遠用 cva default\n children,\n disabled,\n ...props\n },\n ref\n ) => {\n // ── FieldContext：在 Field 內自動讀 size，讓 Button 跟 Input 同高(SSOT:useResolvedFieldSize)──\n const resolvedSize = useResolvedFieldSize(size, 'md')\n\n // ── Dismiss 視覺類 override(2026-04-22 cross-implementation dimming canonical) ──\n // dismiss=true 強制:variant=\"text\" + iconOnly=true + icon 色弱化(fg-muted → hover fg-secondary)\n // 跟 Inline Action dismiss 視覺一致。詳見 button.spec.md「Dismiss 視覺類」。\n const resolvedIconOnly = iconOnly \|\| dismiss\n\n // ── Dev-mode warning:overlayBadge 只適用 iconOnly ──\n // 有 label 的 Button 傳入 overlayBadge 會被忽略(只 render icon / 不渲染 overlay slot),\n // 靜默忽略會讓 consumer 誤以為「傳了但位置錯」。Dev mode 印 warning 引導改用 `badge` prop\n // (inline 位置,跟 label 並列)或改 `iconOnly`。Spec SSOT:badge.spec.md「Overlay 適用元件」。\n if (process.env.NODE_ENV !== 'production' && overlayBadge && !iconOnly) {\n // eslint-disable-next-line no-console\n console.warn(\n '[DS Button] `overlayBadge` 只適用於 `iconOnly` Button。有 label 的 Button 請改用 `badge` prop(inline 位置,跟 label 並列),或移除 label 改為 iconOnly。SSOT:badge.spec.md「Overlay 適用元件 canonical」節。'\n )\n }\n\n // 2026-05-23 deep-audit Phase A.4 Decision 1(user verbatim「決策ㄧ照你建議做」):dev-warn `iconOnly + (endIcon\|badge)` 並用。\n // Spec SSOT:button.spec.md「iconOnly 嚴格定義為『只有一個 icon,正方形』,不可與 endIcon 或 badge 並用」。\n // 例外:overlayBadge 跟 iconOnly 並用 canonical(上方 overlayBadge 反向 warn 已 cover;相對指法,免行號漂移)。\n // 不擋 image canonical「icon + 下拉指示 = 不加 iconOnly + startIcon + endIcon + aria-label」(那 case iconOnly=false 不 trigger)。\n if (process.env.NODE_ENV !== 'production' && iconOnly && (EndIcon !== undefined \|\| badge != null)) {\n // eslint-disable-next-line no-console\n console.warn(\n '[DS Button] `iconOnly` 嚴格定義為「只有一個 icon,正方形」,不可與 `endIcon` 或 `badge` 並用。若需 icon + 下拉指示 → 不加 iconOnly + startIcon + endIcon + aria-label;若需 icon + 角標 → iconOnly + overlayBadge。SSOT:button.spec.md `iconOnly 的邊界` 節 + `badge.spec.md` Overlay 適用元件 canonical。'\n )\n }\n\n // shadcn compat:AlertDialog、Toast 等元件內部會傳入這些 alias,\n // 在此靜默轉換,不暴露到型別或自動完成。\n // dismiss=true 強制 variant=text(dismiss canonical);override 其他 variant 傳入。\n // 2026-06-06 預設 emphasis 改低(對齊世界級:MUI 預設 text / Ant 預設 default / Polaris 低 emphasis —\n // 預設 primary CTA 是 outlier)。labeled 無 variant → `tertiary`(中性外框,清楚可點性,再按重要程度升 primary);\n // iconOnly 無 variant → `text`(toolbar ghost,對齊 action-bar.spec.md「純動作工具/低重量輔助 → text」+\n // Material 3「icon-only = no fill」)。CTA 必 explicit `variant=\"primary\"`(不靠預設)。dismiss 仍強制 text。\n const resolvedVariant: InternalVariant =\n dismiss ? 'text' :\n (variantProp as string) === 'destructive' ? 'primary' :\n (variantProp as string) === 'ghost' ? 'text' :\n (variantProp as InternalVariant) ?? (iconOnly ? 'text' : 'tertiary')\n\n const resolvedDanger = dangerProp \|\| (variantProp as string) === 'destructive'\n\n // Dev-mode warning:danger 僅 primary / secondary / text 有 compoundVariant。\n // tertiary / link + danger 無匹配 compound → 靜默渲染成一般 tertiary / link(灰、無紅色\n // danger 視覺)— consumer 可能出「不紅的刪除鍵」而不自知。Spec SSOT:button.spec.md\n // 「禁止事項」danger 條(2026-07-14 deep-audit 補 warn,對齊既有 overlayBadge / iconOnly warn pattern)。\n if (process.env.NODE_ENV !== 'production' && resolvedDanger && (resolvedVariant === 'tertiary' \|\| resolvedVariant === 'link')) {\n // eslint-disable-next-line no-console\n console.warn(\n `[DS Button] \\`danger\\` 不支援 variant=\"${resolvedVariant}\"(無對應 compoundVariant,會靜默渲染成一般 ${resolvedVariant},無紅色 danger 視覺)。危險操作請改用 primary(立即不可逆)/ secondary(可反悔)/ text(低度)。SSOT:button.spec.md「禁止事項」danger 條。`\n )\n }\n\n // ButtonGroup context：vertical group 自動注入 fullWidth\n const groupCtx = React.useContext(ButtonGroupContext)\n const resolvedFullWidth = fullWidth \|\| !!groupCtx.fullWidth\n\n const Comp = asChild ? Slot : 'button'\n const iconSize = resolvedSize === 'lg' ? 20 : 16\n\n // loading 行為：spinner 永遠在 prefix 位置\n // 有 prefix icon → icon 換成 spinner（同位置，零 layout shift）\n // 無 prefix icon → spinner 加在文字左邊（按鈕略微變寬，可接受）\n const hasSuffix = badge != null \|\| EndIcon !== undefined\n\n // icon-only 自動 tooltip：從 props 提取 aria-label，同時保留在 DOM\n const { 'aria-label': ariaLabel, ...restProps } = props\n\n // Toggle 狀態：pressed 定義時自動寫入 aria-pressed + data-state。\n // 未定義時不寫入任何 toggle 屬性（按鈕為一般 action button）。\n // 樣式由 cva data-[state=on] compoundVariants（variant × pressedTone）套用——\n // secondary/tertiary/text 預設 pressedTone='emphasis' 走 primary-subtle，\n // pressedTone='neutral' 才走 neutral-selected family；primary/link 不定義 on 分支，傳入無效果。\n const toggleAttrs =\n pressed === undefined\n ? {}\n : { 'aria-pressed': pressed, 'data-state': pressed ? 'on' : 'off' }\n\n // Chrome-unbounded marker(2026-04-22 v5 canonical):button 若無視覺邊界(text variant 或 dismiss),\n // 標記 data-unbounded=\"true\"。SurfaceHeader 透過 [&_[data-unbounded]]:my-[...] 套負 margin\n // 讓 layout 佔位縮到 24(chrome-header-height 幾何)— button native size 與 touch target 不變。\n // 詳 overlay-surface.spec.md「Chrome dismiss size canonical」\n const unboundedAttr =\n resolvedVariant === 'text' \|\| dismiss ? { 'data-unbounded': 'true' } : {}\n\n // Native path 內部結構:[loading spinner \| startIcon(+overlayBadge)] [label] [badge + endIcon]。\n // asChild 時不渲染(2026-07-04 fix):Radix Slot 規範 children 必為單一 element\n // (React.Children.only)— 內部多 expression children 變 array 必 runtime throw;\n // asChild 分支只 render consumer child,內容由 consumer 自帶。\n // 詳 CLAUDE.md 失敗記憶索引「asChild ? Slot : Native 內部 JSX 仍渲染多 children」條。\n const nativeChildren = (\n <>\n {loading ? (\n <CircularProgress size={iconSize} className=\"text-current\" />\n ) : StartIcon ? (\n resolvedIconOnly && overlayBadge ? (\n // Overlay badge canonical:wrapper 貼 icon 尺寸,badge 中心對齊 icon top-right corner\n // (Material BadgedBox / iOS App icon),不是 button chrome 角。\n //\n // CSS 細節(2026-04-20 bug fix):用 `inline-block` + 明確 width/height + `leading-none`\n // 避免 `inline-flex` span 在 Button flex container 內被撐高/撐寬(inline-flex 的 span\n // 在某些瀏覽器下會把絕對定位子元素的 translate 計算基準搞錯,造成 badge 噴飛、Button\n // aspect-square 失效)。明確給 span width/height = iconSize 鎖住 positioning context。\n <span\n className=\"relative inline-block leading-none shrink-0 pointer-events-none\"\n style={{ width: iconSize, height: iconSize }}\n >\n <StartIcon size={iconSize} aria-hidden />\n <span className=\"absolute top-0 right-0 translate-x-1/2 -translate-y-1/2 pointer-events-auto\">\n {overlayBadge}\n </span>\n </span>\n ) : (\n <StartIcon size={iconSize} aria-hidden />\n )\n ) : null}\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={iconSize} aria-hidden />}\n </span>\n )}\n </>\n )\n\n const sharedClassName = cn(\n buttonVariants({ variant: resolvedVariant, danger: resolvedDanger, size: resolvedSize, pressedTone, className }),\n // iconOnly 鐵律:padding-free + aspect-square + flex-center (Polaris idiom)\n // 0 magic-number 0 公式自動正方形。詳 ICON_ONLY_BASE rationale。\n resolvedIconOnly && ICON_ONLY_BASE,\n // Dismiss 視覺弱化:override Button text variant 預設 foreground 為 fg-muted → hover fg-secondary\n // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)\n // 弱化 icon hover 一階(item-anatomy.tsx ItemInlineActionButton 同階梯 SSOT)\n dismiss && 'text-fg-muted hover:text-fg-secondary',\n resolvedFullWidth && 'w-full',\n )\n\n // 2026-07-05 D4 修:asChild 原 silently drop loading/disabled 語意(無 aria-busy/aria-disabled/\n // click guard → <a> loading 期間可重複點擊)。補 ARIA(任何 element 合法;aria-disabled 自動點亮\n // cva 既有視覺)+ functional guard(APG aria-disabled 模式:語意+視覺由元件、功能阻斷由 guard)。\n const { onClick: slotConsumerOnClick, ...slotRest } = restProps as typeof restProps & { onClick?: React.MouseEventHandler<HTMLElement> }\n const buttonEl = asChild ? (\n // Slot 分支:children 必為單一 consumer element(React.Children.only),\n // 內部 slot(loading/startIcon/badge)不渲染;不硬塞 type/disabled(consumer child 可能是 <a>)。\n <Comp\n className={sharedClassName}\n ref={ref}\n aria-label={ariaLabel}\n aria-busy={loading \|\| undefined}\n aria-disabled={disabled \|\| loading \|\| undefined}\n onClick={disabled \|\| loading\n ? (e: React.MouseEvent<HTMLElement>) => { e.preventDefault(); e.stopPropagation() }\n : slotConsumerOnClick}\n {...toggleAttrs}\n {...unboundedAttr}\n {...slotRest}\n >\n {children}\n </Comp>\n ) : (\n <Comp\n className={sharedClassName}\n ref={ref}\n type=\"button\"\n disabled={disabled \|\| loading}\n aria-busy={loading \|\| undefined}\n aria-label={ariaLabel}\n {...toggleAttrs}\n {...unboundedAttr}\n {...restProps}\n >\n {nativeChildren}\n </Comp>\n )\n\n // icon-only + aria-label → 自動包 Tooltip（tooltip 是元件保證的行為）\n // 不建立獨立 TooltipProvider——依賴全域 Provider，\n // 這樣所有 tooltip 共享同一組 delay 參數和 warm-up 機制\n if (resolvedIconOnly && typeof ariaLabel === 'string' && !asChild) {\n return (\n <Tooltip>\n <TooltipTrigger asChild>{buttonEl}</TooltipTrigger>\n <TooltipContent>{ariaLabel}</TooltipContent>\n </Tooltip>\n )\n }\n\n return buttonEl\n }\n)\nButton.displayName = 'Button'\n\n/\n componentMeta — Story Auto-Compile 系統消費的結構化 canonical\n * (見 .claude/planning/story-auto-compile.md Phase 1)\n \n compile-stories.mjs 讀本 export + spec.md frontmatter 產出\n * anatomy.stories.tsx 的 variant/size/state/token 矩陣 canonical section。\n \n Keys 必跟 buttonVariants cva + spec frontmatter 對齊(compile-time 驗證)。\n /\nexport const buttonMeta = {\n component: 'Button',\n family: 3, // Pill Layout\n variants: {\n primary: { purpose: '主要 action / CTA' },\n secondary: { purpose: '次要 action(陪襯 primary)' },\n tertiary: { purpose: '第三級 action(tool-like)' },\n text: { purpose: '文字樣式 action(low emphasis / toolbar)' },\n link: { purpose: '內文連結(inline reading)' },\n },\n sizes: {\n xs: { fieldHeight: 24, iconSize: 16, typography: 'caption' },\n sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },\n md: { fieldHeight: 32, iconSize: 16, typography: 'body' },\n lg: { fieldHeight: 36, iconSize: 20, typography: 'body-lg' },\n },\n // 'pressed' = toggle on 持續態(data-[state=on],emphasis 淡藍底/neutral 灰底;2026-07-07 meta 詞彙統一補列)\n // 'loading' = CircularProgress spinner 取代 startIcon + aria-busy + click guard(2026-07-14 deep-audit\n // 補列,原漏 → auto-compile 生成矩陣缺 loading;對齊 anatomy StateBehavior Loading 行 + tsx loading 分支)\n states: ['default', 'hover', 'active', 'pressed', 'loading', 'focus-visible', 'disabled'],\n tokens: {\n // 2026-07-04 audit 補齊:原只列 primary variant 家族;按 buttonVariants cva 真實 class 補\n // secondary/tertiary/text/link/danger 消費的 token(auto-compile token 矩陣依此)。\n // 2026-07-14 deep-audit 二次補齊(掃 cva 全 bg- class):+ neutral-selected-hover / neutral-selected-active\n // (neutral pressedTone compound 消費)+ error / error-hover / error-active(primary+danger bg-error 系)\n bg: ['--primary', '--primary-hover', '--primary-active', '--primary-subtle', '--bg-disabled', '--surface', '--neutral-hover', '--neutral-active', '--neutral-selected', '--neutral-selected-hover', '--neutral-selected-active', '--error', '--error-hover', '--error-active'],\n fg: ['--on-emphasis', '--fg-disabled', '--foreground', '--primary', '--primary-hover', '--primary-active', '--error', '--error-hover', '--error-active'],\n ring: ['--ring'],\n },\n defaultVariant: 'tertiary', // 2026-06-10 修 stale:對齊 cva defaultVariants(2026-06-06 labeled 預設改 tertiary,meta 漏同步)\n defaultSize: 'md',\n} as const\n\nexport { Button, buttonVariants, ButtonGroupContext }\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"button.js","sources":["../../../src/components/Button/button.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.\n// code-quality-allow: file-size — foundational composite(Button + iconOnly + danger + loading + asChild + dismiss + pressedTone)— 跨 7 axis variant 集中 SSOT 一處,拆分會 fragment cva variant catalog。當前 528 < cap 800。\nimport * as React from 'react'\nimport { Slot } from '@radix-ui/react-slot'\nimport { cva, type VariantProps } from 'class-variance-authority'\nimport { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'\nimport type { LucideIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { useResolvedFieldSize } from '@/design-system/components/Field/field-context'\nimport { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'\n\n/*\n Button — shadcn 風格，橋接設計系統 token\n \n ── Variants ──\n * primary 主要操作，藍底白字\n * secondary 次要品牌操作，藍框藍字；正面 vs 負面並存時用於正面那個\n * tertiary 一般輔助操作，灰框灰字，hover 轉藍（最常用的非主要按鈕）\n * text 無底色無邊框，hover 顯示灰底（工具列、密集 UI）\n * link 外觀像連結的按鈕（本質仍是 button）\n \n ── danger prop ──\n * danger 套用危險色（紅色）；僅 primary / secondary / text 支援（tertiary / link 不支援，見 spec 禁止事項）\n \n <Button variant=\"primary\" danger>永久刪除</Button> → 紅底白字（立即不可逆）\n * <Button variant=\"secondary\" danger>移至垃圾桶</Button> → 紅框紅字（點下去還可反悔）\n \n ── pressed prop（toggle）──\n * pressed Toggle 按下狀態（持續 on/off），寫入 aria-pressed + data-state\n * 僅 secondary / tertiary / text 三個 variant 支援 toggle 視覺：\n * - secondary + pressed → primary-subtle 底、primary 字、透明邊框\n * - tertiary + pressed → primary-subtle 底、primary 字、透明邊框（同 secondary 按下視覺）\n * - text + pressed → primary-subtle 底、primary 字、透明邊框（預設 pressedTone='emphasis'，同 secondary/tertiary 按下視覺）；pressedTone='neutral' 時才走 neutral-selected 灰底\n * primary / link 傳入 pressed 無視覺效果（語意不符）\n \n ── Sizes（預設 md）──\n * xs h-field-xs（24px 固定），不隨 density 縮放\n * sm h-field-sm，md=28px / lg=32px\n * md h-field-md，md=32px / lg=36px ← 預設（跟 Field/Input 對齊）\n * lg h-field-lg，md=36px / lg=40px\n * icon-only 不是獨立尺寸 — 加 iconOnly prop 讓任何尺寸變正方形\n \n ── 內部結構 ──\n * [startIcon?] [label] [badge? + endIcon?]\n \n ── 用法範例 ──\n * <Button startIcon={Plus}>新增</Button>\n * <Button variant=\"tertiary\">取消</Button>\n * <Button variant=\"primary\" danger>永久刪除</Button>\n * <Button variant=\"text\" pressed={isPinned} startIcon={Pin} aria-label=\"釘選\" iconOnly />\n * <Button badge={<Badge count={3} />} endIcon={ChevronDown}>通知</Button>\n * <Button size=\"sm\" iconOnly startIcon={Plus} aria-label=\"新增\" />\n * <Button iconOnly startIcon={Bell} aria-label=\"通知 (3 則)\"\n * overlayBadge={<Badge count={3} />} /> ← badge 自動貼 icon 右上角\n \n ── asChild ──\n * <Button asChild><Link to=\"/home\">回首頁</Link></Button>\n /\nconst buttonVariants = cva(\n [\n 'inline-flex items-center justify-center',\n 'whitespace-nowrap font-medium',\n 'border border-transparent',\n // hover 底色瞬間切換,不做過渡(user 2026-09-10 拍板「第三題改成全部瞬間」;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)\n 'cursor-pointer select-none disabled:cursor-not-allowed aria-disabled:cursor-not-allowed',\n // 2026-05-12 Round 4.5 fix(codex M31 Layer C 抓):`aria-disabled` visual 分支補(per WAI-ARIA APG —\n // aria-disabled 給語意 + visual,但不 suppress functionality;functionality 由 consumer 阻 e.g.\n // RowDragHandle listeners 只在 canDrag spread)。故意不加* `aria-disabled:pointer-events-none`\n // — Round 4 RowDragHandle Tooltip flicker fix root cause:aria-disabled buttons 必保 pointer events\n // 讓 Radix Tooltip pointerenter 通過。\n // 2026-09-29(待辦總帳 N46 停用游標全站掃):原生 `disabled` 原本也掛 `pointer-events-none`(「完全 inactive」),\n // 結果上面那句 `disabled:cursor-not-allowed` 從來沒生效 —— 沒有指標事件就沒有游標,全站 35 顆停用的 Button 家族\n //(分頁箭頭 / 輪播箭頭 / AI 面板送出鈕)都是箭頭游標,違反 hit-area-canonical.md「停用的用禁止符號」。\n // 現在停用不再切掉指標事件;滑過 / 按住的回饋改由各 variant 的 `disabled:hover:` / `disabled:active:` 顯式釘在停用靜止值\n //(同 aria-disabled 的寫法;原生 disabled 的按鈕本來就不派發 click)。\n // 2026-05-12 fix v2(playwright pixel-quantified verify 抓 opacity=1 不生效):\n // `opacity-disabled` 是 custom Tailwind v4 `@utility`(opacity.css:21),variant prefix\n // `aria-disabled:` 跟 custom @utility 不 compose(`aria-disabled:cursor-not-allowed` 標準\n // utility 能 work,custom 不行)。改 arbitrary value `opacity-[var(--opacity-disabled)]`\n // 繞 custom @utility 限制(Tailwind v4 arbitrary value 直接生 `opacity: var(--opacity-disabled)`)。\n 'aria-disabled:opacity-[var(--opacity-disabled)]',\n 'rounded-md',\n // Defensive:SVG 不被 flex shrink 擠扁(防 inner-area 計算誤差導致 icon 被擠成\n // width<intrinsic 的 asymmetric 顯示)。詳 ICON_ONLY_PX 段 rationale。\n '[&_svg]:shrink-0',\n ],\n {\n variants: {\n variant: {\n primary: [\n 'bg-primary text-on-emphasis',\n 'hover:bg-primary-hover',\n 'active:bg-primary-active',\n // 開啟中 = 自己的 hover(inline-action.spec.md:26「overlay 開啟 → 同 host hover」)。2026-09-29 待辦總帳 C13:\n // 七家一手裡沒有任何一家「給部分 variant、獨獨豁免 primary」(Atlassian / Fluent 每個 appearance 含 primary 都給;\n // Radix / shadcn / MUI / Ant / Carbon 全都不給);DS 早選了「給」,primary / link 缺的只是同一條規則的落地。\n 'data-[state=open]:bg-primary-hover',\n // aria-disabled 的 hover / active 釘在靜止(button.spec.md「狀態疊加」表 aria-disabled 列:與 disabled 同樣不給互動回饋;\n // 原生 disabled 與 aria-disabled 都顯式釘住(2026-09-29 前原生 disabled 靠 pointer-events-none,見檔頭);先例 switch.tsx 的 `disabled:…:hover:` 守衛)\n 'aria-disabled:hover:bg-primary aria-disabled:active:bg-primary',\n 'disabled:bg-disabled disabled:text-fg-disabled disabled:border-transparent',\n 'disabled:hover:bg-disabled disabled:active:bg-disabled',\n ],\n secondary: [\n 'bg-surface text-primary border-primary',\n 'hover:text-primary-hover hover:border-primary-hover',\n 'active:text-primary-active active:border-primary-active',\n // Overlay trigger active(asChild Popover/DropdownMenu trigger)— 維持 hover 樣式\n // (canonical 對齊 inline-action.spec.md:trigger 維持 host hover 直到 overlay 關閉)\n 'data-[state=open]:text-primary-hover data-[state=open]:border-primary-hover',\n // aria-disabled 釘住(同 primary 註解);`not-aria-pressed` = 只釘「未按下」的靜止,按下的由 pressed compound 自己釘(避免兩組 (0,3,0) 靠產出順序決勝)\n 'aria-disabled:not-aria-pressed:hover:text-primary aria-disabled:not-aria-pressed:hover:border-primary',\n 'aria-disabled:not-aria-pressed:active:text-primary aria-disabled:not-aria-pressed:active:border-primary',\n 'disabled:bg-transparent disabled:text-fg-disabled disabled:border-border',\n 'disabled:hover:text-fg-disabled disabled:hover:border-border disabled:active:text-fg-disabled disabled:active:border-border',\n // 2026-05-21 v12:Toggle pressed 視覺移到 compoundVariants(variant × pressedTone),\n // 同時支援 emphasis(藍底)/ neutral(灰底)兩 tone。詳 cva.compoundVariants 段。\n ],\n tertiary: [\n 'bg-surface text-foreground border-border',\n 'hover:text-primary-hover hover:border-primary-hover',\n 'active:text-primary-active active:border-primary-active',\n // Overlay trigger active — 維持 hover 樣式(同 secondary 邏輯)\n 'data-[state=open]:text-primary-hover data-[state=open]:border-primary-hover',\n // aria-disabled 釘住(同 secondary 註解)\n 'aria-disabled:not-aria-pressed:hover:text-foreground aria-disabled:not-aria-pressed:hover:border-border',\n 'aria-disabled:not-aria-pressed:active:text-foreground aria-disabled:not-aria-pressed:active:border-border',\n 'disabled:bg-transparent disabled:text-fg-disabled disabled:border-border',\n 'disabled:hover:text-fg-disabled disabled:hover:border-border disabled:active:text-fg-disabled disabled:active:border-border',\n ],\n text: [\n 'bg-transparent text-foreground border-transparent',\n 'hover:bg-neutral-hover',\n 'active:bg-neutral-active',\n // Overlay trigger active — 維持 hover 樣式(canonical 2026-05-02 改:hover token,\n // 不另開 selected 4% — 對齊 shadcn/Radix/Material 狀態極簡派,跨 host 一致)\n 'data-[state=open]:bg-neutral-hover',\n // aria-disabled 釘住(同 secondary 註解)\n 'aria-disabled:not-aria-pressed:hover:bg-transparent aria-disabled:not-aria-pressed:active:bg-transparent',\n 'disabled:bg-transparent disabled:text-fg-disabled',\n 'disabled:hover:bg-transparent disabled:hover:text-fg-disabled disabled:active:bg-transparent disabled:active:text-fg-disabled',\n ],\n link: [\n 'bg-transparent text-primary border-transparent',\n 'hover:text-primary-hover',\n 'active:text-primary-active',\n // 開啟中 = 自己的 hover(link 的 hover 只換字色;同 primary 分支註解,2026-09-29 C13)\n 'data-[state=open]:text-primary-hover',\n // aria-disabled 釘住(同 primary 註解;link 無 pressed 視覺,不需 not-aria-pressed)\n 'aria-disabled:hover:text-primary aria-disabled:active:text-primary',\n 'disabled:text-fg-disabled',\n 'disabled:hover:text-fg-disabled disabled:active:text-fg-disabled',\n ],\n },\n danger: {\n true: '', // 實際樣式由 compoundVariants 提供\n },\n /*\n 2026-05-21 v12 — pressed visual tone(per user「我認同這一個方向,然後預設emphasis」):\n * emphasis = 淡藍底(toolbar functional toggle / 篩選啟用 / 面板開關 — Figma toolbar /\n * Linear toolbar / Material ToggleButton 共識)\n * neutral = 灰底(可取消的切換鈕、要比藍底低一級時;不用於導覽 / 目前頁 —— 那是選中列,\n * owner = item-anatomy.spec.md「選中 × 互動疊加」;button.spec.md pressedTone 表,待辦總帳 B5 2026-09-25 更正)\n * 預設 `emphasis` per user directive。實際樣式由 compoundVariants(variant × pressedTone)套用。\n * 只在 secondary / tertiary / text variant 觸發 toggle 視覺;primary / link 無視覺效果。\n /\n pressedTone: {\n emphasis: '',\n neutral: '',\n },\n size: {\n xs: 'h-field-xs px-2 text-caption leading-compact gap-0',\n sm: 'h-field-sm px-3 min-w-14 text-body leading-compact gap-1',\n md: 'h-field-md px-3 min-w-16 text-body leading-compact gap-1',\n lg: 'h-field-lg px-3 min-w-20 text-body-lg leading-compact gap-1',\n },\n },\n compoundVariants: [\n // primary + danger → 紅底白字（立即不可逆操作）\n {\n variant: 'primary',\n danger: true,\n class: [\n 'bg-error text-on-emphasis border-transparent',\n 'hover:bg-error-hover',\n 'active:bg-error-active',\n // 開啟中 = 自己的 hover(同 primary 分支,2026-09-29 C13)\n 'data-[state=open]:bg-error-hover',\n // aria-disabled 釘在自己的靜止紅(button.spec.md「狀態疊加」表 aria-disabled 列)\n 'aria-disabled:hover:bg-error aria-disabled:active:bg-error',\n ],\n },\n // secondary + danger → 紅框紅字（有確認步驟的危險操作）\n {\n variant: 'secondary',\n danger: true,\n class: [\n 'bg-surface text-error border-error',\n 'hover:text-error-hover hover:border-error-hover',\n 'active:text-error-active active:border-error-active',\n // 開啟中 = 自己的 hover(error-hover),不是 secondary 的 primary-hover(inline-action.spec.md「overlay 開啟 → 同 host hover」;\n // button.spec.md「狀態疊加」表開啟中列)。靠 cn()/twMerge 去掉 variant 那組同前綴 class,同本檔 danger 覆寫慣例\n 'data-[state=open]:text-error-hover data-[state=open]:border-error-hover',\n 'aria-disabled:not-aria-pressed:hover:text-error aria-disabled:not-aria-pressed:hover:border-error',\n 'aria-disabled:not-aria-pressed:active:text-error aria-disabled:not-aria-pressed:active:border-error',\n ],\n },\n // text + danger → 紅字，hover 灰底\n {\n variant: 'text',\n danger: true,\n class: [\n 'text-error',\n 'hover:bg-neutral-hover hover:text-error-hover',\n 'active:bg-neutral-active active:text-error-active',\n // 開啟中 = 自己的 hover 配對:底色沿用 text 的 data-[state=open]:bg-neutral-hover,字補上 error-hover(同 secondary+danger 註解)\n 'data-[state=open]:text-error-hover',\n 'aria-disabled:not-aria-pressed:hover:text-error aria-disabled:not-aria-pressed:active:text-error',\n ],\n },\n // ── 2026-05-21 v12 Toggle pressed(variant × pressedTone)──────────────────\n // 視覺由 data-[state=on] + aria-pressed(Radix overlay trigger fallback)觸發\n //\n // emphasis tone:藍底(primary-subtle / primary 字)— functional toggle\n {\n variant: ['secondary', 'tertiary', 'text'],\n pressedTone: 'emphasis',\n class: [\n 'data-[state=on]:bg-primary-subtle data-[state=on]:text-primary data-[state=on]:border-transparent',\n // 按下的 hover / active 只換字(primary-hover / -active),底色與邊框顯式釘住 —— 照 sidebar.tsx\n // `data-[active=true]:hover:bg-neutral-selected` 寫法,釘住 (0,3,0) > variant 的 hover / active (0,2,0)。\n // 之前底色只是靠 CSS 產出順序(data- 排在 hover 之後)才沒被 text 的 neutral-hover 換掉(button.spec.md「狀態疊加」表 pressed × hover / active 列)\n 'data-[state=on]:hover:bg-primary-subtle data-[state=on]:hover:border-transparent data-[state=on]:hover:text-primary-hover',\n 'data-[state=on]:active:bg-primary-subtle data-[state=on]:active:border-transparent data-[state=on]:active:text-primary-active',\n 'data-[state=on]:disabled:bg-disabled data-[state=on]:disabled:text-fg-disabled data-[state=on]:disabled:border-transparent',\n 'data-[state=on]:disabled:hover:bg-disabled data-[state=on]:disabled:hover:text-fg-disabled data-[state=on]:disabled:hover:border-transparent data-[state=on]:disabled:active:bg-disabled data-[state=on]:disabled:active:text-fg-disabled data-[state=on]:disabled:active:border-transparent',\n // aria-pressed fallback(Radix overlay trigger override data-state 時仍生效)—— 逐條鏡像上方 data-[state=on] 分支\n 'aria-pressed:bg-primary-subtle aria-pressed:text-primary aria-pressed:border-transparent',\n 'aria-pressed:hover:bg-primary-subtle aria-pressed:hover:border-transparent aria-pressed:hover:text-primary-hover',\n // 2026-07-07 補齊第三階:fallback 分支與 data-[state=on] 分支同拼寫(選中之上按壓 = active 階)\n 'aria-pressed:active:bg-primary-subtle aria-pressed:active:border-transparent aria-pressed:active:text-primary-active',\n // pressed + disabled:disabled 視覺優先(button.spec.md「狀態 → disabled」pressed + disabled 條);fallback 分支原本缺這條,鏡像 data-[state=on]:disabled\n 'aria-pressed:disabled:bg-disabled aria-pressed:disabled:text-fg-disabled aria-pressed:disabled:border-transparent',\n 'aria-pressed:disabled:hover:bg-disabled aria-pressed:disabled:hover:text-fg-disabled aria-pressed:disabled:hover:border-transparent aria-pressed:disabled:active:bg-disabled aria-pressed:disabled:active:text-fg-disabled aria-pressed:disabled:active:border-transparent',\n // 按下的觸發鈕開啟中 = 按下自己的 hover(底色與邊框不動、字 primary-hover),不是 variant 的開啟樣式\n //(inline-action.spec.md「overlay 開啟 → 同 host hover」;button.spec.md「狀態疊加」表開啟中列)。\n // Radix 會把 data-state 改寫成 open,所以只走 aria-pressed;(0,3,0) > variant 的 data-[state=open] (0,2,0)\n 'aria-pressed:data-[state=open]:bg-primary-subtle aria-pressed:data-[state=open]:border-transparent aria-pressed:data-[state=open]:text-primary-hover',\n // 按下 + aria-disabled:hover / active 釘在按下的靜止字色(底色與邊框已由上方釘住)\n 'data-[state=on]:aria-disabled:hover:text-primary data-[state=on]:aria-disabled:active:text-primary',\n 'aria-pressed:aria-disabled:hover:text-primary aria-pressed:aria-disabled:active:text-primary',\n ],\n },\n // neutral tone:灰底(neutral-selected family)— 可取消的切換鈕;導覽 / 目前頁不用它(選中列規則,item-anatomy.spec.md「選中 × 互動疊加」)\n // 階梯值 selected → -selected-hover → -selected-active(2→3→4):user 2026-09-25 選「甲：保留，維持 2→3→4 (Recommended)」\n // (選項由 AI 提供;待辦總帳 B5)。下方開啟中 / aria-disabled 各條都是「跟著本分支的 hover / 靜止 token 走」,改階梯時同一 compound 內一起改。\n // 2026-09-29(待辦總帳 N7):secondary 從這一組拆出去(下一組)—— 它的靜止底是 `--surface`(「底」),已按下要疊層不換底:\n // 深色 --surface 與 --neutral-selected 都是白 8%,換底後已按下 = 未按下(#1E1E1E = #1E1E1E);tertiary / text 是透明底,換底沒問題。\n {\n variant: ['tertiary', 'text'],\n pressedTone: 'neutral',\n class: [\n 'data-[state=on]:bg-neutral-selected data-[state=on]:text-foreground data-[state=on]:border-transparent',\n // 字與邊框在 hover / active 顯式釘住(secondary / tertiary 的 hover 會把字與框轉 primary;同 emphasis 分支註解)\n 'data-[state=on]:hover:bg-neutral-selected-hover data-[state=on]:hover:text-foreground data-[state=on]:hover:border-transparent',\n 'data-[state=on]:active:bg-neutral-selected-active data-[state=on]:active:text-foreground data-[state=on]:active:border-transparent',\n 'data-[state=on]:disabled:bg-transparent data-[state=on]:disabled:text-fg-disabled',\n 'data-[state=on]:disabled:hover:bg-transparent data-[state=on]:disabled:hover:text-fg-disabled data-[state=on]:disabled:active:bg-transparent data-[state=on]:disabled:active:text-fg-disabled',\n // aria-pressed fallback —— 逐條鏡像上方 data-[state=on] 分支\n 'aria-pressed:bg-neutral-selected aria-pressed:text-foreground aria-pressed:border-transparent',\n 'aria-pressed:hover:bg-neutral-selected-hover aria-pressed:hover:text-foreground aria-pressed:hover:border-transparent',\n // 補齊第三階(按壓):fallback 原本缺,data-[state=on] 分支與 emphasis 分支都有(同 emphasis 2026-07-07 註解)\n 'aria-pressed:active:bg-neutral-selected-active aria-pressed:active:text-foreground aria-pressed:active:border-transparent',\n 'aria-pressed:disabled:bg-transparent aria-pressed:disabled:text-fg-disabled',\n 'aria-pressed:disabled:hover:bg-transparent aria-pressed:disabled:hover:text-fg-disabled aria-pressed:disabled:active:bg-transparent aria-pressed:disabled:active:text-fg-disabled',\n // 按下的觸發鈕開啟中 = 按下自己的 hover(neutral-selected-hover),不是 variant 的 neutral-hover / primary-hover(同 emphasis 分支註解)\n 'aria-pressed:data-[state=open]:bg-neutral-selected-hover aria-pressed:data-[state=open]:text-foreground aria-pressed:data-[state=open]:border-transparent',\n // 按下 + aria-disabled:hover / active 釘在按下的靜止底色\n 'data-[state=on]:aria-disabled:hover:bg-neutral-selected data-[state=on]:aria-disabled:active:bg-neutral-selected',\n 'aria-pressed:aria-disabled:hover:bg-neutral-selected aria-pressed:aria-disabled:active:bg-neutral-selected',\n ],\n },\n // secondary(白底)× neutral:底留 `bg-surface`,已按下三階用疊層 utility(semantic.css `bg-interaction-selected` 家族 =\n // 把 --neutral-selected / -hover / -active 畫成 background-image,在底色之上、內容之下;配對總則第 2 列「底不換,疊一層」)。\n // 淺色疊層結果與換底相同(#F5F5F5 / #F0F0F0 / #E8E8E8),深色才分得出來(#303030 / #37 / #3D)。逐條鏡像上一組;\n // 停用態拿掉疊層(`bg-none`)而不是把底換成透明 —— 白底鈕停用仍是白底。\n {\n variant: 'secondary',\n pressedTone: 'neutral',\n class: [\n // 底寫明 `bg-surface`(與 variant 相同,不換底):疊層是疊在「底」上,hover-own-pair 閘據此判定,不必去別的 compound 找靜止底\n 'data-[state=on]:bg-surface data-[state=on]:bg-interaction-selected data-[state=on]:text-foreground data-[state=on]:border-transparent',\n 'data-[state=on]:hover:bg-interaction-selected-hover data-[state=on]:hover:text-foreground data-[state=on]:hover:border-transparent',\n 'data-[state=on]:active:bg-interaction-selected-active data-[state=on]:active:text-foreground data-[state=on]:active:border-transparent',\n 'data-[state=on]:disabled:bg-none data-[state=on]:disabled:text-fg-disabled',\n 'data-[state=on]:disabled:hover:bg-none data-[state=on]:disabled:hover:text-fg-disabled data-[state=on]:disabled:active:bg-none data-[state=on]:disabled:active:text-fg-disabled',\n 'aria-pressed:bg-surface aria-pressed:bg-interaction-selected aria-pressed:text-foreground aria-pressed:border-transparent',\n 'aria-pressed:hover:bg-interaction-selected-hover aria-pressed:hover:text-foreground aria-pressed:hover:border-transparent',\n 'aria-pressed:active:bg-interaction-selected-active aria-pressed:active:text-foreground aria-pressed:active:border-transparent',\n 'aria-pressed:disabled:bg-none aria-pressed:disabled:text-fg-disabled',\n 'aria-pressed:disabled:hover:bg-none aria-pressed:disabled:hover:text-fg-disabled aria-pressed:disabled:active:bg-none aria-pressed:disabled:active:text-fg-disabled',\n 'aria-pressed:data-[state=open]:bg-interaction-selected-hover aria-pressed:data-[state=open]:text-foreground aria-pressed:data-[state=open]:border-transparent',\n 'data-[state=on]:aria-disabled:hover:bg-interaction-selected data-[state=on]:aria-disabled:active:bg-interaction-selected',\n 'aria-pressed:aria-disabled:hover:bg-interaction-selected aria-pressed:aria-disabled:active:bg-interaction-selected',\n ],\n },\n ],\n defaultVariants: {\n // labeled 預設 = tertiary(2026-06-06 從 primary 改;iconOnly 預設 = text,由 resolvedVariant 注入)。\n // 真正預設邏輯在元件內 resolvedVariant(相對指法,免行號漂移);此 cva default 供直接 buttonVariants() 呼叫者一致。\n variant: 'tertiary',\n size: 'md',\n pressedTone: 'emphasis',\n },\n }\n)\n\n// ── ButtonGroup Context ──────────────────────────────────────────────────────\n// ButtonGroup 提供此 context;Button 讀取它注入 fullWidth。\n// Context 放本檔(不放 button-group.tsx)以避免循環 import。\ninterface ButtonGroupContextValue {\n fullWidth?: boolean\n}\n/** @internal — ButtonGroup↔Button 私有 context(fullWidth 注入);consumer 不直接 import,經 <ButtonGroup> 消費。root barrel 排除(subpath 仍可 wrap 後用)。 /\nconst ButtonGroupContext = React.createContext<ButtonGroupContextValue>({})\n\ntype InternalVariant = VariantProps<typeof buttonVariants>['variant']\n\nexport interface ButtonProps\n extends React.ButtonHTMLAttributes<HTMLButtonElement>,\n Omit<VariantProps<typeof buttonVariants>, 'variant' \| 'danger'> {\n /\n 將樣式套用至子元件（e.g. React Router Link）。\n \n ⚠️ icon-only + asChild 警告:當 `iconOnly={true}` 且 `asChild={true}` 時,內建\n * Tooltip wrapper 不啟動(Radix Slot 不接受多 child)。consumer 必須自管 child 的 `aria-label`\n * 給 screen reader,並視需要自行包 `<Tooltip>`(對齊 Polaris / Radix asChild idiom)。\n * Button 不會主動補 tooltip — 否則會破壞 Slot 單 child 規則。\n /\n asChild?: boolean\n /\n 按鈕視覺強調等級。\n * `destructive` / `ghost` 為 shadcn 內部 compat，請勿在應用程式碼中直接使用。\n /\n variant?: 'primary' \| 'secondary' \| 'tertiary' \| 'text' \| 'link'\n /* 套用危險色（紅色）。僅 primary / secondary / text 支援（tertiary / link 不支援，見 spec 禁止事項）。 /\n danger?: boolean\n /\n Toggle 按下狀態（持續 on/off）。設定時 Button 變為 toggle：\n * - 自動寫入 `aria-pressed` + `data-state=\"on\" \| \"off\"`\n * - 樣式由 variant × `pressedTone` 的 compoundVariants 套用\n * - 僅 secondary / tertiary / text 有 toggle 視覺；primary / link 傳入無效果\n \n 不傳此 prop 時 Button 就是一般按鈕，不帶 aria-pressed。\n /\n pressed?: boolean\n /\n Pressed 視覺色調(2026-05-21 v12 加):\n * - `'emphasis'`(預設)→ 淡藍底 / primary 字(對齊 Figma toolbar / Linear toolbar /\n * Material ToggleButton 共識 — toolbar functional toggle / 篩選啟用 / 面板開關)\n * - `'neutral'` → 灰底 / foreground 字 —— 可取消的切換鈕(再點一次就關掉)需要低一級強調時;\n * 導覽 / 目前頁不用它(那是選中列,滑過釘住;button.spec.md pressedTone 表,2026-09-25 更正)\n \n 僅在 `pressed` 啟用且 variant ∈ {secondary, tertiary, text} 時生效。\n * 跨 toggle context 維持單一 prop API,consumer 視語意選 tone 不另開 variant。\n /\n pressedTone?: 'emphasis' \| 'neutral'\n /* 左側 icon（LucideIcon），最多一個，loading 時自動替換為 spinner /\n startIcon?: LucideIcon\n /* 右側 badge（ReactNode），通常傳入計數指示器 /\n badge?: React.ReactNode\n /\n Overlay badge(iconOnly 專用)。接收 `<Badge>` 元素,Button 內部自動定位在 startIcon 右上角——\n * badge 中心對齊 icon 的 top-right corner(Material BadgedBox / iOS App icon canonical),不是按鈕邊緣。\n * 解決手刻 `relative + absolute -top-1 -right-1` 讓 badge 飄在按鈕 chrome 右上的問題。\n \n 世界級對照:Material BadgedBox、iOS App Icon、Ant Badge wrap icon,badge 相對於視覺重心(icon)。\n * 只在 `iconOnly=true` 時生效;非 iconOnly 時應該用 inline `badge` prop 放 suffix 位置。\n /\n overlayBadge?: React.ReactNode\n /* 右側 icon（LucideIcon），放在 badge 右邊，通常用於 ChevronDown 等方向指示 /\n endIcon?: LucideIcon\n /* Icon-only 模式：移除 padding，變為正方形（必須同時設定 aria-label） /\n iconOnly?: boolean\n /\n Dismiss 視覺類(X close only canonical)。專用於 X(close)icon 的 dismiss 語意 —\n * 「關閉 surface / 忽略訊息」。不適用 Trash / Delete / Clear / Remove 等 destructive / clear 操作。\n \n 自動套用:\n * - `variant=\"text\"`(強制 override 其他 variant)\n * - `iconOnly=true`(強制)\n * - Icon 色 override:`fg-muted` → hover `fg-secondary`(跟 Inline Action dismiss 視覺一致)\n \n 典型 case:Dialog / Sheet / Popover / Alert / Toast / Coachmark 的 chrome corner close X\n * (action group region — corner 可多 action,close 左側加 Separator + refresh / share 等)。\n \n 非 dismiss(不套此 prop):\n * - Trash / Delete → destructive action,Button 用一般 variant 或 Inline Action(按 row size 判)\n * - Clear → 欄位清空,用 Inline Action\n * - Remove → collection 移除,用一般 Button / Inline Action\n \n 詳見 button.spec.md「Dismiss 視覺類」段 + patterns/element-anatomy/inline-action.spec.md\n * 「Dismiss canonical — X close only」段。\n /\n dismiss?: boolean\n /* 載入中狀態：startIcon 替換為 spinner，自動 disabled；badge / endIcon 維持顯示以避免 layout shift /\n loading?: boolean\n /* 撐滿父容器寬度 /\n fullWidth?: boolean\n}\n\n// IconOnly 用 padding-free + aspect-square + flex-center 的 Polaris/Atlassian idiom\n// (M17 SSOT 必可傳播 — 取代 4 個 size 的 magic-number 公式):\n// - aspect-square 鎖 width=height(來自 h-field-X)\n// - p-0 移除 px-3 (label 模式) override\n// - flex justify-center items-center(base 已有)→ SVG 自動視覺置中\n// 結果:0 magic number,0 公式,0 border-deduction,任何 size / icon size 都自然正方形。\n// World-class 對照:Polaris + Atlassian iconOnly 走 padding-free 派(Material/Ant 走\n// padding-based)。我們選 padding-free 因 SSOT 性更強(SegmentedControl / Tag dismiss\n// 等 host 全可共用同 utility class,無需各自抄公式)。詳 button.spec.md「iconOnly 鐵律」。\nconst ICON_ONLY_BASE = 'aspect-square p-0 min-w-0 gap-0'\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst Button = React.forwardRef<HTMLButtonElement, ButtonProps>(\n (\n {\n className,\n variant: variantProp,\n danger: dangerProp,\n size,\n asChild = false,\n startIcon: StartIcon,\n badge,\n overlayBadge,\n endIcon: EndIcon,\n iconOnly = false,\n dismiss = false,\n loading = false,\n fullWidth = false,\n pressed,\n pressedTone, // 2026-06-05 fix(deep-audit P0):原漏 destructure → 落入 ...props 噴到 DOM + 永遠用 cva default\n children,\n disabled,\n ...props\n },\n ref\n ) => {\n // ── FieldContext：在 Field 內自動讀 size，讓 Button 跟 Input 同高(SSOT:useResolvedFieldSize)──\n const resolvedSize = useResolvedFieldSize(size, 'md')\n\n // ── Dismiss 視覺類 override(2026-04-22 cross-implementation dimming canonical) ──\n // dismiss=true 強制:variant=\"text\" + iconOnly=true + icon 色弱化(fg-muted → hover fg-secondary)\n // 跟 Inline Action dismiss 視覺一致。詳見 button.spec.md「Dismiss 視覺類」。\n const resolvedIconOnly = iconOnly \|\| dismiss\n\n // ── Dev-mode warning:overlayBadge 只適用 iconOnly ──\n // 有 label 的 Button 傳入 overlayBadge 會被忽略(只 render icon / 不渲染 overlay slot),\n // 靜默忽略會讓 consumer 誤以為「傳了但位置錯」。Dev mode 印 warning 引導改用 `badge` prop\n // (inline 位置,跟 label 並列)或改 `iconOnly`。Spec SSOT:badge.spec.md「Overlay 適用元件」。\n if (process.env.NODE_ENV !== 'production' && overlayBadge && !iconOnly) {\n console.warn(\n '[DS Button] `overlayBadge` 只適用於 `iconOnly` Button。有 label 的 Button 請改用 `badge` prop(inline 位置,跟 label 並列),或移除 label 改為 iconOnly。SSOT:badge.spec.md「Overlay 適用元件 canonical」節。'\n )\n }\n\n // 2026-05-23 deep-audit Phase A.4 Decision 1(user verbatim「決策ㄧ照你建議做」):dev-warn `iconOnly + (endIcon\|badge)` 並用。\n // Spec SSOT:button.spec.md「iconOnly 嚴格定義為『只有一個 icon,正方形』,不可與 endIcon 或 badge 並用」。\n // 例外:overlayBadge 跟 iconOnly 並用 canonical(上方 overlayBadge 反向 warn 已 cover;相對指法,免行號漂移)。\n // 不擋 image canonical「icon + 下拉指示 = 不加 iconOnly + startIcon + endIcon + aria-label」(那 case iconOnly=false 不 trigger)。\n if (process.env.NODE_ENV !== 'production' && iconOnly && (EndIcon !== undefined \|\| badge != null)) {\n console.warn(\n '[DS Button] `iconOnly` 嚴格定義為「只有一個 icon,正方形」,不可與 `endIcon` 或 `badge` 並用。若需 icon + 下拉指示 → 不加 iconOnly + startIcon + endIcon + aria-label;若需 icon + 角標 → iconOnly + overlayBadge。SSOT:button.spec.md `iconOnly 的邊界` 節 + `badge.spec.md` Overlay 適用元件 canonical。'\n )\n }\n\n // shadcn compat:AlertDialog、Toast 等元件內部會傳入這些 alias,\n // 在此靜默轉換,不暴露到型別或自動完成。\n // dismiss=true 強制 variant=text(dismiss canonical);override 其他 variant 傳入。\n // 2026-06-06 預設 emphasis 改低(對齊世界級:MUI 預設 text / Ant 預設 default / Polaris 低 emphasis —\n // 預設 primary CTA 是 outlier)。labeled 無 variant → `tertiary`(中性外框,清楚可點性,再按重要程度升 primary);\n // iconOnly 無 variant → `text`(toolbar ghost,對齊 action-bar.spec.md「純動作工具/低重量輔助 → text」+\n // Material 3「icon-only = no fill」)。CTA 必 explicit `variant=\"primary\"`(不靠預設)。dismiss 仍強制 text。\n const resolvedVariant: InternalVariant =\n dismiss ? 'text' :\n (variantProp as string) === 'destructive' ? 'primary' :\n (variantProp as string) === 'ghost' ? 'text' :\n (variantProp as InternalVariant) ?? (iconOnly ? 'text' : 'tertiary')\n\n const resolvedDanger = dangerProp \|\| (variantProp as string) === 'destructive'\n\n // Dev-mode warning:danger 僅 primary / secondary / text 有 compoundVariant。\n // tertiary / link + danger 無匹配 compound → 靜默渲染成一般 tertiary / link(灰、無紅色\n // danger 視覺)— consumer 可能出「不紅的刪除鍵」而不自知。Spec SSOT:button.spec.md\n // 「禁止事項」danger 條(2026-07-14 deep-audit 補 warn,對齊既有 overlayBadge / iconOnly warn pattern)。\n if (process.env.NODE_ENV !== 'production' && resolvedDanger && (resolvedVariant === 'tertiary' \|\| resolvedVariant === 'link')) {\n console.warn(\n `[DS Button] \\`danger\\` 不支援 variant=\"${resolvedVariant}\"(無對應 compoundVariant,會靜默渲染成一般 ${resolvedVariant},無紅色 danger 視覺)。危險操作請改用 primary(立即不可逆)/ secondary(可反悔)/ text(低度)。SSOT:button.spec.md「禁止事項」danger 條。`\n )\n }\n\n // ButtonGroup context：vertical group 自動注入 fullWidth\n const groupCtx = React.useContext(ButtonGroupContext)\n const resolvedFullWidth = fullWidth \|\| !!groupCtx.fullWidth\n\n const Comp = asChild ? Slot : 'button'\n const iconSize = resolvedSize === 'lg' ? 20 : 16\n\n // loading 行為：spinner 永遠在 prefix 位置\n // 有 prefix icon → icon 換成 spinner（同位置，零 layout shift）\n // 無 prefix icon → spinner 加在文字左邊（按鈕略微變寬，可接受）\n const hasSuffix = badge != null \|\| EndIcon !== undefined\n\n // icon-only 自動 tooltip：從 props 提取 aria-label，同時保留在 DOM\n const { 'aria-label': ariaLabel, ...restProps } = props\n\n // Toggle 狀態：pressed 定義時自動寫入 aria-pressed + data-state。\n // 未定義時不寫入任何 toggle 屬性（按鈕為一般 action button）。\n // 樣式由 cva data-[state=on] compoundVariants（variant × pressedTone）套用——\n // secondary/tertiary/text 預設 pressedTone='emphasis' 走 primary-subtle，\n // pressedTone='neutral' 才走 neutral-selected family；primary/link 不定義 on 分支，傳入無效果。\n const toggleAttrs =\n pressed === undefined\n ? {}\n : { 'aria-pressed': pressed, 'data-state': pressed ? 'on' : 'off' }\n\n // Chrome-unbounded marker(2026-04-22 v5 canonical):button 若無視覺邊界(text variant 或 dismiss),\n // 標記 data-unbounded=\"true\"。SurfaceHeader 透過 [&_[data-unbounded]]:my-[...] 套負 margin\n // 讓 layout 佔位縮到 24(chrome-header-height 幾何)— button native size 與命中區不變\n // (命中 ≡ 可視,見 ds-canonical/references/hit-area-canonical.md;2026-09-24 把原文的\n // 「touch target」正名為命中區 —— 本 DS 以滑鼠精度為前提,尺寸不以觸控門檻推導)。\n // 詳 patterns/overlay-surface/overlay-chrome-sizing.spec.md「Chrome dismiss size canonical」(2026-09-27 自 overlay-surface.spec.md 拆出)\n const unboundedAttr =\n resolvedVariant === 'text' \|\| dismiss ? { 'data-unbounded': 'true' } : {}\n\n // Native path 內部結構:[loading spinner \| startIcon(+overlayBadge)] [label] [badge + endIcon]。\n // asChild 時不渲染(2026-07-04 fix):Radix Slot 規範 children 必為單一 element\n // (React.Children.only)— 內部多 expression children 變 array 必 runtime throw;\n // asChild 分支只 render consumer child,內容由 consumer 自帶。\n // 詳 CLAUDE.md 失敗記憶索引「asChild ? Slot : Native 內部 JSX 仍渲染多 children」條。\n const nativeChildren = (\n <>\n {loading ? (\n <CircularProgress size={iconSize} className=\"text-current\" />\n ) : StartIcon ? (\n resolvedIconOnly && overlayBadge ? (\n // Overlay badge canonical:wrapper 貼 icon 尺寸,badge 中心對齊 icon top-right corner\n // (Material BadgedBox / iOS App icon),不是 button chrome 角。\n //\n // CSS 細節(2026-04-20 bug fix):用 `inline-block` + 明確 width/height + `leading-none`\n // 避免 `inline-flex` span 在 Button flex container 內被撐高/撐寬(inline-flex 的 span\n // 在某些瀏覽器下會把絕對定位子元素的 translate 計算基準搞錯,造成 badge 噴飛、Button\n // aspect-square 失效)。明確給 span width/height = iconSize 鎖住 positioning context。\n <span\n className=\"relative inline-block leading-none shrink-0 pointer-events-none\"\n style={{ width: iconSize, height: iconSize }}\n >\n <StartIcon size={iconSize} aria-hidden />\n <span className=\"absolute top-0 right-0 translate-x-1/2 -translate-y-1/2 pointer-events-auto\">\n {overlayBadge}\n </span>\n </span>\n ) : (\n <StartIcon size={iconSize} aria-hidden />\n )\n ) : null}\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={iconSize} aria-hidden />}\n </span>\n )}\n </>\n )\n\n const sharedClassName = cn(\n buttonVariants({ variant: resolvedVariant, danger: resolvedDanger, size: resolvedSize, pressedTone, className }),\n // iconOnly 鐵律:padding-free + aspect-square + flex-center (Polaris idiom)\n // 0 magic-number 0 公式自動正方形。詳 ICON_ONLY_BASE rationale。\n resolvedIconOnly && ICON_ONLY_BASE,\n // Dismiss 視覺弱化:override Button text variant 預設 foreground 為 fg-muted → hover fg-secondary\n // 跟 Inline Action dismiss 視覺一致(cross-implementation dimming canonical)\n // 弱化 icon hover 一階(item-anatomy.tsx ItemInlineActionButton 同階梯 SSOT)\n dismiss && 'text-fg-muted hover:text-fg-secondary',\n // aria-disabled 的 dismiss hover 釘在 fg-muted(button.spec.md「狀態疊加」表 aria-disabled 列)\n dismiss && 'aria-disabled:hover:text-fg-muted',\n resolvedFullWidth && 'w-full',\n )\n\n // 2026-07-05 D4 修:asChild 原 silently drop loading/disabled 語意(無 aria-busy/aria-disabled/\n // click guard → <a> loading 期間可重複點擊)。補 ARIA(任何 element 合法;aria-disabled 自動點亮\n // cva 既有視覺)+ functional guard(APG aria-disabled 模式:語意+視覺由元件、功能阻斷由 guard)。\n const { onClick: slotConsumerOnClick, ...slotRest } = restProps as typeof restProps & { onClick?: React.MouseEventHandler<HTMLElement> }\n const buttonEl = asChild ? (\n // Slot 分支:children 必為單一 consumer element(React.Children.only),\n // 內部 slot(loading/startIcon/badge)不渲染;不硬塞 type/disabled(consumer child 可能是 <a>)。\n <Comp\n className={sharedClassName}\n ref={ref}\n aria-label={ariaLabel}\n aria-busy={loading \|\| undefined}\n aria-disabled={disabled \|\| loading \|\| undefined}\n onClick={disabled \|\| loading\n ? (e: React.MouseEvent<HTMLElement>) => { e.preventDefault(); e.stopPropagation() }\n : slotConsumerOnClick}\n {...toggleAttrs}\n {...unboundedAttr}\n {...slotRest}\n >\n {children}\n </Comp>\n ) : (\n <Comp\n className={sharedClassName}\n ref={ref}\n type=\"button\"\n disabled={disabled \|\| loading}\n aria-busy={loading \|\| undefined}\n aria-label={ariaLabel}\n {...toggleAttrs}\n {...unboundedAttr}\n {...restProps}\n >\n {nativeChildren}\n </Comp>\n )\n\n // icon-only + aria-label → 自動包 Tooltip（tooltip 是元件保證的行為）\n // 不建立獨立 TooltipProvider——依賴全域 Provider，\n // 這樣所有 tooltip 共享同一組 delay 參數和 warm-up 機制\n if (resolvedIconOnly && typeof ariaLabel === 'string' && !asChild) {\n return (\n <Tooltip>\n <TooltipTrigger asChild>{buttonEl}</TooltipTrigger>\n <TooltipContent>{ariaLabel}</TooltipContent>\n </Tooltip>\n )\n }\n\n return buttonEl\n }\n)\nButton.displayName = 'Button'\n\n/\n componentMeta — Story Auto-Compile 系統消費的結構化 canonical\n * (見 .claude/planning/story-auto-compile.md Phase 1)\n \n compile-stories.mjs 讀本 export + spec.md frontmatter 產出\n * anatomy.stories.tsx 的 variant/size/state/token 矩陣 canonical section。\n \n Keys 必跟 buttonVariants cva + spec frontmatter 對齊(compile-time 驗證)。\n /\nexport const buttonMeta = {\n component: 'Button',\n family: 3, // Pill Layout\n variants: {\n primary: { purpose: '主要 action / CTA' },\n secondary: { purpose: '次要 action(陪襯 primary)' },\n tertiary: { purpose: '第三級 action(tool-like)' },\n text: { purpose: '文字樣式 action(low emphasis / toolbar)' },\n link: { purpose: '內文連結(inline reading)' },\n },\n sizes: {\n xs: { fieldHeight: 24, iconSize: 16, typography: 'caption' },\n sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },\n md: { fieldHeight: 32, iconSize: 16, typography: 'body' },\n lg: { fieldHeight: 36, iconSize: 20, typography: 'body-lg' },\n },\n // 'pressed' = toggle on 持續態(data-[state=on],emphasis 淡藍底/neutral 灰底;2026-07-07 meta 詞彙統一補列)\n // 'loading' = CircularProgress spinner 取代 startIcon + aria-busy + click guard(2026-07-14 deep-audit\n // 補列,原漏 → auto-compile 生成矩陣缺 loading;對齊 anatomy StateBehavior Loading 行 + tsx loading 分支)\n states: ['default', 'hover', 'active', 'pressed', 'loading', 'focus-visible', 'disabled'],\n tokens: {\n // 2026-07-04 audit 補齊:原只列 primary variant 家族;按 buttonVariants cva 真實 class 補\n // secondary/tertiary/text/link/danger 消費的 token(auto-compile token 矩陣依此)。\n // 2026-07-14 deep-audit 二次補齊(掃 cva 全 bg- class):+ neutral-selected-hover / neutral-selected-active\n // (neutral pressedTone compound 消費)+ error / error-hover / error-active(primary+danger bg-error 系)\n bg: ['--primary', '--primary-hover', '--primary-active', '--primary-subtle', '--bg-disabled', '--surface', '--neutral-hover', '--neutral-active', '--neutral-selected', '--neutral-selected-hover', '--neutral-selected-active', '--error', '--error-hover', '--error-active'],\n fg: ['--on-emphasis', '--fg-disabled', '--foreground', '--primary', '--primary-hover', '--primary-active', '--error', '--error-hover', '--error-active'],\n ring: ['--ring'],\n },\n defaultVariant: 'tertiary', // 2026-06-10 修 stale:對齊 cva defaultVariants(2026-06-06 labeled 預設改 tertiary,meta 漏同步)\n defaultSize: 'md',\n} as const\n\nexport { Button, buttonVariants, ButtonGroupContext }\n"],"names":[],"mappings":";;;;;;;;AA0DA,MAAM,iBAAiB;AAAA,EACrB;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA;AAAA,IAEA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAgBA;AAAA,IACA;AAAA;AAAA;AAAA,IAGA;AAAA,EAAA;AAAA,EAEF;AAAA,IACE,UAAU;AAAA,MACR,SAAS;AAAA,QACP,SAAS;AAAA,UACP;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA;AAAA,UAIA;AAAA;AAAA;AAAA,UAGA;AAAA,UACA;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,WAAW;AAAA,UACT;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA,UAGA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA,QAAA;AAAA,QAIF,UAAU;AAAA,UACR;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,MAAM;AAAA,UACJ;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA,UAGA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA,QAAA;AAAA,QAEF,MAAM;AAAA,UACJ;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA,QAAA;AAAA,MACF;AAAA,MAEF,QAAQ;AAAA,QACN,MAAM;AAAA;AAAA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAWR,aAAa;AAAA,QACX,UAAU;AAAA,QACV,SAAS;AAAA,MAAA;AAAA,MAEX,MAAM;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,QACJ,IAAI;AAAA,MAAA;AAAA,IACN;AAAA,IAEF,kBAAkB;AAAA;AAAA,MAEhB;AAAA,QACE,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,OAAO;AAAA,UACL;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,QAAA;AAAA,MACF;AAAA;AAAA,MAGF;AAAA,QACE,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,OAAO;AAAA,UACL;AAAA,UACA;AAAA,UACA;AAAA;AAAA;AAAA,UAGA;AAAA,UACA;AAAA,UACA;AAAA,QAAA;AAAA,MACF;AAAA;AAAA,MAGF;AAAA,QACE,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,OAAO;AAAA,UACL;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,QAAA;AAAA,MACF;AAAA;AAAA;AAAA;AAAA;AAAA,MAMF;AAAA,QACE,SAAS,CAAC,aAAa,YAAY,MAAM;AAAA,QACzC,aAAa;AAAA,QACb,OAAO;AAAA,UACL;AAAA;AAAA;AAAA;AAAA,UAIA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA;AAAA;AAAA;AAAA,UAIA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,QAAA;AAAA,MACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,MAOF;AAAA,QACE,SAAS,CAAC,YAAY,MAAM;AAAA,QAC5B,aAAa;AAAA,QACb,OAAO;AAAA,UACL;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,UACA;AAAA;AAAA,UAEA;AAAA;AAAA,UAEA;AAAA,UACA;AAAA,QAAA;AAAA,MACF;AAAA;AAAA;AAAA;AAAA;AAAA,MAMF;AAAA,QACE,SAAS;AAAA,QACT,aAAa;AAAA,QACb,OAAO;AAAA;AAAA,UAEL;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,UACA;AAAA,QAAA;AAAA,MACF;AAAA,IACF;AAAA,IAEF,iBAAiB;AAAA;AAAA;AAAA,MAGf,SAAS;AAAA,MACT,MAAM;AAAA,MACN,aAAa;AAAA,IAAA;AAAA,EACf;AAEJ;AASA,MAAM,qBAAqB,MAAM,cAAuC,CAAA,CAAE;AAgG1E,MAAM,iBAAiB;AAGvB,MAAM,SAAS,MAAM;AAAA,EACnB,CACE;AAAA,IACE;AAAA,IACA,SAAS;AAAA,IACT,QAAQ;AAAA,IACR;AAAA,IACA,UAAU;AAAA,IACV,WAAW;AAAA,IACX;AAAA,IACA;AAAA,IACA,SAAS;AAAA,IACT,WAAW;AAAA,IACX,UAAU;AAAA,IACV,UAAU;AAAA,IACV,YAAY;AAAA,IACZ;AAAA,IACA;AAAA;AAAA,IACA;AAAA,IACA;AAAA,IACA,GAAG;AAAA,EAAA,GAEL,QACG;AAEH,UAAM,eAAe,qBAAqB,MAAM,IAAI;AAKpD,UAAM,mBAAmB,YAAY;AAMrC,QAAI,QAAQ,IAAI,aAAa,gBAAgB,gBAAgB,CAAC,UAAU;AACtE,cAAQ;AAAA,QACN;AAAA,MAAA;AAAA,IAEJ;AAMA,QAAI,QAAQ,IAAI,aAAa,gBAAgB,aAAa,YAAY,UAAa,SAAS,OAAO;AACjG,cAAQ;AAAA,QACN;AAAA,MAAA;AAAA,IAEJ;AASA,UAAM,kBACJ,UAAU,SACT,gBAA2B,gBAAgB,YAC3C,gBAA2B,UAAiB,SAC5C,gBAAoC,WAAW,SAAS;AAE3D,UAAM,iBAAiB,cAAe,gBAA2B;AAMjE,QAAI,QAAQ,IAAI,aAAa,gBAAgB,mBAAmB,oBAAoB,cAAc,oBAAoB,SAAS;AAC7H,cAAQ;AAAA,QACN,uCAAuC,eAAe,kCAAkC,eAAe;AAAA,MAAA;AAAA,IAE3G;AAGA,UAAM,WAAW,MAAM,WAAW,kBAAkB;AACpD,UAAM,oBAAoB,aAAa,CAAC,CAAC,SAAS;AAElD,UAAM,OAAO,UAAU,OAAO;AAC9B,UAAM,WAAW,iBAAiB,OAAO,KAAK;AAK9C,UAAM,YAAY,SAAS,QAAQ,YAAY;AAG/C,UAAM,EAAE,cAAc,WAAW,GAAG,cAAc;AAOlD,UAAM,cACJ,YAAY,SACR,KACA,EAAE,gBAAgB,SAAS,cAAc,UAAU,OAAO,MAAA;AAQhE,UAAM,gBACJ,oBAAoB,UAAU,UAAU,EAAE,kBAAkB,OAAA,IAAW,CAAA;AAOzE,UAAM,iBACJ,qBAAA,UAAA,EACG,UAAA;AAAA,MAAA,UACC,oBAAC,oBAAiB,MAAM,UAAU,WAAU,eAAA,CAAe,IACzD,YACF,oBAAoB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,QAQlB;AAAA,UAAC;AAAA,UAAA;AAAA,YACC,WAAU;AAAA,YACV,OAAO,EAAE,OAAO,UAAU,QAAQ,SAAA;AAAA,YAElC,UAAA;AAAA,cAAA,oBAAC,WAAA,EAAU,MAAM,UAAU,eAAW,MAAC;AAAA,cACvC,oBAAC,QAAA,EAAK,WAAU,+EACb,UAAA,aAAA,CACH;AAAA,YAAA;AAAA,UAAA;AAAA,QAAA;AAAA,8BAGD,WAAA,EAAU,MAAM,UAAU,eAAW,MAAC,IAEvC;AAAA,MACH,YAAY,QAAQ,oBAAC,QAAA,EAAK,WAAU,QAAQ,UAAS;AAAA,MACrD,aACC,qBAAC,QAAA,EAAK,WAAU,kCACb,UAAA;AAAA,QAAA;AAAA,QACA,WAAW,oBAAC,SAAA,EAAQ,MAAM,UAAU,eAAW,KAAA,CAAC;AAAA,MAAA,EAAA,CACnD;AAAA,IAAA,GAEJ;AAGF,UAAM,kBAAkB;AAAA,MACtB,eAAe,EAAE,SAAS,iBAAiB,QAAQ,gBAAgB,MAAM,cAAc,aAAa,WAAW;AAAA;AAAA;AAAA,MAG/G,oBAAoB;AAAA;AAAA;AAAA;AAAA,MAIpB,WAAW;AAAA;AAAA,MAEX,WAAW;AAAA,MACX,qBAAqB;AAAA,IAAA;AAMvB,UAAM,EAAE,SAAS,qBAAqB,GAAG,aAAa;AACtD,UAAM,WAAW;AAAA;AAAA;AAAA,MAGf;AAAA,QAAC;AAAA,QAAA;AAAA,UACC,WAAW;AAAA,UACX;AAAA,UACA,cAAY;AAAA,UACZ,aAAW,WAAW;AAAA,UACtB,iBAAe,YAAY,WAAW;AAAA,UACtC,SAAS,YAAY,UACjB,CAAC,MAAqC;AAAE,cAAE,eAAA;AAAkB,cAAE,gBAAA;AAAA,UAAkB,IAChF;AAAA,UACH,GAAG;AAAA,UACH,GAAG;AAAA,UACH,GAAG;AAAA,UAEH;AAAA,QAAA;AAAA,MAAA;AAAA,QAGH;AAAA,MAAC;AAAA,MAAA;AAAA,QACC,WAAW;AAAA,QACX;AAAA,QACA,MAAK;AAAA,QACL,UAAU,YAAY;AAAA,QACtB,aAAW,WAAW;AAAA,QACtB,cAAY;AAAA,QACX,GAAG;AAAA,QACH,GAAG;AAAA,QACH,GAAG;AAAA,QAEH,UAAA;AAAA,MAAA;AAAA,IAAA;AAOL,QAAI,oBAAoB,OAAO,cAAc,YAAY,CAAC,SAAS;AACjE,kCACG,SAAA,EACC,UAAA;AAAA,QAAA,oBAAC,gBAAA,EAAe,SAAO,MAAE,UAAA,UAAS;AAAA,QAClC,oBAAC,kBAAgB,UAAA,UAAA,CAAU;AAAA,MAAA,GAC7B;AAAA,IAEJ;AAEA,WAAO;AAAA,EACT;AACF;AACA,OAAO,cAAc;AAWd,MAAM,aAAa;AAAA,EACxB,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU;AAAA,IACR,SAAS,EAAE,SAAS,kBAAA;AAAA,IACpB,WAAW,EAAE,SAAS,wBAAA;AAAA,IACtB,UAAU,EAAE,SAAS,wBAAA;AAAA,IACrB,MAAM,EAAE,SAAS,sCAAA;AAAA,IACjB,MAAM,EAAE,SAAS,uBAAA;AAAA,EAAuB;AAAA,EAE1C,OAAO;AAAA,IACL,IAAI,EAAE,aAAa,IAAI,UAAU,IAAI,YAAY,UAAA;AAAA,IACjD,IAAI,EAAE,aAAa,IAAI,UAAU,IAAI,YAAY,OAAA;AAAA,IACjD,IAAI,EAAE,aAAa,IAAI,UAAU,IAAI,YAAY,OAAA;AAAA,IACjD,IAAI,EAAE,aAAa,IAAI,UAAU,IAAI,YAAY,UAAA;AAAA,EAAU;AAAA;AAAA;AAAA;AAAA,EAK7D,QAAQ,CAAC,WAAW,SAAS,UAAU,WAAW,WAAW,iBAAiB,UAAU;AAAA,EACxF,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA,IAKN,IAAI,CAAC,aAAa,mBAAmB,oBAAoB,oBAAoB,iBAAiB,aAAa,mBAAmB,oBAAoB,sBAAsB,4BAA4B,6BAA6B,WAAW,iBAAiB,gBAAgB;AAAA,IAC7Q,IAAI,CAAC,iBAAiB,iBAAiB,gBAAgB,aAAa,mBAAmB,oBAAoB,WAAW,iBAAiB,gBAAgB;AAAA,IACvJ,MAAM,CAAC,QAAQ;AAAA,EAAA;AAAA,EAEjB,gBAAgB;AAAA;AAAA,EAChB,aAAa;AACf;"}

package/dist/components/Calendar/calendar.d.ts CHANGED Viewed

@@ -32,7 +32,29 @@ export interface CalendarEvent {
     color?: CategoricalHue;
     metadata?: Record<string, unknown>;
 }
-export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+/** 日期格(整格 + 日期數字)可點與否。不單獨匯出:consumer 一律用 CalendarProps(root barrel 只列 CalendarProps / CalendarEvent)。 */
+type CalendarDateCellProps = {
+    /** 日期格唯讀:不可點、不亮、日期數字不是按鈕;鍵盤仍可在格陣內走動(焦點改停在格子本身)。 */
+    readOnlyDates?: false;
+    /** 點月 cell / 日期數字鈕回調(用於在這天新增)。日期格可點時**必填**:元件沒有內建的「新增」行為(spec「禁止事項」:不自動開表單)。 */
+    onDateClick: (date: Date) => void;
+} | {
+    /** 日期格唯讀:不可點、不亮、日期數字不是按鈕;鍵盤仍可在格陣內走動(焦點改停在格子本身)。宣告了就不可以傳 `onDateClick`。 */
+    readOnlyDates: true;
+    onDateClick?: never;
+};
+/** 事件方塊可點與否。同上,不單獨匯出;MonthEventTile 也吃這一份。 */
+type CalendarEventTileProps = {
+    /** 事件方塊唯讀:不可點、不亮、不是按鈕(只顯示事件,例如公司假日這類沒有詳情可開的標記)。 */
+    readOnlyEvents?: false;
+    /** 點 event tile 回調。事件方塊可點時**必填**:元件沒有內建的「打開事件」行為。 */
+    onEventClick: (event: CalendarEvent) => void;
+} | {
+    /** 事件方塊唯讀:不可點、不亮、不是按鈕(只顯示事件)。宣告了就不可以傳 `onEventClick`。 */
+    readOnlyEvents: true;
+    onEventClick?: never;
+};
+interface CalendarOwnProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
     /** 聚焦日期(月 view 的那個月) */
     referenceDate?: Date;
     defaultReferenceDate?: Date;
@@ -45,12 +67,13 @@ export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     today?: Date;
     /** 事件資料 */
     events?: CalendarEvent[];
-    /** 點 event tile 回調 */
-    onEventClick?: (event: CalendarEvent) => void;
-    /** 點月 cell 回調(用於新增) */
-    onDateClick?: (date: Date) => void;
-    /** 點新事件 CTA 回調 */
-    onCreateEvent?: () => void;
+    /**
+     * 右上角「新事件」CTA 的回調 —— 全域新增入口,恆渲染;日期能不能新增由新增流程自己擋,不由這顆鈕的有無表達
+     *(user 2026-09-29:「右上角那是全域新增,表示點了之後要先選了日期才能新增啊,那肯定會擋住不能新增的日期啊」)。
+     * 元件沒有內建的「新增」行為,所以必填:meta-patterns M23(f)—— 固定元素不以 callback 有無當渲染閘、
+     * 無內建 fallback 的 callback 必填。唯讀月曆(`readOnlyDates` / `readOnlyEvents`)一樣要傳。
+     */
+    onCreateEvent: () => void;
     /** 0 = Sunday, 1 = Monday。預設 0(對齊 Google Calendar 美系預設) */
     weekStartsOn?: 0 | 1;
     /** 自訂 event tile 渲染 */
@@ -64,9 +87,10 @@ export interface CalendarProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     /** 月份導覽 <nav> landmark 的 aria-label。Override for i18n. */
     navAriaLabel?: string;
     todayLabel?: string;
-    /** 「新事件」CTA 文字。Override for i18n。CTA 僅在傳 `onCreateEvent` 時渲染(spec Toolbar 段)。 */
+    /** 「新事件」CTA 文字。Override for i18n。CTA 是 toolbar 的固定元素、恆渲染(spec Toolbar 段;`onCreateEvent` 必填)。 */
     createLabel?: string;
 }
+export type CalendarProps = CalendarOwnProps & CalendarDateCellProps & CalendarEventTileProps;
 declare const Calendar: React.ForwardRefExoticComponent<CalendarProps & React.RefAttributes<HTMLDivElement>>;
 export declare const calendarMeta: {
     readonly component: "Calendar";
@@ -76,8 +100,8 @@ export declare const calendarMeta: {
     readonly states: readonly ["default", "hover", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly ["bg-muted", "bg-neutral-hover", "bg-info", "bg-surface"];
-        readonly fg: readonly ["text-fg-disabled", "text-fg-muted", "text-foreground"];
-        readonly ring: readonly ["ring-ring"];
+        readonly fg: readonly ["text-fg-muted", "text-foreground"];
+        readonly ring: readonly ["focus-ring-inset", "--ring"];
     };
 };
 export { Calendar };

package/dist/components/Calendar/calendar.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/components/Calendar/calendar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;~~AAe9B~~,OAAO,~~EAAyB~~,KAAK,cAAc,EAAE,MAAM,0CAA0C,CAAA;~~AAMrG~~;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;~~AAED~~,~~MAAM~~,~~WAAW~~,~~aAAc~~,~~SAAQ~~,~~IAAI~~,CAAC,KAAK,~~CAAC~~,~~cAAc~~,~~CAAC~~,~~cAAc~~,CAAC,EAAE,~~UAAU~~,~~CAAC~~;~~IAC3F~~,~~wBAAwB~~;~~IACxB~~,aAAa,~~CAAC,~~EAAE,IAAI,CAAA;~~IACpB~~,~~oBAAoB~~,CAAC,EAAE,~~IAAI~~,CAAA;~~IAC3B~~,~~qBAAqB~~,CAAC,EAAE,CAAC,~~IAAI~~,EAAE,~~IAAI~~,KAAK,IAAI,CAAA;~~IAC5C;;;;OAIG~~;~~IACH~~,~~KAAK~~,~~CAAC~~,EAAE,IAAI,CAAA;~~IAEZ~~,~~WAAW;IACX~~,~~MAAM,~~CAAC,EAAE,~~aAAa~~,~~EAAE,~~CAAA;~~IAExB~~,~~sBAAsB~~;~~IACtB~~,~~YAAY~~,~~CAAC~~,~~EAAE~~,CAAC,KAAK,EAAE,aAAa,~~KAAK~~,IAAI,CAAA;~~IAC7C~~,~~uBAAuB~~;~~IACvB~~,~~WAAW~~,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;~~IAClC~~,~~kBAAkB~~;~~IAClB~~,~~aAAa~~,CAAC,EAAE,MAAM,IAAI,CAAA;~~IAE1B~~,2DAA2D;IAC3D,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IAEpB,uBAAuB;IACvB,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,KAAK,CAAC,SAAS,CAAA;IAE3D,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,~~iFAAiF~~;~~IACjF~~,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;~~AAiFD~~,QAAA,MAAM,QAAQ,~~sFA+RZ~~,CAAA;AAKF,eAAO,MAAM,YAAY;;;;;;;;;;;CAgBf,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}
1	+ {"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../../src/components/Calendar/calendar.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAiB9B,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,0CAA0C,CAAA;AAMjH;;;;;;;;;;;;;;;;GAgBG;AAIH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACnC;AAUD,yGAAyG;AACzG,KAAK,qBAAqB,GACtB;IACE,mDAAmD;IACnD,aAAa,CAAC,EAAE,KAAK,CAAA;IACrB,gFAAgF;IAChF,WAAW,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;CAClC,GACD;IACE,0EAA0E;IAC1E,aAAa,EAAE,IAAI,CAAA;IACnB,WAAW,CAAC,EAAE,KAAK,CAAA;CACpB,CAAA;AAEL,8CAA8C;AAC9C,KAAK,sBAAsB,GACvB;IACE,mDAAmD;IACnD,cAAc,CAAC,EAAE,KAAK,CAAA;IACtB,qDAAqD;IACrD,YAAY,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;CAC7C,GACD;IACE,yDAAyD;IACzD,cAAc,EAAE,IAAI,CAAA;IACpB,YAAY,CAAC,EAAE,KAAK,CAAA;CACrB,CAAA;AAEL,UAAU,gBAAiB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,UAAU,CAAC;IACvF,wBAAwB;IACxB,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,oBAAoB,CAAC,EAAE,IAAI,CAAA;IAC3B,qBAAqB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAA;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,IAAI,CAAA;IAEZ,WAAW;IACX,MAAM,CAAC,EAAE,aAAa,EAAE,CAAA;IAExB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,IAAI,CAAA;IAEzB,2DAA2D;IAC3D,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IAEpB,uBAAuB;IACvB,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,KAAK,CAAC,SAAS,CAAA;IAE3D,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,qBAAqB,GAAG,sBAAsB,CAAA;AAiH7F,QAAA,MAAM,QAAQ,sFAugBZ,CAAA;AAKF,eAAO,MAAM,YAAY;;;;;;;;;;;CAgBf,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,CAAA"}