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

package/src/patterns/element-anatomy/item-anatomy.tsx

@@ -3,13 +3,14 @@
 import * as React from "react"
 import type { LucideIcon } from "lucide-react"
 import { cva } from "class-variance-authority"
-import { cn } from "@/lib/utils"
+import { cn, lineClampClass } from "@/lib/utils"
 import { Avatar, type AvatarProps } from "@/design-system/components/Avatar/avatar"
 import {
   Tooltip,
   TooltipTrigger,
   TooltipContent,
 } from "@/design-system/components/Tooltip/tooltip"
+import { useTruncated } from "@/design-system/hooks/use-truncated"
 
 // ── InlineActionConfig ─────────────────────────────────────────────────────
 // 宣告式 API:consumer 只宣告 intent,host 根據 size tier 自動渲染。
@@ -77,18 +78,19 @@ export 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 "@/design-system/patterns/element-anatomy/item-anatomy"
+ * import { ItemAvatar } from "@/design-system/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 const AVATAR_SIZE = {
   inline: { sm: 20, md: 24, lg: 24 },
@@ -120,7 +122,7 @@ export function getUniformPrefixSlotStyle(size: RowSize): React.CSSProperties {
 /**
  * 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 抽出)。
  */
 // code-quality-allow: dead-export — public constant — DS API surface,consumer 可引(即使當前 internal-only)
 export const INLINE_ACTION_HOVER_BG_SIZE: Record<RowSize, number> = {
@@ -215,7 +217,7 @@ ItemPrefix.displayName = "ItemPrefix"
  * 直接用 `<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 → 公式同步。
  */
 // code-quality-allow: long-function — cva variant/styles table — 拆 fn 會失去 type inference + 跨 fn 傳 config 反而難讀
@@ -242,10 +244,31 @@ export const itemPrefixAlignVariants = cva(
   }
 )
 
+// ── 單行截斷偵測 measure(ItemLabel / ItemContent 共用)──────────────────────
+// 截斷 → tooltip 顯完整內容、僅實際截斷時顯示(owner:components/Tooltip/tooltip.spec.md:32;
+// 引擎 SSOT:patterns/element-anatomy/truncated-text.spec.md)。不消費 `<TruncatedText>`——
+// trigger 需自控(ItemLabel 要 forwardRef + data-sidebar attr + props spread;ItemContent 要保留
+// labelTruncate / clamp className 原樣)→ 走 spec 指定解:public `useTruncated` 自組
+// (同 components/InlineEdit/inline-edit.tsx「單行純值 view 截斷 tooltip」段與 components/Tag 的用法)。
+// 兩種「單行截斷」機制都要偵測(MenuItem 的 clamp 走 className escape,量 DOM 才能全蓋):
+// - `truncate`(nowrap)→ scrollWidth 溢出(useTruncated 預設量法)
+// - `line-clamp-1`(MenuItem labelMaxLines/descMaxLines=1、descriptionClamp=1;文字先 wrap
+//   再垂直裁)→ scrollWidth 不溢出,只能量 scrollHeight;以「可視高度 ≈ 1 行」gate 限定單行
+//   clamp。多行 clamp(≥2 行)刻意不顯 tooltip:truncated-text.spec.md「何時不用」(a) 明文
+//   排除多行,DS 尚無多行截斷↔補全 canonical(owner 決策前維持排除)—— gate 機械保證。
+const measureSingleLineClipped = (el: HTMLElement): boolean => {
+  if (el.scrollWidth > el.clientWidth) return true
+  const lineHeight = parseFloat(getComputedStyle(el).lineHeight)
+  if (Number.isNaN(lineHeight)) return false // line-height:normal 等不可量 → 只認橫向溢出
+  const isSingleVisualLine = el.clientHeight < lineHeight * 1.5
+  return isSingleVisualLine && el.scrollHeight > el.clientHeight + 1
+}
+
 /**
  * `<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 能命中。
  *
  * 用法:
@@ -256,29 +279,56 @@ export const itemPrefixAlignVariants = cva(
 export const ItemLabel = React.forwardRef<
   HTMLSpanElement,
   React.HTMLAttributes<HTMLSpanElement>
->(({ className, ...props }, ref) => (
-  <span
-    ref={ref}
-    data-sidebar="menu-label"
-    className={cn("min-w-0 flex-1 truncate", className)}
-    {...props}
-  />
-))
+>(({ className, children, ...props }, forwardedRef) => {
+  const { ref: truncationRef, isTruncated } = useTruncated<HTMLSpanElement>({
+    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 本就含完整文字。
+    <Tooltip open={isTruncated ? undefined : false}>
+      <TooltipTrigger asChild>
+        <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}
+        </span>
+      </TooltipTrigger>
+      <TooltipContent>{children}</TooltipContent>
+    </Tooltip>
+  )
+})
 ItemLabel.displayName = "ItemLabel"
 
 /**
  * `<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
  *
@@ -293,6 +343,7 @@ ItemLabel.displayName = "ItemLabel"
  *   - `"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 才用)
  *
@@ -329,6 +380,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
   /**
@@ -338,7 +392,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
@@ -390,7 +444,21 @@ export const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(
           ? "text-[length:var(--font-body-size)]"
           : ""
 
-    const clampClass = descriptionClamp ? `line-clamp-${descriptionClamp}` : ""
+    const clampClass = lineClampClass(descriptionClamp) ?? ""
+
+    // 截斷 → tooltip(截斷才顯,tooltip.spec.md:32)。量測走 measureSingleLineClipped(檔內
+    // SSOT 註解):label 蓋 labelTruncate `truncate` + MenuItem labelClassName `line-clamp-1`
+    // escape 兩路;description 只在單行截斷(`descriptionClamp === 1` 或 !descriptionWrap 的
+    // truncate 分支,含 className escape)顯示——多行 clamp(≥2)由量測 gate 機械排除
+    // (truncated-text.spec.md「何時不用」(a):本 primitive 不處理多行)。
+    const { ref: labelRef, isTruncated: labelClipped } = useTruncated<HTMLSpanElement>({
+      measure: measureSingleLineClipped,
+      deps: [label],
+    })
+    const { ref: descriptionRef, isTruncated: descriptionClipped } = useTruncated<HTMLSpanElement>({
+      measure: measureSingleLineClipped,
+      deps: [description],
+    })
 
     return (
       <div
@@ -398,29 +466,44 @@ export const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(
         className={cn("flex flex-col min-w-0 flex-1", className)}
         {...props}
       >
-        <span className={cn(labelTruncate && "truncate", labelClassName)}>{label}</span>
+        {/* 永遠 wrap + open 控制(truncated-text.spec.md canonical);hover-only 不加 tabIndex
+            (menu row roving focus 見 ItemLabel 註解)。 */}
+        <Tooltip open={labelClipped ? undefined : false}>
+          <TooltipTrigger asChild>
+            <span ref={labelRef} className={cn(labelTruncate && "truncate", labelClassName)}>
+              {label}
+            </span>
+          </TooltipTrigger>
+          <TooltipContent>{label}</TooltipContent>
+        </Tooltip>
         {description && (
-          <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,
-            )}
-          >
-            {description}
-          </span>
+          <Tooltip open={descriptionClipped ? undefined : false}>
+            <TooltipTrigger asChild>
+              <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,
+                )}
+              >
+                {description}
+              </span>
+            </TooltipTrigger>
+            <TooltipContent>{description}</TooltipContent>
+          </Tooltip>
         )}
       </div>
     )
