@qijenchen/design-system 0.1.0-beta.87 → 0.1.0-beta.89

package/src/components/Breadcrumb/breadcrumb.tsx

@@ -5,7 +5,7 @@ import { Slot } from '@radix-ui/react-slot'
 import { ChevronRight, MoreHorizontal, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { ItemInlineActionButton } from '@/design-system/patterns/element-anatomy/item-anatomy'
-import { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'
+import { TruncatedText } from '@/design-system/patterns/element-anatomy/truncated-text'
 import {
   DropdownMenu,
   DropdownMenuTrigger,
@@ -13,70 +13,9 @@ import {
   DropdownMenuItem,
 } from '@/design-system/components/DropdownMenu/dropdown-menu'
 
-// ── TruncatedLabel ────────────────────────────────────────────────────────────
-// 同 `data-table.tsx TruncateCell` + `tag.tsx isTruncated` SSOT pattern
-// (shared ResizeObserver + scrollWidth > clientWidth → wrap Tooltip)。
-// **TODO** future:Rule-of-3 達 → 抽 `patterns/element-anatomy/truncated-text.tsx` 共用
-// (本 component / DataTable TruncateCell / Tag inner 三處同 idiom,符合 M30 SSOT 抽取門檻)。
-
-type RoCallback = (entry: ResizeObserverEntry) => void
-let sharedRO: ResizeObserver | null = null
-const sharedROCallbacks = new WeakMap<Element, RoCallback>()
-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) }
-}
-
-function TruncatedLabel({ children, fullText }: { children: React.ReactNode; fullText?: 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()
-    // 2026-05-11 fix:首幀 layout 未完成 / 字型 async load → scrollWidth=clientWidth 假陰性。
-    // RAF + 短延遲再驗一次,捕獲字型 / 容器尺寸後變(對齊 TruncateCell / Tag SSOT pattern)。
-    const raf = requestAnimationFrame(check)
-    const t = setTimeout(check, 100)
-    const cleanup = observeShared(el, check)
-    return () => {
-      cancelAnimationFrame(raf)
-      clearTimeout(t)
-      cleanup()
-    }
-  }, [])
-  // Tooltip canonical:per `tooltip.principles.stories.tsx:190`「Tooltip 是資訊補救 — 文字被
-  // truncate 時才顯示完整內容。沒被截斷就不該顯示 tooltip」
-  //
-  // 2026-05-11 fix(playwright tooltip-on-truncate 卡 hover 沒 tooltip):
-  // 原本 isTruncated=false 直接 return 裸 span / true 才 wrap Tooltip → JSX 樹結構改變
-  // → React 把 span unmount + remount(因為 wrapper component 變),ref 換到新 span,
-  // useEffect [] 不重跑(同 component instance)→ 觀察的 DOM 跟實際 DOM 對不上。
-  // Fix:**永遠 wrap Tooltip**(同 DOM 節點生命週期);`open` 由 isTruncated 控制 —
-  // 沒被 truncate 就 force `open={false}`,有 truncate 就 `undefined`(uncontrolled,
-  // hover 走 Radix default behavior)。對齊 canonical「沒被截斷就不該 tooltip」。
-  return (
-    <Tooltip open={isTruncated ? undefined : false}>
-      <TooltipTrigger asChild>
-        <span ref={ref} className="truncate min-w-0 block">{children}</span>
-      </TooltipTrigger>
-      <TooltipContent>{fullText ?? children}</TooltipContent>
-    </Tooltip>
-  )
-}
+// ── TruncatedLabel ── 2026-07-19:truncate+tooltip 引擎 + presentation 已抽成 SSOT primitive
+// `patterns/element-anatomy/truncated-text`(`<TruncatedText>` 消費 `useTruncated` hook)。本檔改為
+// 消費 `<TruncatedText display="block" tooltip={fullText}>`,原 file-local shared RO + TruncatedLabel 已移除。
 
 /**
  * Breadcrumb — 顯示當前頁面在階層中的位置
@@ -212,10 +151,10 @@ const BreadcrumbList = React.forwardRef<HTMLOListElement, BreadcrumbListProps>(
         <BreadcrumbItem key={`${role}-${typeof spec.label === 'string' ? spec.label : idx}`} role={role}>
           {role === 'current'
             ? <BreadcrumbPage startIcon={spec.startIcon}>
-                <TruncatedLabel fullText={typeof spec.label === 'string' ? spec.label : undefined}>{spec.label}</TruncatedLabel>
+                <TruncatedText display="block" tooltip={typeof spec.label === 'string' ? spec.label : undefined}>{spec.label}</TruncatedText>
               </BreadcrumbPage>
             : <BreadcrumbLink href={spec.href} asChild={spec.asChild} startIcon={spec.startIcon}>
-                <TruncatedLabel fullText={typeof spec.label === 'string' ? spec.label : undefined}>{spec.label}</TruncatedLabel>
+                <TruncatedText display="block" tooltip={typeof spec.label === 'string' ? spec.label : undefined}>{spec.label}</TruncatedText>
               </BreadcrumbLink>
           }
         </BreadcrumbItem>
@@ -326,19 +265,30 @@ const BreadcrumbList = React.forwardRef<HTMLOListElement, BreadcrumbListProps>(
                 {collapsedItems.map((item, j) => {
                   // 2026-05-12 Round 4.5 fix(codex M31 Layer C 抓):consumer BreadcrumbItem children 常包
                   // `<BreadcrumbLink href>` = anchor button-like。直接放進 `<DropdownMenuItem>` 會 nested
-                  // interactive(menuitem within button violates HTML / a11y)。Fix:extract href + label,
-                  // 用 `asChild` 把 anchor 接到 menuitem 對齊 declarative path line 245 canonical pattern。
+                  // interactive(menuitem within button violates HTML / a11y)。Fix:把實際 link 元素接到
+                  // menuitem `asChild`,對齊 declarative path canonical pattern。
+                  // 2026-07-19 fix(DA3 對抗稽核抓):原只讀 `c.props.href` → `<BreadcrumbLink asChild>
+                  //   <RouterLink to=…>` 這種(BreadcrumbLink 無 href、RouterLink child 帶 `to`)摺疊後
+                  //   dropdown 失去導航目標。修:asChild 時**保留整個 link 子元素**(RouterLink/<Link to>/<a>,
+                  //   含 to/href/onClick/state 全 forward,前端路由不退化成整頁重載);純 href 才重建 <a>。
                   const innerChildren = (item.props as { children?: React.ReactNode }).children
-                  let href: string | undefined
-                  let label: React.ReactNode = innerChildren
+                  let menuChild: React.ReactNode | undefined  // 接進 menuitem(asChild)的實際 link 元素
+                  let label: React.ReactNode = innerChildren   // fallback:無 link 時的純內容
                   React.Children.forEach(innerChildren, (c) => {
-                    if (React.isValidElement<{ href?: string; children?: React.ReactNode }>(c)) {
-                      if (c.props.href) href = c.props.href
+                    if (!React.isValidElement<{ href?: string; asChild?: boolean; children?: React.ReactNode }>(c)) return
+                    if (c.props.asChild && React.isValidElement(c.props.children)) {
+                      // BreadcrumbLink asChild → 實際 link = 其 child(RouterLink / <Link to> / <a>),整個保留
+                      menuChild = c.props.children
+                      const grand = (c.props.children.props as { children?: React.ReactNode }).children
+                      if (grand != null) label = grand
+                    } else if (c.props.href != null) {
+                      // BreadcrumbLink href → 重建 <a href>(對齊原 canonical，避免 nested interactive)
+                      menuChild = <a href={c.props.href}>{c.props.children}</a>
                       if (c.props.children != null) label = c.props.children
                     }
                   })
-                  return href
-                    ? <DropdownMenuItem key={`collapsed-${j}`} asChild><a href={href}>{label}</a></DropdownMenuItem>
+                  return menuChild
+                    ? <DropdownMenuItem key={`collapsed-${j}`} asChild>{menuChild}</DropdownMenuItem>
                     : <DropdownMenuItem key={`collapsed-${j}`}>{label}</DropdownMenuItem>
                 })}
               </DropdownMenuContent>
@@ -450,7 +400,7 @@ const BreadcrumbLink = React.forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
     // on truncate」per spec.md / Polaris breadcrumb)。Non-string children(consumer 自訂 icon+text
     // 結構)→ pass-through 不 force-wrap(consumer own truncate)。
     const wrappedChildren = typeof children === 'string'
-      ? <TruncatedLabel fullText={children}>{children}</TruncatedLabel>
+      ? <TruncatedText display="block" tooltip={children}>{children}</TruncatedText>
       : children
     const sharedClassName = cn(
       'inline-flex items-center gap-2',
@@ -498,7 +448,7 @@ const BreadcrumbPage = React.forwardRef<HTMLSpanElement, BreadcrumbPageProps>(
     const { size } = React.useContext(BreadcrumbContext)
     // 2026-05-12 fix(同 BreadcrumbLink):純文字 children → auto-wrap TruncatedLabel。
     const wrappedChildren = typeof children === 'string'
-      ? <TruncatedLabel fullText={children}>{children}</TruncatedLabel>
+      ? <TruncatedText display="block" tooltip={children}>{children}</TruncatedText>
       : children
     return (
       <span

package/src/components/Calendar/calendar.stories.tsx

@@ -51,7 +51,7 @@ export const TeamCalendar: Story = {
           defaultReferenceDate={now}
           events={events}
           onEventClick={(e) => alert(`點了事件:${e.title}`)}
-          onDateClick={(d) => console.log('點 date cell:', d)}
+          onDateClick={() => { /* demo:實際 app 在此開「當日新增事件」面板 */ }}
           onCreateEvent={() => alert('開啟新事件對話框')}
         />
       </div>

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>
-}
+// ── TruncateCell ── 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):
@@ -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)
@@ -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 : ''
 

package/src/hooks/use-truncated.ts

@@ -0,0 +1,110 @@
+import * as React from 'react'
+
+// ── useTruncated — 單行文字截斷偵測引擎(SSOT)─────────────────────────────────
+// 收斂 Breadcrumb TruncatedLabel / DataTable TruncateCell / Tag 三處**逐字重複**的
+// module-level shared ResizeObserver 引擎 + isTruncated 狀態機為唯一 owner(M17 SSOT)。
+//
+// 世界級對照(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'