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

package/src/components/Empty/empty.spec.md

@@ -10,7 +10,6 @@ benchmark:
   - Polaris EmptyState: github.com/Shopify/polaris/tree/main/polaris-react/src/components/EmptyState
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Empty 設計原則
 
@@ -18,7 +17,7 @@ benchmark:
 
 ## 定位
 
-一個 **layout pattern**(不是 field-level 元件)。它排列 icon / title / description / action 成居中垂直堆疊,間距走 layout-space token(density-aware)。
+一個 **layout pattern**(不是 field-level 元件)。它排列 icon / title / description / action 成居中垂直堆疊,間距固定不隨 density 變(見「間距」段)。
 
 預設只有 description——icon / title / action 全部可選。
 
@@ -32,6 +31,7 @@ benchmark:
 - **SelectMenu / Combobox 下拉空**：「無選項」「找不到符合的項目」
 - **Page section 無內容**：dashboard widget 暫無資料、設定頁未建立任何項目
 - **初次引導**：讓使用者首次使用時知道「這裡會放什麼」+ 有 CTA 建立
+- **容器級無權限提示**（2026-07-04 Q7 拍板）：卡片 / 區塊 / 面板內容因權限不可見 — **必附 request-access 類 action**（對齊 Atlassian「Request access」empty state 官方範例 + Carbon error-management scenario）；整頁級 403 / 404 仍禁用（→ 專屬錯誤頁面，見「何時不用」）
 
 ## 何時不用
 
@@ -43,21 +43,19 @@ benchmark:
 | Disabled 狀態 | 禁用元件本身 | Empty 是「沒東西」，disabled 是「不能操作」 |
 
 ```
-         [Avatar 48px neutral + icon]     ← 可選
-          gap = --layout-space-tight
-        [Title 16px font-medium centered]  ← 可選
-         --item-gap-label-desc-reading-lg (2px)
-      [Description 14px fg-secondary centered]
-               w-full (no max-width)
-          gap = --layout-space-loose
-              [Action Button]              ← 可選
+      [Icon(Avatar 包覆)]   ← 可選
+      [Title]                ← 可選
+      [Description]          ← 唯一必有
+      [Action]               ← 可選
 ```
 
+(全部居中垂直堆疊;間距原則見「間距」段,具體 class / px 對照見 anatomy stories)
+
 ## Slots
 
 - **Icon**(`icon?: LucideIcon | ReactElement`,預設無):LucideIcon 會自動包 48px neutral Avatar + 28px icon;ReactElement 原樣渲染(consumer 可自帶 Illustration、ColorAvatar、CircularProgress)
 - **Title**(`title?: string`,預設無):主要標題,foreground + medium 字重,居中
-- **Description**(`description?: string`,預設無 — 但是唯一必有的 slot):說明文字,次要色、居中
+- **Description**(`description: string`,必填且不得為空):說明「缺什麼／為何空／下一步」的文字,次要色、居中。Icon、title、action 都不能取代 description
 - **Action**(`action?: ReactNode`,預設無):CTA Button 或任何操作,居中
 
 ## 間距
