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

package/dist/patterns/element-anatomy/index.d.ts

@@ -0,0 +1,3 @@
+export * from './item-anatomy';
+export * from './truncated-text';
+//# sourceMappingURL=index.d.ts.map

package/dist/patterns/element-anatomy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/patterns/element-anatomy/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA"}

package/dist/patterns/element-anatomy/index.js

@@ -0,0 +1,22 @@
+import { AVATAR_SIZE, ICON_SIZE, INLINE_ACTION_HOVER_BG_SIZE, ItemAvatar, ItemContent, ItemIcon, ItemInlineAction, ItemInlineActionButton, ItemLabel, ItemPrefix, ItemSuffix, ROW_PADDING_BY_SIZE, RowSizeProvider, getUniformPrefixSlotStyle, itemPrefixAlignVariants, useRowSize } from "./item-anatomy.js";
+import { TruncatedText } from "./truncated-text.js";
+export {
+  AVATAR_SIZE,
+  ICON_SIZE,
+  INLINE_ACTION_HOVER_BG_SIZE,
+  ItemAvatar,
+  ItemContent,
+  ItemIcon,
+  ItemInlineAction,
+  ItemInlineActionButton,
+  ItemLabel,
+  ItemPrefix,
+  ItemSuffix,
+  ROW_PADDING_BY_SIZE,
+  RowSizeProvider,
+  TruncatedText,
+  getUniformPrefixSlotStyle,
+  itemPrefixAlignVariants,
+  useRowSize
+};
+//# sourceMappingURL=index.js.map

package/dist/patterns/element-anatomy/index.js.map

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

package/dist/patterns/element-anatomy/item-anatomy.d.ts

@@ -49,18 +49,19 @@ export declare const ICON_SIZE: Record<RowSize, number>;
  * - **block**(有 description,avatar 跨越 label + desc 兩行)→ 對齊文字塊中心
  *   sm: 32, md: 32, lg: 40
  *
- * **用法**:所有 row primitive 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree
- * consumer)**必須**從本 module import 這個常數,**不可硬寫 `size={24}`**。
- * 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。
+ * **用法**:row context 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree
+ * consumer)**必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件(自動查
+ * RowSizeContext 對表),**禁止** `import { AVATAR_SIZE }` 手動查表、**不可硬寫
+ * `size={24}`** — 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。
+ * 詳 item-anatomy.spec.md「Helper 程式化封裝 + review 防線」段。
  *
  * ```tsx
- * import { AVATAR_SIZE } from "../../patterns/element-anatomy/item-anatomy"
+ * import { ItemAvatar } from "../../patterns/element-anatomy/item-anatomy"
  *
- * const { size } = useSidebar()  // RowSize
- * <Avatar size={AVATAR_SIZE.inline[size]} />
+ * <ItemAvatar alt="Alan" color="blue" />  // 自動查 AVATAR_SIZE.inline[rowSize]
  * ```
  *
