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

package/dist/components/Field/field-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-context.js","sources":["../../../src/components/Field/field-context.ts"],"sourcesContent":["import * as React from 'react'\nimport type { FieldMode, FieldVariant } from './field-types'\n\n// ── Types ──\nexport type { FieldMode, FieldVariant }\nexport type FieldOrientation = 'vertical' | 'horizontal'\nexport type FieldSize = 'sm' | 'md' | 'lg'\nexport type FieldControlLayout = 'inline' | 'block'\n\n/**\n * Field surface(2026-05-12 codex Q2 verdict — Stream C 4-issues Cluster B fix):\n * 替代散落的 `variant === 'naked'` 判 cell heuristic,讓 Field family components\n * 顯式 query「我在哪 surface」derive cell-specific padding / alignment / overflow。\n *\n * - `'form'`(default)— Standalone Field control(對齊 Polaris / Material Form idiom)\n * - `'toolbar'`— Toolbar / Action bar inline Field(future,目前無 consumer)\n * - `'table-cell'`— DataTable cell-as-input substrate(取代 variant='naked' cell-detection\n *   heuristic;canonical metrics 由 surface 推導,不再 hardcode in Field consumer)\n */\ntype FieldSurface = 'form' | 'toolbar' | 'table-cell'\n\n// ── Context ──\nexport interface FieldContextValue {\n  id: string\n  /** a11y(2026-04-25):FieldLabel 渲染時若元素為 div-based role(combobox/slider\n   * 等非 native form control),`<label for>` 無效,需 aria-labelledby 指向 labelId。\n   * FieldLabel 自動設 id={labelId},下游 control 可讀此值寫入 aria-labelledby。 */\n  labelId: string\n  descriptionId: string\n  errorId: string\n  mode: FieldMode\n  /** 視覺外殼透傳(2026-05-05)。default = 含 border+bg;bare = 透明 variant,hover/focus reveal。\n   *  child Field control 自動繼承,per-control prop override 可覆寫。詳 field-types.ts。 */\n  variant: FieldVariant\n  disabled: boolean\n  required: boolean\n  invalid: boolean\n  size: FieldSize\n  orientation: FieldOrientation\n  controlLayout: FieldControlLayout\n  hasFieldWrapper: true\n  /** 2026-05-12 Stream C Cluster B fix:surface 上下文(form / toolbar / table-cell)\n   *  從 host(Field wrapper / DataTable cell registry)propagate 給 child controls。\n   *  Optional — 未設視同 `'form'`(backward compat)。 */\n  surface?: FieldSurface\n}\n\nexport const FieldContext = React.createContext<FieldContextValue | null>(null)\n\n/** 讓 primitive（Checkbox/Switch/Radio/Button/Input 等）讀 Field context */\nexport function useFieldContext(): FieldContextValue | null {\n  return React.useContext(FieldContext)\n}\n\n/**\n * Surface context — **獨立於 FieldContext** 的 surface signal(2026-05-12 v2 fix)。\n *\n * 原 v1 設計(`FieldSurfaceProvider` 透過 FieldContext.Provider 注入)誤把 stub\n * `hasFieldWrapper: true` 傳給沒有真正 Field wrapper 的場景(例 DataTable cell 內 standalone\n * DatePicker),導致 cells 誤以為有 Field 父 → 視覺 regression(2026-05-12 visual-audit 抓 3\n * stories 超過 baseline budget:DatePicker range-picker / FileViewer open-snapshot /\n * DataTable pinned-columns)。\n *\n * v2 修:**完全分離** FieldSurfaceContext;FieldContext 不被污染;non-FieldWrapper hosts\n * 只能影響 surface signal,不能假冒 Field wrapper 身份。\n */\nconst FieldSurfaceContext = React.createContext<FieldSurface | null>(null)\n\n/**\n * Helper: 取當前 surface,fall back 'form'。\n *\n * Stream C Cluster B canonical entry point — Field family controls 用此 helper 替代\n * 散落的 `variant === 'naked'` cell heuristic。對齊 codex Q2 verdict「surface context」\n * canonical(替代「inCellContext per-prop」反 pattern)。\n *\n * 優先順序:FieldSurfaceContext(host-provided) → FieldContext.surface(Field-wrapper-provided)\n *           → fallback 'form'。\n */\nexport function useFieldSurface(): FieldSurface {\n  const surfaceCtx = React.useContext(FieldSurfaceContext)\n  if (surfaceCtx) return surfaceCtx\n  const fieldCtx = React.useContext(FieldContext)\n  return fieldCtx?.surface ?? 'form'\n}\n\n/**\n * Standalone FieldSurface provider — 給 host(non-Field-wrapper, 如 DataTable cell)\n * **僅**設 surface signal,**不**污染 FieldContext。\n *\n * Usage(per cell-registry.tsx,2026-05-12):\n *   <FieldSurfaceProvider surface=\"table-cell\"><Field control /></FieldSurfaceProvider>\n *\n * 與 FieldContext.Provider 差別:\n *   - FieldContext.Provider — 完整 Field wrapper 用,provides mode/variant/disabled/...\n *   - FieldSurfaceProvider — host **僅**注 surface signal,Field controls 透過\n *     `useFieldSurface()` 讀;`useFieldContext()` 仍 returns null(沒被假冒)。\n */\nexport function FieldSurfaceProvider({\n  surface,\n  children,\n}: {\n  surface: FieldSurface\n  children: React.ReactNode\n}): React.ReactElement {\n  return React.createElement(FieldSurfaceContext.Provider, { value: surface }, children)\n}\n\n/**\n * 2026-05-13 (c) scroll-defer perf SSOT(per codex DataTable perf brief V3 + user 拍板\n * 「Roadmap still >50ms 進 (c)」):\n * Host(DataTable)在 virtualizer.isScrolling=true 期間 wrap children with `TableScrollProvider`,\n * 重 cell 組件(Avatar HoverCard / PeoplePicker / etc.)讀此 signal 跳過昂貴 subtree(如 HoverCard\n * Portal + useDocumentTheme observer),scroll 結束 unset → 重渲染為完整 affordance。\n *\n * 對齊 codex Profile Plan step 6(Scripting vs Layout 判分):scrolling 期間 cell 渲染壓縮 →\n * 240ms/frame catastrophe → close to 50ms target。世界級對齊:AG Grid `deferRender` for slow\n * React cell components / MUI X DataGrid scroll-defer hover affordance。\n *\n * 不放在 FieldSurfaceContext 內(避免 value object identity drift on scroll → 全 cell 重渲)\n * — 用獨立 Context,value = boolean primitive(stable when unchanged)。\n */\nconst TableScrollContext = React.createContext<boolean>(false)\n\nexport function useTableIsScrolling(): boolean {\n  return React.useContext(TableScrollContext)\n}\n\nexport function TableScrollProvider({\n  isScrolling,\n  children,\n}: {\n  isScrolling: boolean\n  children: React.ReactNode\n}): React.ReactElement {\n  return React.createElement(TableScrollContext.Provider, { value: isScrolling }, children)\n}\n"],"names":[],"mappings":";AA+CO,MAAM,eAAe,MAAM,cAAwC,IAAI;AAGvE,SAAS,kBAA4C;AAC1D,SAAO,MAAM,WAAW,YAAY;AACtC;AAcA,MAAM,sBAAsB,MAAM,cAAmC,IAAI;AAYlE,SAAS,kBAAgC;AAC9C,QAAM,aAAa,MAAM,WAAW,mBAAmB;AACvD,MAAI,WAAY,QAAO;AACvB,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,UAAO,qCAAU,YAAW;AAC9B;AAcO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGuB;AACrB,SAAO,MAAM,cAAc,oBAAoB,UAAU,EAAE,OAAO,QAAA,GAAW,QAAQ;AACvF;AAgBA,MAAM,qBAAqB,MAAM,cAAuB,KAAK;AAEtD,SAAS,sBAA+B;AAC7C,SAAO,MAAM,WAAW,kBAAkB;AAC5C;AAEO,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AACF,GAGuB;AACrB,SAAO,MAAM,cAAc,mBAAmB,UAAU,EAAE,OAAO,YAAA,GAAe,QAAQ;AAC1F;"}
+{"version":3,"file":"field-context.js","sources":["../../../src/components/Field/field-context.ts"],"sourcesContent":["import * as React from 'react'\nimport type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from './field-types'\nimport { EMPTY_DISPLAY } from './field-wrapper'\n\n// ── Types ──\nexport type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth }\nexport type FieldOrientation = 'vertical' | 'horizontal'\nexport type FieldSize = 'sm' | 'md' | 'lg'\nexport type FieldControlLayout = 'inline' | 'block'\n\n/**\n * Field surface(2026-05-12 codex Q2 verdict — Stream C 4-issues Cluster B fix):\n * 替代散落的 `variant === 'naked'` 判 cell heuristic,讓 Field family components\n * 顯式 query「我在哪 surface」derive cell-specific padding / alignment / overflow。\n *\n * - `'form'`(default)— Standalone Field control(對齊 Polaris / Material Form idiom)\n * - `'toolbar'`— Toolbar / Action bar inline Field(future,目前無 consumer)\n * - `'table-cell'`— DataTable cell-as-input substrate(取代 variant='naked' cell-detection\n *   heuristic;canonical metrics 由 surface 推導,不再 hardcode in Field consumer)\n * - `'inline-edit'`(2026-07-17)— InlineEdit view 委派 surface。**唯一語義 = 委派控件 view 態\n *   左 px 統一 `--field-px`(不繼承 tagPadding / avatar inset / bare-span 0px)**,讓 InlineEdit\n *   固定 `-mx-[--field-px]` 對齊盒精準抵銷 → 值/tag/avatar 左緣落 label 左緣(x=0)。edit 態**不套**\n *   本 surface(edit 完全繼承原 field,含 tagPadding — Jira 式)。對齊 Atlassian inline-edit\n *   read-view「fixed negative margin + read=edit geometry by construction」。只 InlineEdit display\n *   box 注入;DataTable cell(table-cell)/ 純表單(form)的 tagPadding + bare-span 完全不受影響。\n */\ntype FieldSurface = 'form' | 'toolbar' | 'table-cell' | 'inline-edit'\n\n// ── Context ──\nexport interface FieldContextValue {\n  id: string\n  /** a11y(2026-04-25):FieldLabel 渲染時若元素為 div-based role(combobox/slider\n   * 等非 native form control),`<label for>` 無效,需 aria-labelledby 指向 labelId。\n   * FieldLabel 自動設 id={labelId},下游 control 可讀此值寫入 aria-labelledby。 */\n  labelId: string\n  descriptionId: string\n  errorId: string\n  mode: FieldMode\n  /** 視覺外殼透傳(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 型別收窄至\n   *  FieldVariantInternal(@internal)— 公開 `<Field variant>` 只收 default,故本欄位維持 FieldVariant。\n   *  child Field control 自動繼承,per-control prop override 可覆寫。詳 field-types.ts。 */\n  variant: FieldVariant\n  disabled: boolean\n  required: boolean\n  invalid: boolean\n  size: FieldSize\n  /** `size` 是被決定過的(consumer 顯式傳 / control 宣告偏好)還是 Field 的預設 md。\n   *  預設 md 不得壓過 control 自己宣告的 fallback —— 詳 useResolvedFieldSize 與 field.spec.md。 */\n  sizeExplicit: boolean\n  /** Control 於掛載時宣告偏好尺寸(wrapper/HOC 遮蔽靜態 `fieldPreferredSize` 時的補位通道)。 */\n  registerPreferredSize?: (preferred: FieldSize) => void\n  orientation: FieldOrientation\n  controlLayout: FieldControlLayout\n  hasFieldWrapper: true\n  /** 2026-05-12 Stream C Cluster B fix:surface 上下文(form / toolbar / table-cell)\n   *  從 host(Field wrapper / DataTable cell registry)propagate 給 child controls。\n   *  Optional — 未設視同 `'form'`(backward compat)。 */\n  surface?: FieldSurface\n}\n\nexport const FieldContext = React.createContext<FieldContextValue | null>(null)\n\n/** 讓 primitive（Checkbox/Switch/Radio/Button/Input 等）讀 Field context */\nexport function useFieldContext(): FieldContextValue | null {\n  return React.useContext(FieldContext)\n}\n\n/**\n * Surface context — **獨立於 FieldContext** 的 surface signal(2026-05-12 v2 fix)。\n *\n * 原 v1 設計(`FieldSurfaceProvider` 透過 FieldContext.Provider 注入)誤把 stub\n * `hasFieldWrapper: true` 傳給沒有真正 Field wrapper 的場景(例 DataTable cell 內 standalone\n * DatePicker),導致 cells 誤以為有 Field 父 → 視覺 regression(2026-05-12 visual-audit 抓 3\n * stories 超過 baseline budget:DatePicker range-picker / FileViewer open-snapshot /\n * DataTable pinned-columns)。\n *\n * v2 修:**完全分離** FieldSurfaceContext;FieldContext 不被污染;non-FieldWrapper hosts\n * 只能影響 surface signal,不能假冒 Field wrapper 身份。\n */\nconst FieldSurfaceContext = React.createContext<FieldSurface | null>(null)\n\n/**\n * Helper: 取當前 surface,fall back 'form'。\n *\n * Stream C Cluster B canonical entry point — Field family controls 用此 helper 替代\n * 散落的 `variant === 'naked'` cell heuristic。對齊 codex Q2 verdict「surface context」\n * canonical(替代「inCellContext per-prop」反 pattern)。\n *\n * 優先順序:FieldSurfaceContext(host-provided) → FieldContext.surface(Field-wrapper-provided)\n *           → fallback 'form'。\n */\nexport function useFieldSurface(): FieldSurface {\n  const surfaceCtx = React.useContext(FieldSurfaceContext)\n  if (surfaceCtx) return surfaceCtx\n  const fieldCtx = React.useContext(FieldContext)\n  return fieldCtx?.surface ?? 'form'\n}\n\n/**\n * Standalone FieldSurface provider — 給 host(non-Field-wrapper, 如 DataTable cell)\n * **僅**設 surface signal,**不**污染 FieldContext。\n *\n * Usage(per cell-registry.tsx,2026-05-12):\n *   <FieldSurfaceProvider surface=\"table-cell\"><Field control /></FieldSurfaceProvider>\n *\n * 與 FieldContext.Provider 差別:\n *   - FieldContext.Provider — 完整 Field wrapper 用,provides mode/variant/disabled/...\n *   - FieldSurfaceProvider — host **僅**注 surface signal,Field controls 透過\n *     `useFieldSurface()` 讀;`useFieldContext()` 仍 returns null(沒被假冒)。\n */\nexport function FieldSurfaceProvider({\n  surface,\n  children,\n}: {\n  surface: FieldSurface\n  children: React.ReactNode\n}): React.ReactElement {\n  return React.createElement(FieldSurfaceContext.Provider, { value: surface }, children)\n}\n\n/**\n * 2026-05-13 (c) scroll-defer perf SSOT(per codex DataTable perf brief V3 + user 拍板\n * 「Roadmap still >50ms 進 (c)」):\n * Host(DataTable)在 virtualizer.isScrolling=true 期間 wrap children with `TableScrollProvider`,\n * 重 cell 組件(Avatar HoverCard / PeoplePicker / etc.)讀此 signal 跳過昂貴 subtree(如 HoverCard\n * Portal + useDocumentTheme observer),scroll 結束 unset → 重渲染為完整 affordance。\n *\n * 對齊 codex Profile Plan step 6(Scripting vs Layout 判分):scrolling 期間 cell 渲染壓縮 →\n * 240ms/frame catastrophe → close to 50ms target。世界級對齊:AG Grid `deferRender` for slow\n * React cell components / MUI X DataGrid scroll-defer hover affordance。\n *\n * 不放在 FieldSurfaceContext 內(避免 value object identity drift on scroll → 全 cell 重渲)\n * — 用獨立 Context,value = boolean primitive(stable when unchanged)。\n */\nconst TableScrollContext = React.createContext<boolean>(false)\n\nexport function useTableIsScrolling(): boolean {\n  return React.useContext(TableScrollContext)\n}\n\nexport function TableScrollProvider({\n  isScrolling,\n  children,\n}: {\n  isScrolling: boolean\n  children: React.ReactNode\n}): React.ReactElement {\n  return React.createElement(TableScrollContext.Provider, { value: isScrolling }, children)\n}\n\n/**\n * Surface size signal — 獨立於 FieldContext + FieldSurfaceContext 的純視覺 size context(2026-06-08)。\n * 讓 host(DataTable cell substrate)把「這片 surface 的 density size」propagate 給 child Field controls,\n * 未來新 cell 漏傳 size prop 也自動繼承 → 字級一致(根治 StringCell/NumberCell 漏傳 size class)。\n *\n * 不放進 FieldSurfaceContext value(避免 string→object identity drift on scroll → 全 cell 重渲,\n * 同 TableScrollContext L119-121 canonical)— 獨立 Context,value = FieldSize primitive(stable when unchanged)。\n * 絕不污染 FieldContext:不碰 hasFieldWrapper/mode/invalid/disabled,useFieldContext() 在 cell 內仍 null。\n */\nconst FieldSurfaceSizeContext = React.createContext<FieldSize | null>(null)\n\n/**\n * Resolve Field control size — 控件用此 helper 取代散落的 `sizeProp ?? fieldCtx?.size ?? 'md'`。\n * 優先序:prop(caller 顯式)> FieldContext.size(真 <Field> wrapper)> surface-size(host 如 cell)> 'md'。\n * 真 <Field> 永遠勝 host surface(安全序);cell 無 Field wrapper(fieldCtx=null)→ 自動接 surface-size,\n * 漏傳 size 的新 cell 也字級一致。\n */\nexport function useResolvedFieldSize<T extends string = FieldSize>(sizeProp?: T | null, fallback?: T): T {\n  const fieldCtx = React.useContext(FieldContext)\n  const surfaceSize = React.useContext(FieldSurfaceSizeContext)\n  // generic T(預設 FieldSize)讓非-input 控件(SegmentedControl/Rating 的 'xs'|'sm'|'md'|'lg' 超集、各自 fallback)\n  // 也走同一 SSOT resolution。fieldCtx.size/surfaceSize 為 FieldSize(T 的子集)→ widen cast 安全。\n  // fallback 未傳預設 'md'(input-class 控件向後相容);Rating 傳 'xs'、SegmentedControl 傳 'md'。\n  //\n  // 2026-07-28:Field 的 size 只有在 consumer 顯式指定、或 Field 已解析出 control 偏好時才算「決定過」\n  // (`sizeExplicit`)。否則那只是 Field 的預設 md,不該壓過控件自己宣告的 fallback ——\n  // 舊行為讓「InlineEdit 被包一層 wrapper」時靜默退回 md(詳 field.spec.md 偏好尺寸 SSOT)。\n  const contextSize = fieldCtx && fieldCtx.sizeExplicit ? (fieldCtx.size as T | undefined) : undefined\n  return (sizeProp ?? contextSize ?? fallback ?? (fieldCtx?.size as T | undefined) ?? (surfaceSize as T | undefined) ?? ('md' as T))\n}\n\n/**\n * Control 向外層 Field 宣告偏好尺寸(render-time)。靜態 `fieldPreferredSize` 只有在 control 是\n * Field 的**直接子元件**時才偵測得到;包 wrapper / `React.memo` / HOC 會遮蔽它。本 hook 讓 control\n * 在掛載時主動註冊,Field 的**控件槽高度**因此也能跟上(控件本身的尺寸則由 `useResolvedFieldSize`\n * 同步解析,不等這次註冊)。\n */\nexport function useRegisterFieldPreferredSize(preferred?: FieldSize | null): void {\n  const fieldCtx = React.useContext(FieldContext)\n  const register = fieldCtx?.registerPreferredSize\n  React.useEffect(() => {\n    if (preferred && register) register(preferred)\n  }, [preferred, register])\n}\n\n/**\n * Resolve Field control 的 **disabled** — 取代散落的 `disabledProp ?? fieldCtx?.disabled`(2026-06-08 SSOT)。\n * 優先序:顯式 prop > FieldContext.disabled(`<Field disabled>` / `<Field mode=\"disabled\">`)> false。\n * **caller 必傳「未預設」的原始 prop**(沒傳 = undefined),否則 `disabled=false` 預設會吃掉 `??` fallback。\n * DataTable cell 無 FieldContext(fieldCtx=null)→ 回 prop 或 false,行為與現況完全一致(inert)。\n */\nexport function useResolvedFieldDisabled(disabledProp?: boolean | null): boolean {\n  const fieldCtx = React.useContext(FieldContext)\n  return disabledProp ?? fieldCtx?.disabled ?? false\n}\n\n/**\n * Resolve Field control 的 **mode**(view / readonly / disabled / edit)— 2026-06-08 SSOT,統一兩派散落:\n *   舊 Input 派 `modeProp ?? fieldCtx?.mode ?? (...)` → `<Field disabled>` 時 ctx.mode 仍 'edit',漏 disabled chrome。\n *   舊 picker 派 `disabled ? 'disabled' : mode`(mode 預設 'edit')→ 完全不讀 fieldCtx.mode,`<Field mode=\"view\">` 失效。\n * 統一優先序(world-class:MUI FormControl disabled 完整 cascade + 顯式 prop 永遠最優先):\n *   1. 顯式 mode prop(caller / DataTable cell 傳 mode=\"view\")→ **永遠最優先**,故表格等顯式場景 inert\n *   2. 有效 disabled(prop 或 `<Field disabled>`)→ 'disabled'(完整 disabled chrome)\n *   3. FieldContext.mode(`<Field mode=\"view\"/\"readonly\">`)→ 讓 mode cascade 真正生效\n *   4. 本地 readOnly → 'readonly'\n *   5. 'edit'\n * cell:mode prop 必有 → step 1 命中、fieldCtx=null → 完全 inert(Δ=0)。`disabled` 傳已 resolve 的 boolean 或未預設 prop。\n */\nexport function useResolvedFieldMode({\n  mode,\n  disabled,\n  readOnly,\n}: {\n  mode?: FieldMode | null\n  disabled?: boolean | null\n  readOnly?: boolean\n}): FieldMode {\n  const fieldCtx = React.useContext(FieldContext)\n  if (mode) return mode\n  if ((disabled ?? fieldCtx?.disabled) === true) return 'disabled'\n  if (fieldCtx?.mode) return fieldCtx.mode\n  if (readOnly) return 'readonly'\n  return 'edit'\n}\n\n/**\n * Resolve Field control 的 **variant**(default / naked 視覺外殼;`bare` 2026-07-09 退役)— 2026-06-08 SSOT。\n * 優先序:顯式 prop > FieldContext.variant > 'default'。與既有各控件公式一字不差(Δ=0),統一以利 gate 強制。\n * 2026-07-14 API 策展 E:入參 / 回傳 widen 為 FieldVariantInternal — naked 僅 DataTable cell-registry\n * 經 @internal 通道傳入(公開 prop 型別 = FieldVariant,不含 naked)。\n */\nexport function useResolvedFieldVariant(variantProp?: FieldVariantInternal | null): FieldVariantInternal {\n  const fieldCtx = React.useContext(FieldContext)\n  return variantProp ?? fieldCtx?.variant ?? 'default'\n}\n\n/**\n * Resolve Field control 的 **error/invalid** — 取代散落的 `errorProp || (fieldCtx?.invalid ?? false)`(2026-06-08 SSOT)。\n * 自身 error prop **或** FieldContext.invalid(`<Field invalid>`)任一為真即 error。與既有公式一致(Δ=0)。\n */\nexport function useResolvedFieldInvalid(errorProp?: boolean): boolean {\n  const fieldCtx = React.useContext(FieldContext)\n  return Boolean(errorProp) || (fieldCtx?.invalid ?? false)\n}\n\n/**\n * Host(non-Field-wrapper,如 DataTable cell)注 surface density size 給 child Field controls。\n * 僅注 size 視覺訊號,不污染 FieldContext。Usage:cell-registry buildCellWithSurface。\n */\nexport function FieldSurfaceSizeProvider({\n  size,\n  children,\n}: {\n  size: FieldSize\n  children: React.ReactNode\n}): React.ReactElement {\n  return React.createElement(FieldSurfaceSizeContext.Provider, { value: size }, children)\n}\n\n/**\n * Table-cell 可編輯訊號(2026-07-08 user 拍板)— 獨立於 FieldSurfaceContext / FieldSurfaceSizeContext\n * 的純 boolean context,由 host(DataTable cell registry)注入該 cell 是否可編輯,讓 useFieldEmptyDisplay\n * 分流「可編輯 cell 空 view → 空白」vs「不可編輯 cell 空 view → '-'」。\n * value = boolean primitive(stable when unchanged),不破壞 cell memo identity(同 TableScrollContext /\n * FieldSurfaceSizeContext L119-121 canonical);絕不污染 FieldContext(useFieldContext() 在 cell 內仍 null)。\n */\nconst FieldSurfaceEditableContext = React.createContext<boolean>(false)\n\nexport function FieldSurfaceEditableProvider({\n  isEditable,\n  children,\n}: {\n  isEditable: boolean\n  children: React.ReactNode\n}): React.ReactElement {\n  return React.createElement(FieldSurfaceEditableContext.Provider, { value: isEditable }, children)\n}\n\n/**\n * 空值顯示分流(2026-07-08 user 拍板,verbatim「...都用\"-\"...我從頭到尾哪裡有說要用全形的」):\n *\n * | 情境                                           | 空值顯示 |\n * |------------------------------------------------|----------|\n * | table-cell **可編輯** 的 view 靜止態        | **空白 `''`**(不佔位,affordance = hover outline)|\n * | table-cell **不可編輯**(readonly cell)        | **半形 `-`** |\n * | standalone view / readonly / form / toolbar | **半形 `-`** |\n *\n * 收斂式:`surface==='table-cell' && isEditable ? '' : EMPTY_DISPLAY`。\n * 可編輯 form / edit 輸入框走 native placeholder(不經此 hook)。boolean → unchecked / disabled →\n * 同上文字 + text-fg-disabled(M24),各控件自理。\n * 世界級對照:table-cell blank = MUI X / AG Grid / Ant core / Notion / Airtable grid 域共識;\n * 非 table `-` = Ant ProTable `columnEmptyText`(見 field-wrapper.tsx EMPTY_DISPLAY 註)。\n * SSOT 條文 → field-controls.spec.md「null / undefined 值」;全 Field family view/readonly/disabled\n * 空值渲染必經此 hook,禁直接引 EMPTY_DISPLAY 常數(genre 分流會漏)。\n */\nexport function useFieldEmptyDisplay(): string {\n  const surface = useFieldSurface()\n  const isEditable = React.useContext(FieldSurfaceEditableContext)\n  return surface === 'table-cell' && isEditable ? '' : EMPTY_DISPLAY\n}\n\n/**\n * 空值符號「-」顏色分流(2026-07-09 user 拍板 verbatim「「-」代表的是不可編輯只拿來供檢視的值\n * 所以應該跟readonly 的value同樣顏色吧」):\n *\n * 「-」是「不可編輯、供檢視的值」→ 同 readonly value 色 = `text-foreground`\n * (field-wrapper.tsx base `text-foreground`),**非** `text-fg-muted`(muted 是「可編輯 placeholder\n * 提示」的裝飾語意;空值符號不是提示、是被檢視的值狀態)。\n * disabled 態維持 `text-fg-disabled`(M24 disabled 顯著性 > foreground/muted,不可被蓋)。\n *\n * SSOT:全 Field family view/readonly/disabled 空值 span 消費此 helper,傳入已 resolve 的\n * resolvedMode。純函式(非 hook)—— resolvedMode 已由 useResolvedFieldMode 解析(含控件自身\n * disabled prop,context hook 讀不到);故以 resolvedMode 為入參,可條件呼叫、不受 Rules of Hooks 限制。\n * 世界級對照:Ant read-only / Carbon read-only value = 正常前景色;placeholder 才 muted。\n */\nexport function fieldEmptyColorClass(resolvedMode: FieldMode): string {\n  return resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-foreground'\n}\n"],"names":[],"mappings":";;AA4DO,MAAM,eAAe,MAAM,cAAwC,IAAI;AAGvE,SAAS,kBAA4C;AAC1D,SAAO,MAAM,WAAW,YAAY;AACtC;AAcA,MAAM,sBAAsB,MAAM,cAAmC,IAAI;AAYlE,SAAS,kBAAgC;AAC9C,QAAM,aAAa,MAAM,WAAW,mBAAmB;AACvD,MAAI,WAAY,QAAO;AACvB,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,UAAO,qCAAU,YAAW;AAC9B;AAcO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AACF,GAGuB;AACrB,SAAO,MAAM,cAAc,oBAAoB,UAAU,EAAE,OAAO,QAAA,GAAW,QAAQ;AACvF;AAgBA,MAAM,qBAAqB,MAAM,cAAuB,KAAK;AAEtD,SAAS,sBAA+B;AAC7C,SAAO,MAAM,WAAW,kBAAkB;AAC5C;AAEO,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AACF,GAGuB;AACrB,SAAO,MAAM,cAAc,mBAAmB,UAAU,EAAE,OAAO,YAAA,GAAe,QAAQ;AAC1F;AAWA,MAAM,0BAA0B,MAAM,cAAgC,IAAI;AAQnE,SAAS,qBAAmD,UAAqB,UAAiB;AACvG,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,QAAM,cAAc,MAAM,WAAW,uBAAuB;AAQ5D,QAAM,cAAc,YAAY,SAAS,eAAgB,SAAS,OAAyB;AAC3F,SAAQ,YAAY,eAAe,aAAa,qCAAU,SAA2B,eAAkC;AACzH;AAQO,SAAS,8BAA8B,WAAoC;AAChF,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,QAAM,WAAW,qCAAU;AAC3B,QAAM,UAAU,MAAM;AACpB,QAAiB,SAAU,UAAS,SAAS;AAAA,EAC/C,GAAG,CAAC,WAAW,QAAQ,CAAC;AAC1B;AAQO,SAAS,yBAAyB,cAAwC;AAC/E,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,SAAO,iBAAgB,qCAAU,aAAY;AAC/C;AAcO,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF,GAIc;AACZ,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,MAAI,KAAM,QAAO;AACjB,OAAK,aAAY,qCAAU,eAAc,KAAM,QAAO;AACtD,MAAI,qCAAU,KAAM,QAAO,SAAS;AACpC,MAAI,SAAU,QAAO;AACrB,SAAO;AACT;AAQO,SAAS,wBAAwB,aAAiE;AACvG,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,SAAO,gBAAe,qCAAU,YAAW;AAC7C;AAMO,SAAS,wBAAwB,WAA8B;AACpE,QAAM,WAAW,MAAM,WAAW,YAAY;AAC9C,SAAO,QAAQ,SAAS,OAAM,qCAAU,YAAW;AACrD;AAMO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA;AACF,GAGuB;AACrB,SAAO,MAAM,cAAc,wBAAwB,UAAU,EAAE,OAAO,KAAA,GAAQ,QAAQ;AACxF;AASA,MAAM,8BAA8B,MAAM,cAAuB,KAAK;AAE/D,SAAS,6BAA6B;AAAA,EAC3C;AAAA,EACA;AACF,GAGuB;AACrB,SAAO,MAAM,cAAc,4BAA4B,UAAU,EAAE,OAAO,WAAA,GAAc,QAAQ;AAClG;AAmBO,SAAS,uBAA+B;AAC7C,QAAM,UAAU,gBAAA;AAChB,QAAM,aAAa,MAAM,WAAW,2BAA2B;AAC/D,SAAO,YAAY,gBAAgB,aAAa,KAAK;AACvD;AAgBO,SAAS,qBAAqB,cAAiC;AACpE,SAAO,iBAAiB,aAAa,qBAAqB;AAC5D;"}

