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

package/src/components/Tabs/tabs.tsx

@@ -1,6 +1,7 @@
 // @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.
-// code-quality-allow: file-size — foundational composite(Tabs + overflow scroll mode + dropdown switcher + inline action slot)在單一 wrapper SSOT 內,拆分會破壞 a11y / focus management chain。當前 515 < cap 800。
+// code-quality-allow: file-size — foundational composite(Tabs + overflow scroll mode + dropdown switcher + inline action slot)在單一 wrapper SSOT 內,拆分會破壞 a11y / focus management chain。當前 ~578 < cap 800。
 import * as React from 'react'
+import { createPortal } from 'react-dom'
 import * as TabsPrimitive from '@radix-ui/react-tabs'
 import { cva } from 'class-variance-authority'
 import type { LucideIcon } from 'lucide-react'
@@ -20,6 +21,13 @@ import {
   OverflowMenuTriggerButton,
 } from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'
 import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
+import { useControllable } from '@/design-system/hooks/use-controllable'
+import {
+  getTabsInlineActionPaddingRight,
+  mergeTabsInlineActionStyle,
+  resolveTabsInlineActionPosition,
+  type TabsInlineActionClipRect,
+} from './tabs-inline-action-geometry'
 
 /**
  * Tabs — 基於 Radix Tabs，橋接設計系統 token
@@ -42,7 +50,7 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
  *   slot 間 gap-2，suffix 內 gap-1
  *
  * ── Selected underline ──
- *   使用 ::after 絕對定位在 bottom: -1px，2px primary-hover，
+ *   使用 ::after 絕對定位在 bottom: -1px，2px primary（2026-07-06 拍板:持續選中站 base），
  *   蓋住 TabsList 的 1px gray border（單一視覺線條，不雙線）。
  */
 
@@ -55,6 +63,46 @@ interface TabsContextValue {
 }
 const TabsContext = React.createContext<TabsContextValue>({ size: 'md' })
 
+// ── Inline-action overlay context(2026-07-18 決策1,axe aria-required-children 正規修)──
+// role=tablist 只能擁有 role=tab;per-tab inlineAction(如「更多 ▾」dropdown)若 DOM-在 tablist 內
+// = critical 違規(axe 實測確認)。Radix 要求 trigger 為 TabsList 的 React 子代(roving focus
+// context),故 trigger 必 DOM-在 tablist 內;唯一正規解 = 把 action **portal 出 tablist** 到一個
+// sibling overlay 層,以 trigger 的量測座標定位(涵蓋 3 種 overflow 模式,viewport-relative)。
+// aria-owns 不可行:axe required-children 計 DOM-owned 子代,不因 aria-owns 排除。
+// 代價(user 2026-07-18 接受):鍵盤 Tab 序 = 全部 tab 後才到 action(action 現為 overlay 內獨立 tab stop)。
+const TabsActionOverlayContext = React.createContext<HTMLDivElement | null>(null)
+
+const TABS_ACTION_CLIPPING_OVERFLOW = new Set(['auto', 'scroll', 'hidden', 'clip', 'overlay'])
+
+function getTabsActionClippingAncestors(triggerEl: HTMLElement): HTMLElement[] {
+  const ancestors: HTMLElement[] = []
+  let current = triggerEl.parentElement
+  while (current) {
+    const style = window.getComputedStyle(current)
+    if (
+      TABS_ACTION_CLIPPING_OVERFLOW.has(style.overflowX) ||
+      TABS_ACTION_CLIPPING_OVERFLOW.has(style.overflowY)
+    ) {
+      ancestors.push(current)
+    }
+    current = current.parentElement
+  }
+  return ancestors
+}
+
+function toTabsActionClipRect(element: HTMLElement): TabsInlineActionClipRect {
+  const rect = element.getBoundingClientRect()
+  const style = window.getComputedStyle(element)
+  return {
+    left: rect.left,
+    right: rect.right,
+    top: rect.top,
+    bottom: rect.bottom,
+    clipX: TABS_ACTION_CLIPPING_OVERFLOW.has(style.overflowX),
+    clipY: TABS_ACTION_CLIPPING_OVERFLOW.has(style.overflowY),
+  }
+}
+
 // ── Root ──
 // Wrap Radix Tabs 以支援 value/onValueChange 的 context pass-through
 // （menu 模式的 overflow items 需要能 proxy click 觸發同一個 onValueChange）
