npm - @qijenchen/design-system - Versions diffs - 0.1.0-beta.80 → 0.1.0-beta.82 - Mend

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

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

package/dist/patterns/element-anatomy/item-anatomy.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"item-anatomy.js","sources":["../../../src/patterns/element-anatomy/item-anatomy.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 SSOT for Family 1+2 row primitives + all item-anatomy helpers(ItemContent / ItemIcon / ItemPrefix / ItemSuffix / ItemInlineAction 等),拆檔會讓 primitive 跨檔 import 滿天飛\nimport * as React from \"react\"\nimport type { LucideIcon } from \"lucide-react\"\nimport { cva } from \"class-variance-authority\"\nimport { cn } from \"@/lib/utils\"\nimport { Avatar, type AvatarProps } from \"@/design-system/components/Avatar/avatar\"\nimport {\n Tooltip,\n TooltipTrigger,\n TooltipContent,\n} from \"@/design-system/components/Tooltip/tooltip\"\n\n// ── InlineActionConfig ─────────────────────────────────────────────────────\n// 宣告式 API:consumer 只宣告 intent,host 根據 size tier 自動渲染。\n// 跨 Family 消費(Field family + Row family),SSOT 住 patterns/element-anatomy/\n// 對齊 inline-action.spec.md「API 設計」節。\n//\n// Canonical 實作:`ItemInlineAction`(本檔內)。\nexport interface InlineActionConfig {\n icon: LucideIcon\n /** aria-label,同時作為 tooltip 來源 /\n label: string\n /\n 點擊 handler。可選接收 React 事件物件——有需要時可呼叫 `stopPropagation()` 避免\n * 事件冒泡到父層(例如 Select 清除按鈕在 popover trigger 內,不想觸發 popover open)。\n /\n onClick: (e?: React.MouseEvent<HTMLButtonElement>) => void\n}\n\n/\n Item Layout — 共用工具與常數\n \n 這個檔案不是元件,是 `item-anatomy.spec.md` 的 code-level 實作。\n * 所有 row primitives(`MenuItem` / `TreeItem` / `SidebarMenuButton` /\n * `SelectionItem`)必須 import 本 module 的 ICON_SIZE 和 helpers,\n * 不要各自複製常數或 wrapper className——單一 source of truth,避免不一致。\n \n 詳細規則見 `item-anatomy.spec.md`。\n /\n\n// ── Types ──────────────────────────────────────────────────────────────────\n\n/* Row primitive 的 size 變體,對齊 `--field-height-` token family /\nexport type RowSize = \"sm\" \| \"md\" \| \"lg\"\n\n// ── Constants ──────────────────────────────────────────────────────────────\n\n/*\n Icon 尺寸(px)per row size。\n \n - sm / md: 16px(標準 row icon)\n * - lg: 20px(對齊 text-body-lg 的視覺重量)\n \n 用法:透過 Lucide icon 的 `size` prop 直接傳入,不要用 CSS `[&>svg]:size-`\n selector——當 icon 被包在 `<ItemPrefix>` 的 `h-[1lh]` wrapper 內時,\n * `>` 直接子選擇器會失效,Lucide icon 會 fallback 到預設 24px。\n \n ```tsx\n * import { ICON_SIZE } from \"@/design-system/patterns/element-anatomy/item-anatomy\"\n \n const iconPx = ICON_SIZE[size] // size: RowSize\n * <MyLucideIcon size={iconPx} />\n * ```\n /\nexport const ICON_SIZE: Record<RowSize, number> = {\n sm: 16,\n md: 16,\n lg: 20,\n}\n\n/\n Avatar 尺寸(px)per row size,分 inline / block 兩種模式。\n \n - inline(無 description,大宗情境)→ 對齊第一行 label,用 `h-[1lh]` 容器\n * sm: 20, md: 24, lg: 24\n * - block(有 description,avatar 跨越 label + desc 兩行)→ 對齊文字塊中心\n * sm: 32, md: 32, lg: 40\n \n 用法:所有 row primitive 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree\n * consumer)必須從本 module import 這個常數,不可硬寫 `size={24}`。\n * 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。\n \n ```tsx\n * import { AVATAR_SIZE } from \"@/design-system/patterns/element-anatomy/item-anatomy\"\n \n const { size } = useSidebar() // RowSize\n * <Avatar size={AVATAR_SIZE.inline[size]} />\n * ```\n \n Canonical 實作:`MenuItem` 的內部 `AVATAR_SIZE` 查表(即將 re-export 自此)。\n /\nexport const AVATAR_SIZE = {\n inline: { sm: 20, md: 24, lg: 24 },\n block: { sm: 32, md: 32, lg: 40 },\n} as const satisfies Record<\"inline\" \| \"block\", Record<RowSize, number>>\n\n/\n 回傳 uniform prefix slot 的 inline style(CSS variable form)。\n \n 用法:Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)\n * 把這個 style 套在 `style` prop 上(預先放在 `--mixed-prefix-slot` 候選位置,\n * 由外層 CSS `:has()` 條件化套到 `--item-prefix-slot`),子樹內所有 `<ItemPrefix>` /\n * `<ItemIcon>` / `<ItemAvatar>` 會自動用固定寬槽對齊。\n \n 槽寬 = `AVATAR_SIZE.inline[size]`(20/24/24 @ sm/md/lg)——以最大的 inline\n * prefix(avatar)為基準,icon 在槽內 `justify-center`。\n \n ```tsx\n * <ul style={getUniformPrefixSlotStyle(size)}>\n * <ItemIcon icon={Folder} /> ← 16px icon 在 24px 槽內置中\n * <ItemAvatar alt=\"GitHub\" /> ← 24px logo 填滿槽\n * </ul>\n * ```\n /\nexport function getUniformPrefixSlotStyle(size: RowSize): React.CSSProperties {\n return { \"--item-prefix-slot\": `${AVATAR_SIZE.inline[size]}px` } as React.CSSProperties\n}\n\n/\n Inline action(suffix 裡的 hover-action icon button)hover 背景尺寸(px)。\n * 規則:icon size + 2px(每邊 +1px,用 absolute positioning 溢出不影響排版)。\n * 對齊 `item-anatomy.spec.md`「Inline Action 設計規格」節。\n /\n// code-quality-allow: dead-export — public constant — DS API surface,consumer 可引(即使當前 internal-only)\nexport const INLINE_ACTION_HOVER_BG_SIZE: Record<RowSize, number> = {\n sm: 18,\n md: 18,\n lg: 22,\n}\n\n/\n `ROW_PADDING_BY_SIZE` — Family 1+2 row primitive 的 size → padding + typography 公式 SSOT\n \n Formula(canonical):`py = (field-height - 1lh) / 2`,對齊 1em text 到 field-height center。\n \n 消費者:menuItemVariants / sidebarMenuButtonVariants / treeItemVariants / 未來 row primitive\n * Rationale:前先 3 cva 各自寫同一公式 → drift risk(item-anatomy.spec 有明文「SidebarMenuButton\n * 獨立實作風險」)。抽本 export 後改一處全同步,risk 消失(對齊 Meta-Pattern M17「SSOT 必可傳播」)。\n \n 2026-04-24 D Phase 1+2 consolidation 建立。\n /\nexport const ROW_PADDING_BY_SIZE: Record<RowSize, string> = {\n sm: 'text-body leading-compact py-[calc((var(--field-height-sm)-1lh)/2)]',\n md: 'text-body leading-compact py-[calc((var(--field-height-md)-1lh)/2)]',\n lg: 'text-body-lg leading-compact py-[calc((var(--field-height-lg)-1lh)/2)]',\n}\n\n// ── Helper components ──────────────────────────────────────────────────────\n\n/\n `<ItemPrefix>` — Row primitive 的 prefix slot wrapper。\n \n 把 prefix(icon / avatar / checkbox / indicator)包進 `h-[1lh]` 容器,\n * 強制對齊第一行文字中線。這是 item-layout 的底層規則(詳見 spec「Prefix 垂直對齊」)。\n \n 為什麼:\n * - Row primitive 的 outer flex 是 `items-start`(多行 label 時 prefix 不飄移)\n * - 單行時 prefix 透過這個 wrapper 強制對齊第一行中線,視覺效果 = `items-center`\n * - 不同尺寸的 prefix(icon 16、Avatar 24、Checkbox 20)都能穩定置中\n \n 用法:\n * ```tsx\n * <div className=\"flex items-start gap-2\">\n * <ItemPrefix>\n * <Avatar size={24} />\n * </ItemPrefix>\n * <span className=\"min-w-0 flex-1 truncate\">{label}</span>\n * </div>\n * ```\n \n asChild 的 consumer(例如 `<SidebarMenuButton asChild>`)必須自己用這個 wrapper\n * 包 prefix,不能省略。\n /\nexport const ItemPrefix = React.forwardRef<\n HTMLSpanElement,\n React.HTMLAttributes<HTMLSpanElement>\n>(({ className, ...props }, ref) => (\n <span\n ref={ref}\n className={cn(\n \"h-[1lh] shrink-0 flex items-center\",\n // Uniform prefix slot:讀取 `--item-prefix-slot` CSS variable,\n // fallback `auto`(= 預設行為,不佔額外寬度、不 center)。\n // Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)\n // 若設定這個 var,小尺寸 prefix(icon 16px)會在固定寬槽(24px @ md)內置中,\n // 與大尺寸 prefix(app logo 24px)對齊,達成 label 齊左。\n // 詳見 item-anatomy.spec.md「Uniform prefix slot」節。\n \"min-w-[var(--item-prefix-slot,auto)] justify-center\",\n className\n )}\n {...props}\n />\n))\nItemPrefix.displayName = \"ItemPrefix\"\n\n/\n `itemPrefixAlignVariants` — Prefix 對齊高度的 cva SSOT(for 複雜 prefix 結構)。\n \n ── 存在的理由 ──\n * `<ItemPrefix>` primitive 預設單一 child(icon / avatar 任一)+ inline 對齊。\n * 但複雜 prefix 結構(e.g. MenuItem 可同時含 checkbox + icon/avatar 多 child)\n * 或block mode(大 prefix + description 對齊塊中心)需要自建 wrapper cva。\n * 本 cva 把 block formula SSOT 化,讓 MenuItem 等 consumer 共用,\n * 改值一處(token or cva)→ 所有 block-prefix consumer 同步。\n \n ── Align 變體(對齊 item-anatomy.spec.md「24px 閾值對齊規則」) ──\n * - `\"inline\"`:`h-[1lh]`,小 prefix(≤ 24px)對齊 label 第一行\n * - `\"block-sm\"` / `\"block-md\"`:大 prefix + scanning desc(sm/md menu),\n * 高度 = label(1lh) + gap(token) + desc(caption × 1.3)\n * - `\"block-lg\"`:大 prefix + scanning desc(lg menu),desc 改為 body × 1.3\n \n ── Consumer ──\n * MenuItem(inline / block-sm / block-md / block-lg)。其他 row primitive 簡單情境\n * 直接用 `<ItemPrefix>` 就好,不需此 cva。\n \n ── SSOT 傳播 ──\n * gap 用 `var(--item-gap-label-desc-scanning[-lg])` token(bare 變體已不存在,4 個 mode×size 變體);font-size 用 token-awareness\n * (`var(--font-caption-size)` / `var(--font-body-size)`)。改 token → 公式同步。\n /\n// code-quality-allow: long-function — cva variant/styles table — 拆 fn 會失去 type inference + 跨 fn 傳 config 反而難讀\nexport const itemPrefixAlignVariants = cva(\n \"flex items-center gap-2 shrink-0\",\n {\n variants: {\n align: {\n inline: \"h-[1lh]\",\n // sm/md desc = text-caption (12px × 1.3 = 15.6px)\n // block-sm / block-md:scanning mode(body + caption 組合)→ 用 scanning mode 專屬 gap token\n \"block-sm\":\n \"h-[calc(1lh+var(--item-gap-label-desc-scanning)+var(--font-caption-size)1.3)]\",\n \"block-md\":\n \"h-[calc(1lh+var(--item-gap-label-desc-scanning)+var(--font-caption-size)1.3)]\",\n // block-lg:scanning-lg mode(body-lg + body compact 組合)→ 用 scanning-lg mode 專屬 gap token\n \"block-lg\":\n \"h-[calc(1lh+var(--item-gap-label-desc-scanning-lg)+var(--font-body-size)1.3)]\",\n },\n },\n defaultVariants: {\n align: \"inline\",\n },\n }\n)\n\n/*\n `<ItemLabel>` — Row primitive 的 label span。\n \n 預設 `min-w-0 flex-1 truncate`——單行截斷,佔滿剩餘 flex 空間。\n * 加 `data-sidebar=\"menu-label\"` attribute 讓 sidebar icon 模式的 CSS selector 能命中。\n \n 用法:\n * ```tsx\n * <ItemLabel>{label}</ItemLabel>\n * ```\n /\nexport const ItemLabel = React.forwardRef<\n HTMLSpanElement,\n React.HTMLAttributes<HTMLSpanElement>\n>(({ className, ...props }, ref) => (\n <span\n ref={ref}\n data-sidebar=\"menu-label\"\n className={cn(\"min-w-0 flex-1 truncate\", className)}\n {...props}\n />\n))\nItemLabel.displayName = \"ItemLabel\"\n\n/\n `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。\n \n ── 存在的唯一理由 ──\n * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc-<mode>[-lg])]` gap」結構,\n * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。\n \n ── Consumer 偏離 canonical ──\n * 消費端若有確切合理理由不用 `<ItemContent>` / 需自訂 label/desc 行為,必在\n * 該元件 `spec.md` 明文寫下 rationale(對齊 item-anatomy canonical「偏離必明文」)。\n * 合法偏離範例:\n * - MenuItem 的 `leading-compact + text-caption` scanning-mode typography\n * → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc-scanning[-lg]` token 直接用\n * - SelectionItem 的 control slot 跟 block formula 綁定\n * → SelectionItem spec 明文 rationale\n \n ── Props ──\n * - `label`:label 內容(ReactNode,必填)\n * - `description`:description 內容(ReactNode,optional)\n * - `mode`:typography tier(scanning vs reading,世界級對齊 Material `dense` / Carbon `size` / Ant `size`)\n * - `\"reading\"`(預設):繼承 parent `text-body`(14px / 1.5 leading),舒適閱讀(Family 2 / Material body-large 派)\n * - `\"scanning\"`:desc 縮為 `text-caption`(12px)+ `leading-compact`(1.3),緊湊掃視\n * (Family 1 Menu item / Material body-medium dense 派)\n * - `descriptionTone`:desc 顏色語意\n * - `\"secondary\"`(預設):`text-fg-secondary`\n * - `\"error\"`:`text-error-text`\n * - `\"muted\"`:`text-fg-muted`\n * - `\"disabled\"`:`text-fg-disabled`(對齊 M24 state precedence:disabled > muted > emphasis)\n * - `descriptionWrap`:desc 多行 wrap(預設 true)/ false = truncate\n * - `labelClassName` / `descriptionClassName`:escape hatches(明文 rationale 才用)\n \n ── World-class benchmark ──\n * 6 家 DS(Material / Polaris / Atlassian / Apple HIG / Carbon / Ant)一致用\n * 14/20 vs 16/24 兩擋 body 表達 scanning vs reading。API 兩派:(A)密度 prop\n * Material `dense` / Carbon `size` / Ant `size`(本 DS 採 A 派);(B)typography\n * token 手選 Polaris / Atlassian / Apple。\n /\n\nexport interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivElement>, \"title\"> {\n label: React.ReactNode\n description?: React.ReactNode\n /\n Typography mode — leading 行為(跟 size 正交的另一維):\n * - `\"reading\"`(預設):default leading(1.5)— Family 2 List item 舒適閱讀\n * - `\"scanning\"`:`leading-compact`(1.3)+ desc 降一 tier —— Menu item / Step 掃視\n /\n mode?: \"reading\" \| \"scanning\"\n /\n Size tier — label 字級(跟 mode 正交的另一維):\n * - `\"md\"`(預設):label `text-body`(14)\n * - `\"lg\"`:label `text-body-lg`(16)— desc 永遠比 label 小一 tier(body)\n \n 2 × 2 = 4 typography 組合,對應 4 tokens:\n * - md + reading → body(14/1.5) + body(14/1.5)\n * - md + scanning → body(14/1.3) + caption(12/1.3)\n * - lg + reading → body-lg(16/1.5) + body(14/1.5)\n * - lg + scanning → body-lg(16/1.3) + body(14/1.3)\n /\n size?: \"md\" \| \"lg\"\n descriptionTone?: \"secondary\" \| \"error\" \| \"muted\" \| \"disabled\"\n descriptionWrap?: boolean\n /\n Description 多行截斷(line-clamp-N)。undefined = 不 clamp(自由 wrap)。\n * Tailwind line-clamp utilities 支援 1-6。\n /\n descriptionClamp?: number\n /\n Description `break-words`(default `false`,僅在 consumer 需要時 opt-in)。\n * 使用情境:SelectionItem / Steps 這類 description 可能塞長英文 token 需 break。\n /\n descriptionBreakWords?: boolean\n /\n Label truncate (default `true`, 對齊 row-item 大宗 idiom)。\n * Opt-out(`false`)for card-like consumers(e.g. ProfileCard label 允許 wrap)。\n * World-class 對照:Material `ListItemText primaryTypographyProps.noWrap` default true。\n /\n labelTruncate?: boolean\n labelClassName?: string\n descriptionClassName?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nexport const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(\n (\n {\n label,\n description,\n mode = \"reading\",\n size = \"md\",\n descriptionTone = \"secondary\",\n descriptionWrap = true,\n descriptionClamp,\n descriptionBreakWords = false,\n labelTruncate = true,\n labelClassName,\n descriptionClassName,\n className,\n ...props\n },\n ref,\n ) => {\n const toneClass = {\n secondary: \"text-fg-secondary\",\n error: \"text-error-text\",\n muted: \"text-fg-muted\",\n disabled: \"text-fg-disabled\",\n }[descriptionTone]\n\n // Typography desc class — 2 維 cross-product (mode × size):\n // ┌───────────┬────────────────────────────┬────────────────────────────┐\n // │ │ size=\"md\"(body label 14) │ size=\"lg\"(body-lg label 16)│\n // ├───────────┼────────────────────────────┼────────────────────────────┤\n // │ reading │ 繼承 body(14/1.5) │ body(14)default leading │\n // │ scanning │ caption(12)+ compact │ body(14)+ compact │\n // └───────────┴────────────────────────────┴────────────────────────────┘\n const isLg = size === \"lg\"\n const modeClass =\n mode === \"scanning\"\n ? isLg\n ? \"text-[length:var(--font-body-size)] leading-compact\"\n : \"text-[length:var(--font-caption-size)] leading-compact\"\n : isLg\n ? \"text-[length:var(--font-body-size)]\"\n : \"\"\n\n const clampClass = descriptionClamp ? `line-clamp-${descriptionClamp}` : \"\"\n\n return (\n <div\n ref={ref}\n className={cn(\"flex flex-col min-w-0 flex-1\", className)}\n {...props}\n >\n <span className={cn(labelTruncate && \"truncate\", labelClassName)}>{label}</span>\n {description && (\n <span\n className={cn(\n // Typography-mode-aware gap token(2026-04-23):\n // (mode, size)2 維正交 → 4 token 對應 4 typography 組合\n mode === \"scanning\"\n ? isLg\n ? \"mt-[var(--item-gap-label-desc-scanning-lg)]\"\n : \"mt-[var(--item-gap-label-desc-scanning)]\"\n : isLg\n ? \"mt-[var(--item-gap-label-desc-reading-lg)]\"\n : \"mt-[var(--item-gap-label-desc-reading)]\",\n modeClass,\n toneClass,\n clampClass,\n descriptionBreakWords && \"break-words\",\n !descriptionWrap && \"truncate\",\n descriptionClassName,\n )}\n >\n {description}\n </span>\n )}\n </div>\n )\n },\n)\nItemContent.displayName = \"ItemContent\"\n\n// ── Row size context ──────────────────────────────────────────────────────\n//\n// 作用:讓 row primitive(Sidebar / SelectMenu / Tree / DropdownMenu)只 propagate\n// 一次 size,整個子樹內的 <ItemIcon> / <ItemAvatar> 都自動查到正確尺寸。\n//\n// 存在的唯一理由:消除 asChild pattern 下 consumer 硬寫 `size={24}` 的可能性。\n// 過去 consumer 必須 `useSidebar().size` 再手動傳 `AVATAR_SIZE.inline[size]`,\n// 每個 consumer 都是一次漂移機會(曾發生:sm 欄 avatar 顯示 24 而非 20,破壞規格)。\n// 現在 consumer 只寫 `<ItemAvatar alt=\"...\" />`,尺寸由 context 自動決定。\n//\n// Row primitive 實作者的責任:在元件內部用 `<RowSizeProvider value={size}>` 包裹\n// children(不論 asChild 或非 asChild 路徑),這樣任何 descendant 的 ItemIcon /\n// ItemAvatar 都會拿到正確尺寸。\n\nconst RowSizeContext = React.createContext<RowSize \| null>(null)\n\n/* @internal — L3 row-size primitive;app code 不直接 import,由 MenuItem/Row/Field 等內部消費(inline-action.spec.md)。 /\nexport const RowSizeProvider = RowSizeContext.Provider\n\n/\n 讀取當前 row size。在 row primitive 子樹外呼叫會回 fallback(預設 \"md\")。\n * Row primitive 實作者不該呼叫這個——你們已經知道自己的 size。\n * 這個 hook 是給 `<ItemIcon>` / `<ItemAvatar>` 和 asChild consumer 的逃生艙用。\n /\nexport function useRowSize(fallback: RowSize = \"md\"): RowSize {\n return React.useContext(RowSizeContext) ?? fallback\n}\n\n// ── Prefab prefix elements ────────────────────────────────────────────────\n//\n// `<ItemIcon>` 和 `<ItemAvatar>` 是「prefix slot 的完成品元件」——自帶 ItemPrefix\n// wrapper + 自動查 ICON_SIZE / AVATAR_SIZE。\n//\n// asChild consumer 必須用這兩個元件,禁止手動寫 `<Avatar size={N} />`。\n// 禁令理由見 item-anatomy.spec.md「Avatar 尺寸選擇」節。\n\nexport interface ItemIconProps\n extends Omit<React.SVGAttributes<SVGSVGElement>, \"children\"> {\n /* Lucide icon 元件(不是 JSX element) /\n icon: LucideIcon\n}\n\n/\n `<ItemIcon icon={Folder} />` — 自動查 `ICON_SIZE[rowSize]`,包在 `ItemPrefix` 內。\n * 永遠對齊第一行 label(item-layout 的 icon 永遠 inline)。\n /\nexport const ItemIcon = React.forwardRef<SVGSVGElement, ItemIconProps>(\n ({ icon: Icon, className, ...props }, ref) => {\n const size = useRowSize()\n return (\n // data-prefix-type=\"icon\" 讓 row-primitive 容器的 `:has()` selector 能偵測類型,\n // 用於 `<SidebarProvider uniformPrefix>` opt-in 後的混用 auto-detection\n <ItemPrefix data-prefix-type=\"icon\">\n <Icon\n ref={ref}\n size={ICON_SIZE[size]}\n className={cn(\"shrink-0\", className)}\n aria-hidden\n {...props}\n />\n </ItemPrefix>\n )\n }\n)\nItemIcon.displayName = \"ItemIcon\"\n\nexport interface ItemAvatarProps extends Omit<AvatarProps, \"size\"> {\n /\n 對齊模式(選填,預設 `\"inline\"`):\n * - `\"inline\"`:視覺重量輕的 avatar,對齊第一行 label(20/24/24 @ sm/md/lg)\n * - `\"block\"`:視覺重量重的 avatar,對齊 label + description 文字塊(32/32/40 @ sm/md/lg)\n \n 預設 inline——大宗情境(扁平 row、footer user、主清單)都用這個。\n * 只有 avatar 是 item 主體(人物卡、顯著身份辨識)才用 block。\n \n 詳見 `item-anatomy.spec.md`「Avatar 尺寸選擇」節,含 24px 對齊模式閾值規則。\n /\n mode?: \"inline\" \| \"block\"\n}\n\n/\n `<ItemAvatar alt=\"Alan\" color=\"blue\" />` — 自動查 `AVATAR_SIZE[mode][rowSize]`,\n * 包在 `ItemPrefix` 內。\n \n asChild consumer 的標準用法——不需知道 size,不需 import AVATAR_SIZE,\n * 不可能硬寫錯誤尺寸。\n /\n// code-quality-allow: long-function — forwardRef body 含 size×color×hoverCard 三正交 prop 渲染分流,拆出 sub-fn 反增 prop drilling\nexport const ItemAvatar = React.forwardRef<HTMLDivElement, ItemAvatarProps>(\n ({ mode = \"inline\", ...props }, ref) => {\n const size = useRowSize()\n return (\n // data-prefix-type=\"avatar\" 讓 row-primitive 容器的 `:has()` selector 能偵測類型,\n // 用於 `<SidebarProvider uniformPrefix>` opt-in 後的混用 auto-detection\n <ItemPrefix data-prefix-type=\"avatar\">\n <Avatar ref={ref} size={AVATAR_SIZE[mode][size]} {...props} />\n </ItemPrefix>\n )\n }\n)\nItemAvatar.displayName = \"ItemAvatar\"\n\n// ── Inline action (suffix slot) ───────────────────────────────────────────\n//\n// 共用 row-primitive 的 suffix inline action 渲染——消除過去 Input / NumberInput /\n// Tag / LinkInput / Combobox 各自複製 18 行 JSX 的狀況(見 `item-anatomy.spec.md`\n// 「Inline Action 設計規格」節)。\n//\n// 規格(完全對齊 item-anatomy.spec.md「Inline Action 設計規格」節):\n// - Icon 尺寸 = ICON_SIZE[rowSize] (16/16/20)\n// - Hover bg 尺寸 = icon + 2 (18/18/22,INLINE_ACTION_HOVER_BG_SIZE)\n// - Hover bg 圓角 = rounded-md (sm/md)/ rounded-md (lg)\n// - Icon 顏色:fg-muted → foreground on hover/active\n// - 必須 <button type=\"button\">,aria-label = label,Tooltip(同 label)\n// - cursor-pointer\n\n// ── Low-level:ItemInlineActionButton ──\n//\n// Root 是 `<button>`(不是 Tooltip wrapper),可直接塞進 Radix `asChild` pattern\n// 例如 `<Collapsible.Trigger asChild>`, `<Popover.Trigger asChild>` 等。\n//\n// 自動從 `RowSizeContext` 查:\n// - 寬高 = ICON_SIZE[size]\n// - Hover bg 尺寸 = INLINE_ACTION_HOVER_BG_SIZE[size]\n// - Hover bg 圓角 = rounded-md (sm/md) / rounded-md (lg)\n// - Icon color = fg-muted → foreground on hover/active\n//\n// 接受任何 button props 並 spread(讓 Radix Slot 可以 merge onClick / data-state 等)\n\nexport interface ItemInlineActionButtonProps\n extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, \"children\"> {\n /* Lucide icon 元件 /\n icon: LucideIcon\n /* 可選:額外加在 icon 上的 className(例如 rotate transition) /\n iconClassName?: string\n /\n Size 明確覆寫(用於 fields / Tag 等不在 `RowSizeProvider` 樹內的 host):\n * 傳了就以此為準,否則從 `RowSizeContext` 讀(fallback \"md\")。\n \n 使用時機:\n * - Row primitive 子樹(Sidebar / TreeView / SelectMenu / DropdownMenu)→ 不傳,吃 context\n * - Field / Tag(自有 size 系統,沒包 RowSizeProvider)→ 必傳 `size={hostSize}`\n /\n size?: RowSize\n /\n Hover / active bg className override(chromatic host 專用,如 Tag solid variant)。\n \n 預設 `group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active`。\n * 提供後完全取代 hover + active 雙態 className,但不影響 rest 態(永遠 bg-transparent)\n * 與 overlay-trigger 態(`group-data-[state=open]/action:bg-neutral-hover` — 維持 host hover bg)。\n \n Consumer 須同時包含 hover + active 兩態 selector,例:\n * `'group-hover/action:bg-[var(--my-hover)] group-active/action:bg-[var(--my-active)]'`\n \n Use case:Tag solid(blue/green/red 等)需 hover bg 跟 host 色相一致(非 neutral)。\n /\n hoverBgClassName?: string\n /\n 標記本 button 是 overlay trigger(DropdownMenu / Popover / Tooltip 透過 `asChild` 包覆)。\n \n `true` 時:Radix overlay open 期間(`data-state=\"open\"`)button 維持 host hover 樣式\n * — 視覺鎖,讓 user 追溯 floating panel 來源(對齊 shadcn / Radix Themes / Material)。\n \n `false` 時(default):無 data-state=open 樣式 — 適用 in-place 互動如 `Collapsible.Trigger`\n * (展開內容接在 trigger 下方,不需追溯)、drag handle、dismiss X 等。\n \n Canonical 詳 `inline-action.spec.md`「Overlay trigger canonical」段。\n \n @default false\n /\n overlayTrigger?: boolean\n}\n\n/* @internal — L3 inline-action primitive;app code 禁直接 import,經 MenuItem/Row endActions 消費(inline-action.spec.md)。 /\nexport const ItemInlineActionButton = React.forwardRef<\n HTMLButtonElement,\n ItemInlineActionButtonProps\n>(({ icon: Icon, className, iconClassName, style, type = \"button\", size: sizeProp, hoverBgClassName, overlayTrigger = false, ...rest }, ref) => {\n const contextSize = useRowSize()\n const size = sizeProp ?? contextSize\n const iconPx = ICON_SIZE[size]\n const hoverBgPx = INLINE_ACTION_HOVER_BG_SIZE[size]\n return (\n <button\n ref={ref}\n type={type}\n className={cn(\n \"group/action relative grid place-content-center shrink-0 cursor-pointer\",\n \"text-fg-muted hover:text-foreground active:text-foreground transition-colors\",\n // Overlay trigger active state — 只在 consumer 顯式宣告 overlayTrigger=true 時生效\n // (canonical 2026-05-05:Collapsible / drag / dismiss 等 in-place 互動 ≠ overlay,\n // 不應 leak 視覺 lock。詳 inline-action.spec.md「Overlay trigger canonical」)\n overlayTrigger && \"data-[state=open]:text-foreground\",\n \"focus-visible:outline-2 focus-visible:outline-ring\",\n className\n )}\n style={{ width: iconPx, height: iconPx, ...style }}\n {...rest}\n >\n <span\n aria-hidden\n className={cn(\n \"absolute pointer-events-none\",\n \"rounded-md\",\n \"bg-transparent\",\n hoverBgClassName ?? \"group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active\",\n // Overlay 開啟 = 維持 host hover bg(只在 overlayTrigger=true 時生效)\n overlayTrigger && \"group-data-[state=open]/action:bg-neutral-hover\",\n \"transition-colors\"\n )}\n style={{\n width: hoverBgPx,\n height: hoverBgPx,\n top: \"50%\",\n left: \"50%\",\n transform: \"translate(-50%, -50%)\",\n }}\n />\n <Icon size={iconPx} className={cn(\"relative\", iconClassName)} aria-hidden />\n </button>\n )\n})\nItemInlineActionButton.displayName = \"ItemInlineActionButton\"\n\n// ── High-level:ItemInlineAction ──\n//\n// 宣告式 API:consumer 給 `{ icon, label, onClick }`,元件自動處理 Tooltip +\n// aria-label。適用於 row primitive 的 suffix slot(SidebarMenuButton inlineActions 等)。\n//\n// 內部用 `ItemInlineActionButton`——兩層共用同一套視覺規格、同一個 RowSizeContext 查表。\n// 需要接 Radix asChild(例如 collapsible trigger)時改用 `ItemInlineActionButton`,\n// 那層沒有 Tooltip 包裝,Root 就是 button,可直接塞進 Radix Slot。\n\nexport interface ItemInlineActionProps {\n action: InlineActionConfig\n /* Size 覆寫(見 `ItemInlineActionButtonProps.size`)——Field Controls / Tag 必傳 /\n size?: RowSize\n}\n\n/* @internal — L3 inline-action primitive;app code 禁直接 import,經 row 元件消費(inline-action.spec.md)。 /\nexport const ItemInlineAction = React.forwardRef<\n HTMLButtonElement,\n ItemInlineActionProps\n>(({ action, size }, ref) => (\n <Tooltip>\n <TooltipTrigger asChild>\n <ItemInlineActionButton\n ref={ref}\n icon={action.icon}\n aria-label={action.label}\n onClick={action.onClick}\n size={size}\n />\n </TooltipTrigger>\n <TooltipContent>{action.label}</TooltipContent>\n </Tooltip>\n))\nItemInlineAction.displayName = \"ItemInlineAction\"\n\n// ── Item suffix slot ──────────────────────────────────────────────────────\n//\n// `<ItemSuffix>` — row primitive 的 suffix 容器。對齊 item-layout spec:\n// - `h-[1lh]`:suffix 永遠對齊第一行 label(跟 prefix 解耦)\n// - `ml-auto`:靠右\n// - `gap-2`:多個 inline action 之間的標準間距(item-anatomy.spec.md「Inline Action 設計規格」節)\n// - `hoverReveal` opt-in:opacity 0→1 on 父層 row hover/focus-visible\n//\n// `hoverGroup`(2026-05-05 v8 SSOT 升級):row primitive group selector 參數化。\n// 先前 `/menu-item` hardcode → TreeView(`/tree-item`)/ FileItem(`/row`)/\n// DataTable(`/row`)無法消費,被迫自刻 suffix slot(M1 違反)。\n// 參數化後 4 個 row primitive 都走同一條 SSOT。Tailwind JIT 需 static class,\n// 故用 lookup table 而非動態字串(避免 JIT scan 失敗)。\n\nconst SUFFIX_HOVER_REVEAL_BY_GROUP = {\n \"menu-item\":\n \"opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150\",\n \"tree-item\":\n \"opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150\",\n row: \"opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150\",\n} as const\n\nexport type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP\n\nexport interface ItemSuffixProps extends React.HTMLAttributes<HTMLSpanElement> {\n /\n Hover-reveal:預設隱藏,父層 row hover / keyboard focus-visible 時才淡入。\n * 對齊 TreeView / SidebarMenuButton inline action 行為。預設 false(永遠顯示,如 Badge)。\n \n 用 `group-has-[:focus-visible]` 而非 `group-focus-within`——後者會被 mouse click 觸發,\n * 導致 click 後 suffix 永久顯示直到焦點移走。focus-visible 只在鍵盤 tab 時啟動。\n /\n hoverReveal?: boolean\n /\n 父層 row 的 group selector(consumer 必加 `group/<name>` 到 row wrapper)。\n * 預設 `'menu-item'`(對齊 MenuItem / Sidebar)。其他 row primitive:\n * `'tree-item'`(TreeView)/ `'row'`(DataTable / FileItem)。\n \n 加新 row primitive(且需 hover-reveal)時:在 `SUFFIX_HOVER_REVEAL_BY_GROUP`\n * 加 entry,Tailwind JIT 才能 scan 到 static class。\n */\n hoverGroup?: ItemSuffixHoverGroup\n}\n\nexport const ItemSuffix = React.forwardRef<HTMLSpanElement, ItemSuffixProps>(\n ({ className, hoverReveal = false, hoverGroup = \"menu-item\", ...props }, ref) => (\n <span\n ref={ref}\n className={cn(\n \"h-[1lh] shrink-0 ml-auto flex items-center gap-2\",\n hoverReveal && SUFFIX_HOVER_REVEAL_BY_GROUP[hoverGroup],\n className\n )}\n {...props}\n />\n )\n)\nItemSuffix.displayName = \"ItemSuffix\"\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"item-anatomy.js","sources":["../../../src/patterns/element-anatomy/item-anatomy.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 SSOT for Family 1+2 row primitives + all item-anatomy helpers(ItemContent / ItemIcon / ItemPrefix / ItemSuffix / ItemInlineAction 等),拆檔會讓 primitive 跨檔 import 滿天飛\nimport * as React from \"react\"\nimport type { LucideIcon } from \"lucide-react\"\nimport { cva } from \"class-variance-authority\"\nimport { cn } from \"@/lib/utils\"\nimport { Avatar, type AvatarProps } from \"@/design-system/components/Avatar/avatar\"\nimport {\n Tooltip,\n TooltipTrigger,\n TooltipContent,\n} from \"@/design-system/components/Tooltip/tooltip\"\n\n// ── InlineActionConfig ─────────────────────────────────────────────────────\n// 宣告式 API:consumer 只宣告 intent,host 根據 size tier 自動渲染。\n// 跨 Family 消費(Field family + Row family),SSOT 住 patterns/element-anatomy/\n// 對齊 inline-action.spec.md「API 設計」節。\n//\n// Canonical 實作:`ItemInlineAction`(本檔內)。\nexport interface InlineActionConfig {\n icon: LucideIcon\n /** aria-label,同時作為 tooltip 來源 /\n label: string\n /\n 點擊 handler。可選接收 React 事件物件——有需要時可呼叫 `stopPropagation()` 避免\n * 事件冒泡到父層(例如 Select 清除按鈕在 popover trigger 內,不想觸發 popover open)。\n /\n onClick: (e?: React.MouseEvent<HTMLButtonElement>) => void\n}\n\n/\n Item Layout — 共用工具與常數\n \n 這個檔案不是元件,是 `item-anatomy.spec.md` 的 code-level 實作。\n * 所有 row primitives(`MenuItem` / `TreeItem` / `SidebarMenuButton` /\n * `SelectionItem`)必須 import 本 module 的 ICON_SIZE 和 helpers,\n * 不要各自複製常數或 wrapper className——單一 source of truth,避免不一致。\n \n 詳細規則見 `item-anatomy.spec.md`。\n /\n\n// ── Types ──────────────────────────────────────────────────────────────────\n\n/* Row primitive 的 size 變體,對齊 `--field-height-` token family /\nexport type RowSize = \"sm\" \| \"md\" \| \"lg\"\n\n// ── Constants ──────────────────────────────────────────────────────────────\n\n/*\n Icon 尺寸(px)per row size。\n \n - sm / md: 16px(標準 row icon)\n * - lg: 20px(對齊 text-body-lg 的視覺重量)\n \n 用法:透過 Lucide icon 的 `size` prop 直接傳入,不要用 CSS `[&>svg]:size-`\n selector——當 icon 被包在 `<ItemPrefix>` 的 `h-[1lh]` wrapper 內時,\n * `>` 直接子選擇器會失效,Lucide icon 會 fallback 到預設 24px。\n \n ```tsx\n * import { ICON_SIZE } from \"@/design-system/patterns/element-anatomy/item-anatomy\"\n \n const iconPx = ICON_SIZE[size] // size: RowSize\n * <MyLucideIcon size={iconPx} />\n * ```\n /\nexport const ICON_SIZE: Record<RowSize, number> = {\n sm: 16,\n md: 16,\n lg: 20,\n}\n\n/\n Avatar 尺寸(px)per row size,分 inline / block 兩種模式。\n \n - inline(無 description,大宗情境)→ 對齊第一行 label,用 `h-[1lh]` 容器\n * sm: 20, md: 24, lg: 24\n * - block(有 description,avatar 跨越 label + desc 兩行)→ 對齊文字塊中心\n * sm: 32, md: 32, lg: 40\n \n 用法:所有 row primitive 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree\n * consumer)必須從本 module import 這個常數,不可硬寫 `size={24}`。\n * 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。\n \n ```tsx\n * import { AVATAR_SIZE } from \"@/design-system/patterns/element-anatomy/item-anatomy\"\n \n const { size } = useSidebar() // RowSize\n * <Avatar size={AVATAR_SIZE.inline[size]} />\n * ```\n \n Canonical 消費者:MenuItem 直接 import 本檔 `AVATAR_SIZE`(menu-item.tsx,消費 .block/.inline;re-export 已完成,MenuItem 無內部查表)。\n /\nexport const AVATAR_SIZE = {\n inline: { sm: 20, md: 24, lg: 24 },\n block: { sm: 32, md: 32, lg: 40 },\n} as const satisfies Record<\"inline\" \| \"block\", Record<RowSize, number>>\n\n/\n 回傳 uniform prefix slot 的 inline style(CSS variable form)。\n \n 用法:Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)\n * 把這個 style 套在 `style` prop 上(預先放在 `--mixed-prefix-slot` 候選位置,\n * 由外層 CSS `:has()` 條件化套到 `--item-prefix-slot`),子樹內所有 `<ItemPrefix>` /\n * `<ItemIcon>` / `<ItemAvatar>` 會自動用固定寬槽對齊。\n \n 槽寬 = `AVATAR_SIZE.inline[size]`(20/24/24 @ sm/md/lg)——以最大的 inline\n * prefix(avatar)為基準,icon 在槽內 `justify-center`。\n \n ```tsx\n * <ul style={getUniformPrefixSlotStyle(size)}>\n * <ItemIcon icon={Folder} /> ← 16px icon 在 24px 槽內置中\n * <ItemAvatar alt=\"GitHub\" /> ← 24px logo 填滿槽\n * </ul>\n * ```\n /\nexport function getUniformPrefixSlotStyle(size: RowSize): React.CSSProperties {\n return { \"--item-prefix-slot\": `${AVATAR_SIZE.inline[size]}px` } as React.CSSProperties\n}\n\n/\n Inline action(suffix 裡的 hover-action icon button)hover 背景尺寸(px)。\n * 規則:icon size + 2px(每邊 +1px,用 absolute positioning 溢出不影響排版)。\n * 對齊 `inline-action.spec.md`(canonical SSOT,2026-04-24 自 item-anatomy.spec 抽出)。\n /\n// code-quality-allow: dead-export — public constant — DS API surface,consumer 可引(即使當前 internal-only)\nexport const INLINE_ACTION_HOVER_BG_SIZE: Record<RowSize, number> = {\n sm: 18,\n md: 18,\n lg: 22,\n}\n\n/\n `ROW_PADDING_BY_SIZE` — Family 1+2 row primitive 的 size → padding + typography 公式 SSOT\n \n Formula(canonical):`py = (field-height - 1lh) / 2`,對齊 1em text 到 field-height center。\n \n 消費者:menuItemVariants / sidebarMenuButtonVariants / treeItemVariants / 未來 row primitive\n * Rationale:前先 3 cva 各自寫同一公式 → drift risk(item-anatomy.spec 有明文「SidebarMenuButton\n * 獨立實作風險」)。抽本 export 後改一處全同步,risk 消失(對齊 Meta-Pattern M17「SSOT 必可傳播」)。\n \n 2026-04-24 D Phase 1+2 consolidation 建立。\n /\nexport const ROW_PADDING_BY_SIZE: Record<RowSize, string> = {\n sm: 'text-body leading-compact py-[calc((var(--field-height-sm)-1lh)/2)]',\n md: 'text-body leading-compact py-[calc((var(--field-height-md)-1lh)/2)]',\n lg: 'text-body-lg leading-compact py-[calc((var(--field-height-lg)-1lh)/2)]',\n}\n\n// ── Helper components ──────────────────────────────────────────────────────\n\n/\n `<ItemPrefix>` — Row primitive 的 prefix slot wrapper。\n \n 把 prefix(icon / avatar / checkbox / indicator)包進 `h-[1lh]` 容器,\n * 強制對齊第一行文字中線。這是 item-layout 的底層規則(詳見 spec「Prefix 垂直對齊」)。\n \n 為什麼:\n * - Row primitive 的 outer flex 是 `items-start`(多行 label 時 prefix 不飄移)\n * - 單行時 prefix 透過這個 wrapper 強制對齊第一行中線,視覺效果 = `items-center`\n * - 不同尺寸的 prefix(icon 16、Avatar 24、Checkbox 20)都能穩定置中\n \n 用法:\n * ```tsx\n * <div className=\"flex items-start gap-2\">\n * <ItemPrefix>\n * <Avatar size={24} />\n * </ItemPrefix>\n * <span className=\"min-w-0 flex-1 truncate\">{label}</span>\n * </div>\n * ```\n \n asChild 的 consumer(例如 `<SidebarMenuButton asChild>`)必須自己用這個 wrapper\n * 包 prefix,不能省略。\n /\nexport const ItemPrefix = React.forwardRef<\n HTMLSpanElement,\n React.HTMLAttributes<HTMLSpanElement>\n>(({ className, ...props }, ref) => (\n <span\n ref={ref}\n className={cn(\n \"h-[1lh] shrink-0 flex items-center\",\n // Uniform prefix slot:讀取 `--item-prefix-slot` CSS variable,\n // fallback `auto`(= 預設行為,不佔額外寬度、不 center)。\n // Row-primitive 頂層容器(例如 `<SidebarProvider uniformPrefix>` 的 wrapper)\n // 若設定這個 var,小尺寸 prefix(icon 16px)會在固定寬槽(24px @ md)內置中,\n // 與大尺寸 prefix(app logo 24px)對齊,達成 label 齊左。\n // 詳見 item-anatomy.spec.md「Uniform prefix slot」節。\n \"min-w-[var(--item-prefix-slot,auto)] justify-center\",\n className\n )}\n {...props}\n />\n))\nItemPrefix.displayName = \"ItemPrefix\"\n\n/\n `itemPrefixAlignVariants` — Prefix 對齊高度的 cva SSOT(for 複雜 prefix 結構)。\n \n ── 存在的理由 ──\n * `<ItemPrefix>` primitive 預設單一 child(icon / avatar 任一)+ inline 對齊。\n * 但複雜 prefix 結構(e.g. MenuItem 可同時含 checkbox + icon/avatar 多 child)\n * 或block mode(大 prefix + description 對齊塊中心)需要自建 wrapper cva。\n * 本 cva 把 block formula SSOT 化,讓 MenuItem 等 consumer 共用,\n * 改值一處(token or cva)→ 所有 block-prefix consumer 同步。\n \n ── Align 變體(對齊 item-anatomy.spec.md「24px 閾值對齊規則」) ──\n * - `\"inline\"`:`h-[1lh]`,小 prefix(≤ 24px)對齊 label 第一行\n * - `\"block-sm\"` / `\"block-md\"`:大 prefix + scanning desc(sm/md menu),\n * 高度 = label(1lh) + gap(token) + desc(caption × 1.3)\n * - `\"block-lg\"`:大 prefix + scanning desc(lg menu),desc 改為 body × 1.3\n \n ── Consumer ──\n * MenuItem(inline / block-sm / block-md / block-lg)。其他 row primitive 簡單情境\n * 直接用 `<ItemPrefix>` 就好,不需此 cva。\n \n ── SSOT 傳播 ──\n * gap 用 `var(--item-gap-label-desc-scanning[-lg])` token(bare 變體已不存在,4 個 mode×size 變體);font-size 用 token-awareness\n * (`var(--font-caption-size)` / `var(--font-body-size)`)。改 token → 公式同步。\n /\n// code-quality-allow: long-function — cva variant/styles table — 拆 fn 會失去 type inference + 跨 fn 傳 config 反而難讀\nexport const itemPrefixAlignVariants = cva(\n \"flex items-center gap-2 shrink-0\",\n {\n variants: {\n align: {\n inline: \"h-[1lh]\",\n // sm/md desc = text-caption (12px × 1.3 = 15.6px)\n // block-sm / block-md:scanning mode(body + caption 組合)→ 用 scanning mode 專屬 gap token\n \"block-sm\":\n \"h-[calc(1lh+var(--item-gap-label-desc-scanning)+var(--font-caption-size)1.3)]\",\n \"block-md\":\n \"h-[calc(1lh+var(--item-gap-label-desc-scanning)+var(--font-caption-size)1.3)]\",\n // block-lg:scanning-lg mode(body-lg + body compact 組合)→ 用 scanning-lg mode 專屬 gap token\n \"block-lg\":\n \"h-[calc(1lh+var(--item-gap-label-desc-scanning-lg)+var(--font-body-size)1.3)]\",\n },\n },\n defaultVariants: {\n align: \"inline\",\n },\n }\n)\n\n/*\n `<ItemLabel>` — Row primitive 的 label span。\n \n 預設 `min-w-0 flex-1 truncate`——單行截斷,佔滿剩餘 flex 空間。\n * 加 `data-sidebar=\"menu-label\"` attribute 讓 sidebar icon 模式的 CSS selector 能命中。\n \n 用法:\n * ```tsx\n * <ItemLabel>{label}</ItemLabel>\n * ```\n /\nexport const ItemLabel = React.forwardRef<\n HTMLSpanElement,\n React.HTMLAttributes<HTMLSpanElement>\n>(({ className, ...props }, ref) => (\n <span\n ref={ref}\n data-sidebar=\"menu-label\"\n className={cn(\"min-w-0 flex-1 truncate\", className)}\n {...props}\n />\n))\nItemLabel.displayName = \"ItemLabel\"\n\n/\n `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。\n \n ── 存在的唯一理由 ──\n * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc-<mode>[-lg])]` gap」結構,\n * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。\n \n ── Consumer 偏離 canonical ──\n * 消費端若有確切合理理由不用 `<ItemContent>` / 需自訂 label/desc 行為,必在\n * 該元件 `spec.md` 明文寫下 rationale(對齊 item-anatomy canonical「偏離必明文」)。\n * 合法偏離範例:\n * - MenuItem 的 `leading-compact + text-caption` scanning-mode typography\n * → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc-scanning[-lg]` token 直接用\n * - SelectionItem 的 control slot 跟 block formula 綁定\n * → SelectionItem spec 明文 rationale\n \n ── Props ──\n * - `label`:label 內容(ReactNode,必填)\n * - `description`:description 內容(ReactNode,optional)\n * - `mode`:typography tier(scanning vs reading,世界級對齊 Material `dense` / Carbon `size` / Ant `size`)\n * - `\"reading\"`(預設):繼承 parent `text-body`(14px / 1.5 leading),舒適閱讀(Family 2 / Material body-large 派)\n * - `\"scanning\"`:desc 縮為 `text-caption`(12px)+ `leading-compact`(1.3),緊湊掃視\n * (Family 1 Menu item / Material body-medium dense 派)\n * - `descriptionTone`:desc 顏色語意\n * - `\"secondary\"`(預設):`text-fg-secondary`\n * - `\"error\"`:`text-error-text`\n * - `\"muted\"`:`text-fg-muted`\n * - `\"disabled\"`:`text-fg-disabled`(對齊 M24 state precedence:disabled > muted > emphasis)\n * - `descriptionWrap`:desc 多行 wrap(預設 true)/ false = truncate\n * - `labelClassName` / `descriptionClassName`:escape hatches(明文 rationale 才用)\n \n ── World-class benchmark ──\n * 6 家 DS(Material / Polaris / Atlassian / Apple HIG / Carbon / Ant)一致用\n * 14/20 vs 16/24 兩擋 body 表達 scanning vs reading。API 兩派:(A)密度 prop\n * Material `dense` / Carbon `size` / Ant `size`(本 DS 採 A 派);(B)typography\n * token 手選 Polaris / Atlassian / Apple。\n /\n\nexport interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivElement>, \"title\"> {\n label: React.ReactNode\n description?: React.ReactNode\n /\n Typography mode — leading 行為(跟 size 正交的另一維):\n * - `\"reading\"`(預設):default leading(1.5)— Family 2 List item 舒適閱讀\n * - `\"scanning\"`:`leading-compact`(1.3)+ desc 降一 tier —— Menu item / Step 掃視\n /\n mode?: \"reading\" \| \"scanning\"\n /\n Size tier — label 字級(跟 mode 正交的另一維):\n * - `\"md\"`(預設):label `text-body`(14)\n * - `\"lg\"`:label `text-body-lg`(16)— desc 永遠比 label 小一 tier(body)\n \n 2 × 2 = 4 typography 組合,對應 4 tokens:\n * - md + reading → body(14/1.5) + body(14/1.5)\n * - md + scanning → body(14/1.3) + caption(12/1.3)\n * - lg + reading → body-lg(16/1.5) + body(14/1.5)\n * - lg + scanning → body-lg(16/1.3) + body(14/1.3)\n /\n size?: \"md\" \| \"lg\"\n descriptionTone?: \"secondary\" \| \"error\" \| \"muted\" \| \"disabled\"\n descriptionWrap?: boolean\n /\n Description 多行截斷(line-clamp-N)。undefined = 不 clamp(自由 wrap)。\n * Tailwind line-clamp utilities 支援 1-6。\n /\n descriptionClamp?: number\n /\n Description `break-words`(default `false`,僅在 consumer 需要時 opt-in)。\n * 使用情境:SelectionItem / Steps 這類 description 可能塞長英文 token 需 break。\n /\n descriptionBreakWords?: boolean\n /\n Label truncate (default `true`, 對齊 row-item 大宗 idiom)。\n * Opt-out(`false`)for card-like consumers(e.g. ProfileCard label 允許 wrap)。\n * World-class 對照:Material `ListItemText primaryTypographyProps.noWrap` default true。\n /\n labelTruncate?: boolean\n labelClassName?: string\n descriptionClassName?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nexport const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(\n (\n {\n label,\n description,\n mode = \"reading\",\n size = \"md\",\n descriptionTone = \"secondary\",\n descriptionWrap = true,\n descriptionClamp,\n descriptionBreakWords = false,\n labelTruncate = true,\n labelClassName,\n descriptionClassName,\n className,\n ...props\n },\n ref,\n ) => {\n const toneClass = {\n secondary: \"text-fg-secondary\",\n error: \"text-error-text\",\n muted: \"text-fg-muted\",\n disabled: \"text-fg-disabled\",\n }[descriptionTone]\n\n // Typography desc class — 2 維 cross-product (mode × size):\n // ┌───────────┬────────────────────────────┬────────────────────────────┐\n // │ │ size=\"md\"(body label 14) │ size=\"lg\"(body-lg label 16)│\n // ├───────────┼────────────────────────────┼────────────────────────────┤\n // │ reading │ 繼承 body(14/1.5) │ body(14)default leading │\n // │ scanning │ caption(12)+ compact │ body(14)+ compact │\n // └───────────┴────────────────────────────┴────────────────────────────┘\n const isLg = size === \"lg\"\n const modeClass =\n mode === \"scanning\"\n ? isLg\n ? \"text-[length:var(--font-body-size)] leading-compact\"\n : \"text-[length:var(--font-caption-size)] leading-compact\"\n : isLg\n ? \"text-[length:var(--font-body-size)]\"\n : \"\"\n\n const clampClass = descriptionClamp ? `line-clamp-${descriptionClamp}` : \"\"\n\n return (\n <div\n ref={ref}\n className={cn(\"flex flex-col min-w-0 flex-1\", className)}\n {...props}\n >\n <span className={cn(labelTruncate && \"truncate\", labelClassName)}>{label}</span>\n {description && (\n <span\n className={cn(\n // Typography-mode-aware gap token(2026-04-23):\n // (mode, size)2 維正交 → 4 token 對應 4 typography 組合\n mode === \"scanning\"\n ? isLg\n ? \"mt-[var(--item-gap-label-desc-scanning-lg)]\"\n : \"mt-[var(--item-gap-label-desc-scanning)]\"\n : isLg\n ? \"mt-[var(--item-gap-label-desc-reading-lg)]\"\n : \"mt-[var(--item-gap-label-desc-reading)]\",\n modeClass,\n toneClass,\n clampClass,\n descriptionBreakWords && \"break-words\",\n !descriptionWrap && \"truncate\",\n descriptionClassName,\n )}\n >\n {description}\n </span>\n )}\n </div>\n )\n },\n)\nItemContent.displayName = \"ItemContent\"\n\n// ── Row size context ──────────────────────────────────────────────────────\n//\n// 作用:讓 row primitive(Sidebar / SelectMenu / Tree / DropdownMenu)只 propagate\n// 一次 size,整個子樹內的 <ItemIcon> / <ItemAvatar> 都自動查到正確尺寸。\n//\n// 存在的唯一理由:消除 asChild pattern 下 consumer 硬寫 `size={24}` 的可能性。\n// 過去 consumer 必須 `useSidebar().size` 再手動傳 `AVATAR_SIZE.inline[size]`,\n// 每個 consumer 都是一次漂移機會(曾發生:sm 欄 avatar 顯示 24 而非 20,破壞規格)。\n// 現在 consumer 只寫 `<ItemAvatar alt=\"...\" />`,尺寸由 context 自動決定。\n//\n// Row primitive 實作者的責任:在元件內部用 `<RowSizeProvider value={size}>` 包裹\n// children(不論 asChild 或非 asChild 路徑),這樣任何 descendant 的 ItemIcon /\n// ItemAvatar 都會拿到正確尺寸。\n\nconst RowSizeContext = React.createContext<RowSize \| null>(null)\n\n/* @internal — L3 row-size primitive;app code 不直接 import,由 MenuItem/Row/Field 等內部消費(inline-action.spec.md)。 /\nexport const RowSizeProvider = RowSizeContext.Provider\n\n/\n 讀取當前 row size。在 row primitive 子樹外呼叫會回 fallback(預設 \"md\")。\n * Row primitive 實作者不該呼叫這個——你們已經知道自己的 size。\n * 這個 hook 是給 `<ItemIcon>` / `<ItemAvatar>` 和 asChild consumer 的逃生艙用。\n /\nexport function useRowSize(fallback: RowSize = \"md\"): RowSize {\n return React.useContext(RowSizeContext) ?? fallback\n}\n\n// ── Prefab prefix elements ────────────────────────────────────────────────\n//\n// `<ItemIcon>` 和 `<ItemAvatar>` 是「prefix slot 的完成品元件」——自帶 ItemPrefix\n// wrapper + 自動查 ICON_SIZE / AVATAR_SIZE。\n//\n// asChild consumer 必須用這兩個元件,禁止手動寫 `<Avatar size={N} />`。\n// 禁令理由見 item-anatomy.spec.md「Avatar 尺寸選擇」節。\n\nexport interface ItemIconProps\n extends Omit<React.SVGAttributes<SVGSVGElement>, \"children\"> {\n /* Lucide icon 元件(不是 JSX element) /\n icon: LucideIcon\n}\n\n/\n `<ItemIcon icon={Folder} />` — 自動查 `ICON_SIZE[rowSize]`,包在 `ItemPrefix` 內。\n * 永遠對齊第一行 label(item-layout 的 icon 永遠 inline)。\n /\nexport const ItemIcon = React.forwardRef<SVGSVGElement, ItemIconProps>(\n ({ icon: Icon, className, ...props }, ref) => {\n const size = useRowSize()\n return (\n // data-prefix-type=\"icon\" 讓 row-primitive 容器的 `:has()` selector 能偵測類型,\n // 用於 `<SidebarProvider uniformPrefix>` opt-in 後的混用 auto-detection\n <ItemPrefix data-prefix-type=\"icon\">\n <Icon\n ref={ref}\n size={ICON_SIZE[size]}\n className={cn(\"shrink-0\", className)}\n aria-hidden\n {...props}\n />\n </ItemPrefix>\n )\n }\n)\nItemIcon.displayName = \"ItemIcon\"\n\nexport interface ItemAvatarProps extends Omit<AvatarProps, \"size\"> {\n /\n 對齊模式(選填,預設 `\"inline\"`):\n * - `\"inline\"`:視覺重量輕的 avatar,對齊第一行 label(20/24/24 @ sm/md/lg)\n * - `\"block\"`:視覺重量重的 avatar,對齊 label + description 文字塊(32/32/40 @ sm/md/lg)\n \n 預設 inline——大宗情境(扁平 row、footer user、主清單)都用這個。\n * 只有 avatar 是 item 主體(人物卡、顯著身份辨識)才用 block。\n \n 詳見 `item-anatomy.spec.md`「Avatar 尺寸選擇」節,含 24px 對齊模式閾值規則。\n /\n mode?: \"inline\" \| \"block\"\n}\n\n/\n `<ItemAvatar alt=\"Alan\" color=\"blue\" />` — 自動查 `AVATAR_SIZE[mode][rowSize]`,\n * 包在 `ItemPrefix` 內。\n \n asChild consumer 的標準用法——不需知道 size,不需 import AVATAR_SIZE,\n * 不可能硬寫錯誤尺寸。\n /\n// code-quality-allow: long-function — forwardRef body 含 size×color×hoverCard 三正交 prop 渲染分流,拆出 sub-fn 反增 prop drilling\nexport const ItemAvatar = React.forwardRef<HTMLDivElement, ItemAvatarProps>(\n ({ mode = \"inline\", ...props }, ref) => {\n const size = useRowSize()\n return (\n // data-prefix-type=\"avatar\" 讓 row-primitive 容器的 `:has()` selector 能偵測類型,\n // 用於 `<SidebarProvider uniformPrefix>` opt-in 後的混用 auto-detection\n <ItemPrefix data-prefix-type=\"avatar\">\n <Avatar ref={ref} size={AVATAR_SIZE[mode][size]} {...props} />\n </ItemPrefix>\n )\n }\n)\nItemAvatar.displayName = \"ItemAvatar\"\n\n// ── Inline action (suffix slot) ───────────────────────────────────────────\n//\n// 共用 row-primitive 的 suffix inline action 渲染——消除過去 Input / NumberInput /\n// Tag / LinkInput / Combobox 各自複製 18 行 JSX 的狀況(見 `inline-action.spec.md`)。\n//\n// 規格(完全對齊 inline-action.spec.md — canonical SSOT,2026-04-24 自 item-anatomy.spec 抽出):\n// - Icon 尺寸 = ICON_SIZE[rowSize] (16/16/20)\n// - Hover bg 尺寸 = icon + 2 (18/18/22,INLINE_ACTION_HOVER_BG_SIZE)\n// - Hover bg 圓角 = rounded-md (sm/md)/ rounded-md (lg)\n// - Icon 顏色:fg-muted → foreground on hover/active\n// - 必須 <button type=\"button\">,aria-label = label,Tooltip(同 label)\n// - cursor-pointer\n\n// ── Low-level:ItemInlineActionButton ──\n//\n// Root 是 `<button>`(不是 Tooltip wrapper),可直接塞進 Radix `asChild` pattern\n// 例如 `<Collapsible.Trigger asChild>`, `<Popover.Trigger asChild>` 等。\n//\n// 自動從 `RowSizeContext` 查:\n// - 寬高 = ICON_SIZE[size]\n// - Hover bg 尺寸 = INLINE_ACTION_HOVER_BG_SIZE[size]\n// - Hover bg 圓角 = rounded-md (sm/md) / rounded-md (lg)\n// - Icon color = fg-muted → foreground on hover/active\n//\n// 接受任何 button props 並 spread(讓 Radix Slot 可以 merge onClick / data-state 等)\n\nexport interface ItemInlineActionButtonProps\n extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, \"children\"> {\n /* Lucide icon 元件 /\n icon: LucideIcon\n /* 可選:額外加在 icon 上的 className(例如 rotate transition) /\n iconClassName?: string\n /\n Size 明確覆寫(用於 fields / Tag 等不在 `RowSizeProvider` 樹內的 host):\n * 傳了就以此為準,否則從 `RowSizeContext` 讀(fallback \"md\")。\n \n 使用時機:\n * - Row primitive 子樹(Sidebar / TreeView / SelectMenu / DropdownMenu)→ 不傳,吃 context\n * - Field / Tag(自有 size 系統,沒包 RowSizeProvider)→ 必傳 `size={hostSize}`\n /\n size?: RowSize\n /\n Hover / active bg className override(chromatic host 專用,如 Tag solid variant)。\n \n 預設 `group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active`。\n * 提供後完全取代 hover + active 雙態 className,但不影響 rest 態(永遠 bg-transparent)\n * 與 overlay-trigger 態(`group-data-[state=open]/action:bg-neutral-hover` — 維持 host hover bg)。\n \n Consumer 須同時包含 hover + active 兩態 selector,例:\n * `'group-hover/action:bg-[var(--my-hover)] group-active/action:bg-[var(--my-active)]'`\n \n Use case:Tag solid(blue/green/red 等)需 hover bg 跟 host 色相一致(非 neutral)。\n /\n hoverBgClassName?: string\n /\n 標記本 button 是 overlay trigger(DropdownMenu / Popover / Tooltip 透過 `asChild` 包覆)。\n \n `true` 時:Radix overlay open 期間(`data-state=\"open\"`)button 維持 host hover 樣式\n * — 視覺鎖,讓 user 追溯 floating panel 來源(對齊 shadcn / Radix Themes / Material)。\n \n `false` 時(default):無 data-state=open 樣式 — 適用 in-place 互動如 `Collapsible.Trigger`\n * (展開內容接在 trigger 下方,不需追溯)、drag handle、dismiss X 等。\n \n Canonical 詳 `inline-action.spec.md`「Overlay trigger canonical」段。\n \n @default false\n /\n overlayTrigger?: boolean\n}\n\n/* @internal — L3 inline-action primitive;app code 禁直接 import,經 MenuItem/Row endActions 消費(inline-action.spec.md)。 /\nexport const ItemInlineActionButton = React.forwardRef<\n HTMLButtonElement,\n ItemInlineActionButtonProps\n>(({ icon: Icon, className, iconClassName, style, type = \"button\", size: sizeProp, hoverBgClassName, overlayTrigger = false, ...rest }, ref) => {\n const contextSize = useRowSize()\n const size = sizeProp ?? contextSize\n const iconPx = ICON_SIZE[size]\n const hoverBgPx = INLINE_ACTION_HOVER_BG_SIZE[size]\n return (\n <button\n ref={ref}\n type={type}\n className={cn(\n \"group/action relative grid place-content-center shrink-0 cursor-pointer\",\n \"text-fg-muted hover:text-foreground active:text-foreground transition-colors\",\n // Overlay trigger active state — 只在 consumer 顯式宣告 overlayTrigger=true 時生效\n // (canonical 2026-05-05:Collapsible / drag / dismiss 等 in-place 互動 ≠ overlay,\n // 不應 leak 視覺 lock。詳 inline-action.spec.md「Overlay trigger canonical」)\n overlayTrigger && \"data-[state=open]:text-foreground\",\n \"focus-visible:outline-2 focus-visible:outline-ring\",\n className\n )}\n style={{ width: iconPx, height: iconPx, ...style }}\n {...rest}\n >\n <span\n aria-hidden\n className={cn(\n \"absolute pointer-events-none\",\n \"rounded-md\",\n \"bg-transparent\",\n hoverBgClassName ?? \"group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active\",\n // Overlay 開啟 = 維持 host hover bg(只在 overlayTrigger=true 時生效)\n overlayTrigger && \"group-data-[state=open]/action:bg-neutral-hover\",\n \"transition-colors\"\n )}\n style={{\n width: hoverBgPx,\n height: hoverBgPx,\n top: \"50%\",\n left: \"50%\",\n transform: \"translate(-50%, -50%)\",\n }}\n />\n <Icon size={iconPx} className={cn(\"relative\", iconClassName)} aria-hidden />\n </button>\n )\n})\nItemInlineActionButton.displayName = \"ItemInlineActionButton\"\n\n// ── High-level:ItemInlineAction ──\n//\n// 宣告式 API:consumer 給 `{ icon, label, onClick }`,元件自動處理 Tooltip +\n// aria-label。適用於 row primitive 的 suffix slot(SidebarMenuButton inlineActions 等)。\n//\n// 內部用 `ItemInlineActionButton`——兩層共用同一套視覺規格、同一個 RowSizeContext 查表。\n// 需要接 Radix asChild(例如 collapsible trigger)時改用 `ItemInlineActionButton`,\n// 那層沒有 Tooltip 包裝,Root 就是 button,可直接塞進 Radix Slot。\n\nexport interface ItemInlineActionProps {\n action: InlineActionConfig\n /* Size 覆寫(見 `ItemInlineActionButtonProps.size`)——Field Controls / Tag 必傳 /\n size?: RowSize\n}\n\n/* @internal — L3 inline-action primitive;app code 禁直接 import,經 row 元件消費(inline-action.spec.md)。 /\nexport const ItemInlineAction = React.forwardRef<\n HTMLButtonElement,\n ItemInlineActionProps\n>(({ action, size }, ref) => (\n <Tooltip>\n <TooltipTrigger asChild>\n <ItemInlineActionButton\n ref={ref}\n icon={action.icon}\n aria-label={action.label}\n onClick={action.onClick}\n size={size}\n />\n </TooltipTrigger>\n <TooltipContent>{action.label}</TooltipContent>\n </Tooltip>\n))\nItemInlineAction.displayName = \"ItemInlineAction\"\n\n// ── Item suffix slot ──────────────────────────────────────────────────────\n//\n// `<ItemSuffix>` — row primitive 的 suffix 容器。對齊 item-layout spec:\n// - `h-[1lh]`:suffix 永遠對齊第一行 label(跟 prefix 解耦)\n// - `ml-auto`:靠右\n// - `gap-2`:多個 inline action 之間的標準間距(inline-action.spec.md canonical SSOT)\n// - `hoverReveal` opt-in:opacity 0→1 on 父層 row hover/focus-visible\n//\n// `hoverGroup`(2026-05-05 v8 SSOT 升級):row primitive group selector 參數化。\n// 先前 `/menu-item` hardcode → TreeView(`/tree-item`)/ FileItem(`/row`)/\n// DataTable(`/row`)無法消費,被迫自刻 suffix slot(M1 違反)。\n// 參數化後 4 個 row primitive 都走同一條 SSOT。Tailwind JIT 需 static class,\n// 故用 lookup table 而非動態字串(避免 JIT scan 失敗)。\n\nconst SUFFIX_HOVER_REVEAL_BY_GROUP = {\n \"menu-item\":\n \"opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150\",\n \"tree-item\":\n \"opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150\",\n row: \"opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150\",\n} as const\n\nexport type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP\n\nexport interface ItemSuffixProps extends React.HTMLAttributes<HTMLSpanElement> {\n /\n Hover-reveal:預設隱藏,父層 row hover / keyboard focus-visible 時才淡入。\n * 對齊 TreeView / SidebarMenuButton inline action 行為。預設 false(永遠顯示,如 Badge)。\n \n 用 `group-has-[:focus-visible]` 而非 `group-focus-within`——後者會被 mouse click 觸發,\n * 導致 click 後 suffix 永久顯示直到焦點移走。focus-visible 只在鍵盤 tab 時啟動。\n /\n hoverReveal?: boolean\n /\n 父層 row 的 group selector(consumer 必加 `group/<name>` 到 row wrapper)。\n * 預設 `'menu-item'`(對齊 MenuItem / Sidebar)。其他 row primitive:\n * `'tree-item'`(TreeView)/ `'row'`(DataTable / FileItem)。\n \n 加新 row primitive(且需 hover-reveal)時:在 `SUFFIX_HOVER_REVEAL_BY_GROUP`\n * 加 entry,Tailwind JIT 才能 scan 到 static class。\n */\n hoverGroup?: ItemSuffixHoverGroup\n}\n\nexport const ItemSuffix = React.forwardRef<HTMLSpanElement, ItemSuffixProps>(\n ({ className, hoverReveal = false, hoverGroup = \"menu-item\", ...props }, ref) => (\n <span\n ref={ref}\n className={cn(\n \"h-[1lh] shrink-0 ml-auto flex items-center gap-2\",\n hoverReveal && SUFFIX_HOVER_REVEAL_BY_GROUP[hoverGroup],\n className\n )}\n {...props}\n />\n )\n)\nItemSuffix.displayName = \"ItemSuffix\"\n"],"names":[],"mappings":"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"}