package/dist/components/Field/field-edit-keys.d.ts

@@ -0,0 +1,21 @@
+import type * as React from 'react';
+export interface EditSettleKeyOptions {
+    /** Enter(非組字中)→ 呼叫。已 preventDefault。 */
+    onCommit: (e: React.KeyboardEvent) => void;
+    /** Escape(非組字中)→ 呼叫。已 preventDefault。 */
+    onCancel: (e: React.KeyboardEvent) => void;
+    /**
+     * Enter 是否 = commit。預設 true。
+     * 多行(Textarea)場景設 false:plain Enter = 換行(不攔,交還 Textarea 預設),
+     * Cmd/Ctrl+Enter = commit(**本 handler 內建**,consumer 不需另接 capture handler),
+     * 其餘 commit 走 blur。
+     */
+    commitOnEnter?: boolean;
+}
+/**
+ * edit-in-place 鍵盤結算 handler(SSOT)。IME 組字 guard 為第一道:中文/日文選字的 Enter 是
+ * 組字確認、Esc 是取消組字,非 commit/cancel 意圖 —— 無 guard 會誤送半截組字。`isComposing` 為主,
+ * `keyCode === 229` 補 Safari / 舊 Chrome(該分支不 emit isComposing)。
+ */
+export declare function makeEditSettleKeyHandler(opts: EditSettleKeyOptions): (e: React.KeyboardEvent) => void;
+//# sourceMappingURL=field-edit-keys.d.ts.map