@@ -444,6 +527,7 @@ ItemContent.displayName = "ItemContent"
 
 const RowSizeContext = React.createContext<RowSize | null>(null)
 
+/** @internal — L3 row-size primitive;app code 不直接 import,由 MenuItem/Row/Field 等內部消費(inline-action.spec.md)。 */
 export const RowSizeProvider = RowSizeContext.Provider
 
 /**
@@ -532,14 +616,13 @@ ItemAvatar.displayName = "ItemAvatar"
 // ── Inline action (suffix slot) ───────────────────────────────────────────
 //
 // 共用 row-primitive 的 suffix inline action 渲染——消除過去 Input / NumberInput /
-// Tag / LinkInput / Combobox 各自複製 18 行 JSX 的狀況(見 `item-anatomy.spec.md`
-// 「Inline Action 設計規格」節)。
+// Tag / LinkInput / Combobox 各自複製 18 行 JSX 的狀況(見 `inline-action.spec.md`)。
 //
-// 規格(完全對齊 item-anatomy.spec.md「Inline Action 設計規格」節):
+// 規格(完全對齊 inline-action.spec.md — canonical SSOT,2026-04-24 自 item-anatomy.spec 抽出):
 // - Icon 尺寸 = ICON_SIZE[rowSize]      (16/16/20)
 // - Hover bg 尺寸 = icon + 2            (18/18/22,INLINE_ACTION_HOVER_BG_SIZE)
 // - Hover bg 圓角 = rounded-md (sm/md)/ rounded-md (lg)
-// - Icon 顏色:fg-muted → foreground on hover/active
+// - Icon 顏色:fg-muted → fg-secondary on hover/active
 // - 必須 <button type="button">,aria-label = label,Tooltip(同 label)
 // - cursor-pointer
 
@@ -552,10 +635,11 @@ ItemAvatar.displayName = "ItemAvatar"
 //   - 寬高 = ICON_SIZE[size]
 //   - Hover bg 尺寸 = INLINE_ACTION_HOVER_BG_SIZE[size]
 //   - Hover bg 圓角 = rounded-md (sm/md) / rounded-md (lg)
-//   - Icon color = fg-muted → foreground on hover/active
+//   - Icon color = fg-muted → fg-secondary on hover/active
 //
 // 接受任何 button props 並 spread(讓 Radix Slot 可以 merge onClick / data-state 等)
 
+/** @internal — internal ItemInlineActionButton 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */
 export interface ItemInlineActionButtonProps
   extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
   /** Lucide icon 元件 */