package/dist/patterns/overlay-surface/overlay-surface.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"overlay-surface.js","sources":["../../../src/patterns/overlay-surface/overlay-surface.tsx"],"sourcesContent":["import * as React from 'react'\nimport { cn } from '@/lib/utils'\n// W2 tabsSlot wrapper 契約 SSOT 在 header-canonical(跨家族 W-rule owner);SurfaceHeader 消費同一 const 不 hardcode。\nimport { HEADER_TABS_SLOT_WRAPPER_CLASS } from '@/design-system/patterns/header-canonical/chrome-header'\n\n/*\n @internal — DS-internal primitive(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。\n * end-user app 直接 import 無 functioning UI;由 Dialog / Sheet / Popover / HoverCard / Coachmark 等 DS overlay 元件 wrap 消費。\n \n Overlay Surface primitives — Dialog / Popover / Sheet 共用結構化 sub-components。\n \n 抽象這層避免各自硬寫 padding / border 導致漂移。有特殊行為(Dialog Close 按鈕 /\n * viewport-fill 高度)由 consumer 額外包裝,不污染 primitive。\n \n ── Header / Footer 高度 canonical(2026-04-22 v3 校準,user intent 精確實作)──\n * Padding-based sizing:`py-[var(--layout-space-tight)]`,高度 = max(child) + 2×tight\n * 不用 fixed `min-h`(先前誤用 min-h-chrome-header-height 會讓 bounded button 被鎖死在 48\n * slot 失去自然高度,違反 user 意圖)。\n \n 對齊 `--chrome-header-height`(48/56)的條件:header 只放 unbounded 控件(close X /\n * text variant button,native sm + v5 unbounded trick layout 佔位 24):\n * header = 24 + 2×tight = 48 md / 56 lg ✓。\n \n 若 header 塞 bounded 控件(primary / tertiary with bg/border):header 自然長高\n * (sm 28 + 2×12 = 52 md),因 bounded 按鈕有視覺邊界,padding 不會顯得過大 — 這是預期的。\n \n ── Unbounded controls 在 header canonical(v5 trick,2026-04-22)──\n * Dismiss X(always unbounded)+ text variant header action → `size=\"sm\"` native\n * + SurfaceHeader CSS 自動套負 my trick(對 `[data-unbounded]`),layout 佔位縮回 24\n * (xs 等同)。Rationale:button native size 跟 touch target 保留 sm(a11y 最小 24+ hit\n * target,視覺 render 仍 28/32),layout 佔位精確匹配 chrome-header-height 幾何。詳\n * `overlay-surface.spec.md`「Chrome dismiss size canonical」。\n \n Notification banner family(Notice / Alert / Toast,fixed `px-4 py-3` variant,\n * 無 padding-based header)→ dismiss 用 `size=\"xs\"` explicit(24 固定,無 trick)。\n \n ── Token 規則 ──\n * horizontal padding: `px-[var(--layout-space-loose)]`\n * vertical padding: `py-[var(--layout-space-tight)]`\n * 分隔線: `border-{b\|t} border-divider`\n \n ── Body ──\n * Body padding-based(content area),`px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`。\n * Dialog / Sheet body 走 ScrollArea + chrome padding(`px-loose pt-tight pb-bottom`)。\n * List-as-region 場景(menu / Cmd+K)由 consumer 用 className override 撤 chrome padding +\n * 自管 list outer wrapper(詳 overlay-surface.spec.md「List-as-region in overlay body」)。\n /\n\n// Chrome-slot layout trick(2026-04-22 v5,2026-05-04 重思 parameterize):\n// 所有 unbounded control(Button with `data-unbounded=\"true\"` — Button 自動在 variant=\"text\" 或 dismiss\n// 時標記)的 native size 不變(sm: 28 md / 32 lg),但 layout 佔位* via 負 `my` 縮成 `--chrome-slot-h`。\n//\n// Slot height = header title 的 line-height(讓 button 不 dominate,title 自然撐 header)\n// - Default 衍生自 title typography:`calc(var(--font-body-lg-size)1.5)` = 16×1.5 = 24(Dialog/Sheet title = text-body-lg)。\n// 2026-06-16:從寫死 `var(--field-height-xs)`(巧合也=24)改為衍生 → title 字級若改,slot 自動跟、不靠巧合(M17 SSOT;\n// 1.5 = typography.spec body 行高常數,非 token 故 inline,若 body 行高改 1.3 須同步此處)。\n// - Popover-tier(title = text-body)走 `COMPACT_HEADER_SLOT`(見下)= calc(--font-body-size×1.5) = 14×1.5 = 21\n// (= PopoverTitle text-body line-box,衍生非寫死;2026-06-16 從各自寫死 1.25rem/20 巧合值收斂進 SSOT)\n//\n// Header 永遠 padding-based(無 min-h),但因 slot = title line-box,header 高度由 title 主導:\n// - Dialog: max(24 title, 24 slot) + py-tight(122)= 48 ✓ chrome-header-height\n// - Popover: max(21 title, 21 slot) + py-tight(122)= 45 ✓ 自然輕量\n// Q10 穩定性:title-only / title+button / refresh in/out 全 case header 高度 = title + py(slot=title,不超過)\n//\n// 負 my 公式:(slot - native) / 2,density-aware:\n// Dialog md: (24 - 28) / 2 = -2px; lg: (24 - 32) / 2 = -4px\n// Popover md: (21 - 28) / 2 = -3.5px(sub-pixel,可接受)\nconst CHROME_UNBOUNDED_SLOT = '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)1.5))-var(--field-height-sm))/2)]'\n\n/*\n 輕量浮層 header 的 slot override —— SSOT,禁各自 inline(2026-06-16 收斂)。\n * Popover-tier header(title = PopoverTitle `text-body`)的 slot = body line-box = `calc(--font-body-size×1.5)` = 21,\n * 衍生自 title typography → title 字級改,slot 自動跟(取代舊各自寫死的 1.25rem / 20 巧合值)。\n * 消費者(同設計邏輯,皆 raw SurfaceHeader + PopoverTitle):PopoverHeader / DataTable sort·filter panel /\n * FileItem upload-manager。Default slot(Dialog/Sheet,title = text-body-lg)= 24,在 CHROME_UNBOUNDED_SLOT fallback。\n /\nexport const COMPACT_HEADER_SLOT = '[--chrome-slot-h:calc(var(--font-body-size)1.5)]'\n\nexport interface SurfaceHeaderProps\n extends React.HTMLAttributes<HTMLDivElement> {\n /*\n 是否內含 Tabs。\n * true(無 tabsSlot)→ 移除自身 border-b。\n * 若提供 tabsSlot,自動 column mode + auto suppress border(不需手動傳 withTabs=true)。\n * 對齊 patterns/header-canonical/header-canonical.spec.md W1\n * 「Header semantic owner / TabsList paint owner in withTabs state」。\n /\n withTabs?: boolean\n /\n Tabs row slot(2026-05-18 加 per header-canonical.spec.md W2/W4 真實能用 + user-mandated fix)。\n * 提供時 SurfaceHeader 自動 column 結構:\n * row 1 = children(title + actions/dismiss,px-loose py-tight)\n * row 2 = tabsSlot 包在 `HEADER_TABS_SLOT_WRAPPER_CLASS` wrapper(v3:wrapper 自身\n * 無 px / 無 border;TabsList 自己 w-full + px-loose,border-b 延展全寬 —\n * W1 視覺一條線。詳 chrome-header.tsx v3 fix 註解)\n \n Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 仍放 DialogBody 內。\n * `<Tabs>` root 必須 wrap 整 DialogContent(Radix TabsList ↔ TabsContent 同 root 連動)。\n \n 提供 tabsSlot 自動 withTabs=true,不需另傳 prop。\n /\n tabsSlot?: React.ReactNode\n}\n\nexport const SurfaceHeader = React.forwardRef<\n HTMLDivElement,\n SurfaceHeaderProps\n>(({ className, withTabs, tabsSlot, children, ...props }, ref) => {\n // tabsSlot 提供 → 自動 withTabs(consumer 不需手動兩個 prop)\n const hasTabs = tabsSlot != null \|\| withTabs === true\n\n // Column mode(tabsSlot 提供時)— 對應 header-canonical.spec.md W2 + W4\n if (tabsSlot != null) {\n return (\n <div\n ref={ref}\n className={cn('flex flex-col shrink-0', className)}\n {...props}\n >\n {/ Row 1:header content row(原 single-row behavior 不變,但 border-b 撤掉,row 2 wrapper 接管 paint)/}\n <div\n className={cn(\n 'flex items-center gap-2',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n CHROME_UNBOUNDED_SLOT,\n )}\n >\n {children}\n </div>\n {/ Row 2:tabsSlot wrapper — TabsList 全 dialog 寬 + 內 px-loose padding inset triggers\n 2026-05-18 v3 fix(user verbatim approval「你確定這樣是世界級的設計且符合我們一致的設計\n 語言和 SSOT...就這樣做」):\n - v1: wrapper border + TabsList border = 雙線(W1 違反)\n - v2: wrapper px-loose + TabsList w-full inside = border 只跨 dialog - 2×px-loose\n (不到 dialog 邊 user 抓「分隔線寬度應該要填滿整個 dialog」)\n - v3(本):wrapper 不 inset,TabsList 自己 px-loose 內 padding inset triggers\n → TabsList border-b 延展全 dialog 寬,triggers 對齊 header content\n 對齊既有 `tabs.spec.md:199`「TabsList 自身 border-b border-border 延展全 header 寬,因\n TabsList wrapper 是 block-level full-width」+ `:187-189`「selected 底線從 TabsList\n gray border 位置長出來」+ GitHub Primer UnderlineNav / Ant Design line type / Mantine\n default 共識(全派 TabsList 自畫 full-width underline)。*/}\n <div className={HEADER_TABS_SLOT_WRAPPER_CLASS}>\n {tabsSlot}\n </div>\n </div>\n )\n }\n\n // Padding-based(預設) — Dialog/Sheet 用 body-lg title (16/24)，自然撐 max(24 title, 24 button slot) = 24\n // → header = 24 + py-tight 12×2 = 48 chrome-header-height ✓ 穩定無需 min-h\n // Popover 等輕量 chrome 走 COMPACT_HEADER_SLOT(slot = calc(--font-body-size×1.5)=21 = title line-box,無 min-h / 無 py override)：max(21 title, 21 slot) + py-tight 12×2 = 45（見上方 L57）\n //\n // withTabs=true(無 tabsSlot,backward compat):移除 border-b,consumer 自畫\n return (\n <div\n ref={ref}\n className={cn(\n 'flex items-center gap-2 shrink-0',\n !hasTabs && 'border-b border-divider',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n CHROME_UNBOUNDED_SLOT,\n className,\n )}\n {...props}\n >\n {children}\n </div>\n )\n})\nSurfaceHeader.displayName = 'SurfaceHeader'\n\nexport const SurfaceBody = React.forwardRef<\n HTMLDivElement,\n React.HTMLAttributes<HTMLDivElement>\n>(({ className, ...props }, ref) => (\n // 2026-05-04 viewport-aware scroll canonical:\n // parent(PopoverContent / HoverCardContent / Dialog / Sheet)是 flex flex-col + max-h + overflow-hidden\n // header / footer shrink-0;Body flex-1 min-h-0 overflow-y-auto → 視窗太小時 body 內 scroll\n // 非 flex-col parent 內 flex-1/min-h-0 no-op,backward compat\n <div\n ref={ref}\n className={cn(\n 'flex-1 min-h-0 overflow-y-auto',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n className,\n )}\n {...props}\n />\n))\nSurfaceBody.displayName = 'SurfaceBody'\n\nexport const SurfaceFooter = React.forwardRef<\n HTMLDivElement,\n React.HTMLAttributes<HTMLDivElement>\n>(({ className, ...props }, ref) => (\n <div\n ref={ref}\n className={cn(\n 'flex items-center justify-end gap-2 shrink-0 border-t border-divider',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n className,\n )}\n {...props}\n />\n))\nSurfaceFooter.displayName = 'SurfaceFooter'\n"],"names":[],"mappings":";;;;AAmEA,MAAM,wBAAwB;AASvB,MAAM,sBAAsB;AA4B5B,MAAM,gBAAgB,MAAM,WAGjC,CAAC,EAAE,WAAW,UAAU,UAAU,UAAU,GAAG,MAAA,GAAS,QAAQ;AAEhE,QAAM,UAAU,YAAY,QAAQ,aAAa;AAGjD,MAAI,YAAY,MAAM;AACpB,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW,GAAG,0BAA0B,SAAS;AAAA,QAChD,GAAG;AAAA,QAGJ,UAAA;AAAA,UAAA;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,WAAW;AAAA,gBACT;AAAA,gBACA;AAAA,gBACA;AAAA,cAAA;AAAA,cAGD;AAAA,YAAA;AAAA,UAAA;AAAA,UAcH,oBAAC,OAAA,EAAI,WAAW,gCACb,UAAA,SAAA,CACH;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA,EAGN;AAOA,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA,CAAC,WAAW;AAAA,QACZ;AAAA,QACA;AAAA,QACA;AAAA,MAAA;AAAA,MAED,GAAG;AAAA,MAEH;AAAA,IAAA;AAAA,EAAA;AAGP,CAAC;AACD,cAAc,cAAc;AAErB,MAAM,cAAc,MAAM,WAG/B,CAAC,EAAE,WAAW,GAAG,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA,EAK1B;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA;AAAA,QACA;AAAA,MAAA;AAAA,MAED,GAAG;AAAA,IAAA;AAAA,EAAA;AAAA,CAEP;AACD,YAAY,cAAc;AAEnB,MAAM,gBAAgB,MAAM,WAGjC,CAAC,EAAE,WAAW,GAAG,MAAA,GAAS,QAC1B;AAAA,EAAC;AAAA,EAAA;AAAA,IACC;AAAA,IACA,WAAW;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,EAAA;AACN,CACD;AACD,cAAc,cAAc;"}
1	+ {"version":3,"file":"overlay-surface.js","sources":["../../../src/patterns/overlay-surface/overlay-surface.tsx"],"sourcesContent":["import * as React from 'react'\nimport { cn } from '@/lib/utils'\n// W2 tabsSlot wrapper 契約 SSOT 在 header-canonical(跨家族 W-rule owner);SurfaceHeader 消費同一 const 不 hardcode。\nimport { HEADER_TABS_SLOT_WRAPPER_CLASS } from '@/design-system/patterns/header-canonical/chrome-header'\n\n/*\n @internal — DS-internal primitive(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。\n * end-user app 直接 import 無 functioning UI;由 Dialog / Sheet / Popover / Coachmark 等 DS overlay 元件 wrap 消費(HoverCard 不消費 — 2026-07-04 grep 0 import,spec「何時不用」同步)。\n \n Overlay Surface primitives — Dialog / Popover / Sheet 共用結構化 sub-components。\n \n 抽象這層避免各自硬寫 padding / border 導致漂移。有特殊行為(Dialog Close 按鈕 /\n * viewport-fill 高度)由 consumer 額外包裝,不污染 primitive。\n \n ── Header / Footer 高度 canonical(2026-04-22 v3 校準,user intent 精確實作)──\n * Padding-based sizing:`py-[var(--layout-space-tight)]`,高度 = max(child) + 2×tight\n * 不用 fixed `min-h`(先前誤用 min-h-chrome-header-height 會讓 bounded button 被鎖死在 48\n * slot 失去自然高度,違反 user 意圖)。\n \n 對齊 `--chrome-header-height`(48/56)的條件:header 只放 unbounded 控件(close X /\n * text variant button,native sm + v5 unbounded trick layout 佔位 24):\n * header = 24 + 2×tight = 48 md / 56 lg ✓。\n \n 若 header 塞 bounded 控件(primary / tertiary with bg/border):header 自然長高\n * (sm 28 + 2×12 = 52 md),因 bounded 按鈕有視覺邊界,padding 不會顯得過大 — 這是預期的。\n \n ── Unbounded controls 在 header canonical(v5 trick,2026-04-22)──\n * Dismiss X(always unbounded)+ text variant header action → `size=\"sm\"` native\n * + SurfaceHeader CSS 自動套負 my trick(對 `[data-unbounded]`),layout 佔位縮回 24\n * (xs 等同)。Rationale:button native size 跟 touch target 保留 sm(a11y 最小 24+ hit\n * target,視覺 render 仍 28/32),layout 佔位精確匹配 chrome-header-height 幾何。詳\n * `overlay-surface.spec.md`「Chrome dismiss size canonical」。\n \n Notification banner family(Notice / Alert / Toast,fixed `px-4 py-3` variant,\n * 無 padding-based header)→ dismiss 用 `size=\"xs\"` explicit(24 固定,無 trick)。\n \n ── Token 規則 ──\n * horizontal padding: `px-[var(--layout-space-loose)]`\n * vertical padding: `py-[var(--layout-space-tight)]`\n * 分隔線: `border-{b\|t} border-divider`\n \n ── Body ──\n * Body padding-based(content area),`px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`。\n * Dialog / Sheet body 走 ScrollArea + chrome padding(`px-loose pt-tight pb-bottom`)。\n * List-as-region 場景(menu / Cmd+K)由 consumer 用 className override 撤 chrome padding +\n * 自管 list outer wrapper(詳 overlay-surface.spec.md「List-as-region in overlay body」)。\n /\n\n// Chrome-slot layout trick(2026-04-22 v5,2026-05-04 重思 parameterize):\n// 所有 unbounded control(Button with `data-unbounded=\"true\"` — Button 自動在 variant=\"text\" 或 dismiss\n// 時標記)的 native size 不變(sm: 28 md / 32 lg),但 layout 佔位* via 負 `my` 縮成 `--chrome-slot-h`。\n//\n// Slot height = header title 的 line-height(讓 button 不 dominate,title 自然撐 header)\n// - Default 衍生自 title typography:`calc(var(--font-body-lg-size)1.5)` = 16×1.5 = 24(Dialog/Sheet title = text-body-lg)。\n// 2026-06-16:從寫死 `var(--field-height-xs)`(巧合也=24)改為衍生 → title 字級若改,slot 自動跟、不靠巧合(M17 SSOT;\n// 1.5 = typography.spec body 行高常數,非 token 故 inline,若 body 行高改 1.3 須同步此處)。\n// - Popover-tier(title = text-body)走 `COMPACT_HEADER_SLOT`(見下)= calc(--font-body-size×1.5) = 14×1.5 = 21\n// (= PopoverTitle text-body line-box,衍生非寫死;2026-06-16 從各自寫死 1.25rem/20 巧合值收斂進 SSOT)\n//\n// Header 永遠 padding-based(無 min-h),但因 slot = title line-box,header 高度由 title 主導:\n// - Dialog: max(24 title, 24 slot) + py-tight(122)= 48 ✓ chrome-header-height\n// - Popover: max(21 title, 21 slot) + py-tight(122)= 45 ✓ 自然輕量\n// Q10 穩定性:title-only / title+button / refresh in/out 全 case header 高度 = title + py(slot=title,不超過)\n//\n// 負 my 公式:(slot - native) / 2,density-aware:\n// Dialog md: (24 - 28) / 2 = -2px; lg: (24 - 32) / 2 = -4px\n// Popover md: (21 - 28) / 2 = -3.5px(sub-pixel,可接受)\nconst CHROME_UNBOUNDED_SLOT = '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)1.5))-var(--field-height-sm))/2)]'\n\n/*\n 輕量浮層 header 的 slot override —— SSOT,禁各自 inline(2026-06-16 收斂)。\n * Popover-tier header(title = PopoverTitle `text-body`)的 slot = body line-box = `calc(--font-body-size×1.5)` = 21,\n * 衍生自 title typography → title 字級改,slot 自動跟(取代舊各自寫死的 1.25rem / 20 巧合值)。\n * 消費者(同設計邏輯,皆 raw SurfaceHeader + PopoverTitle):PopoverHeader / DataTable sort·filter panel /\n * FileItem upload-manager。Default slot(Dialog/Sheet,title = text-body-lg)= 24,在 CHROME_UNBOUNDED_SLOT fallback。\n /\nexport const COMPACT_HEADER_SLOT = '[--chrome-slot-h:calc(var(--font-body-size)1.5)]'\n\nexport interface SurfaceHeaderProps\n extends React.HTMLAttributes<HTMLDivElement> {\n /*\n 是否內含 Tabs。\n * true(無 tabsSlot)→ 移除自身 border-b。\n * 若提供 tabsSlot,自動 column mode + auto suppress border(不需手動傳 withTabs=true)。\n * 對齊 patterns/header-canonical/header-canonical.spec.md W1\n * 「Header semantic owner / TabsList paint owner in withTabs state」。\n /\n withTabs?: boolean\n /\n Tabs row slot(2026-05-18 加 per header-canonical.spec.md W2/W4 真實能用 + user-mandated fix)。\n * 提供時 SurfaceHeader 自動 column 結構:\n * row 1 = children(title + actions/dismiss,px-loose py-tight)\n * row 2 = tabsSlot 包在 `HEADER_TABS_SLOT_WRAPPER_CLASS` wrapper(v3:wrapper 自身\n * 無 px / 無 border;TabsList 自己 w-full + px-loose,border-b 延展全寬 —\n * W1 視覺一條線。詳 chrome-header.tsx v3 fix 註解)\n \n Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 仍放 DialogBody 內。\n * `<Tabs>` root 必須 wrap 整 DialogContent(Radix TabsList ↔ TabsContent 同 root 連動)。\n \n 提供 tabsSlot 自動 withTabs=true,不需另傳 prop。\n /\n tabsSlot?: React.ReactNode\n}\n\nexport const SurfaceHeader = React.forwardRef<\n HTMLDivElement,\n SurfaceHeaderProps\n>(({ className, withTabs, tabsSlot, children, ...props }, ref) => {\n // tabsSlot 提供 → 自動 withTabs(consumer 不需手動兩個 prop)\n const hasTabs = tabsSlot != null \|\| withTabs === true\n\n // Column mode(tabsSlot 提供時)— 對應 header-canonical.spec.md W2 + W4\n if (tabsSlot != null) {\n return (\n <div\n ref={ref}\n className={cn('flex flex-col shrink-0', className)}\n {...props}\n >\n {/ Row 1:header content row(原 single-row behavior 不變,但 border-b 撤掉,row 2 wrapper 接管 paint)/}\n <div\n className={cn(\n 'flex items-center gap-2',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n CHROME_UNBOUNDED_SLOT,\n )}\n >\n {children}\n </div>\n {/ Row 2:tabsSlot wrapper — TabsList 全 dialog 寬 + 內 px-loose padding inset triggers\n 2026-05-18 v3 fix(user verbatim approval「你確定這樣是世界級的設計且符合我們一致的設計\n 語言和 SSOT...就這樣做」):\n - v1: wrapper border + TabsList border = 雙線(W1 違反)\n - v2: wrapper px-loose + TabsList w-full inside = border 只跨 dialog - 2×px-loose\n (不到 dialog 邊 user 抓「分隔線寬度應該要填滿整個 dialog」)\n - v3(本):wrapper 不 inset,TabsList 自己 px-loose 內 padding inset triggers\n → TabsList border-b 延展全 dialog 寬,triggers 對齊 header content\n 對齊既有 `tabs.spec.md`「Underline 與 TabsList border 的視覺關係」段「selected 底線從\n TabsList 的 gray border 位置長出來」(token = border-divider,tabs.tsx TABS_LIST_BASE)\n + GitHub Primer UnderlineNav / Ant Design line type / Mantine default 共識\n (全派 TabsList 自畫 full-width underline)。*/}\n <div className={HEADER_TABS_SLOT_WRAPPER_CLASS}>\n {tabsSlot}\n </div>\n </div>\n )\n }\n\n // Padding-based(預設) — Dialog/Sheet 用 body-lg title (16/24)，自然撐 max(24 title, 24 button slot) = 24\n // → header = 24 + py-tight 12×2 = 48 chrome-header-height ✓ 穩定無需 min-h\n // Popover 等輕量 chrome 走 COMPACT_HEADER_SLOT(slot = calc(--font-body-size×1.5)=21 = title line-box,無 min-h / 無 py override)：max(21 title, 21 slot) + py-tight 12×2 = 45（見上方 L57）\n //\n // withTabs=true(無 tabsSlot,backward compat):移除 border-b,consumer 自畫\n return (\n <div\n ref={ref}\n className={cn(\n 'flex items-center gap-2 shrink-0',\n !hasTabs && 'border-b border-divider',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n CHROME_UNBOUNDED_SLOT,\n className,\n )}\n {...props}\n >\n {children}\n </div>\n )\n})\nSurfaceHeader.displayName = 'SurfaceHeader'\n\nexport const SurfaceBody = React.forwardRef<\n HTMLDivElement,\n React.HTMLAttributes<HTMLDivElement>\n>(({ className, ...props }, ref) => (\n // 2026-05-04 viewport-aware scroll canonical:\n // parent(PopoverContent / HoverCardContent / Dialog / Sheet)是 flex flex-col + max-h + overflow-hidden\n // header / footer shrink-0;Body flex-1 min-h-0 overflow-y-auto → 視窗太小時 body 內 scroll\n // 非 flex-col parent 內 flex-1/min-h-0 no-op,backward compat\n <div\n ref={ref}\n className={cn(\n 'flex-1 min-h-0 overflow-y-auto',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n className,\n )}\n {...props}\n />\n))\nSurfaceBody.displayName = 'SurfaceBody'\n\nexport const SurfaceFooter = React.forwardRef<\n HTMLDivElement,\n React.HTMLAttributes<HTMLDivElement>\n>(({ className, ...props }, ref) => (\n <div\n ref={ref}\n className={cn(\n 'flex items-center justify-end gap-2 shrink-0 border-t border-divider',\n 'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',\n className,\n )}\n {...props}\n />\n))\nSurfaceFooter.displayName = 'SurfaceFooter'\n"],"names":[],"mappings":";;;;AAmEA,MAAM,wBAAwB;AASvB,MAAM,sBAAsB;AA4B5B,MAAM,gBAAgB,MAAM,WAGjC,CAAC,EAAE,WAAW,UAAU,UAAU,UAAU,GAAG,MAAA,GAAS,QAAQ;AAEhE,QAAM,UAAU,YAAY,QAAQ,aAAa;AAGjD,MAAI,YAAY,MAAM;AACpB,WACE;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,WAAW,GAAG,0BAA0B,SAAS;AAAA,QAChD,GAAG;AAAA,QAGJ,UAAA;AAAA,UAAA;AAAA,YAAC;AAAA,YAAA;AAAA,cACC,WAAW;AAAA,gBACT;AAAA,gBACA;AAAA,gBACA;AAAA,cAAA;AAAA,cAGD;AAAA,YAAA;AAAA,UAAA;AAAA,UAcH,oBAAC,OAAA,EAAI,WAAW,gCACb,UAAA,SAAA,CACH;AAAA,QAAA;AAAA,MAAA;AAAA,IAAA;AAAA,EAGN;AAOA,SACE;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA,CAAC,WAAW;AAAA,QACZ;AAAA,QACA;AAAA,QACA;AAAA,MAAA;AAAA,MAED,GAAG;AAAA,MAEH;AAAA,IAAA;AAAA,EAAA;AAGP,CAAC;AACD,cAAc,cAAc;AAErB,MAAM,cAAc,MAAM,WAG/B,CAAC,EAAE,WAAW,GAAG,SAAS;AAAA;AAAA;AAAA;AAAA;AAAA,EAK1B;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,WAAW;AAAA,QACT;AAAA,QACA;AAAA,QACA;AAAA,MAAA;AAAA,MAED,GAAG;AAAA,IAAA;AAAA,EAAA;AAAA,CAEP;AACD,YAAY,cAAc;AAEnB,MAAM,gBAAgB,MAAM,WAGjC,CAAC,EAAE,WAAW,GAAG,MAAA,GAAS,QAC1B;AAAA,EAAC;AAAA,EAAA;AAAA,IACC;AAAA,IACA,WAAW;AAAA,MACT;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,EAAA;AACN,CACD;AACD,cAAc,cAAc;"}