package/dist/components/Field/field-edit-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-edit-keys.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field-edit-keys.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAA;AAEnC,MAAM,WAAW,oBAAoB;IACnC,wCAAwC;IACxC,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAA;IAC1C,yCAAyC;IACzC,QAAQ,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAA;IAC1C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,oBAAoB,IAEzD,GAAG,KAAK,CAAC,aAAa,UAiB/B"}

package/dist/components/Field/field-edit-keys.js

@@ -0,0 +1,19 @@
+function makeEditSettleKeyHandler(opts) {
+  const commitOnEnter = opts.commitOnEnter ?? true;
+  return (e) => {
+    if (e.nativeEvent.isComposing || e.nativeEvent.keyCode === 229) return;
+    if (e.key === "Escape") {
+      e.preventDefault();
+      opts.onCancel(e);
+    } else if (e.key === "Enter") {
+      if (commitOnEnter || e.metaKey || e.ctrlKey) {
+        e.preventDefault();
+        opts.onCommit(e);
+      }
+    }
+  };
+}
+export {
+  makeEditSettleKeyHandler
+};
+//# sourceMappingURL=field-edit-keys.js.map

package/dist/components/Field/field-edit-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-edit-keys.js","sources":["../../../src/components/Field/field-edit-keys.ts"],"sourcesContent":["// @internal — DS-internal 單元(edit-in-place 鍵盤結算 SSOT);consumer 用 InlineEdit / DataTable,不直用。\n// ── 消費的 SSOT ──\n// (本檔即是被消費的 SSOT;不 import 其他 canonical)\n//\n// ── 為什麼存在 ──\n// 「就地編輯(edit-in-place)」的鍵盤結算契約 —— Enter=commit / Esc=cancel + **中文 IME 組字 guard** ——\n// 原本在兩處各寫一份、且**已分歧**:\n//   - DataTable `cell-registry.tsx` makeKeyHandler:有 IME guard(2026-07-05 D4 fix)\n//   - InlineEdit `inline-edit.tsx`:**無 IME guard** → 中文使用者按 Enter 確認選字時,會把半截組字\n//     提交並退出 edit(Esc 則丟棄整個 draft)= latent bug。\n// 2026-07-09 edit-in-place SSOT 研究(6-agent + 世界級)結論:**不抽大的共用狀態機**(兩 host 的 draft\n// 擁有權 / state locus / focus model 根本不同,強抽違 M21 + 破壞表格虛擬捲動效能),**但抽這一片**——\n// 唯一在兩處逐字重複、且現在分歧、且不碰 draft/state/focus 的純鍵盤結算邏輯。抽出後 InlineEdit 順手\n// 得到 IME guard(修 bug)。對齊世界級「controls + 型別 registry 共用,orchestration 各自」split。\n//\n// **不含**:blur=commit(各 host 的 blur 語意不同)、finalizedRef 單次結算 guard(InlineEdit 專屬,\n// 防 blur-after-Enter 雙 commit)、draft 管理(host-specific)。這些刻意留在各 host。\n//\n// ── 新增 edit-in-place host 的規矩(2026-07-10)──\n// 之後任何新的「就地編輯」host(第 3 個以上),**Enter/Esc/Cmd·Ctrl+Enter/IME 組字結算一律消費本\n// helper**,禁再手刻 `isComposing || keyCode===229` guard 或 Enter/Esc dispatch —— 現有 3 host\n// (cell string / cell number / InlineEdit multiline)已全數收斂於此,手刻 = drift 回頭路(正是 2026-07\n// 之前 InlineEdit 漏 IME guard 的病根)。單行傳 `commitOnEnter` 預設;多行傳 `commitOnEnter:false`\n// (本 helper 內建 Cmd/Ctrl+Enter=commit)。此為文件層 SSOT 規矩,不另設 hook(host 少 + 避治理膨脹)。\n\nimport type * as React from 'react'\n\nexport interface EditSettleKeyOptions {\n  /** Enter(非組字中)→ 呼叫。已 preventDefault。 */\n  onCommit: (e: React.KeyboardEvent) => void\n  /** Escape(非組字中)→ 呼叫。已 preventDefault。 */\n  onCancel: (e: React.KeyboardEvent) => void\n  /**\n   * Enter 是否 = commit。預設 true。\n   * 多行(Textarea)場景設 false:plain Enter = 換行(不攔,交還 Textarea 預設),\n   * Cmd/Ctrl+Enter = commit(**本 handler 內建**,consumer 不需另接 capture handler),\n   * 其餘 commit 走 blur。\n   */\n  commitOnEnter?: boolean\n}\n\n/**\n * edit-in-place 鍵盤結算 handler(SSOT)。IME 組字 guard 為第一道:中文/日文選字的 Enter 是\n * 組字確認、Esc 是取消組字,非 commit/cancel 意圖 —— 無 guard 會誤送半截組字。`isComposing` 為主,\n * `keyCode === 229` 補 Safari / 舊 Chrome(該分支不 emit isComposing)。\n */\nexport function makeEditSettleKeyHandler(opts: EditSettleKeyOptions) {\n  const commitOnEnter = opts.commitOnEnter ?? true\n  return (e: React.KeyboardEvent) => {\n    // IME 組字 guard(見檔頭)—— 對齊 cell-registry 既有寫法 + data-table nav handler。\n    if (e.nativeEvent.isComposing || (e.nativeEvent as { keyCode?: number }).keyCode === 229) return\n    if (e.key === 'Escape') {\n      e.preventDefault()\n      opts.onCancel(e)\n    } else if (e.key === 'Enter') {\n      // 單行(commitOnEnter):Enter = commit。\n      // 多行(commitOnEnter:false):plain Enter = 換行(不攔,交還 Textarea 預設),\n      //   Cmd/Ctrl+Enter = commit —— 此契約由本 SSOT 擁有,3 個 consumer\n      //   (cell string/number + InlineEdit multiline)不再各自手刻 capture handler。\n      if (commitOnEnter || e.metaKey || e.ctrlKey) {\n        e.preventDefault()\n        opts.onCommit(e)\n      }\n    }\n  }\n}\n"],"names":[],"mappings":"AA8CO,SAAS,yBAAyB,MAA4B;AACnE,QAAM,gBAAgB,KAAK,iBAAiB;AAC5C,SAAO,CAAC,MAA2B;AAEjC,QAAI,EAAE,YAAY,eAAgB,EAAE,YAAqC,YAAY,IAAK;AAC1F,QAAI,EAAE,QAAQ,UAAU;AACtB,QAAE,eAAA;AACF,WAAK,SAAS,CAAC;AAAA,IACjB,WAAW,EAAE,QAAQ,SAAS;AAK5B,UAAI,iBAAiB,EAAE,WAAW,EAAE,SAAS;AAC3C,UAAE,eAAA;AACF,aAAK,SAAS,CAAC;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AACF;"}

