@qijenchen/design-system 0.1.0-beta.88 → 0.1.0-beta.90

package/src/components/DataTable/data-table.tsx

@@ -45,6 +45,7 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
 import { dragSourceStyle, dropIndicatorRow, dropIndicatorColumn, dragActiveCursor, isReorderNoop, reconstructFullRowGhost, snapToCursorModifier } from '@/design-system/lib/drag-visual'
 import { nakedCellEditableDisplayHover, fieldDisplayTextClass } from '@/design-system/components/Field/field-wrapper'
 import { Tooltip, TooltipContent, TooltipTrigger } from '@/design-system/components/Tooltip/tooltip'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
 import { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator } from '@/design-system/components/DropdownMenu/dropdown-menu'
 import { ItemInlineActionButton } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { columnTypeDefaults, type ColumnType } from './column-types'
@@ -403,50 +404,11 @@ function columnSizeStyle(
 const SYSTEM_COL_IDS = new Set([SELECT_COL_ID, '__drag__', '__actions__'])
 const isSystemColumn = (colId: string) => SYSTEM_COL_IDS.has(colId)
 
-// ── TruncateCell ─────────────────────────────────────────────────────────────
-// Shared ResizeObserver(2026-04-22 D3 perf audit):從 per-cell RO 改為全 DS 共用一個 RO
-// dispatch 到 per-element callback。10 col × 100 row = 1 RO(before:1000 RO)。
-// 跨 OS 一致的 RO 行為;element 卸載時 cleanup。
-
-type RoCallback = (entry: ResizeObserverEntry) => void
-let sharedResizeObserver: ResizeObserver | null = null
-const roCallbacks = new WeakMap<Element, RoCallback>()
-
-function getSharedRO(): ResizeObserver {
-  if (sharedResizeObserver) return sharedResizeObserver
-  sharedResizeObserver = new ResizeObserver((entries) => {
-    entries.forEach((entry) => {
-      const cb = roCallbacks.get(entry.target)
-      if (cb) cb(entry)
-    })
-  })
-  return sharedResizeObserver
-}
-
-function observeShared(el: Element, cb: RoCallback): () => void {
-  const obs = getSharedRO()
-  roCallbacks.set(el, cb)
-  obs.observe(el)
-  return () => {
-    roCallbacks.delete(el)
-    obs.unobserve(el)
-  }
-}
-
-function TruncateCell({ children, className }: { children: React.ReactNode; className?: string }) {
-  const ref = React.useRef<HTMLSpanElement>(null)
-  const [isTruncated, setIsTruncated] = React.useState(false)
-  React.useEffect(() => {
-    const el = ref.current
-    if (!el) return
-    const check = () => setIsTruncated(el.scrollWidth > el.clientWidth)
-    check()
-    return observeShared(el, check)
-  }, [])
-  const span = <span ref={ref} className={cn('truncate min-w-0', className)}>{children}</span>
-  if (!isTruncated) return span
-  return <Tooltip><TooltipTrigger asChild>{span}</TooltipTrigger><TooltipContent>{children}</TooltipContent></Tooltip>
-}
+// ── TruncatedText ── 2026-07-19:truncate+tooltip 引擎 + presentation 已抽成 SSOT primitive
+// `patterns/element-anatomy/truncated-text`(`<TruncatedText>` 消費 `useTruncated` hook)。原 file-local
+// shared RO(2026-04-22 D3 perf audit 的「全 DS 共用單一 RO」特性由 hook 承接)+ TruncateCell 已移除,
+// 改用 `<TruncatedText tooltip={children} className={...}>`(display 預設 inline,保 cell baseline)。
+// compound 欄位仍在 renderCellContent bypass(見下)—— 只 primitive string/number 走 TruncatedText。
 
 // ── L4 Row Drag: SortableRowContext(v15 Path B;2026-07-14 JSDoc 對齊實作)──────
 // 每 region(left / center / right)各 mount 一次 SortableRowProvider,依 role 分流(v15.4 split):
@@ -1511,10 +1473,10 @@ function DataTableInner<TData>(
     const meta = cell.column.columnDef.meta
     const colType = meta?.type as ColumnType | undefined
     const wrap = autoRowHeight && meta?.wrap === true
-    // 已知 compound 欄位(Tag / PersonDisplay / LinkInput 等自帶 layout)直接 bypass TruncateCell,
+    // 已知 compound 欄位(Tag / PersonDisplay / LinkInput 等自帶 layout)直接 bypass TruncatedText,
     // 因為 `truncate` 的 inline baseline context 會破壞自訂 layout 的垂直對齊。
     // 2026-05-09 D-path:date / time 加入(showDisplayEndIcon → Field naked-view 需 full width 才能
-    //   右對齊 ItemSuffix。TruncateCell 的 `<span truncate min-w-0>` block-display 會 collapse Field
+    //   右對齊 ItemSuffix。TruncatedText 的 `<span truncate min-w-0>` block-display 會 collapse Field
     //   to content size,讓 Calendar / Clock icon 緊貼 value text 而非右邊緣)。
     const isKnownCompound = colType === 'select' || colType === 'multiSelect' || colType === 'person' || colType === 'multiPerson' || colType === 'url' || colType === 'date' || colType === 'time'
     const rowId = cell.row.id
@@ -1555,8 +1517,8 @@ function DataTableInner<TData>(
       content = flexRender(cell.column.columnDef.cell, cell.getContext())
     }
     // Consumer 自訂 cell(無 colType)若回傳 React element,視為 compound — consumer 自己處理
-    // 對齊與截斷。回傳 primitive(string / number)才走 TruncateCell。
-    // 理由:TruncateCell 的 `span.truncate` 強制 white-space:nowrap + inline baseline,
+    // 對齊與截斷。回傳 primitive(string / number)才走 TruncatedText。
+    // 理由:TruncatedText 的 `span.truncate` 強制 white-space:nowrap + inline baseline,
     // 對 inline-flex / icon+text 自訂結構會拉歪(見 circular-progress sync table 案例)。
     // **edit mode bypass**(2026-05-05 v9 Bug 2 修):editing cell 內部是 Field 控件
     // (Input/Textarea/Select etc.)自管 layout + 替代元素(textarea)不該被包進 inline span
@@ -1565,7 +1527,7 @@ function DataTableInner<TData>(
     return isEditingThisCell ? content
       : wrap ? <span className="break-words min-w-0">{content}</span>
       : (isKnownCompound || isConsumerCompound) ? content
-      : <TruncateCell>{content}</TruncateCell>
+      : <TruncatedText>{content}</TruncatedText>
   }
 
   // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
@@ -1790,7 +1752,7 @@ function DataTableInner<TData>(
           //   - **沒有** cell 自己 box-shadow ring — focus / hover / open ring 由 Field naked 自帶
           //     state machine 提供(對齊 user「狀態樣式取決於原輸入框」reminder)
           // 字級隨 size:sm/md text-body / lg text-body-lg(fieldDisplayTextClass),對齊 Field family
-          // size→font SSOT。此為非-Field content(consumer 自訂 cell / TruncateCell 純文字)的 fallback 字級;
+          // size→font SSOT。此為非-Field content(consumer 自訂 cell / TruncatedText 純文字)的 fallback 字級;
           // typed cell 各自的 Field 控件已自帶 size→font(cell-registry 傳 size)。
           'group/cell flex text-foreground font-normal shrink-0 relative self-stretch',
           fieldDisplayTextClass(size),
@@ -2216,9 +2178,9 @@ function DataTableInner<TData>(
             canSort && 'focus-visible:ring-2 focus-visible:ring-ring rounded-md',
           )}
         >
-          <TruncateCell className={cn('min-w-0', align === 'right' && 'text-right', align === 'center' && 'text-center')}>
+          <TruncatedText className={cn('min-w-0', align === 'right' && 'text-right', align === 'center' && 'text-center')}>
             {header.isPlaceholder ? null : flexRender(header.column.columnDef.header, header.getContext())}
-          </TruncateCell>
+          </TruncatedText>
           {canSort && sortDir && !isMultiSort && (
             // 2026-05-18 改 per user 拍板「DataTable sort 跟 row size 變」+「做完」approval:
             // 原固定 14 違反 uiSize.spec.md Icon Tier(sm/md→16, lg→20)。改 ICON_SIZE[size]

package/src/components/Tag/tag.tsx

@@ -5,6 +5,7 @@ import type { LucideIcon } from "lucide-react"
 
 import { cn } from "@/lib/utils"
 import { Tooltip, TooltipTrigger, TooltipContent } from "@/design-system/components/Tooltip/tooltip"
+import { useTruncated } from "@/design-system/hooks/use-truncated"
 import { ItemInlineActionButton } from "@/design-system/patterns/element-anatomy/item-anatomy"
 import { CAT_SUBTLE, CAT_SOLID, CAT_INTERACT } from "@/design-system/tokens/categorical-color"
 
@@ -129,16 +130,16 @@ function TagInner(
   forwardedRef: React.ForwardedRef<HTMLDivElement>,
 ) {
   const solidClass = solid ? SOLID_CLASSES[color ?? 'neutral'] : undefined
-  const ownRef = React.useRef<HTMLDivElement | null>(null)
-  const [isTruncated, setIsTruncated] = React.useState(false)
-
-  React.useLayoutEffect(() => {
-    const el = ownRef.current
-    if (!el) return
-    const ctx = getMeasureCtx()
-    const check = () => {
+  // 截斷偵測用 SSOT 引擎 `useTruncated`(patterns/element-anatomy 的 hook)。Tag 走**變異型**:
+  //   - measure = Canvas measureText(flex 內 scrollWidth 不可靠,line 20)：observe root、量測內層
+  //     `[data-tag-text]` span(trigger≠量測元素);回 undefined = 無法量測時保留前一 state。
+  //   - timing='layoutEffect'(避免 paint flash)/ deps=[children](children 變重量)/ recheckAfterPaint=false
+  //     (Tag 原本即無 rAF/timeout 二次量)—— 三處變異全走 options,行為零漂移。
+  const { ref: ownRef, isTruncated } = useTruncated<HTMLDivElement>({
+    measure: (el) => {
       const textSpan = el.querySelector('[data-tag-text]')
-      if (!textSpan || !ctx) return
+      const ctx = getMeasureCtx()
+      if (!textSpan || !ctx) return undefined
       const text = textSpan.textContent || ''
       const cs = getComputedStyle(textSpan)
       ctx.font = `${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`
@@ -146,13 +147,12 @@ function TagInner(
       const padL = parseFloat(cs.paddingLeft) || 0
       const padR = parseFloat(cs.paddingRight) || 0
       const needed = textWidth + padL + padR
-      setIsTruncated(needed > (textSpan as HTMLElement).clientWidth + 1)
-    }
-    check()
-    const obs = new ResizeObserver(check)
-    obs.observe(el)
-    return () => obs.disconnect()
-  }, [children])
+      return needed > (textSpan as HTMLElement).clientWidth + 1
+    },
+    deps: [children],
+    timing: 'layoutEffect',
+    recheckAfterPaint: false,
+  })
 
   const label = typeof children === 'string' ? children : ''
 
@@ -208,10 +208,14 @@ function TagInner(
     </div>
   )
 
-  if (!isTruncated) return tag
-
+  // 永遠 wrap Tooltip、以 open 控制可見(對齊 truncated-text.spec.md:49「永遠 wrap」+ :55「❌ 條件 wrap」canonical
+  // + useTruncated 家族;tooltip.principles.stories.tsx:190「沒被截斷就不該顯示 tooltip」由 open={false} 機械保證)。
+  // 未截斷 open={false} → tooltip 靜默(TooltipTrigger asChild 只把 handler/data-state 合併到 tag div,零多餘 DOM、
+  // 視覺與裸 tag 等價,pixel-identical)。always-wrap 保 tag div 生命週期穩定 → isTruncated false→true 不 remount:
+  // 先前條件-wrap(未截斷回裸 tag / 截斷才 wrap)切換 JSX 樹會 remount tag div,但 useTruncated deps=[children] 未變
+  // → effect 不重跑重新 observe 新 div → shared RO 卡在舊 detached div → isTruncated 卡 true(未截斷仍顯示 tooltip)。
   return (
-    <Tooltip>
+    <Tooltip open={isTruncated ? undefined : false}>
       <TooltipTrigger asChild>{tag}</TooltipTrigger>
       <TooltipContent>{children}</TooltipContent>
     </Tooltip>

package/src/hooks/use-truncated.ts

@@ -0,0 +1,111 @@
+import * as React from 'react'
+
+// ── useTruncated — 單行文字截斷偵測引擎(SSOT)─────────────────────────────────
+// 收斂 Breadcrumb TruncatedLabel / DataTable TruncateCell(兩處 module-level shared ResizeObserver 引擎
+// **逐字重複**,僅變數名不同)+ Tag(原 per-instance `new ResizeObserver`)三處的截斷偵測 + isTruncated
+// 狀態機為唯一 owner(M17 SSOT);Tag 亦收斂進共用 shared RO,行為等價。
+//
+// 世界級對照(M8):MUI/MUI-X 官方無第一方 primitive,社群共識 = 「hook 量測 scrollWidth>clientWidth
+//   + ref + 以 Tooltip `open` prop 條件控制」(issue #37211);此 hook 即該低階量測層,
+//   上層 `<TruncatedText>`(patterns/element-anatomy)對應 Ant `Typography.Text ellipsis` 高階元件。
+//
+// 三處變異點皆以 options 注入,**行為零漂移**:
+//   - Breadcrumb / DataTable:預設 scrollWidth>clientWidth。
+//   - Tag:trigger≠量測元素(observe root、量測內層 span)+ Canvas measureText(flex 內 scrollWidth
+//     不可靠)+ useLayoutEffect(避免 paint flash)+ deps=[children] → 全走 options。
+
+type RoCallback = (entry: ResizeObserverEntry) => void
+
+let sharedRO: ResizeObserver | null = null
+const sharedROCallbacks = new WeakMap<Element, RoCallback>()
+
+// 全 DS 共用單一 ResizeObserver,dispatch 到 per-element callback(2026-04-22 DataTable D3 perf audit
+// 成果:10 col × 100 row = 1 RO 而非 1000)。element 卸載時 cleanup,singleton RO 本身不 disconnect。
+function getSharedRO(): ResizeObserver {
+  if (sharedRO) return sharedRO
+  sharedRO = new ResizeObserver((entries) => {
+    entries.forEach((e) => {
+      const cb = sharedROCallbacks.get(e.target)
+      if (cb) cb(e)
+    })
+  })
+  return sharedRO
+}
+
+function observeShared(el: Element, cb: RoCallback): () => void {
+  const obs = getSharedRO()
+  sharedROCallbacks.set(el, cb)
+  obs.observe(el)
+  return () => {
+    sharedROCallbacks.delete(el)
+    obs.unobserve(el)
+  }
+}
+
+export interface UseTruncatedOptions {
+  /**
+   * 偵測策略:回傳 `true` = 截斷、`false` = 未截斷、`undefined` = 本次無法量測(保留前一狀態)。
+   * 預設 = `el.scrollWidth > el.clientWidth`(觀察元素自身)。
+   * Tag 傳自訂 fn:observe root、內部 `querySelector('[data-tag-text]')` + Canvas measureText。
+   */
+  measure?: (observedEl: HTMLElement) => boolean | undefined
+  /** deps 變更時 cleanup + 重新量測 / 重新訂閱(Tag 傳 `[children]`)。預設 `[]`(mount-once)。 */
+  deps?: React.DependencyList
+  /**
+   * 是否在首次 paint 後以 `requestAnimationFrame` + `setTimeout(100)` 再量一次,捕獲首幀 layout
+   * 未完成 / 字型 async load 的假陰性(Breadcrumb 已採此 robust 版)。預設 `true`。
+   */
+  recheckAfterPaint?: boolean
+  /** `'layoutEffect'` = `useLayoutEffect`(量測在 paint 前,避免 flash;Tag 用)/ `'effect'` = `useEffect`。預設 `'effect'`。 */
+  timing?: 'effect' | 'layoutEffect'
+}
+
+const defaultMeasure = (el: HTMLElement): boolean => el.scrollWidth > el.clientWidth
+
+/**
+ * 偵測 ref 所指元素的文字是否被截斷,回傳 `{ ref, isTruncated }`。
+ * `isTruncated` 用來驅動 Tooltip「僅截斷時顯示」(對齊 `tooltip.principles.stories.tsx`「沒被截斷就不該顯示 tooltip」)。
+ */
+export function useTruncated<E extends HTMLElement = HTMLElement>(
+  options: UseTruncatedOptions = {},
+): { ref: React.MutableRefObject<E | null>; isTruncated: boolean } {
+  const { measure = defaultMeasure, deps = [], recheckAfterPaint = true, timing = 'effect' } = options
+  // MutableRefObject(consumer 可經 callback ref 寫入 .current 以與 forwardedRef 合併,如 Tag)。
+  const ref = React.useRef<E | null>(null)
+  const [isTruncated, setIsTruncated] = React.useState(false)
+
+  // measure 每 render 可能是新 closure(consumer inline);收進 ref 讓 effect 不因它重訂閱,
+  // 但 RO 回呼仍讀到最新版。
+  const measureRef = React.useRef(measure)
+  measureRef.current = measure
+
+  // timing 為 call-site 固定字面值(某 consumer 永遠同一值)→ 每個 component instance 每 render
+  // 呼叫同一個 effect hook,符合 rules-of-hooks。
+  const useIsoEffect = timing === 'layoutEffect' ? React.useLayoutEffect : React.useEffect
+
+  useIsoEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const check = () => {
+      const r = measureRef.current(el)
+      if (r !== undefined) setIsTruncated(r)
+    }
+    check()
+    let raf = 0
+    let t: ReturnType<typeof setTimeout> | undefined
+    if (recheckAfterPaint) {
+      raf = requestAnimationFrame(check)
+      t = setTimeout(check, 100)
+    }
+    const cleanup = observeShared(el, check)
+    return () => {
+      if (raf) cancelAnimationFrame(raf)
+      if (t) clearTimeout(t)
+      cleanup()
+    }
+    // deps 由 consumer 決定(Tag: [children];其餘: []);measure 走 ref 不需進 deps。
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, deps)
+
+  return { ref, isTruncated }
+}

package/src/index.ts

@@ -601,6 +601,8 @@ export type {
 //   - patterns/element-anatomy:ItemInlineActionButtonProps
 //   - patterns/element-anatomy:ItemInlineActionProps
 //   - patterns/element-anatomy:RowSizeProvider
+//   - patterns/element-anatomy:TruncatedText
+//   - patterns/element-anatomy:TruncatedTextProps
 
 // ─── Tokens(JS mirrors — token SSOT 程式面)──────────────────────────────
 export * from './tokens/categorical-color'
@@ -614,6 +616,7 @@ export * from './hooks/use-controllable'
 export * from './hooks/use-is-narrow-viewport'
 export * from './hooks/use-is-touch-device'
 export * from './hooks/use-overflow-items'
+export * from './hooks/use-truncated'
 
 // ─── Lib utilities ────────────────────────────────────────────────────────
 export * from './lib/drag-visual'

package/src/patterns/element-anatomy/index.ts

@@ -3,3 +3,4 @@
 //   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
 // Regenerate: node scripts/gen-component-indexes.mjs
 export * from './item-anatomy'
+export * from './truncated-text'

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

@@ -0,0 +1,57 @@
+---
+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`,不處理多行);(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);回 `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)。

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'