@@ -73,13 +71,13 @@ Outer padding 由 **consumer 容器** 決定(Table 空狀態需較大留白、Se
 ## Typography
 
 - **Title**:body-lg + medium 字重 / foreground 色(主要閱讀重量)
-- **Description**:body tier / **`fg-muted` placeholder 等級色**(跟 input placeholder 同色,提示「這裡暫時沒內容」)
+- **Description**:字級跟 `RowSizeContext` 對齊——standalone(無 context,fallback `md`)或 `sm`/`md` row 子樹 = body tier(14px);渲染在 `lg` 的 `RowSizeContext` 子樹(如 lg menu)內時自動升 body-lg(16px),對齊該 menu items 字級。色彩條件式:有 title / action 時走 **`fg-secondary`**(次要閱讀色,與 title 形成主次層級);孤身 description(無 title / action)時走 **`fg-muted` placeholder 等級色**(跟 input placeholder 同色,提示「這裡暫時沒內容」);disabled context 時走 `fg-disabled`
 
 完整 slot / gap / typography 的 class 與 px 對照見 anatomy `Overview`(Slot 與 Spacing)+ `SlotCombinations`(Slot 間距規則)stories。
 
 ## 文字不限寬
 
-Description **不加 max-width**。文字撐滿容器,由容器 padding 控制行寬。文案設計者自己規劃換行(文案長度 = 設計的一部分),Empty 不該強制截斷。
+Description **不加 max-width**。文字置中(由 `items-center` 居中,span 收縮成內容寬度,非 w-full),行寬由容器 padding 控制。文案設計者自己規劃換行(文案長度 = 設計的一部分),Empty 不該強制截斷。
 
 ## 垂直定位(Consumer 容器的責任)
 
@@ -96,6 +94,12 @@ Empty 只管**水平居中**。垂直定位由 consumer 的容器決定:
 
 無框容器沒有邊界——如果居中,Empty 會脫離頁面視覺中心,使用者不知道空的範圍有多大。頂部對齊 + `calc(var(--layout-space-bottom) * 2)` padding 讓 Empty 有固定位置,用留白空間本身創造「這裡是空的」的視覺重量,取代框線的作用。
 
+## 邊界案例
+
+- **極長 description**:不截斷、不限寬,自然換行(見「文字不限寬」段)— 文案長度由文案設計者控制
+- **動態變空**(filter / search 從有結果 → 無結果):視覺與靜態空狀態完全相同,無轉場;consumer 容器加 `aria-live="polite"` 通知 SR(見「A11y 預設」)
+- **全 slot 缺值**:code 不擋空 render,但 description 是唯一必有 slot(見「Slots」段)— 無任何 slot 的 `<Empty>` 渲染成空容器,屬 consumer 誤用
+
 ---
 
 ## A11y 預設
@@ -104,12 +108,12 @@ Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 cons
 
 | 場景 | Consumer 容器應加 | 為什麼 |
 |------|----------------|------|
-| Table / List 空狀態 | `<table aria-describedby={emptyId}>` 或在容器加 `aria-live="polite"` | screen reader 在資料載入完成時主動通知「無資料」(對齊 Polaris EmptyState pattern) | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-| Search / Filter 無結果 | container `aria-live="polite"` + 文案明確指向搜尋詞(「找不到符合『XXX』的結果」)| 對齊 Material `<NoOptions>` + Atlassian Empty Search idiom — 變動結果需 live region | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Table / List 空狀態 | `<table aria-describedby={emptyId}>` 或在容器加 `aria-live="polite"` | screen reader 在資料載入完成時主動通知「無資料」 |
+| Search / Filter 無結果 | container `aria-live="polite"` + 文案明確指向搜尋詞(「找不到符合『XXX』的結果」)| 變動結果需 live region，讓非視覺使用者知道查詢已完成且結果改變 |
 | Page section 暫無內容 | `<section aria-labelledby={titleId}>` + `<h2>` 包 title slot | 對齊 WCAG 2.1 SC 2.4.6 標題明確語意 |
 | 初次引導(有 CTA) | Action Button 自帶 a11y;無需 Empty 層額外 ARIA | CTA 是真實互動 element,自己的 a11y 足夠 |
 
-**Title slot heading level**:Empty 不渲染 heading tag(`<h1>` / `<h2>`),只 `<div>` + 視覺 typography。Consumer 若需 heading semantic,在外層自包 `<h2>{title}</h2>` + 不傳 Empty 的 title prop(避免重複)。
+**Title slot heading level**:Empty 不渲染 heading tag(`<h1>` / `<h2>`),只 `<span>` + 視覺 typography。Consumer 若需 heading semantic,在外層自包 `<h2>{title}</h2>` + 不傳 Empty 的 title prop(避免重複)。
 
 **Icon slot**:LucideIcon 自動渲染 `aria-hidden="true"`(decorative);ReactElement(自帶 Avatar / Illustration)由 consumer 控制 `aria-hidden` / `alt`(若是 `<img>` 必傳 `alt=""` 表示 decorative)。
 
@@ -120,15 +124,15 @@ Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 cons
 - **Material** `<NoOptions>`(Autocomplete 內):容器自帶 `role="listbox"` + `aria-live="polite"` 通知無結果
 - **Carbon** `<EmptyState>`:無自帶 ARIA,文檔指引 consumer 在父容器設 `aria-describedby`
 
-本 DS 對齊 Carbon「primitive 不自帶 ARIA,consumer 控制」哲學——避免 Empty 強加 role 跟 consumer 容器衝突。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Empty primitive 不自帶 role；consumer 擁有 table、search region 或 initial-empty 的語境，強加單一 role 會與外層 live-region / describedby contract 衝突。
 
 ---
 
 ## 消費範例
 
 ```tsx
-// Table 空狀態(最簡)
-<Empty description="沒有資料" />
+// Table 空狀態(最簡)——文案仍點出「缺什麼資料」,避免抽象的「無資料」(見「禁止事項」)
+<Empty description="還沒有訂單" />
 
 // SelectMenu 無結果
 <Empty icon={SearchX} description="找不到符合的結果" />
@@ -155,39 +159,40 @@ Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 cons
 />
 ```
 
-## 現有消費者改寫
+## 現有消費者
 
-| 元件 | 現況 | 改為 |
+| 元件 | 消費方式 | Padding 落點 |
 |---|---|---|
-| DataTable | inline `<div>` 硬寫 className | `<Empty description={emptyState} className="py-12" />` |
-| SelectMenu | — | `<Empty description="無選項" className="py-6" />` |
-| Combobox | — | `<Empty description="找不到結果" className="py-6" />` |
+| DataTable | 外層 `<div className="flex-1 flex items-center justify-center py-12">` 包 `<Empty description={emptyState} />`(有框置中) | wrapper div(非 Empty className) |
+| SelectMenu | 無結果時 `<Empty description={emptyText} className="py-6" />`;spinner-only loading 改由具 accessible name 的 `role="status"` wrapper 包 `<CircularProgress size={48}/>` | Empty className / loading wrapper |
+| Combobox | 透過 SelectMenu(dropdown 即 SelectMenu primitive)→ 無結果時顯 SelectMenu 的 `<Empty>` | 同 SelectMenu |
 
 ## 禁止事項
 
-- ❌ 把 Empty 拿來顯示 loading state(無 description 又無 spinner)— Empty 是「確定沒有」語意,loading 用 `<Skeleton>` / `<CircularProgress>` 或 `<Empty icon={<CircularProgress />}/>` compose
+- ❌ 把 Empty 拿來當 spinner-only loading host — Empty 是「確定沒有」語意;loading 用 `<Skeleton>`，或用具 accessible name 的 `role="status"` wrapper 包 `<CircularProgress>`。只有確實有空狀態解釋時才可在 Empty 內含進度視覺，且仍必須傳 meaningful description
 - ❌ 把 Empty 拿來顯示 error state(只有 description)— error 需明確 action(重試 / 報告 / 聯絡支援),用 `<Alert>` + 重試 button
-- ❌ Empty title / description 文案太抽象(「Nothing here」「No data」)— 應描述「缺什麼資料」+「為什麼空」+「下一步動作」(對齊 Polaris EmptyState / Carbon Empty State copy guideline) <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- ❌ Empty title / description 文案太抽象(「Nothing here」「No data」)— 應描述「缺什麼資料」+「為什麼空」+「下一步動作」，讓空狀態本身可以指引恢復路徑
 - ❌ Action button 用 destructive variant — Empty 是引導 onboarding 心境,destructive 視覺敵意衝突
 - ❌ 整頁 Empty 但無 action — user 困惑「我該做什麼」;若該頁本質無 action(等待後台 invite),改用 Alert/Notice 解釋
 
-## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+## 為何無 ColorMatrix / SizeMatrix / StateBehavior
 
-Empty 是 **pure layout primitive**(排列 icon / title / description / action 成居中垂直堆疊),不是互動元件,也不是 variant-driven 元件:
+Empty 是 **pure layout primitive**(排列 icon / title / description / action 成居中垂直堆疊),不是 variant-driven 元件,也無互動狀態:
 
-- **無 Inspector**:Empty 的「關鍵決策」是 slot 組合(description only → full),已在 `SlotCombinations` story 呈現四種組合對照(最簡 → 輕引導 → 中引導 → full)。互動切換式 Inspector 不會比 slot composition 對照更有教學價值——consumer 需要的是「這四種場景怎麼選」。
-- **無 ColorMatrix**:Empty 自身不帶任何色彩,bg transparent,text color 全部走 semantic token(`text-foreground` / `text-fg-muted`)。Avatar icon 的色彩由 consumer 透過 `<Avatar color="...">` 決定,非 Empty 層級 variant。
+- **無 ColorMatrix**:Empty 自身不帶任何色彩,bg transparent,text color 全部走 semantic token(`text-foreground` title / `text-fg-secondary` description-with-title / `text-fg-muted` 孤身 description / `text-fg-disabled` disabled context)。Avatar icon 的色彩由 consumer 透過 `<Avatar color="...">` 決定,非 Empty 層級 variant。
 - **無 SizeMatrix**:Empty 無 `size` prop,垂直 padding 由 consumer 容器決定(Table `py-12` / SelectMenu `py-6` / Page `py-16`),固定間距不隨 density 變(展示性元件,見本 spec「間距」段)。
-- **無 StateBehavior**:Empty 是非互動展示元件,無 hover / focus / active / selected / disabled。CTA button 的互動狀態屬 Button 層級,不屬 Empty。
+- **無 StateBehavior**:Empty 是非互動展示元件,無 hover / focus / active / selected 互動狀態。CTA button 的互動狀態屬 Button 層級,不屬 Empty。**唯一例外是 disabled context state**(`disabled?: boolean` prop):非互動狀態,但元件支援——disabled 時 title / description 轉 `text-fg-disabled`、icon glyph 轉 fg-disabled(供 FileUpload disabled 等情境消費),不影響既有 consumer(預設 false)。
+
+**Inspector**:提供互動切換式 Inspector(右側 Controls 面板切換 icon / title / description / action),讓 consumer 即時查看 Empty 在不同 slot 組合下的呈現——slot 組合(description only → full)是 Empty 唯一的關鍵決策。
 
-對應 anatomy story:保留 `Overview` + 元件特有 `ScenarioMatrix`(常見業務場景) + 元件特有 `SlotCombinations`(slot 組合對照)。
+對應 anatomy story:`Overview` + `Inspector`(互動切換)+ `Accessibility` + 元件特有 `ScenarioMatrix`(常見業務場景)+ 元件特有 `SlotCombinations`(slot 組合對照)。
 
 ---
 
 ## 相關
 
 - `../Avatar/avatar.tsx` — Icon 渲染實作
-- `../CircularProgress/circular-progress.spec.md` — Loading 狀態(非「空」而是「還沒來」;全頁 loading 可 `<Empty icon={<CircularProgress size={48}/>}/>` compose)
+- `../CircularProgress/circular-progress.spec.md` — Loading 狀態(非「空」而是「還沒來」;spinner-only loading 用具 accessible name 的 `role="status"` host)
 - `../Alert/alert.spec.md` — Error 狀態（非中性空，是需處理的問題）
 - `../FileUpload/file-upload.spec.md` — **本元件 consumer**:FileUpload 預設 children 直接渲染 `<Empty icon={Upload} title description />`,共用 icon+title+desc SSOT
 - `../../tokens/typography/typography.spec.md` — Typography tier
@@ -199,16 +204,11 @@ Empty 是 **pure layout primitive**(排列 icon / title / description / action
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `carousel.spec.md`
+- `circular-progress.spec.md`
+- `command.spec.md`
+- `file-upload.spec.md`
 - `file-viewer.spec.md`
 - `select-menu.spec.md`
+- `sheet.spec.md`
 - `skeleton.spec.md`
 - `tree-view.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `combobox.spec.md`
-- `command.spec.md`
-- `select.spec.md`
-- `sheet.spec.md`

package/src/components/Empty/empty.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { SearchX, Lock, Inbox } from 'lucide-react'
+import { Empty } from './empty'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta<typeof Empty> = {
+  title: 'Design System/Components/Empty/展示',
+  component: Empty,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '用於容器內沒有資料、搜尋無結果、尚未開始或無權檢視的狀態，並說明原因與下一步。錯誤或失敗改用 Alert / Notice，載入中改用 Spinner / Skeleton，整頁 403 / 404 使用專屬錯誤頁。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Empty>
+
+/* ── 搜尋無結果(Jira / Linear 慣例)─────────────────────────────────── */
+export const SearchNoResults: Story = {
+  name: '搜尋無結果',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={SearchX}
+        title="找不到相符的任務"
+        description="試試其他關鍵字,或調整篩選條件"
+        action={<Button variant="tertiary">清除所有篩選</Button>}
+      />
+    </div>
+  ),
+}
+
+/* ── 空清單 — Jira 無 task ────────────────────────────────────────── */
+export const NoTasks: Story = {
+  name: '空清單',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={Inbox}
+        title="這個 Sprint 還沒有任務"
+        description="從 backlog 拖拉任務進來,或直接建立新任務"
+        action={<Button variant="primary">建立任務</Button>}
+      />
+    </div>
+  ),
+}
+
+// Retired 2026-07-04 audit(Q 拍板):原 LoadFailure story 正面示範 spec 明文禁止的 error-state
+// 用法(empty.spec.md「何時不用」+ 禁止事項「錯誤/失敗狀態 → 改用 Alert」)— showcase 不得把
+// 反例當正例教。錯誤示範保留在 principles 的 ❌ 反例(empty.principles.stories.tsx)。
+
+/* ── 權限不足 ─────────────────────────────────────────────────────── */
+export const NoPermission: Story = {
+  name: '權限不足',
+  render: () => (
+    <div className="border border-border rounded-lg p-8 max-w-md">
+      <Empty
+        icon={Lock}
+        title="你沒有檢視這個專案的權限"
+        description="請聯絡專案擁有者要求存取,或返回你有權限的工作區"
+        action={<Button variant="tertiary">聯絡擁有者</Button>}
+      />
+    </div>
+  ),
+}

package/src/components/Empty/empty.tsx

@@ -8,12 +8,14 @@ import { useRowSize } from '@/design-system/patterns/element-anatomy/item-anatom
  * Empty — 空狀態視覺元件
  *
  * 居中垂直堆疊:icon(Avatar) → title → description → action。
- * 所有 slot 皆可選,預設只需 description。
+ * description 必填；icon / title / action 可選。
  *
  * 間距固定,不隨 density 變（Empty 是展示性元件,不是工作區域元件）:
  *   icon → text = mb-4（16px）
  *   desc → action = mt-6（24px）
- *   title → desc = `var(--item-gap-label-desc)`（token,預設 2px,item-anatomy SSOT）
+ *   title → desc = `var(--item-gap-label-desc-reading-lg)`（reading-lg tier token,item-anatomy SSOT;bare `--item-gap-label-desc` 已 retire）
+ *
+ * description 字級隨 RowSizeContext 變（sm/md → text-body 14px,lg → text-body-lg 16px）。
  *
  * Outer padding 由 consumer 容器決定(py-12 / py-6 / py-16 等）。
  */
@@ -23,14 +25,20 @@ export interface EmptyProps extends React.HTMLAttributes<HTMLDivElement> {
   icon?: LucideIcon | React.ReactElement
   /** 標題(可選,font-medium,適用於首次引導) */
   title?: string
-  /** 說明文字 */
-  description?: string
+  /** 必填的情境說明；不得用空字串代替載入中或其他狀態。 */
+  description: string
   /** 行動按鈕(可選) */
   action?: React.ReactNode
+  /**
+   * Disabled context(2026-06-03 加 — FileUpload disabled 等情境消費):title / description 轉
+   * `text-fg-disabled`(語意 disabled token,非 opacity)。icon glyph 也 → fg-disabled(icon 是文字一環);icon-circle bg 維持 muted。
+   * 預設 false,不影響既有 consumer。
+   */
+  disabled?: boolean
 }
 
 const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
-  ({ icon, title, description, action, className, ...props }, ref) => {
+  ({ icon, title, description, action, disabled = false, className, ...props }, ref) => {
     // 字體 tier:讀 RowSizeContext(menu 內自動對齊 menu items 的字體）
     // 沒有 context(standalone）→ fallback 'md' → text-body (14px)
     const rowSize = useRowSize('md')
@@ -42,10 +50,14 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
     let iconElement: React.ReactNode = null
     if (icon) {
       if (React.isValidElement(icon)) {
-        iconElement = icon
+        // disabled:自訂 element 同樣變淡(2026-07-07 補漏 — docblock/spec 無條件宣稱「icon glyph →
+        // fg-disabled」但原僅 LucideIcon 分支生效)。`contents` wrapper 不進 layout,[&_svg] token swap
+        // 只染 svg 系自訂 icon;非 svg(img 照片)不強制染色。
+        iconElement = disabled ? <span className="contents [&_svg]:!text-fg-disabled">{icon}</span> : icon
       } else {
         const Icon = icon as LucideIcon
-        iconElement = <Avatar icon={Icon} size={48} color="neutral" />
+        // disabled:glyph → fg-disabled([&_svg]:!… 蓋過 Avatar 內聯 color;circle bg 維持 muted)。icon 是文字一環,隨 disabled 變淡。
+        iconElement = <Avatar icon={Icon} size={48} color="neutral" className={disabled ? '[&_svg]:!text-fg-disabled' : undefined} />
       }
     }
 
@@ -59,7 +71,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
           <div className="mb-4">{iconElement}</div>
         )}
         {title && (
-          <span className="text-body-lg font-medium text-foreground">
+          <span className={cn('text-body-lg font-medium', disabled ? 'text-fg-disabled' : 'text-foreground')}>
             {title}
           </span>
         )}
@@ -69,7 +81,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
               // 字體跟 RowSizeContext 對齊:sm/md = text-body (14px),lg = text-body-lg (16px)
               // 在 menu 內自動對齊 menu items;standalone 時 fallback text-body
               descFont,
-              (title || action) ? 'text-fg-secondary' : 'text-fg-muted',
+              disabled ? 'text-fg-disabled' : (title || action) ? 'text-fg-secondary' : 'text-fg-muted',
               // Empty title 永遠 body-lg(16)→ 用 reading-lg token(label tier 決定)
               title && 'mt-[var(--item-gap-label-desc-reading-lg)]',
             )}
@@ -97,10 +109,10 @@ export const emptyMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default', 'disabled'],
   tokens: {
     bg: [],
-    fg: ['text-fg-muted', 'text-fg-secondary', 'text-foreground'],
+    fg: ['text-fg-muted', 'text-fg-secondary', 'text-foreground', 'text-fg-disabled'],
     ring: [],
   },
 } as const

package/src/components/Empty/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 './empty'

package/src/components/Field/field-context.ts

@@ -1,8 +1,9 @@
 import * as React from 'react'
-import type { FieldMode, FieldVariant } from './field-types'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from './field-types'
+import { EMPTY_DISPLAY } from './field-wrapper'
 
 // ── Types ──
-export type { FieldMode, FieldVariant }
+export type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth }
 export type FieldOrientation = 'vertical' | 'horizontal'
 export type FieldSize = 'sm' | 'md' | 'lg'
 export type FieldControlLayout = 'inline' | 'block'
@@ -16,8 +17,14 @@ export type FieldControlLayout = 'inline' | 'block'
  * - `'toolbar'`— Toolbar / Action bar inline Field(future,目前無 consumer)
  * - `'table-cell'`— DataTable cell-as-input substrate(取代 variant='naked' cell-detection
  *   heuristic;canonical metrics 由 surface 推導,不再 hardcode in Field consumer)
+ * - `'inline-edit'`(2026-07-17)— InlineEdit view 委派 surface。**唯一語義 = 委派控件 view 態
+ *   左 px 統一 `--field-px`(不繼承 tagPadding / avatar inset / bare-span 0px)**,讓 InlineEdit
+ *   固定 `-mx-[--field-px]` 對齊盒精準抵銷 → 值/tag/avatar 左緣落 label 左緣(x=0)。edit 態**不套**
+ *   本 surface(edit 完全繼承原 field,含 tagPadding — Jira 式)。對齊 Atlassian inline-edit
+ *   read-view「fixed negative margin + read=edit geometry by construction」。只 InlineEdit display
+ *   box 注入;DataTable cell(table-cell)/ 純表單(form)的 tagPadding + bare-span 完全不受影響。
  */
-type FieldSurface = 'form' | 'toolbar' | 'table-cell'
+type FieldSurface = 'form' | 'toolbar' | 'table-cell' | 'inline-edit'
 
 // ── Context ──
 export interface FieldContextValue {
@@ -29,13 +36,19 @@ export interface FieldContextValue {
   descriptionId: string
   errorId: string
   mode: FieldMode
-  /** 視覺外殼透傳(2026-05-05)。default = 含 border+bg;bare = 透明 variant,hover/focus reveal。
+  /** 視覺外殼透傳(2026-05-05)。default = 含 border+bg;naked = cell-as-input(edit×naked 自畫 border-based state machine;view×naked 用 transparent border 由 host cell 供邊框);`bare` 2026-07-09 退役;naked 2026-07-14 型別收窄至
+   *  FieldVariantInternal(@internal)— 公開 `<Field variant>` 只收 default,故本欄位維持 FieldVariant。
    *  child Field control 自動繼承,per-control prop override 可覆寫。詳 field-types.ts。 */
   variant: FieldVariant
   disabled: boolean
   required: boolean
   invalid: boolean
   size: FieldSize
+  /** `size` 是被決定過的(consumer 顯式傳 / control 宣告偏好)還是 Field 的預設 md。
+   *  預設 md 不得壓過 control 自己宣告的 fallback —— 詳 useResolvedFieldSize 與 field.spec.md。 */
+  sizeExplicit: boolean
+  /** Control 於掛載時宣告偏好尺寸(wrapper/HOC 遮蔽靜態 `fieldPreferredSize` 時的補位通道)。 */
+  registerPreferredSize?: (preferred: FieldSize) => void
   orientation: FieldOrientation
   controlLayout: FieldControlLayout
   hasFieldWrapper: true
@@ -134,3 +147,182 @@ export function TableScrollProvider({
 }): React.ReactElement {
   return React.createElement(TableScrollContext.Provider, { value: isScrolling }, children)
 }
+
+/**
+ * Surface size signal — 獨立於 FieldContext + FieldSurfaceContext 的純視覺 size context(2026-06-08)。
+ * 讓 host(DataTable cell substrate)把「這片 surface 的 density size」propagate 給 child Field controls,
+ * 未來新 cell 漏傳 size prop 也自動繼承 → 字級一致(根治 StringCell/NumberCell 漏傳 size class)。
+ *
+ * 不放進 FieldSurfaceContext value(避免 string→object identity drift on scroll → 全 cell 重渲,
+ * 同 TableScrollContext L119-121 canonical)— 獨立 Context,value = FieldSize primitive(stable when unchanged)。
+ * 絕不污染 FieldContext:不碰 hasFieldWrapper/mode/invalid/disabled,useFieldContext() 在 cell 內仍 null。
+ */
+const FieldSurfaceSizeContext = React.createContext<FieldSize | null>(null)
+
+/**
+ * Resolve Field control size — 控件用此 helper 取代散落的 `sizeProp ?? fieldCtx?.size ?? 'md'`。
+ * 優先序:prop(caller 顯式)> FieldContext.size(真 <Field> wrapper)> surface-size(host 如 cell)> 'md'。
+ * 真 <Field> 永遠勝 host surface(安全序);cell 無 Field wrapper(fieldCtx=null)→ 自動接 surface-size,
+ * 漏傳 size 的新 cell 也字級一致。
+ */
+export function useResolvedFieldSize<T extends string = FieldSize>(sizeProp?: T | null, fallback?: T): T {
+  const fieldCtx = React.useContext(FieldContext)
+  const surfaceSize = React.useContext(FieldSurfaceSizeContext)
+  // generic T(預設 FieldSize)讓非-input 控件(SegmentedControl/Rating 的 'xs'|'sm'|'md'|'lg' 超集、各自 fallback)
+  // 也走同一 SSOT resolution。fieldCtx.size/surfaceSize 為 FieldSize(T 的子集)→ widen cast 安全。
+  // fallback 未傳預設 'md'(input-class 控件向後相容);Rating 傳 'xs'、SegmentedControl 傳 'md'。
+  //
+  // 2026-07-28:Field 的 size 只有在 consumer 顯式指定、或 Field 已解析出 control 偏好時才算「決定過」
+  // (`sizeExplicit`)。否則那只是 Field 的預設 md,不該壓過控件自己宣告的 fallback ——
+  // 舊行為讓「InlineEdit 被包一層 wrapper」時靜默退回 md(詳 field.spec.md 偏好尺寸 SSOT)。
+  const contextSize = fieldCtx && fieldCtx.sizeExplicit ? (fieldCtx.size as T | undefined) : undefined
+  return (sizeProp ?? contextSize ?? fallback ?? (fieldCtx?.size as T | undefined) ?? (surfaceSize as T | undefined) ?? ('md' as T))
+}
+
+/**
+ * Control 向外層 Field 宣告偏好尺寸(render-time)。靜態 `fieldPreferredSize` 只有在 control 是
+ * Field 的**直接子元件**時才偵測得到;包 wrapper / `React.memo` / HOC 會遮蔽它。本 hook 讓 control
+ * 在掛載時主動註冊,Field 的**控件槽高度**因此也能跟上(控件本身的尺寸則由 `useResolvedFieldSize`
+ * 同步解析,不等這次註冊)。
+ */
+export function useRegisterFieldPreferredSize(preferred?: FieldSize | null): void {
+  const fieldCtx = React.useContext(FieldContext)
+  const register = fieldCtx?.registerPreferredSize
+  React.useEffect(() => {
+    if (preferred && register) register(preferred)
+  }, [preferred, register])
+}
+
+/**
+ * Resolve Field control 的 **disabled** — 取代散落的 `disabledProp ?? fieldCtx?.disabled`(2026-06-08 SSOT)。
+ * 優先序:顯式 prop > FieldContext.disabled(`<Field disabled>` / `<Field mode="disabled">`)> false。
+ * **caller 必傳「未預設」的原始 prop**(沒傳 = undefined),否則 `disabled=false` 預設會吃掉 `??` fallback。
+ * DataTable cell 無 FieldContext(fieldCtx=null)→ 回 prop 或 false,行為與現況完全一致(inert)。
+ */
+export function useResolvedFieldDisabled(disabledProp?: boolean | null): boolean {
+  const fieldCtx = React.useContext(FieldContext)
+  return disabledProp ?? fieldCtx?.disabled ?? false
+}
+
+/**
+ * Resolve Field control 的 **mode**(view / readonly / disabled / edit)— 2026-06-08 SSOT,統一兩派散落:
+ *   舊 Input 派 `modeProp ?? fieldCtx?.mode ?? (...)` → `<Field disabled>` 時 ctx.mode 仍 'edit',漏 disabled chrome。
+ *   舊 picker 派 `disabled ? 'disabled' : mode`(mode 預設 'edit')→ 完全不讀 fieldCtx.mode,`<Field mode="view">` 失效。
+ * 統一優先序(world-class:MUI FormControl disabled 完整 cascade + 顯式 prop 永遠最優先):
+ *   1. 顯式 mode prop(caller / DataTable cell 傳 mode="view")→ **永遠最優先**,故表格等顯式場景 inert
+ *   2. 有效 disabled(prop 或 `<Field disabled>`)→ 'disabled'(完整 disabled chrome)
+ *   3. FieldContext.mode(`<Field mode="view"/"readonly">`)→ 讓 mode cascade 真正生效
+ *   4. 本地 readOnly → 'readonly'
+ *   5. 'edit'
+ * cell:mode prop 必有 → step 1 命中、fieldCtx=null → 完全 inert(Δ=0)。`disabled` 傳已 resolve 的 boolean 或未預設 prop。
+ */
+export function useResolvedFieldMode({
+  mode,
+  disabled,
+  readOnly,
+}: {
+  mode?: FieldMode | null
+  disabled?: boolean | null
+  readOnly?: boolean
+}): FieldMode {
+  const fieldCtx = React.useContext(FieldContext)
+  if (mode) return mode
+  if ((disabled ?? fieldCtx?.disabled) === true) return 'disabled'
+  if (fieldCtx?.mode) return fieldCtx.mode
+  if (readOnly) return 'readonly'
+  return 'edit'
+}
+
+/**
+ * Resolve Field control 的 **variant**(default / naked 視覺外殼;`bare` 2026-07-09 退役)— 2026-06-08 SSOT。
+ * 優先序:顯式 prop > FieldContext.variant > 'default'。與既有各控件公式一字不差(Δ=0),統一以利 gate 強制。
+ * 2026-07-14 API 策展 E:入參 / 回傳 widen 為 FieldVariantInternal — naked 僅 DataTable cell-registry
+ * 經 @internal 通道傳入(公開 prop 型別 = FieldVariant,不含 naked)。
+ */
+export function useResolvedFieldVariant(variantProp?: FieldVariantInternal | null): FieldVariantInternal {
+  const fieldCtx = React.useContext(FieldContext)
+  return variantProp ?? fieldCtx?.variant ?? 'default'
+}
+
+/**
+ * Resolve Field control 的 **error/invalid** — 取代散落的 `errorProp || (fieldCtx?.invalid ?? false)`(2026-06-08 SSOT)。
+ * 自身 error prop **或** FieldContext.invalid(`<Field invalid>`)任一為真即 error。與既有公式一致(Δ=0)。
+ */
+export function useResolvedFieldInvalid(errorProp?: boolean): boolean {
+  const fieldCtx = React.useContext(FieldContext)
+  return Boolean(errorProp) || (fieldCtx?.invalid ?? false)
+}
+
+/**
+ * Host(non-Field-wrapper,如 DataTable cell)注 surface density size 給 child Field controls。
+ * 僅注 size 視覺訊號,不污染 FieldContext。Usage:cell-registry buildCellWithSurface。
+ */
+export function FieldSurfaceSizeProvider({
+  size,
+  children,
+}: {
+  size: FieldSize
+  children: React.ReactNode
+}): React.ReactElement {
+  return React.createElement(FieldSurfaceSizeContext.Provider, { value: size }, children)
+}
+
+/**
+ * Table-cell 可編輯訊號(2026-07-08 user 拍板)— 獨立於 FieldSurfaceContext / FieldSurfaceSizeContext
+ * 的純 boolean context,由 host(DataTable cell registry)注入該 cell 是否可編輯,讓 useFieldEmptyDisplay
+ * 分流「可編輯 cell 空 view → 空白」vs「不可編輯 cell 空 view → '-'」。
+ * value = boolean primitive(stable when unchanged),不破壞 cell memo identity(同 TableScrollContext /
+ * FieldSurfaceSizeContext L119-121 canonical);絕不污染 FieldContext(useFieldContext() 在 cell 內仍 null)。
+ */
+const FieldSurfaceEditableContext = React.createContext<boolean>(false)
+
+export function FieldSurfaceEditableProvider({
+  isEditable,
+  children,
+}: {
+  isEditable: boolean
+  children: React.ReactNode
+}): React.ReactElement {
+  return React.createElement(FieldSurfaceEditableContext.Provider, { value: isEditable }, children)
+}
+
+/**
+ * 空值顯示分流(2026-07-08 user 拍板,verbatim「...都用"-"...我從頭到尾哪裡有說要用全形的」):
+ *
+ * | 情境                                           | 空值顯示 |
+ * |------------------------------------------------|----------|
+ * | table-cell **可編輯** 的 view 靜止態        | **空白 `''`**(不佔位,affordance = hover outline)|
+ * | table-cell **不可編輯**(readonly cell)        | **半形 `-`** |
+ * | standalone view / readonly / form / toolbar | **半形 `-`** |
+ *
+ * 收斂式:`surface==='table-cell' && isEditable ? '' : EMPTY_DISPLAY`。
+ * 可編輯 form / edit 輸入框走 native placeholder(不經此 hook)。boolean → unchecked / disabled →
+ * 同上文字 + text-fg-disabled(M24),各控件自理。
+ * 世界級對照:table-cell blank = MUI X / AG Grid / Ant core / Notion / Airtable grid 域共識;
+ * 非 table `-` = Ant ProTable `columnEmptyText`(見 field-wrapper.tsx EMPTY_DISPLAY 註)。
+ * SSOT 條文 → field-controls.spec.md「null / undefined 值」;全 Field family view/readonly/disabled
+ * 空值渲染必經此 hook,禁直接引 EMPTY_DISPLAY 常數(genre 分流會漏)。
+ */
+export function useFieldEmptyDisplay(): string {
+  const surface = useFieldSurface()
+  const isEditable = React.useContext(FieldSurfaceEditableContext)
+  return surface === 'table-cell' && isEditable ? '' : EMPTY_DISPLAY
+}
+
+/**
+ * 空值符號「-」顏色分流(2026-07-09 user 拍板 verbatim「「-」代表的是不可編輯只拿來供檢視的值
+ * 所以應該跟readonly 的value同樣顏色吧」):
+ *
+ * 「-」是「不可編輯、供檢視的值」→ 同 readonly value 色 = `text-foreground`
+ * (field-wrapper.tsx base `text-foreground`),**非** `text-fg-muted`(muted 是「可編輯 placeholder
+ * 提示」的裝飾語意;空值符號不是提示、是被檢視的值狀態)。
+ * disabled 態維持 `text-fg-disabled`(M24 disabled 顯著性 > foreground/muted,不可被蓋)。
+ *
+ * SSOT:全 Field family view/readonly/disabled 空值 span 消費此 helper,傳入已 resolve 的
+ * resolvedMode。純函式(非 hook)—— resolvedMode 已由 useResolvedFieldMode 解析(含控件自身
+ * disabled prop,context hook 讀不到);故以 resolvedMode 為入參,可條件呼叫、不受 Rules of Hooks 限制。
+ * 世界級對照:Ant read-only / Carbon read-only value = 正常前景色;placeholder 才 muted。
+ */
+export function fieldEmptyColorClass(resolvedMode: FieldMode): string {
+  return resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-foreground'
+}