@@ -576,7 +660,7 @@ export interface ItemInlineActionButtonProps
    *
    * 預設 `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)]'`
@@ -600,6 +684,7 @@ export interface ItemInlineActionButtonProps
   overlayTrigger?: boolean
 }
 
+/** @internal — L3 inline-action primitive;app code 禁直接 import,經 MenuItem/Row endActions 消費(inline-action.spec.md)。 */
 export const ItemInlineActionButton = React.forwardRef<
   HTMLButtonElement,
   ItemInlineActionButtonProps
@@ -614,11 +699,15 @@ export const ItemInlineActionButton = React.forwardRef<
       type={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
       )}
@@ -659,12 +748,14 @@ ItemInlineActionButton.displayName = "ItemInlineActionButton"
 // 需要接 Radix asChild(例如 collapsible trigger)時改用 `ItemInlineActionButton`,
 // 那層沒有 Tooltip 包裝,Root 就是 button,可直接塞進 Radix Slot。
 
+/** @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 const ItemInlineAction = React.forwardRef<
   HTMLButtonElement,
   ItemInlineActionProps
@@ -689,7 +780,7 @@ ItemInlineAction.displayName = "ItemInlineAction"
 // `<ItemSuffix>` — row primitive 的 suffix 容器。對齊 item-layout spec:
 // - `h-[1lh]`:suffix 永遠對齊第一行 label(跟 prefix 解耦)
 // - `ml-auto`:靠右
-// - `gap-2`:多個 inline action 之間的標準間距(item-anatomy.spec.md「Inline Action 設計規格」節)
+// - `gap-2`:多個 inline action 之間的標準間距(inline-action.spec.md canonical SSOT)
 // - `hoverReveal` opt-in:opacity 0→1 on 父層 row hover/focus-visible
 //
 // `hoverGroup`(2026-05-05 v8 SSOT 升級):row primitive group selector 參數化。
@@ -700,10 +791,10 @@ 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",
+    "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",
-  row: "opacity-0 group-hover/row:opacity-100 group-has-[:focus-visible]/row:opacity-100 transition-opacity duration-150",
+    "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",
 } as const
 
 export type ItemSuffixHoverGroup = keyof typeof SUFFIX_HOVER_REVEAL_BY_GROUP

package/src/patterns/element-anatomy/truncated-text.spec.md

@@ -0,0 +1,68 @@
+---
+component: TruncatedText
+family: non-family
+isInternal: true
+benchmark:
+  - Ant Design Typography.Text ellipsis={{ tooltip }}: https://ant.design/components/typography
+  - MUI 社群共識 useIsOverflow hook + 條件 Tooltip: https://github.com/mui/material-ui/issues/37211
+  - Carbon Overflow content(truncate 樣式 + hover tooltip 同 pattern): https://carbondesignsystem.com/patterns/overflow-content/
+---
+
+# TruncatedText / useTruncated 設計原則(SSOT)
+
+**Layout Family**:non-family(hosted inline element,無 own layout —— 嵌在宿主 row/cell/pill 內)。
+
+**定位**:「單行文字**可能**溢出容器 → 溢出時 `text-ellipsis` 截斷 + **僅截斷時**顯示 tooltip 補全」的共用引擎與呈現層。收斂 Breadcrumb label / DataTable 純文字 cell / Tag 三處**先前逐字重複**的截斷偵測 + tooltip 邏輯為單一 SSOT(2026-07-19,user 拍板)。
+
+## 兩層架構(對齊世界級聯集)
+
+| 層 | 物件 | 職責 | 對標 |
+|----|------|------|------|
+| 底層量測引擎 | **`useTruncated(options?)` hook**(public,`hooks/use-truncated`)| 全 DS 共用單一 `ResizeObserver`(dispatch 到 per-element callback,`WeakMap`)+ `isTruncated` 狀態機 + 二次量測時序。回 `{ ref, isTruncated }` | MUI/MUI-X 社群「hook 量測 + 條件 Tooltip」 |
+| 上層組合 | **`<TruncatedText>` component**(@internal,本檔)| 消費 hook + 封裝「永遠 wrap Tooltip、`open` 控制可見」的截斷 span 呈現 | Ant `Typography.Text ellipsis` 高階元件 |
+
+**為何兩層**:Breadcrumb / DataTable 結構同構(截斷 span 即 tooltip trigger)→ 用 component;Tag 因 **trigger(整個 tag root)≠ 量測元素(內層 `[data-tag-text]` span)** + Canvas `measureText`(flex 內 `scrollWidth` 不可靠)+ 截斷才 `tabIndex=0`/focus-ring 的自訂 a11y → **只用 hook 自組**。缺任一層 = 假 SSOT(只抽 component 則 Tag 被迫留自己的 RO copy;只抽 hook 則兩個 component consumer 各自重寫 wrap JSX)。
+
+## `open` 控制而非條件 wrap(canonical)
+
+「**永遠** wrap Tooltip、`open={isTruncated ? undefined : false}`」而非「未截斷回裸 span、截斷才 wrap」:後者切換 JSX 樹 → span unmount/remount → ref 換到新 DOM、`useEffect([])` 不重跑 → 觀察的 DOM 與實際 DOM 對不上(Breadcrumb 2026-05-11 抓的 bug)。`open={false}` 時 `TooltipTrigger asChild` 只把 handler/`data-state` 合併到同一 span(無多餘 DOM、tooltip 靜默),與裸 span 視覺行為等價。對齊 `components/Tooltip/tooltip.principles.stories.tsx`「沒被截斷就不該顯示 tooltip」。
+
+## 何時用 / 何時不用
+
+- **用**:宿主 row/cell/pill 內「寬度受限的單行文字」,溢出時要保留可讀性(hover/focus 見全文)。
+- **不用**:(a) 多行文字(本 primitive 是 `truncate` 單行 `white-space:nowrap`,不處理多行——排除的是 **≥2 行** clamp;`line-clamp-1` 只顯示 1 行,屬單行 scope,item-anatomy 以自訂 measure 偵測,見下表);(b) compound content(icon+field/select/person 等自帶 layout)—— `truncate` 的 inline baseline 會 collapse Field/inline-flex 對齊(DataTable 於 `renderCellContent` 對 compound 欄位**bypass** `<TruncatedText>`,只 primitive string/number 才走);(c) 內容永遠放得下(不需 tooltip 補救)。
+
+## 消費者變異點(hook options)
+
+| option | 預設 | 用途 |
+|--------|------|------|
+| `measure` | `scrollWidth > clientWidth`(觀察元素自身)| Tag 傳 Canvas `measureText`(observe root、量測內層 span);item-anatomy(`ItemLabel` / `ItemContent`)傳單行截斷量法 `measureSingleLineClipped`(scrollWidth 溢出 ∨「可視高度 ≈ 1 行」+ scrollHeight 溢出)把 `line-clamp-1` 納入單行 scope、≥2 行 clamp 機械排除;回 `undefined` = 保留前狀態 |
+| `deps` | `[]`(mount-once)| Tag 傳 `[children]`(children 變重量)|
+| `recheckAfterPaint` | `true`(rAF + `setTimeout(100)` 二次量,抓字型 async 假陰性)| Tag 傳 `false`(原無二次量)|
+| `timing` | `'effect'` | Tag 傳 `'layoutEffect'`(避免 paint flash)|
+
+`<TruncatedText>` props:`children` / `className`(align passthrough)/ `tooltip`(預設 = children;Breadcrumb 傳 `fullText`)/ `display`（`'inline'` 預設保 baseline;`'block'` Breadcrumb 用)。
+
+## A11y 預設
+
+- 截斷才顯示 tooltip(補全被裁文字);未截斷不顯示(避免噪音)。
+- Tooltip 經 Radix `TooltipTrigger`/`TooltipContent`:hover + keyboard focus 皆可觸發(對齊 W3C APG Tooltip pattern)。
+- Tag 變異:截斷時 root `tabIndex=0` + focus-visible ring(讓 Tab 到即見全文,APG 前提 trigger 可 focus);未截斷不入 tab 序。此 a11y 由 Tag 讀 `isTruncated` 自渲染,不進 hook(consumer 自控)。
+
+## 禁止事項
+
+- ❌ 把 Tag 的偵測改回 `scrollWidth`(flex 內不可靠 → 行為漂移)。
+- ❌ 用條件 wrap(未截斷裸 span / 截斷才 wrap)—— 見上「`open` 控制」canonical。
+- ❌ 對 compound content 套 `<TruncatedText>`(baseline collapse);走宿主 bypass。
+- ❌ 多 consumer 各自 `new ResizeObserver` / 複製 shared RO 引擎 —— 一律消費 `useTruncated`(SSOT)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `calendar.spec.md`
+- `date-picker.spec.md`
+- `dialog.spec.md`
+- `inline-edit.spec.md`
+- `item-anatomy.spec.md`
+- `link-input.spec.md`

package/src/patterns/element-anatomy/truncated-text.tsx

@@ -0,0 +1,61 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+import { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'
+import { useTruncated } from '@/design-system/hooks/use-truncated'
+
+// ── 消費的 SSOT ──
+// - hooks/use-truncated（useTruncated）：截斷偵測引擎 + isTruncated 狀態（本 primitive 的量測核心）
+// - components/Tooltip（Tooltip/TooltipTrigger/TooltipContent）：截斷才顯示完整文字的補救 overlay
+// - lib/utils（cn）：className 合併
+// - spec: patterns/element-anatomy/truncated-text.spec.md（本 primitive「何時用/為什麼」）
+// - governing: components/Tooltip/tooltip.principles.stories.tsx「沒被截斷就不該顯示 tooltip」→ 由 open 控制機械保證
+
+// ── TruncatedText — 單行截斷 + 截斷才顯示 tooltip 的組合式 primitive ──────────────
+// 消費 `useTruncated`(量測引擎 SSOT)+ 封裝「永遠 wrap Tooltip、以 `open` 控制可見」的正解結構。
+// 收斂 Breadcrumb `TruncatedLabel` 與 DataTable `TruncateCell` 兩處同構的 truncate-span+tooltip presentation。
+// Tag 因 trigger≠量測元素(整個 tag root vs 內層 text span)+ Canvas measure + 自訂 a11y,正當地
+//   只消費 `useTruncated` hook、不走本 component(見 tag.tsx)。
+//
+// 「永遠 wrap + `open={isTruncated?undefined:false}`」而非「未截斷回裸 span、截斷才 wrap」:
+//   後者切換 JSX 樹會讓 span unmount/remount → ref 換到新 DOM、useEffect[] 不重跑 → 觀察的 DOM 與
+//   實際 DOM 對不上(Breadcrumb 2026-05-11 抓的 bug)。always-wrap 保 DOM 節點生命週期穩定;
+//   `open={false}` 時 TooltipTrigger asChild 只把 handler/data-state 合併到同一 span(無多餘 DOM、
+//   tooltip 靜默),與裸 span 視覺行為等價。
+
+/** @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 function TruncatedText({ children, className, tooltip, display = 'inline' }: TruncatedTextProps) {
+  const { ref, isTruncated } = useTruncated<HTMLSpanElement>()
+  return (
+    <Tooltip open={isTruncated ? undefined : false}>
+      <TooltipTrigger asChild>
+        <span ref={ref} className={cn('truncate min-w-0', display === 'block' && 'block', className)}>
+          {children}
+        </span>
+      </TooltipTrigger>
+      <TooltipContent>{tooltip ?? children}</TooltipContent>
+    </Tooltip>
+  )
+}
+TruncatedText.displayName = 'TruncatedText'

package/src/patterns/header-canonical/chrome-header.tsx

@@ -2,8 +2,24 @@ import * as React from 'react'
 import { cn } from '@/lib/utils'
 
 /**
- * @internal — DS-internal primitive(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。
- * end-user app 直接 render `<ChromeHeader />` 無 functioning UI;由 Sidebar / FileViewer / Dialog / Sheet / Popover 等 DS 元件 wrap 消費。
+ * Header 家族 tabsSlot wrapper className(W2 SSOT,header-canonical.spec.md Rule W2)。
+ * 兩家族(ChromeHeader chrome / SurfaceHeader overlay)的 column-mode tabsSlot row 共用此契約:
+ * 對 `[data-slot=tabs-list]`(tabs.tsx 三種 overflow 模式的 role=tablist 元素皆自標,對齊
+ * shadcn v4 data-slot idiom)注入內 `px-loose` inset triggers(對齊 header content = W2)。
+ * 寬度不在此注入 — TabsList 各模式自帶(none `w-full` border-b 延展全寬 = W1 一條線;
+ * scroll/menu `min-w-full` 讓 border 隨溢出內容成長,blanket `w-full` 會把 border 截在可視寬)。
+ * v4(2026-07-30 regression fix):beta.86 inlineAction overlay(fc2a3a5c)包 `<div class="relative">`
+ * 後,原 `[&>[role=tablist]]` direct-child 結構選擇器全滅(px-loose 靜默消失,且 scroll/menu 深度
+ * 本就 >1 從未命中)→ 改 data-slot attribute contract + descendant selector,免疫 DOM 深度重構。
+ * SSOT 在此(header-canonical = 跨家族 W-rule owner);overlay-surface.tsx SurfaceHeader 消費同一 const,
+ * 禁各自 hardcode(原兩處逐字重複,2026-06-08 收斂為單一 SSOT,per user「照你建議做到完美…不改A壞B」)。
+ */
+export const HEADER_TABS_SLOT_WRAPPER_CLASS =
+  '[&_[data-slot=tabs-list]]:px-[var(--layout-space-loose)]'
+
+/**
+ * Public chrome-header composition primitive(header-canonical Pattern 的 runtime 件,對標 item-anatomy 的 MenuItem/slots:屬公開 Pattern 的可 import primitive)。
+ * 標準頁面 chrome 用成品元件(AppShell / Sidebar / FileViewer 內建 header);自建客製 header 才直接消費本 primitive,並 follow header-canonical.spec.md 設計契約。
  *
  * ChromeHeader — Fixed-height chrome header primitive(Layout Family B,header-canonical.spec.md)
  *
@@ -45,8 +61,10 @@ export interface ChromeHeaderProps
    * Tabs row slot(2026-05-18 加 per W2/W4 真實能用 + user-mandated fix)。
    * 提供時 ChromeHeader 自動 column 結構:
    *   row 1 = children(h-chrome-header-height 固定,px-loose,跟 single-row 模式同)
-   *   row 2 = tabsSlot 包在 `<div px-loose border-b border-divider>`
-   *           ↑ wrapper 提供 W2 padding inheritance + W1 全寬 paint(一條線)
+   *   row 2 = tabsSlot 包在 `HEADER_TABS_SLOT_WRAPPER_CLASS` wrapper
+   *           (`[&_[data-slot=tabs-list]]` 注入 TabsList 內 px-loose;寬度 TabsList 各
+   *           overflow 模式自帶 w-full / min-w-full;wrapper 本身無 padding 無 border——
+   *           border 由 TabsList 自畫,W1 全寬 paint 一條線)
    *
    * Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 放 ChromeHeader 之外。
    * Standalone Tabs(無 chrome header)該直接用 `<TabsList>` 不需 wrapper。
@@ -112,8 +130,10 @@ export const ChromeHeader = React.forwardRef<HTMLElement, ChromeHeaderProps>(
           {/* Row 2:tabsSlot wrapper — TabsList 全 dialog 寬 + 內 px-loose inset triggers
               2026-05-18 v3 fix(同 SurfaceHeader,per user verbatim「分隔線寬度應該要填滿整個
               dialog」+「就這樣做」approval):TabsList 自己 px-loose 內 padding 而非 wrapper
-              提供,讓 TabsList border-b 延展全 dialog 寬。對齊 `tabs.spec.md:199` 既有 canonical。*/}
-          <div className="[&>[role=tablist]]:w-full [&>[role=tablist]]:px-[var(--layout-space-loose)]">
+              提供,讓 TabsList border-b 延展全 dialog 寬。對齊 `tabs.spec.md:199` 既有 canonical。
+              2026-07-30 v4:選取機制改 `data-slot="tabs-list"` attribute contract(beta.86
+              overlay 包裹層破 direct-child;詳 HEADER_TABS_SLOT_WRAPPER_CLASS 註解)。*/}
+          <div className={HEADER_TABS_SLOT_WRAPPER_CLASS}>
             {tabsSlot}
           </div>
         </header>