package/dist/tokens/categorical-color.d.ts CHANGED Viewed

@@ -21,7 +21,7 @@
  * (dark-mode 方向 pre-computed,**不可**用 primitive step-5,否則 dark mode 反向)。12 色相皆已定義。
  *
  * **加色相**:加進 `CATEGORICAL_HUES` + 下列 5 個 map 各補一行字面值(key X 用 `--color-X-*`,1:1)。
- * **機械防線**:`check_categorical_color_1to1.sh` 強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset)。
+ * **機械防線**:`scripts/categorical-color-invariants.mjs` I1(release:preflight 已 chain)強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset;原引 hook 名不存在,2026-07-04 修)。
  */
 /** 12 個 categorical 色相(順序對齊 primitives.css / Storybook color token 列)。 */
 export declare const CATEGORICAL_HUES: readonly ["blue", "green", "deep-orange", "yellow", "red", "orange", "amber", "lime", "turquoise", "indigo", "purple", "magenta"];

package/dist/tokens/categorical-color.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"categorical-color.js","sources":["../../src/tokens/categorical-color.ts"],"sourcesContent":["/*\n categorical-color.ts — Categorical 色相 SSOT(2026-06-04 codify)\n \n Tag / Avatar / Calendar 等「以色相做分類標籤」的元件,色彩 variant 一律消費此 SSOT。\n * 目的:variant 名 == primitive 色相名,1:1,零 offset —— 根治「red variant 接到 deep-orange」\n * 這類 categorical-vs-semantic 混淆(2026-06-04 user 抓:red = 品牌紅 hue-25〔--brand #DF3232 同族〕\n * ≠ deep-orange hue-38 ≠ semantic --error〔= deep-orange〕。三者完全無關)。\n \n 世界級對照:\n * - Ant Design Tag preset colors —— 用原始色相名(red/orange/green/blue…)做 categorical labeling\n * (https://ant.design/components/tag/)。本 DS Tag/Avatar 採此模型。\n * - Atlassian Color 原則 —— categorical(裝飾)色 vs semantic(狀態)色必須分離\n * (https://atlassian.design/foundations/color):categorical `red` 用 `--color-red-`,跟 semantic\n `--error`(= deep-orange)無關;把 error 色拿來當 categorical 標籤 = 反 pattern。\n \n ⚠️ Tailwind v4 掃描限制:class 字串必須以字面形式出現在被掃描的 source(本檔在 src/,會被掃),\n * 不可用 runtime function 拼字串(否則 `bg-[var(--color-orange-1)]` 不被生成 → silent 失效)。\n * 故本 SSOT 以字面 const map 提供;consumer `import` 後索引(cva 列 key 取值,保 VariantProps 型別)。\n \n 互動 state(solid dismiss hover/active)用 semantic `--{hue}-hover` / `--{hue}-active`\n * (dark-mode 方向 pre-computed,不可用 primitive step-5,否則 dark mode 反向)。12 色相皆已定義。\n \n 加色相:加進 `CATEGORICAL_HUES` + 下列 5 個 map 各補一行字面值(key X 用 `--color-X-`,1:1)。\n 機械防線:`check_categorical_color_1to1.sh` 強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset)。\n /\n\n/* 12 個 categorical 色相(順序對齊 primitives.css / Storybook color token 列)。 /\nexport const CATEGORICAL_HUES = [\n 'blue',\n 'green',\n 'deep-orange',\n 'yellow',\n 'red',\n 'orange',\n 'amber',\n 'lime',\n 'turquoise',\n 'indigo',\n 'purple',\n 'magenta',\n] as const\n\nexport type CategoricalHue = (typeof CATEGORICAL_HUES)[number]\n\n/* neutral 不是色相(無 hue),用 secondary/foreground + neutral-9 solid,各 consumer 自處理(不在下列 map)。 /\nexport type CategoricalColor = CategoricalHue \| 'neutral'\n\n/* subtle 模式 class:step-1 底 + step-7 字。key X 一律對 `--color-X-`(1:1)。 /\nexport const CAT_SUBTLE: Record<CategoricalHue, string> = {\n blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)]',\n green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)]',\n 'deep-orange': 'bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)]',\n yellow: 'bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)]',\n red: 'bg-[var(--color-red-1)] text-[var(--color-red-7)]',\n orange: 'bg-[var(--color-orange-1)] text-[var(--color-orange-7)]',\n amber: 'bg-[var(--color-amber-1)] text-[var(--color-amber-7)]',\n lime: 'bg-[var(--color-lime-1)] text-[var(--color-lime-7)]',\n turquoise: 'bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)]',\n indigo: 'bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)]',\n purple: 'bg-[var(--color-purple-1)] text-[var(--color-purple-7)]',\n magenta: 'bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)]',\n}\n\n/*\n solid 模式 class:step-6 底 + on-emphasis 配對文字。\n * 文字色依「step-6 底亮度」分桶(WCAG ≥3:1 大粗字門檻,2026-06-04 user「以最低為原則」):\n * - 夠深的色底 → `text-on-emphasis`(白):blue / deep-orange / red / turquoise / indigo / purple / magenta\n * - 太亮的色底 → `text-on-emphasis-dark`(深):yellow / amber / orange / lime(白字連 3:1 都不過)\n * - ★ green 例外:白字 2.47 連 3:1 都不過,但 user 拍板維持白字(綠底白字慣見觀感)= documented exception。\n * 對比為 oklch→相對亮度實測(scripts/categorical-color-invariants.mjs 機械驗,green 列 exempt)。\n /\nexport const CAT_SOLID: Record<CategoricalHue, string> = {\n blue: 'bg-[var(--color-blue-6)] text-on-emphasis',\n green: 'bg-[var(--color-green-6)] text-on-emphasis', // ★白字 documented exception(實測 2.47 < 3:1)\n 'deep-orange': 'bg-[var(--color-deep-orange-6)] text-on-emphasis',\n yellow: 'bg-[var(--color-yellow-6)] text-on-emphasis-dark',\n red: 'bg-[var(--color-red-6)] text-on-emphasis',\n orange: 'bg-[var(--color-orange-6)] text-on-emphasis-dark',\n amber: 'bg-[var(--color-amber-6)] text-on-emphasis-dark',\n lime: 'bg-[var(--color-lime-6)] text-on-emphasis-dark',\n turquoise: 'bg-[var(--color-turquoise-6)] text-on-emphasis',\n indigo: 'bg-[var(--color-indigo-6)] text-on-emphasis',\n purple: 'bg-[var(--color-purple-6)] text-on-emphasis',\n magenta: 'bg-[var(--color-magenta-6)] text-on-emphasis',\n}\n\n/* solid 互動(dismiss hover/active)— semantic dark-mode-aware token。 /\nexport const CAT_INTERACT: Record<CategoricalHue, { hover: string; active: string }> = {\n blue: { hover: 'var(--blue-hover)', active: 'var(--blue-active)' },\n green: { hover: 'var(--green-hover)', active: 'var(--green-active)' },\n 'deep-orange': { hover: 'var(--deep-orange-hover)', active: 'var(--deep-orange-active)' },\n yellow: { hover: 'var(--yellow-hover)', active: 'var(--yellow-active)' },\n red: { hover: 'var(--red-hover)', active: 'var(--red-active)' },\n orange: { hover: 'var(--orange-hover)', active: 'var(--orange-active)' },\n amber: { hover: 'var(--amber-hover)', active: 'var(--amber-active)' },\n lime: { hover: 'var(--lime-hover)', active: 'var(--lime-active)' },\n turquoise: { hover: 'var(--turquoise-hover)', active: 'var(--turquoise-active)' },\n indigo: { hover: 'var(--indigo-hover)', active: 'var(--indigo-active)' },\n purple: { hover: 'var(--purple-hover)', active: 'var(--purple-active)' },\n magenta: { hover: 'var(--magenta-hover)', active: 'var(--magenta-active)' },\n}\n\n/* Avatar style 物件用:subtle / solid 的 raw token { bg, text }(非 class)。 /\nexport const CAT_SUBTLE_TOKENS: Record<CategoricalHue, { bg: string; text: string }> = {\n blue: { bg: 'var(--color-blue-1)', text: 'var(--color-blue-7)' },\n green: { bg: 'var(--color-green-1)', text: 'var(--color-green-7)' },\n 'deep-orange': { bg: 'var(--color-deep-orange-1)', text: 'var(--color-deep-orange-7)' },\n yellow: { bg: 'var(--color-yellow-1)', text: 'var(--color-yellow-7)' },\n red: { bg: 'var(--color-red-1)', text: 'var(--color-red-7)' },\n orange: { bg: 'var(--color-orange-1)', text: 'var(--color-orange-7)' },\n amber: { bg: 'var(--color-amber-1)', text: 'var(--color-amber-7)' },\n lime: { bg: 'var(--color-lime-1)', text: 'var(--color-lime-7)' },\n turquoise: { bg: 'var(--color-turquoise-1)', text: 'var(--color-turquoise-7)' },\n indigo: { bg: 'var(--color-indigo-1)', text: 'var(--color-indigo-7)' },\n purple: { bg: 'var(--color-purple-1)', text: 'var(--color-purple-7)' },\n magenta: { bg: 'var(--color-magenta-1)', text: 'var(--color-magenta-7)' },\n}\n// 同 CAT_SOLID 的文字分桶(白 / 深),raw token 版供 Avatar style 物件用。green = ★白字 exception。\nexport const CAT_SOLID_TOKENS: Record<CategoricalHue, { bg: string; text: string }> = {\n blue: { bg: 'var(--color-blue-6)', text: 'var(--on-emphasis)' },\n green: { bg: 'var(--color-green-6)', text: 'var(--on-emphasis)' }, // ★白字 documented exception\n 'deep-orange': { bg: 'var(--color-deep-orange-6)', text: 'var(--on-emphasis)' },\n yellow: { bg: 'var(--color-yellow-6)', text: 'var(--on-emphasis-dark)' },\n red: { bg: 'var(--color-red-6)', text: 'var(--on-emphasis)' },\n orange: { bg: 'var(--color-orange-6)', text: 'var(--on-emphasis-dark)' },\n amber: { bg: 'var(--color-amber-6)', text: 'var(--on-emphasis-dark)' },\n lime: { bg: 'var(--color-lime-6)', text: 'var(--on-emphasis-dark)' },\n turquoise: { bg: 'var(--color-turquoise-6)', text: 'var(--on-emphasis)' },\n indigo: { bg: 'var(--color-indigo-6)', text: 'var(--on-emphasis)' },\n purple: { bg: 'var(--color-purple-6)', text: 'var(--on-emphasis)' },\n magenta: { bg: 'var(--color-magenta-6)', text: 'var(--on-emphasis)' },\n}\n\n/* Calendar event tile:subtle 底 + hover step-2(1:1)。 /\nexport const CAT_EVENT: Record<CategoricalHue, string> = {\n blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)] hover:bg-[var(--color-blue-2)]',\n green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)] hover:bg-[var(--color-green-2)]',\n 'deep-orange': 'bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)] hover:bg-[var(--color-deep-orange-2)]',\n yellow: 'bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)] hover:bg-[var(--color-yellow-2)]',\n red: 'bg-[var(--color-red-1)] text-[var(--color-red-7)] hover:bg-[var(--color-red-2)]',\n orange: 'bg-[var(--color-orange-1)] text-[var(--color-orange-7)] hover:bg-[var(--color-orange-2)]',\n amber: 'bg-[var(--color-amber-1)] text-[var(--color-amber-7)] hover:bg-[var(--color-amber-2)]',\n lime: 'bg-[var(--color-lime-1)] text-[var(--color-lime-7)] hover:bg-[var(--color-lime-2)]',\n turquoise: 'bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)] hover:bg-[var(--color-turquoise-2)]',\n indigo: 'bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)] hover:bg-[var(--color-indigo-2)]',\n purple: 'bg-[var(--color-purple-1)] text-[var(--color-purple-7)] hover:bg-[var(--color-purple-2)]',\n magenta: 'bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)] hover:bg-[var(--color-magenta-2)]',\n}\n\n/* Calendar all-day accent:左側 step-6 實心條。 */\nexport const CAT_ACCENT: Record<CategoricalHue, string> = {\n blue: 'border-l-[3px] border-[var(--color-blue-6)]',\n green: 'border-l-[3px] border-[var(--color-green-6)]',\n 'deep-orange': 'border-l-[3px] border-[var(--color-deep-orange-6)]',\n yellow: 'border-l-[3px] border-[var(--color-yellow-6)]',\n red: 'border-l-[3px] border-[var(--color-red-6)]',\n orange: 'border-l-[3px] border-[var(--color-orange-6)]',\n amber: 'border-l-[3px] border-[var(--color-amber-6)]',\n lime: 'border-l-[3px] border-[var(--color-lime-6)]',\n turquoise: 'border-l-[3px] border-[var(--color-turquoise-6)]',\n indigo: 'border-l-[3px] border-[var(--color-indigo-6)]',\n purple: 'border-l-[3px] border-[var(--color-purple-6)]',\n magenta: 'border-l-[3px] border-[var(--color-magenta-6)]',\n}\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"categorical-color.js","sources":["../../src/tokens/categorical-color.ts"],"sourcesContent":["/*\n categorical-color.ts — Categorical 色相 SSOT(2026-06-04 codify)\n \n Tag / Avatar / Calendar 等「以色相做分類標籤」的元件,色彩 variant 一律消費此 SSOT。\n * 目的:variant 名 == primitive 色相名,1:1,零 offset —— 根治「red variant 接到 deep-orange」\n * 這類 categorical-vs-semantic 混淆(2026-06-04 user 抓:red = 品牌紅 hue-25〔--brand #DF3232 同族〕\n * ≠ deep-orange hue-38 ≠ semantic --error〔= deep-orange〕。三者完全無關)。\n \n 世界級對照:\n * - Ant Design Tag preset colors —— 用原始色相名(red/orange/green/blue…)做 categorical labeling\n * (https://ant.design/components/tag/)。本 DS Tag/Avatar 採此模型。\n * - Atlassian Color 原則 —— categorical(裝飾)色 vs semantic(狀態)色必須分離\n * (https://atlassian.design/foundations/color):categorical `red` 用 `--color-red-`,跟 semantic\n `--error`(= deep-orange)無關;把 error 色拿來當 categorical 標籤 = 反 pattern。\n \n ⚠️ Tailwind v4 掃描限制:class 字串必須以字面形式出現在被掃描的 source(本檔在 src/,會被掃),\n * 不可用 runtime function 拼字串(否則 `bg-[var(--color-orange-1)]` 不被生成 → silent 失效)。\n * 故本 SSOT 以字面 const map 提供;consumer `import` 後索引(cva 列 key 取值,保 VariantProps 型別)。\n \n 互動 state(solid dismiss hover/active)用 semantic `--{hue}-hover` / `--{hue}-active`\n * (dark-mode 方向 pre-computed,不可用 primitive step-5,否則 dark mode 反向)。12 色相皆已定義。\n \n 加色相:加進 `CATEGORICAL_HUES` + 下列 5 個 map 各補一行字面值(key X 用 `--color-X-`,1:1)。\n 機械防線:`scripts/categorical-color-invariants.mjs` I1(release:preflight 已 chain)強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset;原引 hook 名不存在,2026-07-04 修)。\n /\n\n/* 12 個 categorical 色相(順序對齊 primitives.css / Storybook color token 列)。 /\nexport const CATEGORICAL_HUES = [\n 'blue',\n 'green',\n 'deep-orange',\n 'yellow',\n 'red',\n 'orange',\n 'amber',\n 'lime',\n 'turquoise',\n 'indigo',\n 'purple',\n 'magenta',\n] as const\n\nexport type CategoricalHue = (typeof CATEGORICAL_HUES)[number]\n\n/* neutral 不是色相(無 hue),用 secondary/foreground + neutral-9 solid,各 consumer 自處理(不在下列 map)。 /\nexport type CategoricalColor = CategoricalHue \| 'neutral'\n\n/* subtle 模式 class:step-1 底 + step-7 字。key X 一律對 `--color-X-`(1:1)。 /\nexport const CAT_SUBTLE: Record<CategoricalHue, string> = {\n blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)]',\n green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)]',\n 'deep-orange': 'bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)]',\n yellow: 'bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)]',\n red: 'bg-[var(--color-red-1)] text-[var(--color-red-7)]',\n orange: 'bg-[var(--color-orange-1)] text-[var(--color-orange-7)]',\n amber: 'bg-[var(--color-amber-1)] text-[var(--color-amber-7)]',\n lime: 'bg-[var(--color-lime-1)] text-[var(--color-lime-7)]',\n turquoise: 'bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)]',\n indigo: 'bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)]',\n purple: 'bg-[var(--color-purple-1)] text-[var(--color-purple-7)]',\n magenta: 'bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)]',\n}\n\n/*\n solid 模式 class:step-6 底 + on-emphasis 配對文字。\n * 文字色依「step-6 底亮度」分桶(WCAG ≥3:1 大粗字門檻,2026-06-04 user「以最低為原則」):\n * - 夠深的色底 → `text-on-emphasis`(白):blue / deep-orange / red / turquoise / indigo / purple / magenta\n * - 太亮的色底 → `text-on-emphasis-dark`(深):yellow / amber / orange / lime(白字連 3:1 都不過)\n * - ★ green 例外:白字 2.47 連 3:1 都不過,但 user 拍板維持白字(綠底白字慣見觀感)= documented exception。\n * 對比為 oklch→相對亮度實測(scripts/categorical-color-invariants.mjs 機械驗,green 列 exempt)。\n /\nexport const CAT_SOLID: Record<CategoricalHue, string> = {\n blue: 'bg-[var(--color-blue-6)] text-on-emphasis',\n green: 'bg-[var(--color-green-6)] text-on-emphasis', // ★白字 documented exception(實測 2.47 < 3:1)\n 'deep-orange': 'bg-[var(--color-deep-orange-6)] text-on-emphasis',\n yellow: 'bg-[var(--color-yellow-6)] text-on-emphasis-dark',\n red: 'bg-[var(--color-red-6)] text-on-emphasis',\n orange: 'bg-[var(--color-orange-6)] text-on-emphasis-dark',\n amber: 'bg-[var(--color-amber-6)] text-on-emphasis-dark',\n lime: 'bg-[var(--color-lime-6)] text-on-emphasis-dark',\n turquoise: 'bg-[var(--color-turquoise-6)] text-on-emphasis',\n indigo: 'bg-[var(--color-indigo-6)] text-on-emphasis',\n purple: 'bg-[var(--color-purple-6)] text-on-emphasis',\n magenta: 'bg-[var(--color-magenta-6)] text-on-emphasis',\n}\n\n/* solid 互動(dismiss hover/active)— semantic dark-mode-aware token。 /\nexport const CAT_INTERACT: Record<CategoricalHue, { hover: string; active: string }> = {\n blue: { hover: 'var(--blue-hover)', active: 'var(--blue-active)' },\n green: { hover: 'var(--green-hover)', active: 'var(--green-active)' },\n 'deep-orange': { hover: 'var(--deep-orange-hover)', active: 'var(--deep-orange-active)' },\n yellow: { hover: 'var(--yellow-hover)', active: 'var(--yellow-active)' },\n red: { hover: 'var(--red-hover)', active: 'var(--red-active)' },\n orange: { hover: 'var(--orange-hover)', active: 'var(--orange-active)' },\n amber: { hover: 'var(--amber-hover)', active: 'var(--amber-active)' },\n lime: { hover: 'var(--lime-hover)', active: 'var(--lime-active)' },\n turquoise: { hover: 'var(--turquoise-hover)', active: 'var(--turquoise-active)' },\n indigo: { hover: 'var(--indigo-hover)', active: 'var(--indigo-active)' },\n purple: { hover: 'var(--purple-hover)', active: 'var(--purple-active)' },\n magenta: { hover: 'var(--magenta-hover)', active: 'var(--magenta-active)' },\n}\n\n/* Avatar style 物件用:subtle / solid 的 raw token { bg, text }(非 class)。 /\nexport const CAT_SUBTLE_TOKENS: Record<CategoricalHue, { bg: string; text: string }> = {\n blue: { bg: 'var(--color-blue-1)', text: 'var(--color-blue-7)' },\n green: { bg: 'var(--color-green-1)', text: 'var(--color-green-7)' },\n 'deep-orange': { bg: 'var(--color-deep-orange-1)', text: 'var(--color-deep-orange-7)' },\n yellow: { bg: 'var(--color-yellow-1)', text: 'var(--color-yellow-7)' },\n red: { bg: 'var(--color-red-1)', text: 'var(--color-red-7)' },\n orange: { bg: 'var(--color-orange-1)', text: 'var(--color-orange-7)' },\n amber: { bg: 'var(--color-amber-1)', text: 'var(--color-amber-7)' },\n lime: { bg: 'var(--color-lime-1)', text: 'var(--color-lime-7)' },\n turquoise: { bg: 'var(--color-turquoise-1)', text: 'var(--color-turquoise-7)' },\n indigo: { bg: 'var(--color-indigo-1)', text: 'var(--color-indigo-7)' },\n purple: { bg: 'var(--color-purple-1)', text: 'var(--color-purple-7)' },\n magenta: { bg: 'var(--color-magenta-1)', text: 'var(--color-magenta-7)' },\n}\n// 同 CAT_SOLID 的文字分桶(白 / 深),raw token 版供 Avatar style 物件用。green = ★白字 exception。\nexport const CAT_SOLID_TOKENS: Record<CategoricalHue, { bg: string; text: string }> = {\n blue: { bg: 'var(--color-blue-6)', text: 'var(--on-emphasis)' },\n green: { bg: 'var(--color-green-6)', text: 'var(--on-emphasis)' }, // ★白字 documented exception\n 'deep-orange': { bg: 'var(--color-deep-orange-6)', text: 'var(--on-emphasis)' },\n yellow: { bg: 'var(--color-yellow-6)', text: 'var(--on-emphasis-dark)' },\n red: { bg: 'var(--color-red-6)', text: 'var(--on-emphasis)' },\n orange: { bg: 'var(--color-orange-6)', text: 'var(--on-emphasis-dark)' },\n amber: { bg: 'var(--color-amber-6)', text: 'var(--on-emphasis-dark)' },\n lime: { bg: 'var(--color-lime-6)', text: 'var(--on-emphasis-dark)' },\n turquoise: { bg: 'var(--color-turquoise-6)', text: 'var(--on-emphasis)' },\n indigo: { bg: 'var(--color-indigo-6)', text: 'var(--on-emphasis)' },\n purple: { bg: 'var(--color-purple-6)', text: 'var(--on-emphasis)' },\n magenta: { bg: 'var(--color-magenta-6)', text: 'var(--on-emphasis)' },\n}\n\n/* Calendar event tile:subtle 底 + hover step-2(1:1)。 /\nexport const CAT_EVENT: Record<CategoricalHue, string> = {\n blue: 'bg-[var(--color-blue-1)] text-[var(--color-blue-7)] hover:bg-[var(--color-blue-2)]',\n green: 'bg-[var(--color-green-1)] text-[var(--color-green-7)] hover:bg-[var(--color-green-2)]',\n 'deep-orange': 'bg-[var(--color-deep-orange-1)] text-[var(--color-deep-orange-7)] hover:bg-[var(--color-deep-orange-2)]',\n yellow: 'bg-[var(--color-yellow-1)] text-[var(--color-yellow-7)] hover:bg-[var(--color-yellow-2)]',\n red: 'bg-[var(--color-red-1)] text-[var(--color-red-7)] hover:bg-[var(--color-red-2)]',\n orange: 'bg-[var(--color-orange-1)] text-[var(--color-orange-7)] hover:bg-[var(--color-orange-2)]',\n amber: 'bg-[var(--color-amber-1)] text-[var(--color-amber-7)] hover:bg-[var(--color-amber-2)]',\n lime: 'bg-[var(--color-lime-1)] text-[var(--color-lime-7)] hover:bg-[var(--color-lime-2)]',\n turquoise: 'bg-[var(--color-turquoise-1)] text-[var(--color-turquoise-7)] hover:bg-[var(--color-turquoise-2)]',\n indigo: 'bg-[var(--color-indigo-1)] text-[var(--color-indigo-7)] hover:bg-[var(--color-indigo-2)]',\n purple: 'bg-[var(--color-purple-1)] text-[var(--color-purple-7)] hover:bg-[var(--color-purple-2)]',\n magenta: 'bg-[var(--color-magenta-1)] text-[var(--color-magenta-7)] hover:bg-[var(--color-magenta-2)]',\n}\n\n/* Calendar all-day accent:左側 step-6 實心條。 */\nexport const CAT_ACCENT: Record<CategoricalHue, string> = {\n blue: 'border-l-[3px] border-[var(--color-blue-6)]',\n green: 'border-l-[3px] border-[var(--color-green-6)]',\n 'deep-orange': 'border-l-[3px] border-[var(--color-deep-orange-6)]',\n yellow: 'border-l-[3px] border-[var(--color-yellow-6)]',\n red: 'border-l-[3px] border-[var(--color-red-6)]',\n orange: 'border-l-[3px] border-[var(--color-orange-6)]',\n amber: 'border-l-[3px] border-[var(--color-amber-6)]',\n lime: 'border-l-[3px] border-[var(--color-lime-6)]',\n turquoise: 'border-l-[3px] border-[var(--color-turquoise-6)]',\n indigo: 'border-l-[3px] border-[var(--color-indigo-6)]',\n purple: 'border-l-[3px] border-[var(--color-purple-6)]',\n magenta: 'border-l-[3px] border-[var(--color-magenta-6)]',\n}\n"],"names":[],"mappings":"AAgDO,MAAM,aAA6C;AAAA,EACxD,MAAM;AAAA,EACN,OAAO;AAAA,EACP,eAAe;AAAA,EACf,QAAQ;AAAA,EACR,KAAK;AAAA,EACL,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;AAUO,MAAM,YAA4C;AAAA,EACvD,MAAM;AAAA,EACN,OAAO;AAAA;AAAA,EACP,eAAe;AAAA,EACf,QAAQ;AAAA,EACR,KAAK;AAAA,EACL,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;AAGO,MAAM,eAA0E;AAAA,EACrF,MAAM,EAAE,OAAO,qBAAqB,QAAQ,qBAAA;AAAA,EAC5C,OAAO,EAAE,OAAO,sBAAsB,QAAQ,sBAAA;AAAA,EAC9C,eAAe,EAAE,OAAO,4BAA4B,QAAQ,4BAAA;AAAA,EAC5D,QAAQ,EAAE,OAAO,uBAAuB,QAAQ,uBAAA;AAAA,EAChD,KAAK,EAAE,OAAO,oBAAoB,QAAQ,oBAAA;AAAA,EAC1C,QAAQ,EAAE,OAAO,uBAAuB,QAAQ,uBAAA;AAAA,EAChD,OAAO,EAAE,OAAO,sBAAsB,QAAQ,sBAAA;AAAA,EAC9C,MAAM,EAAE,OAAO,qBAAqB,QAAQ,qBAAA;AAAA,EAC5C,WAAW,EAAE,OAAO,0BAA0B,QAAQ,0BAAA;AAAA,EACtD,QAAQ,EAAE,OAAO,uBAAuB,QAAQ,uBAAA;AAAA,EAChD,QAAQ,EAAE,OAAO,uBAAuB,QAAQ,uBAAA;AAAA,EAChD,SAAS,EAAE,OAAO,wBAAwB,QAAQ,wBAAA;AACpD;AAGO,MAAM,oBAA0E;AAAA,EACrF,MAAM,EAAE,IAAI,uBAAuB,MAAM,sBAAA;AAAA,EACzC,OAAO,EAAE,IAAI,wBAAwB,MAAM,uBAAA;AAAA,EAC3C,eAAe,EAAE,IAAI,8BAA8B,MAAM,6BAAA;AAAA,EACzD,QAAQ,EAAE,IAAI,yBAAyB,MAAM,wBAAA;AAAA,EAC7C,KAAK,EAAE,IAAI,sBAAsB,MAAM,qBAAA;AAAA,EACvC,QAAQ,EAAE,IAAI,yBAAyB,MAAM,wBAAA;AAAA,EAC7C,OAAO,EAAE,IAAI,wBAAwB,MAAM,uBAAA;AAAA,EAC3C,MAAM,EAAE,IAAI,uBAAuB,MAAM,sBAAA;AAAA,EACzC,WAAW,EAAE,IAAI,4BAA4B,MAAM,2BAAA;AAAA,EACnD,QAAQ,EAAE,IAAI,yBAAyB,MAAM,wBAAA;AAAA,EAC7C,QAAQ,EAAE,IAAI,yBAAyB,MAAM,wBAAA;AAAA,EAC7C,SAAS,EAAE,IAAI,0BAA0B,MAAM,yBAAA;AACjD;AAEO,MAAM,mBAAyE;AAAA,EACpF,MAAM,EAAE,IAAI,uBAAuB,MAAM,qBAAA;AAAA,EACzC,OAAO,EAAE,IAAI,wBAAwB,MAAM,qBAAA;AAAA;AAAA,EAC3C,eAAe,EAAE,IAAI,8BAA8B,MAAM,qBAAA;AAAA,EACzD,QAAQ,EAAE,IAAI,yBAAyB,MAAM,0BAAA;AAAA,EAC7C,KAAK,EAAE,IAAI,sBAAsB,MAAM,qBAAA;AAAA,EACvC,QAAQ,EAAE,IAAI,yBAAyB,MAAM,0BAAA;AAAA,EAC7C,OAAO,EAAE,IAAI,wBAAwB,MAAM,0BAAA;AAAA,EAC3C,MAAM,EAAE,IAAI,uBAAuB,MAAM,0BAAA;AAAA,EACzC,WAAW,EAAE,IAAI,4BAA4B,MAAM,qBAAA;AAAA,EACnD,QAAQ,EAAE,IAAI,yBAAyB,MAAM,qBAAA;AAAA,EAC7C,QAAQ,EAAE,IAAI,yBAAyB,MAAM,qBAAA;AAAA,EAC7C,SAAS,EAAE,IAAI,0BAA0B,MAAM,qBAAA;AACjD;AAGO,MAAM,YAA4C;AAAA,EACvD,MAAM;AAAA,EACN,OAAO;AAAA,EACP,eAAe;AAAA,EACf,QAAQ;AAAA,EACR,KAAK;AAAA,EACL,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;AAGO,MAAM,aAA6C;AAAA,EACxD,MAAM;AAAA,EACN,OAAO;AAAA,EACP,eAAe;AAAA,EACf,QAAQ;AAAA,EACR,KAAK;AAAA,EACL,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;"}

package/dist/tokens/uiSize/icon-size.d.ts CHANGED Viewed

@@ -17,7 +17,7 @@
  * `field-height-xs / sm / md` → icon **16px**
  * `field-height-lg`           → icon **20px**
  *
- * 詳 spec L132+ Icon Size Tier 段(stroke 下限 12px / Tag-Field 配對 / etc.)
+ * 詳 uiSize.spec.md「Icon 尺寸 Tier」段(段名指法免行號漂移;stroke 下限 12px / Tag-Field 配對 / etc.)
  *
  * ── Consumer 用法 ──
  * ```tsx
@@ -26,7 +26,7 @@
  * // sm/md → 16, lg → 20
  * <LucideIcon size={ICON_SIZE[size]} />
  *
- * // form control xs(field-height-xs 24)用 ICON_SIZE.sm(同 16,per spec L132 Tier)
+ * // form control xs(field-height-xs 24)用 ICON_SIZE.sm(同 16,per uiSize.spec.md「Icon 尺寸 Tier」段)
  * <LucideIcon size={size === 'xs' ? ICON_SIZE.sm : ICON_SIZE[size]} />
  * ```
  *

package/ds-canonical/fork/governance.lock CHANGED Viewed

@@ -57,7 +57,7 @@
     },
     {
       "file": "hooks/check_opacity_token_usage.sh",
-      "sha256": "1772e83242520f569a9a44e96d08d74e121c119c940c019c8ed50989f14de646",
+      "sha256": "f085fdf2b681f6ad20a51863ca580f4c56633091f0b044e05cf1b9ef665fdf0d",
       "sourceHook": "check_opacity_token_usage.sh",
       "bucket": "SHIP_REWRITTEN"
     },

