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

package/src/components/Breadcrumb/breadcrumb.stories.tsx

@@ -0,0 +1,381 @@
+// @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.
+// @story-history: Breadcrumb 是純結構導覽元件,disabled/states 由 BreadcrumbLink 內部 :focus-visible / :hover / :active 處理(spec.md 互動狀態段已 cover),無 element-level disabled mode(spec.md 互動狀態 > Disabled 段「通常 breadcrumb link 不會 disabled」)。互動行為示範由 InteractiveEllipsis story + anatomy StateBehavior 完整覆蓋。AllSizes retired per F migration 2026-05-15(anatomy auto-compile SizeMatrix owns size showcase)。
+import type { Meta, StoryObj } from '@storybook/react'
+import { House } from 'lucide-react'
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbEllipsis,
+} from './breadcrumb'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+
+const meta: Meta<typeof Breadcrumb> = {
+  title: 'Design System/Components/Breadcrumb/展示',
+  tags: ['autodocs'],
+  component: Breadcrumb,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '顯示目前頁面在資訊架構中的階層路徑，並讓使用者返回上層。頁面位於兩層以上導覽結構且需要保留位置感時使用；平行頁面切換改用 Tabs 或側欄。' } },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof Breadcrumb>
+
+// ── Default ──────────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  name: '預設',
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/">首頁</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="/projects">專案</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>新增專案</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
+}
+
+// ── Interactive ellipsis (折疊路徑 → DropdownMenu) ─────────────────────────
+
+export const InteractiveEllipsis: Story = {
+  name: '可互動省略',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      {/* 內部實作(對 consumer 不可見):BreadcrumbEllipsis 永遠 render <button> + DropdownMenuTrigger
+          asChild 注入 dropdown 行為;hover 走 neutral(fg-muted → foreground + neutral hover bg,消費
+          ItemInlineActionButton),刻意與 BreadcrumbLink 的 primary-hover 語言區隔。 */}
+      <div className="text-caption text-fg-muted max-w-xl">
+        點 <code>⋯</code> 會開選單,列出被折疊起來的中間層級。滑鼠移上去時 <code>⋯</code> 用中性灰的高亮
+        (和一般連結的主色高亮刻意分開,讓「展開選單」和「跳到某一層」兩種動作一眼可辨),對齊 Material /
+        Atlassian / Ant Design 的做法。
+      </div>
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink href="/">首頁</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <BreadcrumbEllipsis />
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start">
+                <DropdownMenuItem asChild>
+                  <a href="/org" onClick={(e) => e.preventDefault()}>組織</a>
+                </DropdownMenuItem>
+                <DropdownMenuItem asChild>
+                  <a href="/org/team" onClick={(e) => e.preventDefault()}>產品團隊</a>
+                </DropdownMenuItem>
+                <DropdownMenuItem asChild>
+                  <a href="/org/team/members" onClick={(e) => e.preventDefault()}>成員管理</a>
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbLink href="/org/team/members/alice">Alice</BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbPage>權限設定</BreadcrumbPage>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>
+    </div>
+  ),
+}
+
+// @story-history: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
+// ── Declarative items + auto-collapse(Phase B,2026-05-10)──────────────────
+//
+// @story-history: 此 story 展示 Phase B declarative `items` API + auto-collapse
+// (maxItems=4)+ flex-shrink hierarchy + truncate-on-overflow + tooltip canonical(per
+// `tooltip.principles.stories.tsx:190`)。Disabled / States 仍由 BreadcrumbLink 內部 :hover /
+// :focus-visible / :active 處理(spec.md 互動狀態 > Disabled 段,無 element-level disabled)。
+
+export const DeclarativeAutoCollapse: Story = {
+  name: '宣告式 API + 自動收合',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-2xl">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">
+          ≤ maxItems(4)— 全顯
+        </h3>
+        <p className="text-caption text-fg-muted mb-3">
+          3 items 不超 maxItems=4,所有 item 自然 render。
+        </p>
+        <Breadcrumb>
+          <BreadcrumbList
+            items={[
+              { label: '首頁', href: '/' },
+              { label: '專案', href: '/projects' },
+              { label: '我的新專案' },  // 無 href → 自動 BreadcrumbPage(末位)
+            ]}
+          />
+        </Breadcrumb>
+      </div>
+
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">
+          5 items 超 maxItems(4)— auto-collapse 中段
+        </h3>
+        <p className="text-caption text-fg-muted mb-3">
+          itemsBeforeCollapse=1 + itemsAfterCollapse=1 → 首 + ⋯ + 末。
+          中段 [專案, Q1, 行銷活動] 全進 DropdownMenu(點 ⋯ 看)。
+        </p>
+        <Breadcrumb>
+          <BreadcrumbList
+            items={[
+              { label: '首頁', href: '/' },
+              { label: '專案', href: '/projects' },
+              { label: 'Q1', href: '/projects/q1' },
+              { label: '行銷活動', href: '/projects/q1/marketing' },
+              { label: '電子報設計' },
+            ]}
+          />
+        </Breadcrumb>
+      </div>
+
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">
+          自訂 maxItems / itemsAfterCollapse
+        </h3>
+        <p className="text-caption text-fg-muted mb-3">
+          maxItems=6 + itemsAfterCollapse=2 → 首 1 + ⋯ + 末 2(parent + current)。
+        </p>
+        <Breadcrumb>
+          <BreadcrumbList
+            maxItems={6}
+            itemsAfterCollapse={2}
+            items={[
+              { label: '組織', href: '/org' },
+              { label: '產品團隊', href: '/org/team' },
+              { label: '成員', href: '/org/team/members' },
+              { label: 'Alice', href: '/org/team/members/alice' },
+              { label: '權限', href: '/.../permissions' },
+              { label: '角色', href: '/.../roles' },
+              { label: '編輯' },
+            ]}
+          />
+        </Breadcrumb>
+      </div>
+
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">
+          窄容器 + 長 label — flex-shrink hierarchy + truncate + tooltip
+        </h3>
+        <p className="text-caption text-fg-muted mb-3">
+          縮放瀏覽器寬度可觀察:容器變窄時,首項最先被壓縮、中段次之、當前頁最後才縮。
+          每一項文字被截斷時自動顯示 ...,滑鼠移上去會用 tooltip 顯示完整文字;沒被截斷則不顯示 tooltip。
+        </p>
+        {/* @story-history: 2026-05-14 per user 拍板「拿掉 fixed 320px 讓 resize window 測 RWD」— Breadcrumb 是純結構導覽,disabled/states 由 BreadcrumbLink :focus-visible/:hover/:active 處理(spec.md 互動狀態 > Disabled 段),trait check 沿用 file header rationale */}
+        <div className="border border-dashed border-divider rounded-md p-2">
+          <Breadcrumb>
+            <BreadcrumbList
+              items={[
+                { label: 'Global Platform Infrastructure Group', href: '/org' },
+                { label: 'Product Engineering Team', href: '/team' },
+                { label: 'Design System Component Refactor Sprint 23' },
+              ]}
+            />
+          </Breadcrumb>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// @story-history: Deep(5 層)+ TwoLevels(2 層)retired 2026-05-30 per earn-existence 2-test —
+// 兩者與 Default(3 層)教的原則完全相同(BreadcrumbLink + Separator + 末項 BreadcrumbPage),差別僅「深度數字」。
+// 路徑深度變化已由 anatomy Inspector `pathLength` control(3/4/5/6/7 即時切換)+ DeclarativeAutoCollapse(5 層 + auto-collapse)涵蓋。
+
+// @story-history: WithHomeIcon(首項配首頁圖示)retired 2026-06-11 per earn-existence 2-test —
+// 首項 House icon 慣例 + icon 尺寸隨字級自動(sm/md 16px / lg 20px)已由下方 PairedWithPageTitle 三個
+// size 的首項完整示範(原則層 ScopeRule 另有教學),單獨一則 md 尺寸範例屬重複;LinkTo 全庫 grep 無引用。
+
+// ── 配對頁面標題(spec.md size canonical:sm→h4 / md→h3 / lg→h2)─────────
+
+export const PairedWithPageTitle: Story = {
+  name: '與頁面標題配對',
+  parameters: {
+    docs: {
+      description: {
+        story: 'Breadcrumb 的字級應對應頁面標題的層級:sm 配 h4(對話框 / 側板),md 配 h3(一般頁面 header,預設),lg 配 h2(詳情頁主視覺)。讓階層視覺維持平衡,麵包屑不搶走標題的視覺權重。首項配 House icon 為業界慣例,用 startIcon 傳入即可,圖示尺寸由元件依字級自動決定(sm/md 16px、lg 20px),三個尺寸可對照觀察。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-12">
+      <section>
+        <Breadcrumb>
+          <BreadcrumbList size="sm">
+            <BreadcrumbItem><BreadcrumbLink href="/" startIcon={House}>首頁</BreadcrumbLink></BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem><BreadcrumbLink href="/settings">設定</BreadcrumbLink></BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem><BreadcrumbPage>個人偏好</BreadcrumbPage></BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <h4 className="text-h4 text-foreground mt-2">個人偏好</h4>
+        <p className="text-caption text-fg-muted mt-1">size="sm" 配 text-h4 — Dialog / Panel / Drawer header</p>
+      </section>
+
+      <section>
+        <Breadcrumb>
+          <BreadcrumbList size="md">
+            <BreadcrumbItem><BreadcrumbLink href="/" startIcon={House}>首頁</BreadcrumbLink></BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem><BreadcrumbLink href="/projects">專案</BreadcrumbLink></BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem><BreadcrumbPage>Q1 行銷活動</BreadcrumbPage></BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <h3 className="text-h3 text-foreground mt-2">Q1 行銷活動</h3>
+        <p className="text-caption text-fg-muted mt-1">size="md"(預設)配 text-h3 — 一般頁面 header</p>
+      </section>
+
+      <section>
+        <Breadcrumb>
+          <BreadcrumbList size="lg">
+            <BreadcrumbItem><BreadcrumbLink href="/" startIcon={House}>首頁</BreadcrumbLink></BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem><BreadcrumbLink href="/products">產品</BreadcrumbLink></BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem><BreadcrumbPage>2026 春季新品</BreadcrumbPage></BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <h2 className="text-h2 text-foreground mt-2">2026 春季新品</h2>
+        <p className="text-caption text-fg-muted mt-1">size="lg" 配 text-h2 — Detail page hero / Landing</p>
+      </section>
+    </div>
+  ),
+}
+
+// ── 整合 React Router / Next.js Link(asChild slot,replace anchor element)──
+
+export const IntegrateRouterLink: Story = {
+  name: '整合 React Router / Next.js Link',
+  parameters: {
+    docs: {
+      description: {
+        story: '需把 BreadcrumbLink 的樣式與行為套到 router 自帶的 Link 元件(React Router Link / Next.js Link / TanStack Link),用 asChild prop 把 anchor 元素替換成 router Link,樣式 / hover / focus 全自動繼承。常見場景:SPA 不希望 default <a> 觸發整頁 reload。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <div className="text-caption text-fg-muted">
+        以下用 native &lt;a onClick prevent&gt; 模擬 router Link 行為:
+      </div>
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>
+            <BreadcrumbLink asChild>
+              <a href="/" onClick={(e) => e.preventDefault()}>首頁</a>
+            </BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbLink asChild>
+              <a href="/projects" onClick={(e) => e.preventDefault()}>專案</a>
+            </BreadcrumbLink>
+          </BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>
+            <BreadcrumbPage>詳情</BreadcrumbPage>
+          </BreadcrumbItem>
+        </BreadcrumbList>
+      </Breadcrumb>
+    </div>
+  ),
+}
+
+// ── Router Link + 自動摺疊(2026-07-19 回歸防線)────────────────────────────
+//
+// @story-history: 專驗 auto-collapse 抽取器把 `<BreadcrumbLink asChild><router Link>` 中段項目
+//   摺疊進 ⋯ dropdown 時,link 元素(含 to/href/onClick)整個保留、非退化成純文字 —— DA3 對抗稽核抓到的
+//   邏輯 gap 回歸鎖。play() 開摺疊選單並斷言摺疊項目為可點 <a href>(role=menuitem 落在 anchor 上,
+//   非外層 div = 無 nested-interactive)。此處以 `<a onClick prevent>` 模擬 React Router / Next Link。
+export const IntegrateRouterLinkAutoCollapse: Story = {
+  name: '整合 Router Link — 自動摺疊保留導航',
+  parameters: {
+    docs: {
+      description: {
+        story: '6 層路徑超過 maxItems(預設 4)自動摺疊中段;中段用 asChild 套 router Link。摺疊進 ⋯ 下拉後 link 必完整保留(SPA 導航不退化成整頁重載)。點 ⋯ 可見每個摺疊項目仍是可點連結。',
+      },
+    },
+  },
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/" onClick={(e) => e.preventDefault()}>首頁</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/org" onClick={(e) => e.preventDefault()}>組織</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/org/team" onClick={(e) => e.preventDefault()}>產品團隊</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/org/team/members" onClick={(e) => e.preventDefault()}>成員管理</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbItem>
+          <BreadcrumbLink asChild>
+            <a href="/org/team/members/alice" onClick={(e) => e.preventDefault()}>Alice</a>
+          </BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbItem>
+          <BreadcrumbPage>權限設定</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
+  play: async ({ canvasElement }) => {
+    const { userEvent, within, expect, waitFor } = await import('@storybook/test')
+    const canvas = within(canvasElement)
+    // 開摺疊選單(BreadcrumbEllipsis 預設 aria-label = 顯示折疊路徑)
+    const ellipsis = await canvas.findByLabelText('顯示折疊路徑')
+    await userEvent.click(ellipsis)
+    // 核心回歸斷言:摺疊進 dropdown 的 router-link 必保留為可點 <a href="/org/team">(修前會被丟掉 → anchor 不存在)。
+    // 註:DS DropdownMenuItem 內部把 children 包進 role="presentation" 的 MenuItem(role=menuitem 在 Radix Item 層),
+    //   故不斷言 anchor 自身 role;直接驗「導航目標的 anchor 存在且文字對」= 連結保留的真義。dropdown portal 到 body。
+    await waitFor(async () => {
+      const link = document.querySelector('a[href="/org/team"]')
+      await expect(link, '摺疊的 router-link「產品團隊」應保留為可點 <a href="/org/team">(修前退化成純文字)').not.toBeNull()
+      await expect(link?.textContent).toContain('產品團隊')
+    })
+    // 收尾關摺疊選單:Radix DropdownMenu(modal)開著時對背景 nav 上 aria-hidden,背景麵包屑連結
+    // 仍 focusable → axe aria-hidden-focus。斷言已驗完,按 Escape 還原(選單開只為跑斷言,關掉無損展示)。
+    await userEvent.keyboard('{Escape}')
+  },
+}

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:339 TruncateCell` + `tag.tsx:138 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>
-  )
-}
+// ── TruncatedText ── 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 — 顯示當前頁面在階層中的位置
@@ -105,7 +44,7 @@ function TruncatedLabel({ children, fullText }: { children: React.ReactNode; ful
  * ── 視覺 ──
  *   Link (預設): text-fg-secondary
  *   Link hover:  text-primary-hover (canonical「互動高亮」, 跟 Tabs / Chip 用法一致)
- *   Page (當前): text-foreground + font-medium
+ *   Page (當前): text-foreground(不加粗 — 加粗會讓 breadcrumb 最右端視覺過重,見 spec)
  *   Separator:  ChevronRight (size 跟 list 一致), text-fg-muted
  *
  * ── 詳見 breadcrumb.spec.md ──
@@ -127,7 +66,8 @@ const BREADCRUMB_TEXT_CLASS: Record<BreadcrumbSize, string> = {
   lg: 'text-body-lg',
 }
 
-// Separator / ellipsis icon 尺寸 — 對齊 uiSize.spec.md「Icon Size Tier」(field-height-sm/md→16,lg→20)
+// Separator chevron + BreadcrumbLink/Item start icon 尺寸 — 對齊 uiSize.spec.md「Icon Size Tier」(field-height-sm/md→16,lg→20)。
+// 注意:BreadcrumbEllipsis 不消費此常數,固定 md(16px icon,見 BreadcrumbEllipsis 定義),size='lg' 時不隨 chevron 放大到 20
 // 2026-05-18 改 per user 拍板「A 先改 16/16/20」+「做完」approval:
 // 撤回 text-flow 例外設計,Breadcrumb chevron 跟其他 chrome icon 同 tier。
 // World-class 對齊:Atlassian Breadcrumb chevron 16 default / Material 3 / Ant Design 同。
@@ -205,14 +145,16 @@ const BreadcrumbList = React.forwardRef<HTMLOListElement, BreadcrumbListProps>(
     // Declarative mode(items prop provided):自動 render + auto-collapse
     const declarativeContent = React.useMemo(() => {
       if (!items) return null
-      const renderItem = (spec: BreadcrumbItemSpec, role: 'root' | 'middle' | 'current') => (
-        <BreadcrumbItem key={`${role}-${typeof spec.label === 'string' ? spec.label : Math.random()}`} role={role}>
+      // 2026-07-04 修:非字串 label 的 key 原用 Math.random() → 每次 render 新 key 造成
+      // BreadcrumbItem unmount/remount(重置 TruncatedText ResizeObserver 與 state)→ 改 stable idx key
+      const renderItem = (spec: BreadcrumbItemSpec, role: 'root' | 'middle' | 'current', idx: number) => (
+        <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>
@@ -264,7 +206,7 @@ const BreadcrumbList = React.forwardRef<HTMLOListElement, BreadcrumbListProps>(
             </BreadcrumbItem>
           )
         } else {
-          rendered.push(renderItem(entry.spec, entry.role))
+          rendered.push(renderItem(entry.spec, entry.role, i))
         }
       })
       return rendered
@@ -323,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>
@@ -389,7 +342,7 @@ BreadcrumbList.displayName = 'BreadcrumbList'
  * 設計回應 user 兩 challenges:
  *   (a) Root 也 truncate(shrink:3,不是 shrink-0)
  *   (b) 不用 fixed max-width — flex-shrink hierarchy 容器寬時自然展開不浪費空間,
- *       窄時按優先級縮 + TruncatedLabel 內部 CSS truncate + tooltip。
+ *       窄時按優先級縮 + TruncatedText 內部 CSS truncate + tooltip。
  */
 interface BreadcrumbItemProps extends React.ComponentPropsWithoutRef<'li'> {
   role?: 'root' | 'middle' | 'current' | 'ellipsis'
@@ -443,11 +396,11 @@ const BreadcrumbLink = React.forwardRef<HTMLAnchorElement, BreadcrumbLinkProps>(
   ({ asChild, className, children, startIcon: StartIcon, ...props }, ref) => {
     const { size } = React.useContext(BreadcrumbContext)
     // 2026-05-12 fix(user 抓 image 2 Deep story 麵包屑沒符合 single-line + truncate canonical):
-    // 純文字 children → auto-wrap TruncatedLabel(canonical「single-line + ellipsis + tooltip
+    // 純文字 children → auto-wrap TruncatedText(canonical「single-line + ellipsis + tooltip
     // 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',
@@ -493,9 +446,9 @@ interface BreadcrumbPageProps extends React.ComponentPropsWithoutRef<'span'> {
 const BreadcrumbPage = React.forwardRef<HTMLSpanElement, BreadcrumbPageProps>(
   ({ className, children, startIcon: StartIcon, ...props }, ref) => {
     const { size } = React.useContext(BreadcrumbContext)
-    // 2026-05-12 fix(同 BreadcrumbLink):純文字 children → auto-wrap TruncatedLabel。
+    // 2026-05-12 fix(同 BreadcrumbLink):純文字 children → auto-wrap TruncatedText。
     const wrappedChildren = typeof children === 'string'
-      ? <TruncatedLabel fullText={children}>{children}</TruncatedLabel>
+      ? <TruncatedText display="block" tooltip={children}>{children}</TruncatedText>
       : children
     return (
       <span
@@ -596,7 +549,11 @@ export const breadcrumbMeta = {
 
   },
   sizes: {
-
+    // 值源 = code SSOT:BREADCRUMB_TEXT_CLASS(sm/md=text-body, lg=text-body-lg)+ BREADCRUMB_ICON_SIZE(sm/md=16, lg=20)。
+    // Breadcrumb 是文字列無固定高度 token,故不列 height(對照 Tag meta 有自身 h-* 才列)。
+    sm: { iconSize: 16, typography: 'body' },
+    md: { iconSize: 16, typography: 'body' },
+    lg: { iconSize: 20, typography: 'body-lg' },
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {

package/src/components/Breadcrumb/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './breadcrumb'