package/src/patterns/header-canonical/header-canonical.css

@@ -9,16 +9,15 @@
      + 5-DS 共識:Linear / Notion / Figma / Slack / Polaris chrome header brand mark
      皆固定 24px,不 density-scale 也不 row-size-scale)。
 
-     Chrome header **不是 row context**(per `item-anatomy.spec.md:535` scope 限定
-     段)— chrome header 內 avatar 用 raw `<Avatar size={24}>`,**不用 `<ItemAvatar>`**。
+     Chrome header **不是 row context**(per `item-anatomy.spec.md`「Scope 例外:Chrome header 不是 row context」段;段名指法免行號漂移)— chrome header 內 avatar 用 raw `<Avatar size={24}>`,**不用 `<ItemAvatar>`**。
 
      Consumers(2,需 sync):
-       1. WorkspaceBrand demo(`_demo-helpers.tsx`)hardcode `<Avatar size={24}>` + comment cite token
+       1. WorkspaceBrand demo(`components/AppShell/_demo-helpers.tsx`)hardcode `<Avatar size={24}>` + comment cite token
        2. SidebarHeader 收合 padding 公式:
           calc((var(--sidebar-width-icon) - var(--chrome-header-avatar-size)) / 2)
 
      **Sync invariant**:Token 值 + WorkspaceBrand `size={24}` literal + AVATAR_SIZE.inline.md
-     (`item-anatomy.tsx:93`)三者必同 24。改 spec canonical 時 grep
+     (`item-anatomy.tsx:94` AVATAR_SIZE.inline.md)三者必同 24。改 spec canonical 時 grep
      `--chrome-header-avatar-size` + `chrome header avatar canonical` 雙向找 sync 點。
    ───────────────────────────────────────────────────────── */