package/ds-canonical/fork/hooks/check_opacity_token_usage.sh CHANGED Viewed

@@ -11,7 +11,7 @@ set -uo pipefail
 # 檢的 block category:
 #   - opacity:opacity-{5..95} numeric tier(原 logic,保留)
 #   - typography:text-{xs..9xl} / font-{thin|light|semibold|black} / leading-{N} numeric / tracking-{wide..widest|tighter|tight}
-#   - radius:rounded-{xl|2xl|3xl} / rounded(unscoped)
+#   - radius:rounded-{xl|2xl|3xl} / rounded(unscoped)/ rounded-[...] arbitrary(例外 rounded-[inherit])
 #   - elevation:shadow-{sm|md|lg|xl|2xl|inner} / shadow(unscoped)
 #   - shadcn alias:bg-popover / text-muted-foreground / bg-accent 等
 #   - primitive 色名:bg-neutral-N / text-blue-N 等(越過 semantic 層)
@@ -105,6 +105,14 @@ if [ -n "$HITS_RADIUS" ]; then
   VIOLATIONS="${VIOLATIONS}\n   [radius out-of-range] $(echo "$HITS_RADIUS" | tr '\n' ' ')"
 fi
+# 6b) Radius arbitrary bracket(2026-07-04 dim 47 補洞:registry block arbitrary_value 但 hook 從沒偵測)
+#     rounded-[6px] / rounded-[var(--radius-md)] / rounded-t-[...] 皆 block;
+#     唯一例外 rounded-[inherit](registry radius.allow,passthrough 非 radius 值,anchor scroll-area.tsx Viewport)
+HITS_RADIUS_ARB=$(echo "$NEW_CONTENT" | grep -oE "\brounded(-(t|b|l|r|tl|tr|bl|br|s|e|ss|se|es|ee))?-\[[^]]+\]" | grep -v "rounded-\[inherit\]" | sort -u || true)
+if [ -n "$HITS_RADIUS_ARB" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [radius arbitrary] $(echo "$HITS_RADIUS_ARB" | tr '\n' ' ')"
+fi
 # 7) Shadow Tailwind size(shadow-sm/md/lg/xl/2xl/inner — DS 用 shadow-[var(--elevation-N)] N∈{100,200})
 HITS_SHADOW=$(echo "$NEW_CONTENT" | grep -oE "\bshadow-(sm|md|lg|xl|2xl|inner)\b" | sort -u || true)
 if [ -n "$HITS_SHADOW" ]; then
@@ -138,6 +146,7 @@ EOF_HEAD
      leading-{N}   → leading-compact / leading-normal
      tracking-*    → tracking-shortcut(or codify role-specific semantic utility)
      rounded-xl..  → rounded-xs..rounded-lg / rounded-full
+     rounded-[..]  → rounded-xs..lg 語意 utility(rounded-[inherit] 唯一例外,registry allow)
      shadow-sm..   → shadow-[var(--elevation-100)] / shadow-[var(--elevation-200)]
      bg-popover .. → direct semantic token(--surface-raised / --fg-muted / --error 等)
      bg-neutral-N  → semantic utility(bg-surface 等)或 bg-[var(--color-neutral-N)]

package/ds-canonical/hooks/check_audit_post_report_validator.sh CHANGED Viewed

@@ -106,6 +106,19 @@ if [ "$DIM_COUNT" -ge 10 ]; then   # 只對 full/deep-audit 規模 report 要求
     WARNINGS="${WARNINGS}\n  🔴 [G] PURE-JUDGMENT dim 真跑證據不足:report 只 ${EVIDENCE_COUNT} 個 per-dim 證據 marker < ${PJ_COUNT} judgment dim(含 infra 62/66/68/72)。judgment dim 無 script/hook 兜底,必每 dim show『DS-wide N files scanned + file:line / 0-after-全掃』證據,否則=mention-only 偷懶。補齊再出 report。"
     TRIGGER_PRUNE=1; CRITICAL_FAIL=1
   fi
+  # ─ Validator I: D3/D4/D5 domain-skill chain invocation evidence(2026-07-04 solo-run 偏差 anchor:
+  #   稽核 canonical 6-維度表 D3→/performance-audit、D4→/ux-audit、D5→/visual-audit,但歷次 deep run
+  #   performance-audit 0 次 invoke = chain 缺席沒任何機械閘抓。deep-scale report 必含三 skill 名
+  #   (= 有 chain 或有明寫 N/A 豁免理由;mention 缺席即偷懶 risk)─
+  _D345_MISSING=""
+  for _sk in performance-audit ux-audit visual-audit; do
+    grep -q "$_sk" "$FILE_PATH" 2>/dev/null || _D345_MISSING="${_D345_MISSING} ${_sk}"
+  done
+  if [ -n "$_D345_MISSING" ]; then
+    WARNINGS="${WARNINGS}\n  🔴 [I] D3/D4/D5 domain-skill chain 證據缺席:report 未提及${_D345_MISSING}。稽核 canonical 6-維度表(CLAUDE.md)deep 規模必 chain 三 domain skill(或明寫豁免理由 + skill 名)。補跑/補記再出 report。"
+    TRIGGER_PRUNE=1; CRITICAL_FAIL=1
+  fi
 fi
 # ─ Validator BLOCK gate(2026-05-31 fix infra-audit self-finding:原 hook 只 exit 0 + additionalContext

package/ds-canonical/hooks/check_full_story_visual_interaction_sweep.sh CHANGED Viewed

@@ -1,15 +1,16 @@
 #!/bin/bash
 # check_full_story_visual_interaction_sweep.sh — P0 BLOCKER
 #
-# Codex M31 P0 finding 2026-05-27: ds-story-manifest.json 是 62-component / 916-story
-# SSOT,但無 hook 攔 audit reports 漏 manifest story IDs / screenshots / metrics / probe.
+# Codex M31 P0 finding 2026-05-27: ds-story-manifest.json 是 story 總數 SSOT(動態,
+# 禁 hardcode 數字 — 真值以 manifest.totalStories 為準;2026-07-04 dim 73 修 stale 916),
+# 但無 hook 攔 audit reports 漏 manifest story IDs / screenshots / metrics / probe.
 # User 2026-05-27 verbatim「不准抽樣 全 visual + interaction 全跑」.
 #
 # Triggers when audit report JSON is edited/written:
 #   - /tmp/codex-*-sweep/audit-report.json
 #   - /tmp/claude-*-sweep/audit-report.json
 #   - .claude/snapshots/*audit-report.json
-# Verifies storyResults.length === manifest.totalStories (916) — block if sample.
+# Verifies storyResults.length === manifest.totalStories(動態讀 manifest)— block if sample.
 #
 # Escape: report frontmatter `"_sampling_allowed": "<rationale>"`(極罕見).

package/ds-canonical/hooks/check_opacity_token_usage.sh CHANGED Viewed

@@ -11,7 +11,7 @@ set -uo pipefail
 # 檢的 block category:
 #   - opacity:opacity-{5..95} numeric tier(原 logic,保留)
 #   - typography:text-{xs..9xl} / font-{thin|light|semibold|black} / leading-{N} numeric / tracking-{wide..widest|tighter|tight}
-#   - radius:rounded-{xl|2xl|3xl} / rounded(unscoped)
+#   - radius:rounded-{xl|2xl|3xl} / rounded(unscoped)/ rounded-[...] arbitrary(例外 rounded-[inherit])
 #   - elevation:shadow-{sm|md|lg|xl|2xl|inner} / shadow(unscoped)
 #   - shadcn alias:bg-popover / text-muted-foreground / bg-accent 等
 #   - primitive 色名:bg-neutral-N / text-blue-N 等(越過 semantic 層)
@@ -105,6 +105,14 @@ if [ -n "$HITS_RADIUS" ]; then
   VIOLATIONS="${VIOLATIONS}\n   [radius out-of-range] $(echo "$HITS_RADIUS" | tr '\n' ' ')"
 fi
+# 6b) Radius arbitrary bracket(2026-07-04 dim 47 補洞:registry block arbitrary_value 但 hook 從沒偵測)
+#     rounded-[6px] / rounded-[var(--radius-md)] / rounded-t-[...] 皆 block;
+#     唯一例外 rounded-[inherit](registry radius.allow,passthrough 非 radius 值,anchor scroll-area.tsx Viewport)
+HITS_RADIUS_ARB=$(echo "$NEW_CONTENT" | grep -oE "\brounded(-(t|b|l|r|tl|tr|bl|br|s|e|ss|se|es|ee))?-\[[^]]+\]" | grep -v "rounded-\[inherit\]" | sort -u || true)
+if [ -n "$HITS_RADIUS_ARB" ]; then
+  VIOLATIONS="${VIOLATIONS}\n   [radius arbitrary] $(echo "$HITS_RADIUS_ARB" | tr '\n' ' ')"
+fi
 # 7) Shadow Tailwind size(shadow-sm/md/lg/xl/2xl/inner — DS 用 shadow-[var(--elevation-N)] N∈{100,200})
 HITS_SHADOW=$(echo "$NEW_CONTENT" | grep -oE "\bshadow-(sm|md|lg|xl|2xl|inner)\b" | sort -u || true)
 if [ -n "$HITS_SHADOW" ]; then
@@ -138,6 +146,7 @@ EOF_HEAD
      leading-{N}   → leading-compact / leading-normal
      tracking-*    → tracking-shortcut(or codify role-specific semantic utility)
      rounded-xl..  → rounded-xs..rounded-lg / rounded-full
+     rounded-[..]  → rounded-xs..lg 語意 utility(rounded-[inherit] 唯一例外,registry allow)
      shadow-sm..   → shadow-[var(--elevation-100)] / shadow-[var(--elevation-200)]
      bg-popover .. → direct semantic token(--surface-raised / --fg-muted / --error 等)
      bg-neutral-N  → semantic utility(bg-surface 等)或 bg-[var(--color-neutral-N)]

package/ds-canonical/hooks/check_plugin_fork_health.sh CHANGED Viewed

@@ -30,49 +30,57 @@ if ! grep -q '"@qijenchen/design-system"' "$CWD/package.json" 2>/dev/null; then
   exit 0
 fi
-# (c) Plugin 已安裝?Anthropic plugin install 可能使用 <plugin> 或
-# <plugin>@<marketplace> directory name;accept both.
-PLUGIN_INSTALLED=0
-# 2026-05-31 fix(infra-audit P1):真實 Claude Code layout = ~/.claude/plugins/marketplaces/<name>/
-# + known_marketplaces.json(keyed by marketplace name)。原查 plugins/design-system + 錯的
-# .claude/marketplaces(漏 plugins/)= 裝了仍誤判未裝。marketplace name = qijenchen-ds。
+# (c) C-prime committed 治理鏈健康?(2026-07-04 dim 58 對齊:主路徑 = committed-config + npm,
+# 免 plugin — 2026-06-17 C-prime 改版,plugin 路線不可靠 per memory reference_cloud_governance_loading)
+# dispatcher(committed 啟動器)+ manifest(npm ship 治理本體)都在 → 官方 fork hooks 會 fire → 健康。
+DISPATCHER="$CWD/.claude/hooks/fork-governance-dispatcher.sh"
+MANIFEST="$CWD/node_modules/@qijenchen/design-system/ds-canonical/fork/manifest.json"
+if [ -f "$DISPATCHER" ] && [ -f "$MANIFEST" ]; then
+  exit 0
+fi
+# (d) Legacy plugin 路線仍裝著 → 治理可 cross-load,不 nag(marketplaces layout per 2026-05-31 fix)。
 MARKETPLACE="qijenchen-ds"
 KM="$HOME/.claude/plugins/known_marketplaces.json"
+PLUGIN_INSTALLED=0
 [ -d "$HOME/.claude/plugins/marketplaces/$MARKETPLACE" ] && PLUGIN_INSTALLED=1
 [ -d "$CWD/.claude/plugins/marketplaces/$MARKETPLACE" ] && PLUGIN_INSTALLED=1
 { [ -f "$KM" ] && grep -q "\"$MARKETPLACE\"" "$KM"; } && PLUGIN_INSTALLED=1
-# legacy / 舊 layout fallback
 [ -d "$HOME/.claude/plugins/design-system" ] && PLUGIN_INSTALLED=1
 [ -d "$CWD/.claude/plugins/design-system" ] && PLUGIN_INSTALLED=1
-if [ "$PLUGIN_INSTALLED" = "1" ]; then
-  exit 0
+[ "$PLUGIN_INSTALLED" = "1" ] && exit 0
+# 治理鏈缺失 → context inject(SessionStart additional context),修法 = npm(免 plugin)
+if [ -f "$DISPATCHER" ]; then
+  MISSING_DESC="接線骨架(dispatcher)已 commit ✅,但治理本體 manifest 不在 node_modules ❌(還沒 npm install)"
+  FIX_CMD="npm install   # 治理本體隨 @qijenchen/design-system ship,裝完 dispatcher 自動跑官方 fork hooks"
+else
+  MISSING_DESC="C-prime 接線骨架(.claude/hooks/fork-governance-dispatcher.sh)不存在 ❌(fork 尚未 adopt C-prime)"
+  FIX_CMD="npm run sync-all   # 從 npm 刷新 committed 啟動器 + settings + skills 骨架;首次啟用只需 npm install"
 fi
-# All YES → fork-user 沒裝 plugin → context inject(SessionStart additional context)
 cat <<EOF
-🚨 Fork-user plugin not installed — DS governance hooks 不會 fire,憑記憶寫 mock 不會被攔。
+🚨 Fork-user DS 治理鏈未就位 — 官方 fork governance hooks 不會 fire,憑記憶寫 mock 不會被攔。
 偵測:
   cwd = $CWD
   package.json 含 @qijenchen/design-system dep ✅
-  ~/.claude/plugins/design-system@qijenchen-ds/ 或 .claude/plugins/design-system@qijenchen-ds/ 不存在 ❌
+  $MISSING_DESC
 → 後果(2026-05-26 anchor event):憑記憶寫 App.tsx mock(漏 SidebarTrigger / collapsible / startIcon /
   tooltip / SidebarFooter)= production-grade fork-user 跑版 anti-pattern。
-修法:**session 開始第一件事必跑**
-  1. \`/plugin marketplace add github:ajenchen/design-system\`
-  2. \`/plugin install design-system@qijenchen-ds\`(or 對應 plugin name per marketplace.json)
+修法(**session 開始第一件事,終端跑 1 條;免 /plugin install**):
+  $FIX_CMD
-跑完 plugin install 後:
-  - 59 個 DS governance hooks 自動 fire(M29 anchor preflight / approval-preflight / story_invariants / inject_deploy_url_after_push 等;count snapshot 2026-05-29)
-  - DS canonical / rules / skills 從 ~/.claude/plugins/ 可 cross-load
-  - Fork-user 寫 App.tsx 時憑記憶寫 mock 會被 mechanical BLOCKER 攔
+就位後:
+  - fork-governance-dispatcher.sh 每 event 讀 node_modules 官方 manifest 跑全部 fork 治理 hooks(BLOCKER 會轉發攔截)
+  - DS canonical / rules / skills 從 node_modules/@qijenchen/design-system/ds-canonical/ cross-load
+  - 憑記憶寫 mock 會被 mechanical BLOCKER 攔
 對應 canonical:
-  - product-workspace CLAUDE.md「Fork-and-go onboarding」step 2-3
-  - .claude-plugin/marketplace.json
+  - template CLAUDE.md「🚀 Onboarding(C-prime)」段
+  - ds-canonical/fork/manifest.json(build-fork-governance.mjs 生成)
 EOF
 exit 0
 }