package/dist/components/Field/field-types.d.ts

@@ -1,5 +1,24 @@
-export type FieldMode = 'edit' | 'display' | 'readonly' | 'disabled';
-export type FieldVariant = 'default' | 'bare' | 'naked';
-/** CommandList 最小高度 = field-height × rows + 16px(CommandGroup py-2 上下 padding） */
+export type FieldMode = 'edit' | 'view' | 'readonly' | 'disabled';
+export type FieldVariant = 'default';
+/**
+ * @internal Substrate union — 公開 FieldVariant + `naked`(cell-as-input)。
+ * 2026-07-14 API 策展 E(user 拍板「全部收窄」):naked 從公開 union 拆出,型別層防 consumer
+ * `<Input variant="naked">` 繞過 canonical chrome / focus。內部實作(field-wrapper cva、各控件
+ * useResolvedFieldVariant 分支)吃本型別;唯一合法 naked 傳入點 = DataTable cell-registry
+ * (field-controls.spec.md「軸二 variant」明文)。
+ */
+export type FieldVariantInternal = FieldVariant | 'naked';
+/**
+ * @internal 型別層 naked 通道 — 把 Field control 的公開 `variant?: FieldVariant` widen 為
+ * FieldVariantInternal(純型別、零 runtime;元件 runtime 本就支援 naked)。消費者:DataTable
+ * cell-registry(naked 起點)+ PeoplePicker(wrapper forward 給 Select / Combobox,M30 全 surface
+ * forward)。保留原 call signature 與 statics(`Pick<C, keyof C>`),widen 方向與函式參數
+ * contravariance 相容,故單次 assertion 可過(非 `as unknown as` 雙跳,型別仍受檢)。
+ */
+export type WithFieldVariantInternal<C> = C extends (props: infer P) => infer R ? ((props: Omit<P, 'variant'> & {
+    variant?: FieldVariantInternal;
+}) => R) & Pick<C, keyof C> : never;
+export type FieldWidth = 'fill' | 'hug';
+/** @internal — CommandList 最小高度 = field-height × rows + 16px(CommandGroup py-2 上下 padding);Command/Select 內部 helper,consumer 不直接 import。root barrel 排除(subpath 仍可用)。 */
 export declare function getMenuListMinHeight(size: string, rows?: number): string;
 //# sourceMappingURL=field-types.d.ts.map