- * Canonical 實作:`MenuItem` 的內部 `AVATAR_SIZE` 查表(即將 re-export 自此)。
+ * Canonical 消費者:MenuItem 直接 import 本檔 `AVATAR_SIZE`(menu-item.tsx,消費 .block/.inline;re-export 已完成,MenuItem 無內部查表)。
  */
 export declare const AVATAR_SIZE: {
     readonly inline: {
@@ -96,7 +97,7 @@ export declare function getUniformPrefixSlotStyle(size: RowSize): React.CSSPrope
 /**
  * Inline action(suffix 裡的 hover-action icon button)hover 背景尺寸(px)。
  * 規則:icon size + 2px(每邊 +1px,用 absolute positioning 溢出不影響排版)。
- * 對齊 `item-anatomy.spec.md`「Inline Action 設計規格」節。
+ * 對齊 `inline-action.spec.md`(canonical SSOT,2026-04-24 自 item-anatomy.spec 抽出)。
  */
 export declare const INLINE_ACTION_HOVER_BG_SIZE: Record<RowSize, number>;
 /**
@@ -157,7 +158,7 @@ export declare const ItemPrefix: React.ForwardRefExoticComponent<React.HTMLAttri
  * 直接用 `<ItemPrefix>` 就好,不需此 cva。
  *
  * ── SSOT 傳播 ──
- * gap 用 `var(--item-gap-label-desc)` token;font-size 用 token-awareness
+ * gap 用 `var(--item-gap-label-desc-scanning[-lg])` token(bare 變體已不存在,4 個 mode×size 變體);font-size 用 token-awareness
  * (`var(--font-caption-size)` / `var(--font-body-size)`)。改 token → 公式同步。
  */
 export declare const itemPrefixAlignVariants: (props?: ({
@@ -167,6 +168,7 @@ export declare const itemPrefixAlignVariants: (props?: ({
  * `<ItemLabel>` — Row primitive 的 label span。
  *
  * 預設 `min-w-0 flex-1 truncate`——單行截斷,佔滿剩餘 flex 空間。
+ * 截斷時 hover 顯 tooltip 補全(截斷才顯,tooltip.spec.md:32;內建,consumer 免自接)。
  * 加 `data-sidebar="menu-label"` attribute 讓 sidebar icon 模式的 CSS selector 能命中。
  *
  * 用法:
@@ -179,15 +181,20 @@ export declare const ItemLabel: React.ForwardRefExoticComponent<React.HTMLAttrib
  * `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。
  *
  * ── 存在的唯一理由 ──
- * 封裝「flex-col + label + description + `mt-[var(--item-gap-label-desc)]` gap」結構,
+ * 封裝「flex-col + label + description + canonical label/description gap」結構,
  * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。
  *
+ * ── 截斷 → tooltip(內建,consumer 免自接)──
+ * label(`truncate` 或 `line-clamp-1` escape)與單行截斷 description 在實際截斷時 hover 顯
+ * tooltip 補全(截斷才顯,tooltip.spec.md:32);多行 clamp(≥2 行)排除 —— 見
+ * `measureSingleLineClipped` 註解(truncated-text.spec.md「何時不用」(a))。
+ *
  * ── Consumer 偏離 canonical ──
  * 消費端若有**確切合理理由**不用 `<ItemContent>` / 需自訂 label/desc 行為,必在
  * 該元件 `spec.md` 明文寫下 rationale(對齊 item-anatomy canonical「偏離必明文」)。
  * 合法偏離範例:
  *   - MenuItem 的 `leading-compact + text-caption` scanning-mode typography
- *     → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc` token 直接用
+ *     → MenuItem spec 明文 rationale + 消費 `--item-gap-label-desc-scanning[-lg]` token 直接用
  *   - SelectionItem 的 control slot 跟 block formula 綁定
  *     → SelectionItem spec 明文 rationale
  *
@@ -202,6 +209,7 @@ export declare const ItemLabel: React.ForwardRefExoticComponent<React.HTMLAttrib
  *   - `"secondary"`(預設):`text-fg-secondary`
  *   - `"error"`:`text-error-text`
  *   - `"muted"`:`text-fg-muted`
+ *   - `"disabled"`:`text-fg-disabled`(對齊 M24 state precedence:disabled > muted > emphasis)
  * - `descriptionWrap`:desc 多行 wrap(預設 true)/ false = truncate
  * - `labelClassName` / `descriptionClassName`:escape hatches(明文 rationale 才用)
  *
@@ -237,6 +245,9 @@ export interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     /**
      * Description 多行截斷(line-clamp-N)。undefined = 不 clamp(自由 wrap)。
      * Tailwind line-clamp utilities 支援 1-6。
+     * `1`(單行 clamp)截斷時 hover 顯 tooltip 補全(截斷才顯,tooltip.spec.md:32);
+     * `>= 2`(多行)不配 tooltip —— truncated-text.spec.md「何時不用」(a) 排除多行,
+     * DS 尚無多行截斷↔補全 canonical(owner 決策前維持排除)。
      */
     descriptionClamp?: number;
     /**
@@ -246,7 +257,7 @@ export interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     descriptionBreakWords?: boolean;
     /**
      * Label truncate (default `true`, 對齊 row-item 大宗 idiom)。
-     * Opt-out(`false`)for card-like consumers(e.g. NameCard label 允許 wrap)。
+     * Opt-out(`false`)for card-like consumers(e.g. ProfileCard label 允許 wrap)。
      * World-class 對照:Material `ListItemText primaryTypographyProps.noWrap` default true。
      */
     labelTruncate?: boolean;
@@ -254,6 +265,7 @@ export interface ItemContentProps extends Omit<React.HTMLAttributes<HTMLDivEleme
     descriptionClassName?: string;
 }
 export declare const ItemContent: React.ForwardRefExoticComponent<ItemContentProps & React.RefAttributes<HTMLDivElement>>;
+/** @internal — L3 row-size primitive;app code 不直接 import,由 MenuItem/Row/Field 等內部消費(inline-action.spec.md)。 */
 export declare const RowSizeProvider: React.Provider<RowSize | null>;
 /**
  * 讀取當前 row size。在 row primitive 子樹外呼叫會回 fallback(預設 "md")。
@@ -291,6 +303,7 @@ export interface ItemAvatarProps extends Omit<AvatarProps, "size"> {
  * 不可能硬寫錯誤尺寸。
  */
 export declare const ItemAvatar: React.ForwardRefExoticComponent<ItemAvatarProps & React.RefAttributes<HTMLDivElement>>;
+/** @internal — internal ItemInlineActionButton 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */
 export interface ItemInlineActionButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
     /** Lucide icon 元件 */
     icon: LucideIcon;
@@ -310,7 +323,7 @@ export interface ItemInlineActionButtonProps extends Omit<React.ButtonHTMLAttrib
      *
      * 預設 `group-hover/action:bg-neutral-hover group-active/action:bg-neutral-active`。
      * 提供後**完全取代** hover + active 雙態 className,但**不影響** rest 態(永遠 bg-transparent)
-     * 與 overlay-trigger 態(`group-data-[state=open]:bg-neutral-selected`)。
+     * 與 overlay-trigger 態(`group-data-[state=open]/action:bg-neutral-hover` — 維持 host hover bg)。
      *
      * Consumer 須**同時**包含 hover + active 兩態 selector,例:
      * `'group-hover/action:bg-[var(--my-hover)] group-active/action:bg-[var(--my-active)]'`
@@ -333,17 +346,20 @@ export interface ItemInlineActionButtonProps extends Omit<React.ButtonHTMLAttrib
      */
     overlayTrigger?: boolean;
 }
+/** @internal — L3 inline-action primitive;app code 禁直接 import,經 MenuItem/Row endActions 消費(inline-action.spec.md)。 */
 export declare const ItemInlineActionButton: React.ForwardRefExoticComponent<ItemInlineActionButtonProps & React.RefAttributes<HTMLButtonElement>>;
+/** @internal — internal ItemInlineAction 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */
 export interface ItemInlineActionProps {
     action: InlineActionConfig;
     /** Size 覆寫(見 `ItemInlineActionButtonProps.size`)——Field Controls / Tag 必傳 */
     size?: RowSize;
 }
+/** @internal — L3 inline-action primitive;app code 禁直接 import,經 row 元件消費(inline-action.spec.md)。 */
 export declare const ItemInlineAction: React.ForwardRefExoticComponent<ItemInlineActionProps & React.RefAttributes<HTMLButtonElement>>;
 declare const SUFFIX_HOVER_REVEAL_BY_GROUP: {
-    readonly "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150";
-    readonly "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150";
-    readonly row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150";
+    readonly "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0";
+    readonly "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0";
+    readonly row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150 motion-reduce:duration-0";
 };
 export type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP;
 export interface ItemSuffixProps extends React.HTMLAttributes<HTMLSpanElement> {

package/dist/patterns/element-anatomy/item-anatomy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item-anatomy.d.ts","sourceRoot":"","sources":["../../../src/patterns/element-anatomy/item-anatomy.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"item-anatomy.d.ts","sourceRoot":"","sources":["../../../src/patterns/element-anatomy/item-anatomy.tsx"],"names":[],"mappings":"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"}

package/dist/patterns/element-anatomy/item-anatomy.js

@@ -1,9 +1,10 @@
-import { jsxs, jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import { cva } from "class-variance-authority";
-import { cn } from "../../lib/utils.js";
+import { cn, lineClampClass } from "../../lib/utils.js";
 import { Avatar } from "../../components/Avatar/avatar.js";
 import { Tooltip, TooltipTrigger, TooltipContent } from "../../components/Tooltip/tooltip.js";
+import { useTruncated } from "../../hooks/use-truncated.js";
 const ICON_SIZE = {
   sm: 16,
   md: 16,
@@ -64,15 +65,43 @@ const itemPrefixAlignVariants = cva(
     }
   }
 );
-const ItemLabel = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
-  "span",
-  {
-    ref,
-    "data-sidebar": "menu-label",
-    className: cn("min-w-0 flex-1 truncate", className),
-    ...props
-  }
-));
+const measureSingleLineClipped = (el) => {
+  if (el.scrollWidth > el.clientWidth) return true;
+  const lineHeight = parseFloat(getComputedStyle(el).lineHeight);
+  if (Number.isNaN(lineHeight)) return false;
+  const isSingleVisualLine = el.clientHeight < lineHeight * 1.5;
+  return isSingleVisualLine && el.scrollHeight > el.clientHeight + 1;
+};
+const ItemLabel = React.forwardRef(({ className, children, ...props }, forwardedRef) => {
+  const { ref: truncationRef, isTruncated } = useTruncated({
+    measure: measureSingleLineClipped,
+    deps: [children]
+  });
+  return (
+    // 永遠 wrap + `open` 控制(truncated-text.spec.md canonical:條件 wrap 會 remount span、
+    // ref 對不上真 DOM)。hover-only:trigger = 不可聚焦 span,不加 tabIndex —— menu row 的
+    // roving focus 在宿主 row 上,label 加 tab stop 會破壞 APG menu 鍵盤導航;先例 = Tag 帶
+    // 內建截斷 tooltip 渲染於 SelectMenu option 內(select.tsx renderLabel → tag.tsx),
+    // menu 內無抑制。鍵盤/SR 無損失:row accessible name 本就含完整文字。
+    /* @__PURE__ */ jsxs(Tooltip, { open: isTruncated ? void 0 : false, children: [
+      /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
+        "span",
+        {
+          ref: (el) => {
+            truncationRef.current = el;
+            if (typeof forwardedRef === "function") forwardedRef(el);
+            else if (forwardedRef) forwardedRef.current = el;
+          },
+          "data-sidebar": "menu-label",
+          className: cn("min-w-0 flex-1 truncate", className),
+          ...props,
+          children
+        }
+      ) }),
+      /* @__PURE__ */ jsx(TooltipContent, { children })
+    ] })
+  );
+});
 ItemLabel.displayName = "ItemLabel";
 const ItemContent = React.forwardRef(
   ({
@@ -98,7 +127,15 @@ const ItemContent = React.forwardRef(
     }[descriptionTone];
     const isLg = size === "lg";
     const modeClass = mode === "scanning" ? isLg ? "text-[length:var(--font-body-size)] leading-compact" : "text-[length:var(--font-caption-size)] leading-compact" : isLg ? "text-[length:var(--font-body-size)]" : "";
-    const clampClass = descriptionClamp ? `line-clamp-${descriptionClamp}` : "";
+    const clampClass = lineClampClass(descriptionClamp) ?? "";
+    const { ref: labelRef, isTruncated: labelClipped } = useTruncated({
+      measure: measureSingleLineClipped,
+      deps: [label]
+    });
+    const { ref: descriptionRef, isTruncated: descriptionClipped } = useTruncated({
+      measure: measureSingleLineClipped,
+      deps: [description]
+    });
     return /* @__PURE__ */ jsxs(
       "div",
       {
@@ -106,24 +143,31 @@ const ItemContent = React.forwardRef(
         className: cn("flex flex-col min-w-0 flex-1", className),
         ...props,
         children: [
-          /* @__PURE__ */ jsx("span", { className: cn(labelTruncate && "truncate", labelClassName), children: label }),
-          description && /* @__PURE__ */ jsx(
-            "span",
-            {
-              className: cn(
-                // Typography-mode-aware gap token(2026-04-23):
-                // (mode, size)2 維正交 → 4 token 對應 4 typography 組合
-                mode === "scanning" ? isLg ? "mt-[var(--item-gap-label-desc-scanning-lg)]" : "mt-[var(--item-gap-label-desc-scanning)]" : isLg ? "mt-[var(--item-gap-label-desc-reading-lg)]" : "mt-[var(--item-gap-label-desc-reading)]",
-                modeClass,
-                toneClass,
-                clampClass,
-                descriptionBreakWords && "break-words",
-                !descriptionWrap && "truncate",
-                descriptionClassName
-              ),
-              children: description
-            }
-          )
+          /* @__PURE__ */ jsxs(Tooltip, { open: labelClipped ? void 0 : false, children: [
+            /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx("span", { ref: labelRef, className: cn(labelTruncate && "truncate", labelClassName), children: label }) }),
+            /* @__PURE__ */ jsx(TooltipContent, { children: label })
+          ] }),
+          description && /* @__PURE__ */ jsxs(Tooltip, { open: descriptionClipped ? void 0 : false, children: [
+            /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
+              "span",
+              {
+                ref: descriptionRef,
+                className: cn(
+                  // Typography-mode-aware gap token(2026-04-23):
+                  // (mode, size)2 維正交 → 4 token 對應 4 typography 組合
+                  mode === "scanning" ? isLg ? "mt-[var(--item-gap-label-desc-scanning-lg)]" : "mt-[var(--item-gap-label-desc-scanning)]" : isLg ? "mt-[var(--item-gap-label-desc-reading-lg)]" : "mt-[var(--item-gap-label-desc-reading)]",
+                  modeClass,
+                  toneClass,
+                  clampClass,
+                  descriptionBreakWords && "break-words",
+                  !descriptionWrap && "truncate",
+                  descriptionClassName
+                ),
+                children: description
+              }
+            ) }),
+            /* @__PURE__ */ jsx(TooltipContent, { children: description })
+          ] })
         ]
       }
     );