@@ -65,26 +113,58 @@ const TabsValueContext = React.createContext<{
   onValueChange?: (value: string) => void
 }>({})
 
+
+// ── getElementRef(Radix Slot idiom;鏡射 chip.tsx 同名 helper — 2026-07-05 M10 同型修)──
+// 讀 child 既有 ref 而不觸發 React 18/19 dev deprecation warning。
+function getElementRef(element: React.ReactElement): React.Ref<HTMLElement> | undefined {
+  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get
+  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element as unknown as { ref?: React.Ref<HTMLElement> }).ref
+  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get
+  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element.props as { ref?: React.Ref<HTMLElement> }).ref
+  return (
+    (element.props as { ref?: React.Ref<HTMLElement> }).ref ??
+    (element as unknown as { ref?: React.Ref<HTMLElement> }).ref ??
+    undefined
+  )
+}
+
+// 遞迴攤平 Fragment：React.Children.toArray 不展開 <>…</>(把 Fragment 當單一 element),
+// 導致 menu 模式 dropdown 漏掉被 Fragment 包起來的 trigger（如條件渲染的溢出 tabs）+ cloneElement
+// 對 Fragment 傳 ref 會噴 React warning。攤平後每個 keyless child 補 path-index key,對齊
+// React.Children.toArray 的自動 key 行為,避免 list key warning。
+function flattenTabTriggers(children: React.ReactNode, prefix = ''): React.ReactElement[] {
+  const out: React.ReactElement[] = []
+  React.Children.forEach(children, (child, i) => {
+    if (!React.isValidElement(child)) return
+    if (child.type === React.Fragment) {
+      out.push(
+        ...flattenTabTriggers((child.props as { children?: React.ReactNode }).children, `${prefix}${i}.`),
+      )
+    } else {
+      out.push(child.key != null ? child : React.cloneElement(child, { key: `tab-${prefix}${i}` }))
+    }
+  })
+  return out
+}
+
 const Tabs = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
   TabsProps
 >(({ value, onValueChange, defaultValue, children, ...props }, ref) => {
-  // 內部維護一份 uncontrolled state，讓 overflow menu 的 proxy 有 onValueChange 可呼叫
-  const [internalValue, setInternalValue] = React.useState<string | undefined>(defaultValue)
-  const isControlled = value !== undefined
-  const currentValue = isControlled ? value : internalValue
-
-  const handleValueChange = React.useCallback(
-    (next: string) => {
-      if (!isControlled) setInternalValue(next)
-      onValueChange?.(next)
-    },
-    [isControlled, onValueChange]
-  )
+  // Wrapper mirror 是 Tabs 與 overflow menu proxy 的共同 SSOT。空字串代表尚未選取，
+  // 因此 Radix 從 mount 起恆為 controlled；未提供 defaultValue 的第一次選取也不會
+  // 從 value=undefined 翻成字串而觸發 uncontrolled → controlled 警告。
+  const [currentValue, setCurrentValue] = useControllable<string>({
+    value,
+    defaultValue: defaultValue ?? '',
+    onChange: onValueChange,
+  })
 
   const valueContext = React.useMemo(
-    () => ({ value: currentValue, onValueChange: handleValueChange }),
-    [currentValue, handleValueChange]
+    () => ({ value: currentValue, onValueChange: setCurrentValue }),
+    [currentValue, setCurrentValue]
   )
 
   return (
@@ -92,7 +172,7 @@ const Tabs = React.forwardRef<
       <TabsPrimitive.Root
         ref={ref}
         value={currentValue}
-        onValueChange={handleValueChange}
+        onValueChange={setCurrentValue}
         {...props}
       >
         {children}
@@ -103,13 +183,21 @@ const Tabs = React.forwardRef<
 Tabs.displayName = 'Tabs'
 
 // ── List ──
+// data-slot="tabs-list" 契約(2026-07-30):三種 overflow 模式的 role=tablist 元素
+// (TabsPrimitive.List)一律自標 `data-slot="tabs-list"`,供容器以 attribute contract 注入樣式
+// (header-canonical HEADER_TABS_SLOT_WRAPPER_CLASS 消費,詳 chrome-header.tsx 註解)。
+// 對齊 shadcn v4 tabs.tsx `<TabsPrimitive.List data-slot="tabs-list">` idiom
+// (https://github.com/shadcn-ui/ui/blob/main/apps/v4/registry/new-york-v4/ui/tabs.tsx)
+// + DS 既有 data-unbounded 標記式契約(overlay-surface.tsx CHROME_UNBOUNDED_SLOT)。
+// 背景:beta.86 inlineAction overlay(fc2a3a5c)包 `<div class="relative">` 後,tablist DOM 深度
+// 不再穩定,結構性 direct-child 選擇器不可靠 → 顯式契約免疫未來 DOM 重構。
 // TabsList 基礎 class — inline-flex 單列 + gap-loose + 底部 border-divider
 // 2026-05-18 改 border-border → border-divider(per user verbatim「我認為應該把 tabs 的
 // 下底線統一改成是 divider 色吧?」+「做」approval):
 // - 跟 Dialog / Sheet / Popover / Sidebar header `border-b border-divider`(neutral-4)同色
 // - withTabs scenario 下 tabs underline = chrome separator,跟 dialog 其他 separator 視覺一致
 // - Selected trigger 2px primary 仍 overlay underlying divider(對比 primary >> divider 不弱)
-// - 對齊 `color.spec.md:706-708` outer-vs-divider 判準(Dialog 結構,T-junction 思路適用)
+// - 對齊 `color.spec.md`「T-junction connectivity 原則」段 outer-vs-divider 判準(Dialog 結構,T-junction 思路適用)
 const TABS_LIST_BASE = [
   'inline-flex items-stretch',
   'gap-[var(--layout-space-loose)]',
@@ -123,7 +211,7 @@ interface TabsListProps
    * Overflow 處理模式。詳見 tabs.spec.md 的 overflow 段。
    *   'none'   ★ 預設，不處理，triggers 溢出父容器（適用 tabs 數量可控的情境）
    *   'scroll' 單行橫向滾動 + 邊緣 fade mask（Material / Polaris / iOS 作法）
-   *   'menu'   塞不下收進 "⋯" dropdown，所有 triggers 仍在 DOM 保留 Radix a11y
+   *   'menu'   show-all navigator——全部 triggers 一直顯示在底層 overflow-x-auto 捲動容器內,
    *            （Ant Design / Atlassian 作法）
    */
   overflow?: TabsOverflow
@@ -134,34 +222,46 @@ const TabsList = React.forwardRef<
   TabsListProps
 >(({ className, size = 'sm', overflow = 'none', children, ...props }, ref) => {
   const tabsSizeContext = React.useMemo(() => ({ size }), [size])
+  // Overlay 層(決策1):per-tab inlineAction 由 TabsTrigger portal 到此,DOM-在 tablist 外,
+  // 以量測座標定位在對應 tab 之上。pointer-events-none(action span 自帶 auto);z 疊在 tab 之上。
+  const [overlayEl, setOverlayEl] = React.useState<HTMLDivElement | null>(null)
+
+  let listNode: React.ReactNode
   if (overflow === 'scroll') {
-    return (
-      <TabsContext.Provider value={tabsSizeContext}>
-        <ScrollTabsList ref={ref} className={className} {...props}>
-          {children}
-        </ScrollTabsList>
-      </TabsContext.Provider>
+    listNode = (
+      <ScrollTabsList ref={ref} className={className} {...props}>
+        {children}
+      </ScrollTabsList>
     )
-  }
-  if (overflow === 'menu') {
-    return (
-      <TabsContext.Provider value={tabsSizeContext}>
-        <MenuTabsList ref={ref} className={className} {...props}>
-          {children}
-        </MenuTabsList>
-      </TabsContext.Provider>
+  } else if (overflow === 'menu') {
+    listNode = (
+      <MenuTabsList ref={ref} className={className} {...props}>
+        {children}
+      </MenuTabsList>
     )
-  }
-  // none（預設）
-  return (
-    <TabsContext.Provider value={tabsSizeContext}>
+  } else {
+    // none（預設）
+    listNode = (
       <TabsPrimitive.List
         ref={ref}
-        className={cn(TABS_LIST_BASE, 'w-fit', className)}
+        data-slot="tabs-list"
+        className={cn(TABS_LIST_BASE, 'w-full', className)}
         {...props}
       >
         {children}
       </TabsPrimitive.List>
+    )
+  }
+
+  return (
+    <TabsContext.Provider value={tabsSizeContext}>
+      <TabsActionOverlayContext.Provider value={overlayEl}>
+        <div className="relative">
+          {listNode}
+          {/* inline-action overlay:sibling of tablist(非其 DOM 子代)→ 修 axe aria-required-children */}
+          <div ref={setOverlayEl} className="pointer-events-none absolute inset-0 z-10" />
+        </div>
+      </TabsActionOverlayContext.Provider>
     </TabsContext.Provider>
   )
 })
@@ -204,7 +304,7 @@ const ScrollTabsList = React.forwardRef<
     //   overflow-x:auto + overflow-y:visible 必 compute auto)。
     //   不加 `pb-px`(outer border 撤後 list border 已接 -1px 部分,加 pb 多 1px 多餘空白)。
     //   對齊 Primer UnderlineNav `overflow-x:auto; overflow-y:hidden` canonical 同步動
-    //   horizontal-overflow.spec.md L75/L101/L129 owner 升 list 內部。
+    //   horizontal-overflow.spec.md(「Hook re-export」+「典型 scroll / menu 模式組裝」段)owner 升 list 內部。
     <div className="relative">
       <div
         ref={scrollRef}
@@ -213,7 +313,8 @@ const ScrollTabsList = React.forwardRef<
       >
         <TabsPrimitive.List
           ref={ref}
-          className={cn(TABS_LIST_BASE, 'w-fit', className)}
+          data-slot="tabs-list"
+          className={cn(TABS_LIST_BASE, 'min-w-full', className)}
           {...props}
         >
           {children}
@@ -234,7 +335,7 @@ ScrollTabsList.displayName = 'ScrollTabsList'
 // Show-all navigator pattern (Chrome tab dropdown / VS Code editor tabs / Discord channel jumper):
 //   - Menu 永遠顯示全部 tabs,active 的用 checked 標記 (單選語意)
 //   - 點 menu item = onValueChange + scrollIntoView(center),把該 tab 捲到視圖中央
-//   - Menu 內容穩定,跟 scroll 位置無關,使用者對「⋯ = navigator」的直覺一致
+//   - Menu 內容穩定,跟 scroll 位置無關,使用者對「⌄ = navigator」的直覺一致
 //
 // 為什麼底層仍是 overflow-x-auto 而非 overflow-hidden:
 //   - scrollIntoView 需要真實 scroll 容器
@@ -267,17 +368,27 @@ const MenuTabsList = React.forwardRef<
     []
   )
 
+  // Fragment-safe:攤平 <>…</> 讓條件渲染的溢出 tabs 也進 dropdown / ref map(見 flattenTabTriggers）
   const items = React.useMemo(
-    () => React.Children.toArray(children).filter(React.isValidElement) as React.ReactElement[],
+    () => flattenTabTriggers(children),
     [children]
   )
 
-  const enhancedChildren = items.map((child, i) =>
-    React.cloneElement(
+  // 2026-07-05 M10 同型修(Chip MenuChipGroup 同款):原 cloneElement 直接覆寫 child ref,
+  // consumer 自有 ref 被靜默取代 → compose(registerItem + child 原 ref)。
+  const enhancedChildren = items.map((child, i) => {
+    const childRef = getElementRef(child)
+    return React.cloneElement(
       child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,
-      { ref: registerItem(i) }
+      {
+        ref: (el: HTMLElement | null) => {
+          registerItem(i)(el)
+          if (typeof childRef === 'function') childRef(el)
+          else if (childRef) (childRef as React.MutableRefObject<HTMLElement | null>).current = el
+        },
+      }
     )
-  )
+  })
 
   // Menu 模式沒有 arrows,但仍套 fade mask (reserveArrowWidth: 0) 軟化內容硬邊
   // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜
@@ -309,7 +420,8 @@ const MenuTabsList = React.forwardRef<
       >
         <TabsPrimitive.List
           ref={ref}
-          className={cn(TABS_LIST_BASE, 'w-fit', className)}
+          data-slot="tabs-list"
+          className={cn(TABS_LIST_BASE, 'min-w-full', className)}
           {...props}
         >
           {enhancedChildren}
@@ -365,8 +477,8 @@ const tabsTriggerVariants = cva(
     'transition-colors duration-150',
     'cursor-pointer select-none',
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
-    // Trigger 無水平 padding — 寬度 = 內容寬度。triggers 間的分隔靠 TabsList 的 gap-[layout-space-loose]
-    // selected underline：::after 絕對定位在 bottom:-1px，2px primary-hover
+    // Trigger 無水平 padding — 寬度 = 內容寬度。triggers 間的分隔靠 TabsList 的 gap-[var(--layout-space-loose)]
+    // selected underline：::after 絕對定位在 bottom:-1px，2px primary（持續選中 base）
     // left-0/right-0 因為 trigger 已無 padding，底線等於內容寬度
     // 底線蓋住 TabsList 的 1px gray border，視覺單一線條
     'after:absolute after:left-0 after:right-0 after:bottom-[-1px] after:h-0.5',
@@ -375,7 +487,9 @@ const tabsTriggerVariants = cva(
     'hover:text-foreground',
     // selected
     'data-[state=active]:text-foreground data-[state=active]:font-medium',
-    'data-[state=active]:after:bg-primary-hover',
+    // 2026-07-06 user 拍板:選中底線 hover 階 → primary base(持續選中站 base;
+    // Ant inkBarColor = colorPrimary / Material 3 active indicator = primary 同款)
+    'data-[state=active]:after:bg-primary',
     // disabled：cursor-not-allowed + 不吃 hover 色
     // 不用 pointer-events-none，否則 cursor 不會改變；button[disabled] 本身就擋 click
     'disabled:cursor-not-allowed disabled:text-fg-disabled',
@@ -401,7 +515,10 @@ const tabsTriggerVariants = cva(
 )
 
 interface TabsTriggerProps
-  extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger> {
+  // asChild Omit(2026-07-18 決策2):Tab trigger 固定渲染 [startIcon?, <span>{children}</span>,
+  // suffix?] 多節點陣列 → Radix Slot 的 React.Children.only 恆 crash(每個 tab 都會)。
+  // children(label)保留合法;TabsRoot / TabsList 為真容器不收窄。
+  extends Omit<React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>, 'asChild'> {
   /** 左側 icon（LucideIcon） */
   startIcon?: LucideIcon
   /** 右側 badge（通常是計數指示器） */
@@ -416,8 +533,11 @@ interface TabsTriggerProps
    * Inline action slot(2026-05-21 v3 加,per user「圖一 後綴應該是 inline action」+「點擊
    * 該 tab 的 inline action 跟其他地方應該不同反應」directive):
    * 提供 `<ItemInlineAction>` / `<DropdownMenuTrigger asChild><ItemInlineAction ... /></DropdownMenuTrigger>`
-   * 等獨立 click target。**TabsTrigger 自動 stopPropagation**,inline action 點擊不冒泡到 tab body,
-   * 達成 split-click 行為(對齊 GitHub「Code ▾」/ Linear "Triage..." menu / Atlassian split-tab 共識)。
+   * 等獨立 click target。**DOM 上是 trigger 的 sibling(絕對定位),非巢狀 button**
+   * (2026-07-05 D4 修:Radix TabsTrigger 是原生 `<button>`,巢 button = HTML 不合法 +
+   * axe nested-interactive;同 SidebarMenuButton suffixNode canonical),inline action
+   * 點擊天然不落在 tab body,達成 split-click 行為(對齊 GitHub「Code ▾」/
+   * Linear "Triage..." menu / Atlassian split-tab 共識)。
    *
    * 跟 endIcon 區別:endIcon = 純視覺 indicator(無獨立行為,連同 tab 一起 click),
    * inlineAction = 獨立 click target(自己的 handler,不切 tab)。語意分家明確。
@@ -428,17 +548,68 @@ interface TabsTriggerProps
 const TabsTrigger = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Trigger>,
   TabsTriggerProps
->(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, inlineAction, children, ...props }, ref) => {
+>(({ className, startIcon: StartIcon, badge, endIcon: EndIcon, inlineAction, children, style, ...props }, ref) => {
   const { size } = React.useContext(TabsContext)
+  const overlayEl = React.useContext(TabsActionOverlayContext)
   // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
-  const hasSuffix = badge != null || EndIcon !== undefined || inlineAction != null
+  const hasSuffix = badge != null || EndIcon !== undefined
+  // inlineAction 幾何:trigger 以 paddingRight 預留 action 空間 — icon 寬 + sibling
+  // canonical gap-2(8px)。badge/endIcon 是 trigger 內 suffix，不得壓縮與獨立 action 的間距。2026-07-05 修 button-巢-button
+  // (sibling 佈局);2026-07-18 決策1 再進化:action 不再是 tablist DOM 內的 sibling(axe
+  // aria-required-children critical),改 portal 到 TabsList 的 overlay 層(tablist 外),以量測座標
+  // 定位在 trigger 右緣。trigger 仍在 tablist 內(Radix roving focus 要求)。
+  const hasAction = inlineAction != null
+  const actionPaddingRight = getTabsInlineActionPaddingRight(iconSize, hasAction)
 
-  return (
+  // 量測 trigger 位置(viewport-relative,涵蓋 none/scroll/menu 三模式),同步 overlay 內 action 座標。
+  const triggerElRef = React.useRef<HTMLButtonElement | null>(null)
+  const setTriggerRef = React.useCallback(
+    (el: HTMLButtonElement | null) => {
+      triggerElRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLButtonElement | null>).current = el
+    },
+    [ref],
+  )
+  const [actionPos, setActionPos] = React.useState<{ left: number; top: number; height: number } | null>(null)
+
+  React.useLayoutEffect(() => {
+    if (!hasAction || !overlayEl) return
+    const el = triggerElRef.current
+    if (!el) return
+    const clippingAncestors = getTabsActionClippingAncestors(el)
+    const compute = () => {
+      const t = triggerElRef.current?.getBoundingClientRect()
+      const o = overlayEl.getBoundingClientRect()
+      if (!t) return
+      setActionPos(resolveTabsInlineActionPosition({
+        trigger: t,
+        overlay: o,
+        clips: clippingAncestors.map(toTabsActionClipRect),
+        actionWidth: iconSize,
+      }))
+    }
+    compute()
+    const ro = new ResizeObserver(compute)
+    ro.observe(el)
+    ro.observe(overlayEl)
+    for (const clippingAncestor of clippingAncestors) ro.observe(clippingAncestor)
+    window.addEventListener('resize', compute)
+    window.addEventListener('scroll', compute, true) // capture:含 scroll-mode 捲動容器內部捲動
+    return () => {
+      ro.disconnect()
+      window.removeEventListener('resize', compute)
+      window.removeEventListener('scroll', compute, true)
+    }
+  }, [hasAction, iconSize, overlayEl])
+
+  const trigger = (
     <TabsPrimitive.Trigger
-      ref={ref}
+      ref={setTriggerRef}
       className={cn(tabsTriggerVariants({ size }), className)}
       {...props}
+      style={mergeTabsInlineActionStyle(style, actionPaddingRight)}
     >
       {StartIcon && <StartIcon size={iconSize} aria-hidden />}
       {children != null && <span>{children}</span>}
@@ -446,30 +617,31 @@ const TabsTrigger = React.forwardRef<
         <span className="inline-flex items-center gap-1">
           {badge}
           {EndIcon && <EndIcon size={iconSize} aria-hidden />}
-          {inlineAction != null && (
-            // 2026-05-21 split-click invariant:inlineAction 點擊不冒泡到 TabsPrimitive.Trigger。
-            // Radix Tabs 在 3 個 channel 觸發 tab 切換,全部 stopPropagation:
-            //   - onMouseDown(primary, Radix Tabs source code main switch trigger)
-            //   - onFocus(activationMode='automatic' default,focus 落內部按鈕也算「focused」)
-            //   - onKeyDown Enter/Space(鍵盤啟動)
-            // 加 onPointerDown / onClick 防禦其他 framework 慣例。
-            // 對齊 GitHub「Code ▾」/ Linear "Triage..." split-tab 共識。
-            <span
-              onPointerDown={(e) => e.stopPropagation()}
-              onMouseDown={(e) => e.stopPropagation()}
-              onClick={(e) => e.stopPropagation()}
-              onFocus={(e) => e.stopPropagation()}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter' || e.key === ' ') e.stopPropagation()
-              }}
-            >
-              {inlineAction}
-            </span>
-          )}
         </span>
       )}
     </TabsPrimitive.Trigger>
   )
+
+  if (!hasAction) return trigger
+
+  return (
+    <>
+      {trigger}
+      {overlayEl &&
+        actionPos &&
+        createPortal(
+          // action portal 到 overlay(tablist 外);left=trigger.right + `-translate-x-full` → action
+          // 右緣對齊 trigger 右緣;top/height + items-center → 垂直置中(同原 right-0 + top-1/2 幾何)。
+          <span
+            className="pointer-events-auto absolute inline-flex -translate-x-full items-center"
+            style={{ left: actionPos.left, top: actionPos.top, height: actionPos.height }}
+          >
+            {inlineAction}
+          </span>,
+          overlayEl,
+        )}
+    </>
+  )
 })
 TabsTrigger.displayName = 'TabsTrigger'
 
@@ -481,6 +653,12 @@ const TabsContent = React.forwardRef<
   <TabsPrimitive.Content
     ref={ref}
     className={cn(
+      // 與 TabsList 的間距 canonical(2026-06-12 user 拍板):--layout-space-tight(md 12px,
+      // density 連動)。依 layoutSpace.spec「親疏 3 級」:Tabs↔Content 同 bundle(第一級,
+      // 元件 spec own),值取規則 3「直接功能依賴 = tight」精神(heading → labeled content 同類)。
+      // 收斂原 DS-wide 四種土法(無間距 / mt-4 / p-4 / pt-4 — M17 假 SSOT)。
+      // full-height 佈局(AppShell pane)用 className="mt-0" 覆寫(tailwind-merge)。
+      'mt-[var(--layout-space-tight)]',
       'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
       className
     )}
@@ -497,14 +675,16 @@ export const tabsMeta = {
   variants: {
 
   },
+  // 注:`fieldHeight` 為 meta 通用 height key;Tabs **不複用 field-height**,值為 `--tab-height-*`(md density,對齊 spec.md size table + uiSize.css)
   sizes: {
-    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
-    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
-    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+    sm: { fieldHeight: 32, iconSize: 16, typography: 'body' },
+    md: { fieldHeight: 40, iconSize: 16, typography: 'body' },
+    lg: { fieldHeight: 48, iconSize: 20, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 選中 tab(Radix DOM attr 為 data-state="active",meta 詞彙統一用 'selected' 避免與「按壓 active」混用;2026-07-07)
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-primary-hover', 'bg-transparent'],
+    bg: ['bg-primary', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],
     ring: ['ring-ring'],
   },

package/src/components/Tag/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 './tag'