package/dist/components/Field/field-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field-types.ts"],"names":[],"mappings":"AAkBA,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;AAgBpE,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAA;AAYvD,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,MAAM,CAG3E"}
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field-types.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAA;AA6BjE,MAAM,MAAM,YAAY,GAAG,SAAS,CAAA;AAEpC;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,YAAY,GAAG,OAAO,CAAA;AAEzD;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GAC3E,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;CAAE,KAAK,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,GAC1F,KAAK,CAAA;AAgBT,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAA;AAYvC,wKAAwK;AACxK,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,MAAM,CAG3E"}

package/dist/components/Field/field-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"field-types.js","sources":["../../../src/components/Field/field-types.ts"],"sourcesContent":["// ── Field Mode ───────────────────────────────────────────────────────────────\n//\n// 4 模式 canonical(2026-05-05 expand to 4):\n//   edit     — 一般可編輯 input(預設 variant:border + bg)\n//   display  — **純展示**(無 input chrome / 無互動 affordance);語意「這是 read-only 內容,展示給人看」\n//              對齊 Carbon read-only / PatternFly inline-edit hidden-input / Cloudscape display-mode\n//   readonly — input chrome + non-editable(保留 underline / border subtle 給 a11y signal「這是 input 但鎖了」)\n//              對齊 Carbon read-only-with-underline。差異:`display` 完全無 chrome;`readonly` 保留 input affordance signal\n//   disabled — input chrome + disabled state(灰底,不可互動,語意「不適用」)\n//\n// `display` vs `readonly` 判別:\n//   - 該位置語意上是「純展示資料」(如 DataTable cell read mode / NameCard meta) → `display`\n//   - 該位置是「表單欄位但目前不可改」(如 form 鎖部分欄位) → `readonly`\n//\n// World-class refs(M22 verified):\n//   Carbon: https://carbondesignsystem.com/patterns/read-only-states-pattern/\n//   PatternFly: https://www.patternfly.org/components/inline-edit/design-guidelines/\n//   Cloudscape: https://cloudscape.design/patterns/general/disabled-and-read-only-states/\nexport type FieldMode = 'edit' | 'display' | 'readonly' | 'disabled'\n\n// ── Field Variant ────────────────────────────────────────────────────────────\n//\n// 視覺外殼(對齊主流 DS canonical M22 verified 2026-05-05):\n//   - Ant Design `Input variant`: 'outlined' | 'borderless' | 'filled' | 'underlined'\n//   - MUI `TextField variant`: 'outlined' | 'standard' | 'filled'\n//\n//   default — 含 border + bg(一般 form input,= Ant outlined / MUI outlined)\n//   bare    — 透明 variant,hover/focus 才 reveal inner border(VS Code/Figma toolbar inline editing idiom,\n//             ≈ Ant borderless,但保留 hover/focus reveal)\n//   naked   — 完全無 chrome / 無 focus ring on wrapper(cell-as-input — host cell 提供 border + focus visual)\n//             對齊 Airtable / Notion / Excel cell editing — cell 本身扮演 input frame,內無 wrapper\n//\n// 透傳機制:Field 透過 FieldContext.variant 一次宣告,所有 child Field control 自動繼承。\n// per-control prop override 可覆寫 context。\nexport type FieldVariant = 'default' | 'bare' | 'naked'\n\n// ── Menu List Min Height ─────────────────────────────────────────────────────\n// SelectMenu / Select / Combobox 共用的 CommandList minHeight 計算。\n// 確保空狀態有足夠高度讓 Empty 垂直置中(有框容器 → 置中原則)。\n\nconst FIELD_HEIGHT_TOKEN: Record<string, string> = {\n  sm: 'var(--field-height-sm)',\n  md: 'var(--field-height-md)',\n  lg: 'var(--field-height-lg)',\n}\n\n/** CommandList 最小高度 = field-height × rows + 16px(CommandGroup py-2 上下 padding） */\nexport function getMenuListMinHeight(size: string, rows: number = 3): string {\n  const token = FIELD_HEIGHT_TOKEN[size] ?? FIELD_HEIGHT_TOKEN.md\n  return `calc(${token} * ${rows} + 16px)`\n}\n\n"],"names":[],"mappings":"AAwCA,MAAM,qBAA6C;AAAA,EACjD,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAGO,SAAS,qBAAqB,MAAc,OAAe,GAAW;AAC3E,QAAM,QAAQ,mBAAmB,IAAI,KAAK,mBAAmB;AAC7D,SAAO,QAAQ,KAAK,MAAM,IAAI;AAChC;"}
+{"version":3,"file":"field-types.js","sources":["../../../src/components/Field/field-types.ts"],"sourcesContent":["// ── Field Mode ───────────────────────────────────────────────────────────────\n//\n// 4 模式 canonical(2026-05-05 expand;2026-07-16 round16 `display`→`view` 更名 + Model A 幾何):\n//   edit     — 一般可編輯 input(預設 variant:border + bg)\n//   view     — **純展示值(非表單)**;語意「要呈現給人看的值本體」(cell / InlineEdit / 詳情)。\n//              **Model A**:view = edit 幾何減 chrome(透明 bg/border,**保留 px 內距 + 高度**)→ read↔edit\n//              零跳(view 與 edit 同一顆控件、只差 chrome)。對齊 Atlassian inline-edit(read=edit 幾何)\n//              + Bootstrap `.form-control-plaintext`(留 padding)。詳 field-controls.spec.md「軸一 view mode」。\n//   readonly — input chrome + non-editable(bg-readonly + a11y ring「這是 input 但鎖了」);表單語境、值仍算數可選取\n//   disabled — input chrome + disabled state(灰底,不可互動,不送出,語意「目前不適用」);表單專屬\n//\n// `view` vs `readonly` 判別:\n//   - 「純展示值、非表單」(DataTable cell / InlineEdit view / ProfileCard meta) → `view`\n//   - 「表單欄位但目前不可改、值仍送出」(form 鎖部分欄位) → `readonly`\n//\n// 命名(命名 3-test 全過):MUI X cellMode=view / Atlassian readVIEW 字根 / 與 edit 成對。\n// World-class refs(M22 verified):\n//   Carbon: https://carbondesignsystem.com/patterns/read-only-states-pattern/\n//   PatternFly: https://www.patternfly.org/components/inline-edit/design-guidelines/\n//   Cloudscape: https://cloudscape.design/patterns/general/disabled-and-read-only-states/\nexport type FieldMode = 'edit' | 'view' | 'readonly' | 'disabled'\n\n// ── Field Variant ────────────────────────────────────────────────────────────\n//\n// 視覺外殼(公開 1 + internal 1;2026-07-09 user 拍板退役 `bare`,2026-07-14 API 策展 E user 拍板\n// 「全部收窄」把 naked 從公開 union 拆出 — 見下方 note):\n//   default — 含 border + bg(一般 form input,= Ant outlined / MUI outlined)。公開 FieldVariant 唯一值\n//   naked   — @internal(FieldVariantInternal)。cell-as-input(host cell substrate)。edit×naked 自畫\n//             border-based state machine(rest → hover → focus-within:border-primary → error 紅框);\n//             view×naked 用 transparent border,由 host cell 提供視覺邊框。\n//             對齊 Airtable / Notion / Excel cell editing。唯一合法消費者 = DataTable cell-registry\n//             (field-controls.spec.md「軸二 variant」明文)— consumer 直傳 `<Input variant=\"naked\">`\n//             會繞過 canonical chrome / focus,故公開型別排除\n//\n// **`bare` 退役紀錄(2026-07-09)**:原「透明外殼、hover/focus 才顯 border」variant,2026-05-05 加入時\n//   宣稱用途 = toolbar inline editing(FileViewer zoom / config toolbar)。實測全 repo(DS + apps + stories)\n//   `variant=\"bare\"` **零真實 JSX 消費者**:唯一出現處是一個 ❌ 反例 story + 過時註解(含錯誤宣稱 FileViewer\n//   縮放用 bare — 實為 `<Input size=\"sm\" autoWidth>` default variant)。其目標場景已被 default(toolbar,\n//   對齊「邊框給互動元素、輸入框就該有邊框」原則)與 naked(cell-as-input)覆蓋 → 純冗餘,移除。\n//   ⚠️ 注意:被大量 import 的 `bareInputStyles` 常數(field-wrapper.tsx)是**內層 <input> 的重置樣式**\n//   (透明底 / 無 border / 繼承字體),與本 variant 同名但不同物,**保留不動**(8 個控件共用)。\n//\n// 透傳機制:Field 透過 FieldContext.variant 一次宣告,所有 child Field control 自動繼承。\n// per-control prop override 可覆寫 context。\n//\n// Benchmark(M22 verified 2026-07-09):Ant `Input variant` 有 borderless(https://ant.design/components/input/)\n//   → 「無邊框輸入框」概念世界級合法;但 Material M3 只有 filled/outlined 無無邊框變體\n//   (https://m3.material.io/components/text-fields/guidelines),MUI standard(underline)已 deprecated。\n//   我們的取捨:無真實消費場景 → 不保留純預留 variant(對齊自家「消費既有、不憑空造」原則)。\nexport type FieldVariant = 'default'\n\n/**\n * @internal Substrate union — 公開 FieldVariant + `naked`(cell-as-input)。\n * 2026-07-14 API 策展 E(user 拍板「全部收窄」):naked 從公開 union 拆出,型別層防 consumer\n * `<Input variant=\"naked\">` 繞過 canonical chrome / focus。內部實作(field-wrapper cva、各控件\n * useResolvedFieldVariant 分支)吃本型別;唯一合法 naked 傳入點 = DataTable cell-registry\n * (field-controls.spec.md「軸二 variant」明文)。\n */\nexport type FieldVariantInternal = FieldVariant | 'naked'\n\n/**\n * @internal 型別層 naked 通道 — 把 Field control 的公開 `variant?: FieldVariant` widen 為\n * FieldVariantInternal(純型別、零 runtime;元件 runtime 本就支援 naked)。消費者:DataTable\n * cell-registry(naked 起點)+ PeoplePicker(wrapper forward 給 Select / Combobox,M30 全 surface\n * forward)。保留原 call signature 與 statics(`Pick<C, keyof C>`),widen 方向與函式參數\n * contravariance 相容,故單次 assertion 可過(非 `as unknown as` 雙跳,型別仍受檢)。\n */\nexport type WithFieldVariantInternal<C> = C extends (props: infer P) => infer R\n  ? ((props: Omit<P, 'variant'> & { variant?: FieldVariantInternal }) => R) & Pick<C, keyof C>\n  : never\n\n// ── Field Width ──────────────────────────────────────────────────────────────\n//\n// 寬度軸(2026-07-08 user 拍板,正交於 mode / variant / size — 只改寬度,chrome 與互動不變):\n//   fill — `w-full` 填滿容器(default;form 直欄對齊 / DataTable cell 滿格)\n//   hug  — `w-fit max-w-full` 依內容收縮:value 寬 + 各 slot 元素寬 + gap + field 內 padding\n//          (detail pane inline metadata / toolbar 內 field 場景)\n//\n// Benchmark(M22 verified):\n//   shadcn v4 SelectTrigger 預設 `w-fit`\n//     https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/new-york-v4/ui/select.tsx\n//   Radix Select Trigger intrinsic sizing\n//     https://www.radix-ui.com/primitives/docs/components/select\n//\n// SSOT:fieldWrapperStyles `width` variant(field-wrapper.tsx)+ field-controls.spec.md「寬度軸」。\nexport type FieldWidth = 'fill' | 'hug'\n\n// ── Menu List Min Height ─────────────────────────────────────────────────────\n// SelectMenu / Select / Combobox 共用的 CommandList minHeight 計算。\n// 確保空狀態有足夠高度讓 Empty 垂直置中(有框容器 → 置中原則)。\n\nconst FIELD_HEIGHT_TOKEN: Record<string, string> = {\n  sm: 'var(--field-height-sm)',\n  md: 'var(--field-height-md)',\n  lg: 'var(--field-height-lg)',\n}\n\n/** @internal — CommandList 最小高度 = field-height × rows + 16px(CommandGroup py-2 上下 padding);Command/Select 內部 helper,consumer 不直接 import。root barrel 排除(subpath 仍可用)。 */\nexport function getMenuListMinHeight(size: string, rows: number = 3): string {\n  const token = FIELD_HEIGHT_TOKEN[size] ?? FIELD_HEIGHT_TOKEN.md\n  return `calc(${token} * ${rows} + 16px)`\n}\n\n"],"names":[],"mappings":"AA2FA,MAAM,qBAA6C;AAAA,EACjD,IAAI;AAAA,EACJ,IAAI;AAAA,EACJ,IAAI;AACN;AAGO,SAAS,qBAAqB,MAAc,OAAe,GAAW;AAC3E,QAAM,QAAQ,mBAAmB,IAAI,KAAK,mBAAmB;AAC7D,SAAO,QAAQ,KAAK,MAAM,IAAI;AAChC;"}