@@ -178,11 +222,15 @@ const ItemInlineActionButton = React.forwardRef(({ icon: Icon, className, iconCl
       type,
       className: cn(
         "group/action relative grid place-content-center shrink-0 cursor-pointer",
-        "text-fg-muted hover:text-foreground active:text-foreground transition-colors",
+        // 弱化 icon hover 階梯 SSOT(2026-07-30 user 拍板):fg-muted(neutral-7)→ 一階 fg-secondary
+        // (neutral-8),不跳到 foreground(neutral-9)。inline-action.spec.md「Icon 色彩」+
+        // tokens/color/semantic.css:53 為 rule owner;世界級對照 Fluent 2
+        // (neutralForeground3Hover === neutralForeground2 值)/ MUI Chip deleteIcon(.26 → .4)。
+        "text-fg-muted hover:text-fg-secondary active:text-fg-secondary transition-colors",
         // Overlay trigger active state — 只在 consumer 顯式宣告 overlayTrigger=true 時生效
         // (canonical 2026-05-05:Collapsible / drag / dismiss 等 in-place 互動 ≠ overlay,
         // 不應 leak 視覺 lock。詳 inline-action.spec.md「Overlay trigger canonical」)
-        overlayTrigger && "data-[state=open]:text-foreground",
+        overlayTrigger && "data-[state=open]:text-fg-secondary",
         "focus-visible:outline-2 focus-visible:outline-ring",
         className
       ),
@@ -232,9 +280,9 @@ const ItemInlineAction = React.forwardRef(({ action, size }, ref) => /* @__PURE_
 ] }));
 ItemInlineAction.displayName = "ItemInlineAction";
 const SUFFIX_HOVER_REVEAL_BY_GROUP = {
-  "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150",
-  "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150",
-  row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150"
+  "menu-item": "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0",
+  "tree-item": "opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0",
+  row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150 motion-reduce:duration-0"
 };
 const ItemSuffix = React.forwardRef(
   ({ className, hoverReveal = false, hoverGroup = "menu-item", ...props }, ref) => /* @__PURE__ */ jsx(

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

@@ -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)` token;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)]` 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` 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 * - `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. NameCard 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\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]:bg-neutral-selected`)。\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\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\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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"}
+{"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, lineClampClass } 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\"\nimport { useTruncated } from \"@/design-system/hooks/use-truncated\"\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 context 的 consumer(包含 `asChild` pattern 的 Sidebar / Tree\n * consumer)**必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件(自動查\n * RowSizeContext 對表),**禁止** `import { AVATAR_SIZE }` 手動查表、**不可硬寫\n * `size={24}`** — 硬寫會讓 sm 變體的 avatar 尺寸錯誤、跟 ICON_SIZE 對齊規則脫鉤。\n * 詳 item-anatomy.spec.md「Helper 程式化封裝 + review 防線」段。\n *\n * ```tsx\n * import { ItemAvatar } from \"@/design-system/patterns/element-anatomy/item-anatomy\"\n *\n * <ItemAvatar alt=\"Alan\" color=\"blue\" />  // 自動查 AVATAR_SIZE.inline[rowSize]\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// ── 單行截斷偵測 measure(ItemLabel / ItemContent 共用)──────────────────────\n// 截斷 → tooltip 顯完整內容、僅實際截斷時顯示(owner:components/Tooltip/tooltip.spec.md:32;\n// 引擎 SSOT:patterns/element-anatomy/truncated-text.spec.md)。不消費 `<TruncatedText>`——\n// trigger 需自控(ItemLabel 要 forwardRef + data-sidebar attr + props spread;ItemContent 要保留\n// labelTruncate / clamp className 原樣)→ 走 spec 指定解:public `useTruncated` 自組\n// (同 components/InlineEdit/inline-edit.tsx「單行純值 view 截斷 tooltip」段與 components/Tag 的用法)。\n// 兩種「單行截斷」機制都要偵測(MenuItem 的 clamp 走 className escape,量 DOM 才能全蓋):\n// - `truncate`(nowrap)→ scrollWidth 溢出(useTruncated 預設量法)\n// - `line-clamp-1`(MenuItem labelMaxLines/descMaxLines=1、descriptionClamp=1;文字先 wrap\n//   再垂直裁)→ scrollWidth 不溢出,只能量 scrollHeight;以「可視高度 ≈ 1 行」gate 限定單行\n//   clamp。多行 clamp(≥2 行)刻意不顯 tooltip:truncated-text.spec.md「何時不用」(a) 明文\n//   排除多行,DS 尚無多行截斷↔補全 canonical(owner 決策前維持排除)—— gate 機械保證。\nconst measureSingleLineClipped = (el: HTMLElement): boolean => {\n  if (el.scrollWidth > el.clientWidth) return true\n  const lineHeight = parseFloat(getComputedStyle(el).lineHeight)\n  if (Number.isNaN(lineHeight)) return false // line-height:normal 等不可量 → 只認橫向溢出\n  const isSingleVisualLine = el.clientHeight < lineHeight * 1.5\n  return isSingleVisualLine && el.scrollHeight > el.clientHeight + 1\n}\n\n/**\n * `<ItemLabel>` — Row primitive 的 label span。\n *\n * 預設 `min-w-0 flex-1 truncate`——單行截斷,佔滿剩餘 flex 空間。\n * 截斷時 hover 顯 tooltip 補全(截斷才顯,tooltip.spec.md:32;內建,consumer 免自接)。\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, children, ...props }, forwardedRef) => {\n  const { ref: truncationRef, isTruncated } = useTruncated<HTMLSpanElement>({\n    measure: measureSingleLineClipped,\n    deps: [children],\n  })\n  return (\n    // 永遠 wrap + `open` 控制(truncated-text.spec.md canonical:條件 wrap 會 remount span、\n    // ref 對不上真 DOM)。hover-only:trigger = 不可聚焦 span,不加 tabIndex —— menu row 的\n    // roving focus 在宿主 row 上,label 加 tab stop 會破壞 APG menu 鍵盤導航;先例 = Tag 帶\n    // 內建截斷 tooltip 渲染於 SelectMenu option 內(select.tsx renderLabel → tag.tsx),\n    // menu 內無抑制。鍵盤/SR 無損失:row accessible name 本就含完整文字。\n    <Tooltip open={isTruncated ? undefined : false}>\n      <TooltipTrigger asChild>\n        <span\n          ref={(el) => {\n            truncationRef.current = el\n            if (typeof forwardedRef === \"function\") forwardedRef(el)\n            else if (forwardedRef) forwardedRef.current = el\n          }}\n          data-sidebar=\"menu-label\"\n          className={cn(\"min-w-0 flex-1 truncate\", className)}\n          {...props}\n        >\n          {children}\n        </span>\n      </TooltipTrigger>\n      <TooltipContent>{children}</TooltipContent>\n    </Tooltip>\n  )\n})\nItemLabel.displayName = \"ItemLabel\"\n\n/**\n * `<ItemContent>` — Row primitive 的 label + optional description 內容區(SSOT)。\n *\n * ── 存在的唯一理由 ──\n * 封裝「flex-col + label + description + canonical label/description gap」結構,\n * 避免 13+ 消費者各自 hard-code `mt-0.5`。改 token 一處,全 DS 同步。\n *\n * ── 截斷 → tooltip(內建,consumer 免自接)──\n * label(`truncate` 或 `line-clamp-1` escape)與單行截斷 description 在實際截斷時 hover 顯\n * tooltip 補全(截斷才顯,tooltip.spec.md:32);多行 clamp(≥2 行)排除 —— 見\n * `measureSingleLineClipped` 註解(truncated-text.spec.md「何時不用」(a))。\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   * `1`(單行 clamp)截斷時 hover 顯 tooltip 補全(截斷才顯,tooltip.spec.md:32);\n   * `>= 2`(多行)不配 tooltip —— truncated-text.spec.md「何時不用」(a) 排除多行,\n   * DS 尚無多行截斷↔補全 canonical(owner 決策前維持排除)。\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 = lineClampClass(descriptionClamp) ?? \"\"\n\n    // 截斷 → tooltip(截斷才顯,tooltip.spec.md:32)。量測走 measureSingleLineClipped(檔內\n    // SSOT 註解):label 蓋 labelTruncate `truncate` + MenuItem labelClassName `line-clamp-1`\n    // escape 兩路;description 只在單行截斷(`descriptionClamp === 1` 或 !descriptionWrap 的\n    // truncate 分支,含 className escape)顯示——多行 clamp(≥2)由量測 gate 機械排除\n    // (truncated-text.spec.md「何時不用」(a):本 primitive 不處理多行)。\n    const { ref: labelRef, isTruncated: labelClipped } = useTruncated<HTMLSpanElement>({\n      measure: measureSingleLineClipped,\n      deps: [label],\n    })\n    const { ref: descriptionRef, isTruncated: descriptionClipped } = useTruncated<HTMLSpanElement>({\n      measure: measureSingleLineClipped,\n      deps: [description],\n    })\n\n    return (\n      <div\n        ref={ref}\n        className={cn(\"flex flex-col min-w-0 flex-1\", className)}\n        {...props}\n      >\n        {/* 永遠 wrap + open 控制(truncated-text.spec.md canonical);hover-only 不加 tabIndex\n            (menu row roving focus 見 ItemLabel 註解)。 */}\n        <Tooltip open={labelClipped ? undefined : false}>\n          <TooltipTrigger asChild>\n            <span ref={labelRef} className={cn(labelTruncate && \"truncate\", labelClassName)}>\n              {label}\n            </span>\n          </TooltipTrigger>\n          <TooltipContent>{label}</TooltipContent>\n        </Tooltip>\n        {description && (\n          <Tooltip open={descriptionClipped ? undefined : false}>\n            <TooltipTrigger asChild>\n              <span\n                ref={descriptionRef}\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            </TooltipTrigger>\n            <TooltipContent>{description}</TooltipContent>\n          </Tooltip>\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 → fg-secondary 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 → fg-secondary on hover/active\n//\n// 接受任何 button props 並 spread(讓 Radix Slot 可以 merge onClick / data-state 等)\n\n/** @internal — internal ItemInlineActionButton 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */\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        // 弱化 icon hover 階梯 SSOT(2026-07-30 user 拍板):fg-muted(neutral-7)→ 一階 fg-secondary\n        // (neutral-8),不跳到 foreground(neutral-9)。inline-action.spec.md「Icon 色彩」+\n        // tokens/color/semantic.css:53 為 rule owner;世界級對照 Fluent 2\n        // (neutralForeground3Hover === neutralForeground2 值)/ MUI Chip deleteIcon(.26 → .4)。\n        \"text-fg-muted hover:text-fg-secondary active:text-fg-secondary 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-fg-secondary\",\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\n/** @internal — internal ItemInlineAction 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */\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 motion-reduce:duration-0\",\n  \"tree-item\":\n    \"opacity-0 group-hover/tree-item:opacity-100 group-has-[:focus-visible]/tree-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0\",\n  row: \"opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150 motion-reduce:duration-0\",\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/element-anatomy/truncated-text.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+/** @internal 隨 `TruncatedText`(DS-internal 組合 primitive)一併不進 root barrel front-door;subpath 仍可取。 */
+export interface TruncatedTextProps {
+    children: React.ReactNode;
+    /** 附加到截斷 span 的 className(如 DataTable 的 text-align)。 */
+    className?: string;
+    /**
+     * Tooltip 顯示內容,預設 = `children`。當 `children` 為非字串 ReactNode(icon+text 等)、
+     * 但已知完整文字時傳入(Breadcrumb 的 `fullText`)。
+     */
+    tooltip?: React.ReactNode;
+    /**
+     * span 的 display:`'inline'`(預設,保 baseline/垂直對齊,DataTable cell 用)/ `'block'`(Breadcrumb 用)。
+     * ⚠️ DataTable 刻意用 inline —— `block` 會改 baseline 使 Field/inline-flex cell 垂直對齊 collapse。
+     */
+    display?: 'block' | 'inline';
+}
+/**
+ * @internal DS-internal 組合 primitive:由 Breadcrumb / DataTable 內部消費以統一 truncate-tooltip 呈現。
+ * end-user app 若需「單行截斷 + tooltip」直接消費 public `useTruncated` hook 自組(trigger/a11y 自控),
+ * 或經 per-component subpath 取用本 component。不進 root barrel front-door。
+ */
+export declare function TruncatedText({ children, className, tooltip, display }: TruncatedTextProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TruncatedText {
+    var displayName: string;
+}
+//# sourceMappingURL=truncated-text.d.ts.map

package/dist/patterns/element-anatomy/truncated-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncated-text.d.ts","sourceRoot":"","sources":["../../../src/patterns/element-anatomy/truncated-text.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAyB9B,oGAAoG;AACpG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAA;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,OAAkB,EAAE,EAAE,kBAAkB,2CAYrG;yBAZe,aAAa"}