package/dist/components/Field/field-wrapper.d.ts

@@ -1,17 +1,35 @@
 export declare const fieldWrapperStyles: (props?: ({
-    mode?: "display" | "disabled" | "edit" | "readonly" | null | undefined;
-    variant?: "default" | "bare" | "naked" | null | undefined;
+    mode?: "view" | "disabled" | "edit" | "readonly" | null | undefined;
+    variant?: "default" | "naked" | null | undefined;
     size?: "sm" | "md" | "lg" | null | undefined;
+    width?: "fill" | "hug" | null | undefined;
+    error?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare const bareInputStyles: string;
 export declare const nakedCellRowModeAlign = "group-data-[row-mode=auto]/cell:items-start";
 export declare const nakedCellEditableDisplayHover = "hover:outline hover:outline-1 hover:outline-offset-[-1px] hover:outline-[var(--cell-hover-outline-color,var(--border-hover))]";
-export declare const EMPTY_DISPLAY = "\u2014";
+export declare const EMPTY_DISPLAY = "-";
 /**
- * 2026-05-14 I2 fix(per field-controls.spec.md contract (e) display typography canonical):
- * Field family display path bare-span helper — `sm/md → text-body` / `lg → text-body-lg`,
- * 跨 9 元件 display 視覺尺寸統一(user 抓 LinkInput 字體跟其他 Field 不一致 = SSOT 違反)。
+ * 2026-05-14 I2 fix(per field-controls.spec.md contract (e) view typography canonical):
+ * Field family view path bare-span helper — `sm/md → text-body` / `lg → text-body-lg`,
+ * 跨 9 元件 view 視覺尺寸統一(user 抓 LinkInput 字體跟其他 Field 不一致 = SSOT 違反)。
  * Consumer:LinkInput / Select / Combobox / DatePicker / TimePicker non-D-path bare-span 套此 class。
  */
 export declare const fieldDisplayTextClass: (size: "sm" | "md" | "lg") => string;
+/**
+ * 2026-07-16 round16 Model A(user GO):Field view mode 幾何 SSOT(= view×default compound 的
+ * 幾何部分,抽成 class helper 供 **InlineEdit 純值/標題路徑** 消費,避免 InlineEdit 自帶重複的
+ * geometry cva〔M17 消重〕)。
+ *
+ * 回傳「edit 幾何減 chrome」的排版盒:
+ *   - 水平:`px-[var(--field-px)]`(= edit 內距,靠 InlineEdit `-mx` 拉回欄左緣後,值落 edit 值位置)
+ *   - 單行:`min-h-[var(--field-height-N)]` N∈{sm,md,lg} + `items-center`(垂直置中於 field 高度,= edit 單行)
+ *   - 多行:`items-start` + `py-2`(頂對齊 + 上下內距,**= Textarea edit `py-2`**,textarea.tsx base;
+ *     read↔edit 零跳)。⚠️ py-2 與 Textarea 同值 = SSOT 契約,`scripts/inline-edit-view-geometry-invariant.mjs`
+ *     機械鎖(Textarea py 一改即紅)。
+ *
+ * 值-格式化路徑(Select→Tag / Date / avatar)**不用**此 helper —— 直接委派 `<Control mode="view">`,
+ * 幾何 + 內部間距皆由控件 view×default 提供(read=edit 同一顆 → 天生一致)。
+ */
+export declare const fieldViewGeometry: (size: "sm" | "md" | "lg", multiline?: boolean) => string;
 //# sourceMappingURL=field-wrapper.d.ts.map

package/dist/components/Field/field-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-wrapper.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field-wrapper.tsx"],"names":[],"mappings":"AAmBA,eAAO,MAAM,kBAAkB;;;;8EAsN9B,CAAA;AAID,eAAO,MAAM,eAAe,QAsBjB,CAAA;AAmBX,eAAO,MAAM,qBAAqB,gDAAgD,CAAA;AAsClF,eAAO,MAAM,6BAA6B,kIAAkI,CAAA;AAsB5K,eAAO,MAAM,aAAa,WAAM,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,KAAG,MACnB,CAAA"}
+{"version":3,"file":"field-wrapper.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field-wrapper.tsx"],"names":[],"mappings":"AAwBA,eAAO,MAAM,kBAAkB;;;;;;8EA+N9B,CAAA;AAID,eAAO,MAAM,eAAe,QAsBjB,CAAA;AAmBX,eAAO,MAAM,qBAAqB,gDAAgD,CAAA;AAsClF,eAAO,MAAM,6BAA6B,kIAAkI,CAAA;AA4B5K,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,KAAG,MACnB,CAAA;AAE9C;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,EAAE,YAAY,OAAO,KAAG,MAa/E,CAAA"}

package/dist/components/Field/field-wrapper.js

@@ -1,4 +1,5 @@
 import { cva } from "class-variance-authority";
+import { cn } from "../../lib/utils.js";
 const fieldWrapperStyles = cva(
   [
     // K10 fix(2026-05-04):`group/field` 讓 inner placeholder/text 可透過 `group-data-[field-mode=...]/field:` 變體
@@ -14,7 +15,9 @@ const fieldWrapperStyles = cva(
     // 修一處全 Field family 跟動(Input/Select/Combobox/DatePicker/TimePicker/LinkInput/
     // Textarea/NumberInput/PeoplePicker)— 對齊 M17/M19/M23 一處 SSOT + data-table.spec.md:233
     // 「禁硬裁無 ellipsis」DS canonical + MUI X DataGrid / Ant Table column.ellipsis 共識。
-    "inline-flex items-center w-full min-w-0 rounded-md",
+    // 2026-07-08 width 軸:`w-full` 從 base 移入 `width` variant(fill = 原行為 default,
+    // 零回歸;hug = w-fit 依內容收縮)。詳 field-controls.spec.md「寬度軸(width: fill / hug)」。
+    "inline-flex items-center min-w-0 rounded-md",
     "text-foreground font-normal",
     "transition-colors duration-150"
   ],
@@ -22,26 +25,49 @@ const fieldWrapperStyles = cva(
     variants: {
       mode: {
         edit: "",
-        display: "",
+        view: "",
         readonly: "",
         disabled: ""
       },
       variant: {
         // default — 完整 Field wrapper chrome(bg-surface、明顯 border、hover/focus 回饋)
         default: "",
-        // bare — 透明 variant,hover / focus 才出現 border。適用 Toolbar inline editing
-        // (FileViewer zoom input / chart config / rich text toolbar number input 等)。
-        // 世界級對照:VS Code settings / Figma toolbar number / Notion prop input。
-        bare: "",
-        // naked — 完全無 variant,hover/focus 也不出 border。適用 cell-as-input
-        // (host cell 自管 border + focus visual,內部 input 純文字承載)。
+        // naked — cell-as-input(Notion / Airtable / Excel canonical)。**edit×naked 自畫** border +
+        // hover:border-border-hover + focus-within:border-primary + error 紅框(v14 border-based state
+        // machine,見下方 compoundVariants L182-196);view×naked 用 transparent
+        // border 由 host cell 提供視覺邊框,內部 input 純文字承載。
         // 世界級對照:Airtable / Notion / Excel / Google Sheets cell editing。
+        // (2026-07-09 `bare` variant 已退役 — 見 field-types.ts FieldVariant 註解;
+        //  被 import 的 `bareInputStyles` 常數是內層 input 重置樣式、與此不同物、保留。)
         naked: ""
       },
       size: {
-        sm: "text-body h-field-sm px-3 gap-2",
-        md: "text-body h-field-md px-3 gap-2",
-        lg: "text-body-lg h-field-lg px-3 gap-2"
+        sm: "text-body h-field-sm px-[var(--field-px)] gap-2",
+        md: "text-body h-field-md px-[var(--field-px)] gap-2",
+        lg: "text-body-lg h-field-lg px-[var(--field-px)] gap-2"
+      },
+      // width(2026-07-08 user 拍板,正交軸):寬度軸 — 只改寬度,chrome / hover / focus /
+      // error / mode compoundVariants 全部不動(user verbatim「框線和互動和樣式都不變,
+      // 只有寬度有變而已 … 把 field 和 value 的寬度都改成 hug」)。
+      //   fill(default)— `w-full` 填滿容器 = 與移軸前 base 完全等價(零回歸不變量)
+      //   hug — `w-fit` 依內容收縮:value 寬 + 各 slot 元素寬 + gap + field 內 padding;
+      //         `max-w-full` 保證窄容器不溢出(min-w-0 保留,仍可 truncate)
+      // Benchmark(M22):shadcn v4 SelectTrigger 預設 `w-fit`
+      //   https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/new-york-v4/ui/select.tsx
+      //   Radix Select Trigger intrinsic sizing https://www.radix-ui.com/primitives/docs/components/select
+      width: {
+        fill: "w-full",
+        hug: "w-fit max-w-full"
+      },
+      // error(2026-07-04 Q1 拍板,SSOT 集中):原散在各控件的 error border classes 因
+      // focus-within:!border-primary(!important)被蓋 = dead code(聚焦永遠藍)。
+      // Benchmark 實查證偽舊宣稱:MUI(紅框加粗)/ Ant(紅框紅 glow)/ Polaris(紅 border
+      // + 獨立藍 focus ring)聚焦時 error 紅皆保留;唯一切藍的 Carbon 靠 in-field 紅 icon 補償。
+      // DS 邊框是唯一 error 載體 → error 勝 focus 的「顏色」通道。錯誤清除(edit-clears-error,
+      // useFormValidation)後自然回 focus 藍。
+      error: {
+        true: "",
+        false: ""
       }
     },
     // mode x variant 交叉:visual chrome 由 compoundVariants 決定
@@ -72,23 +98,42 @@ const fieldWrapperStyles = cva(
           // 副作用 — Ant 風「選後藍 / 取消灰」自動達成:
           //   - 選 option close popover → Radix focus return to trigger → focus-within fires → 藍
           //   - 點外取消 close popover → focus 移外 → focus-within 不 fire → 灰
-          "focus-within:!border-primary focus-within:hover:!border-primary",
+          //
+          // 2026-07-04 Q1 拍板修訂:「focus dominates everything」對 error 讓位(見 error variant
+          // 註解)— focus 藍只在 error:false compound(下方),error:true 走 error compound 紅。
           "data-[state=open]:border-border-hover"
         ]
       },
+      { mode: "edit", variant: "default", error: false, className: "focus-within:!border-primary focus-within:hover:!border-primary" },
       {
-        mode: "display",
+        // 2026-07-16 round16 Model A(user GO,推翻 2026-05-13 Path Ⅰ 的 `!px-0 !py-0`):
+        // view×default = **edit 幾何減 chrome** — 保留 size 軸的 `px-[var(--field-px)]` + `h-field-*`,
+        // 只拔 border/bg(透明)。理由 = view 用在 cell/inline-edit/詳情,要對齊的是「edit 的值位置」
+        // (非 label 左緣),故水平垂直都留 → view 與 edit 同一顆控件、只差 chrome → read↔edit 零跳。
+        // 世界級對照:Atlassian inline-edit(read=edit 幾何,靠容器負邊距對齊)+ Bootstrap
+        // `.form-control-plaintext`(`padding: $input-padding-y 0` 留 padding);我們比 Bootstrap 更徹底
+        // (連水平 px 也留),因用例是 align-to-edit 非 align-to-label。詳 field-controls.spec.md「軸一 view mode」
+        // + planning/2026-07-15-inline-edit-field-mode-remediation.md round16。
+        // ⚠️ view×default ≠ view×naked:naked = bare(cell substrate,host TD 給 padding);default = 留幾何。
+        mode: "view",
         variant: "default",
-        // 2026-05-13 Q3 Path Ⅰ(user 拍板 Path Ⅰ 全 zero chrome + codex V2 verdict + field-controls.spec.md (d)):
-        // default display = zero chrome — !px-0 !py-0 override size token 的 px-3,跟 Select / Combobox
-        // / DatePicker / TimePicker / LinkInput non-D-path bare-span idiom 一致(Carbon read-only / Stripe
-        // display / Notion property / Polaris readonly TextField 全 zero chrome)。
-        className: "bg-transparent border border-transparent !px-0 !py-0"
+        className: "bg-transparent border border-transparent"
       },
       {
         mode: "readonly",
         variant: "default",
-        className: "bg-disabled border border-transparent"
+        // 2026-07-09 A11y fix(WCAG 2.4.7 Focus Visible):readonly **有值** 渲染 native `<input readOnly>`
+        // = 可 Tab 聚焦、可選取/複製,但原 compound 無任何 focus 指示 → 鍵盤使用者聚焦不可見 = 違反。
+        // 補 focus ring 採 **ring idiom**(`ring-2 ring-ring ring-offset-1`,與 Button/Checkbox/Tabs/
+        // Switch 同一套 focus-visible canonical;`--ring == --primary` semantic.css:334)而非 edit mode
+        // 的 `border-primary` idiom —— readonly 邊框 transparent 無可染;且 ring 語義 = 「可聚焦但非文字
+        // 輸入」(對齊 button/tab/checkbox 這類 focusable-非-text-entry 控件的視覺語言)。
+        // `:has(:focus-visible)`:readonly 渲 native `<input readOnly>`。⚠️ 瀏覽器對 text-entry 控件的
+        // :focus-visible 啟發式在滑鼠點擊時**亦 match**(text input 恆視為 focus-visible,對齊
+        // field-controls.spec.md「Focus 行為」段『文字輸入永遠 focus-visible、CSS 無法區分點擊與 Tab』),
+        // 故點擊 readonly input 也會顯 ring,勿宣稱僅鍵盤觸發(button 的 focus-visible 才滑鼠不觸發,
+        // input 不同;真要滑鼠抑制需 JS 追蹤 input modality,屬 API 擴充)。
+        className: "bg-readonly border border-transparent [&:has(:focus-visible)]:ring-2 [&:has(:focus-visible)]:ring-ring [&:has(:focus-visible)]:ring-offset-1"
       },
       {
         // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):
@@ -99,35 +144,14 @@ const fieldWrapperStyles = cva(
         variant: "default",
         className: "bg-disabled border border-transparent cursor-not-allowed"
       },
-      // bare variant chrome by mode
+      // (2026-07-09 `bare` variant 退役:原 edit×bare / edit×bare×error compounds 已移除。)
+      // error chrome(mode=edit 限定,variant 不分 — naked cell 內 error 同樣紅框,保留既有控件層行為):
       {
         mode: "edit",
-        variant: "bare",
-        className: [
-          "bg-transparent border border-transparent",
-          "hover:border-border",
-          // 同 default chrome v13.3 SSOT:focus-within !important 強制勝過 data-state
-          "focus-within:!border-primary focus-within:hover:!border-primary",
-          "data-[state=open]:border-border"
-        ]
-      },
-      {
-        mode: "display",
-        variant: "bare",
-        // bare + display:cell-as-input default state(無 variant,完全融入 cell;hover/focus 才有 affordance 等 user 點下去切 edit mode)
-        className: "bg-transparent border border-transparent"
-      },
-      {
-        mode: "readonly",
-        variant: "bare",
-        className: "bg-transparent border border-transparent"
-      },
-      {
-        // 2026-05-13 R3.5:移除 `opacity-disabled` blanket(per Avatar self-dim canonical)
-        mode: "disabled",
-        variant: "bare",
-        className: "bg-transparent border border-transparent cursor-not-allowed"
+        error: true,
+        className: "border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error"
       },
+      // (2026-07-09 `bare` variant 退役:原 display×bare / readonly×bare / disabled×bare compounds 已移除。)
       // naked variant — cell-as-input substrate(Notion / Airtable / Excel canonical)
       //
       // ── 2026-05-06 v14:revert v12 → v9 baseline + keep v13.3 ──
@@ -155,15 +179,16 @@ const fieldWrapperStyles = cva(
           "!px-[var(--table-cell-px)] !py-[var(--table-cell-py)]",
           "border border-border",
           "hover:border-border-hover",
-          // v13.3 SSOT canonical:focus-within !important(同 default + bare)
-          "focus-within:!border-primary focus-within:hover:!border-primary",
+          // v13.3 SSOT canonical:focus-within !important(同 default + bare;
+          // 2026-07-04 Q1:focus 藍移到 error:false compound,error:true 走共用 error compound)
           "data-[state=open]:border-border-hover",
           "group-data-[row-mode=auto]/cell:!items-start"
         ]
       },
+      { mode: "edit", variant: "naked", error: false, className: "focus-within:!border-primary focus-within:hover:!border-primary" },
       {
         // 2026-05-12 fix v2(M32 root invariant audit):
-        //   Q1 root invariant?:cell-as-input display 視覺位置 = `cell.items-{X}` × `Field.height`
+        //   Q1 root invariant?:cell-as-input view 視覺位置 = `cell.items-{X}` × `Field.height`
         //                       兩變數函數;canonical = autoRow → Field intrinsic + cell.items-start
         //                       (text 在 cell top + cellPadding-y),fixed → Field h-field-md +
         //                       cell.items-center(text 在 cell vertical center)。
@@ -177,40 +202,25 @@ const fieldWrapperStyles = cva(
         //                  override h-field-md → Field intrinsic line-height → cell items-start
         //                  真實 anchor text at cell.top + padding。
         // Edit mode 不動(`!h-full` 保留 — border 必滿格對齊 cell border)。
-        mode: "display",
+        // 2026-07-16 round16:view×naked 保持 bare(cell substrate,host TD 給 padding)— 與 view×default
+        // (edit 幾何減 chrome、留 px/py)本質不同用途,**不 collapse**(round14 合併是錯的)。
+        mode: "view",
         variant: "naked",
         className: [
           "bg-transparent !rounded-none !px-0 !py-0 !h-auto",
           "border border-transparent"
         ]
-      },
-      {
-        mode: "readonly",
-        variant: "naked",
-        className: [
-          "bg-transparent !rounded-none !px-0 !py-0 !h-auto",
-          "border border-transparent"
-        ]
-      },
-      {
-        // 2026-05-13 Q3 fix(per codex Q3 verdict + color.spec.md:729 逃生艙 rule):
-        // 移除 `opacity-disabled` blanket — naked wrapper 只負責 substrate(透明 border + 抑制 cursor),
-        // 內部 content(text / icon / avatar)各自 disabled context 處理(text-fg-disabled / Avatar opacity 等具體 token)。
-        // 對齊 DataTable cell-disabled TD 加 `bg-disabled` 表達 cell-level disabled state 的 SSOT 分權。
-        // **default/bare disabled variant(line 107, 135)deferred R3.5** — 仍依賴 wrapper opacity-disabled
-        // for Avatar dim(Avatar 尚未 fieldCtx-aware self-dim);Avatar self-dim 實作後再連帶移除。
-        mode: "disabled",
-        variant: "naked",
-        className: [
-          "bg-transparent !rounded-none cursor-not-allowed !px-0 !py-0 !h-auto",
-          "border border-transparent"
-        ]
       }
+      // 2026-07-16 round16:`readonly×naked` / `disabled×naked` 死格移除 —— DataTable cell 廢除
+      //   disabled 態(view 一律 mode="view";displayOrDisabled helper 已刪)+ readonly 從不入 naked
+      //   路徑(全庫 0 消費)。軸對稱靠 cva 省略即天然覆蓋(base+size+透明),不需 dead compound 佔位。
     ],
     defaultVariants: {
       mode: "edit",
       variant: "default",
-      size: "md"
+      size: "md",
+      width: "fill",
+      error: false
     }
   }
 );
@@ -221,7 +231,7 @@ const bareInputStyles = [
   // bareInputStyles 套上,placeholder 無 ellipsis → narrow cell(<160px)硬裁無 `...`(user round 3
   // 圖一證據)。加 truncate 後 `<input>` `text-overflow: ellipsis` 啟動,符合 user 「placeholder 直接被截掉沒有變...」
   // 該顯 ellipsis 的 SSOT。對齊 data-table.spec.md:233「禁硬裁無 ellipsis」+ field-controls.spec.md:286
-  // 共享 contract(a)「display/readonly/disabled/edit 4 mode 共享同一 renderer」semantic 對齊。
+  // 共享 contract(a)「view/readonly/disabled/edit 4 mode 共享同一 renderer」semantic 對齊。
   "flex-1 min-w-0 truncate bg-transparent",
   "outline-none border-none p-0",
   "text-[inherit] font-[inherit] leading-[inherit]",
@@ -239,12 +249,26 @@ const bareInputStyles = [
 ].join(" ");
 const nakedCellRowModeAlign = "group-data-[row-mode=auto]/cell:items-start";
 const nakedCellEditableDisplayHover = "hover:outline hover:outline-1 hover:outline-offset-[-1px] hover:outline-[var(--cell-hover-outline-color,var(--border-hover))]";
-const EMPTY_DISPLAY = "—";
+const EMPTY_DISPLAY = "-";
 const fieldDisplayTextClass = (size) => size === "lg" ? "text-body-lg" : "text-body";
+const fieldViewGeometry = (size, multiline) => cn(
+  "flex w-full min-w-0 px-[var(--field-px)]",
+  size === "sm" && "min-h-[var(--field-height-sm)]",
+  size === "md" && "min-h-[var(--field-height-md)]",
+  size === "lg" && "min-h-[var(--field-height-lg)]",
+  // 多行 view py 必等於 Textarea edit py(同一 --field-control-py-* token),否則
+  // InlineEdit 多行 read↔edit 垂直跳位;scripts/inline-edit-view-geometry-invariant.mjs 機械鎖。
+  multiline && "items-start",
+  multiline && size === "sm" && "py-[var(--field-control-py-sm)]",
+  multiline && size === "md" && "py-[var(--field-control-py-md)]",
+  multiline && size === "lg" && "py-[var(--field-control-py-lg)]",
+  !multiline && "items-center"
+);
 export {
   EMPTY_DISPLAY,
   bareInputStyles,
   fieldDisplayTextClass,
+  fieldViewGeometry,
   fieldWrapperStyles,
   nakedCellEditableDisplayHover,
   nakedCellRowModeAlign