@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -39,9 +39,9 @@ const fieldWrapperStyles = cva(
         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"
       }
     },
     // mode x variant 交叉:visual chrome 由 compoundVariants 決定
@@ -80,7 +80,7 @@ const fieldWrapperStyles = cva(
         mode: "display",
         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
+        // default display = zero chrome — !px-0 !py-0 override size token 的 px-[var(--field-px)],跟 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"
@@ -88,7 +88,7 @@ const fieldWrapperStyles = cva(
       {
         mode: "readonly",
         variant: "default",
-        className: "bg-disabled border border-transparent"
+        className: "bg-readonly border border-transparent"
       },
       {
         // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):

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

@@ -1 +1 @@
-{"version":3,"file":"field-wrapper.js","sources":["../../../src/components/Field/field-wrapper.tsx"],"sourcesContent":["// @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.\nimport { cva } from 'class-variance-authority'\n\n// ── Field Wrapper Styles ────────────────────────────────────────────────────\n// 所有 Field 元件共用的 input wrapper 樣式。\n//\n// 4 種模式(2026-05-05 expand):\n//   edit     — bg-surface, border, hover/focus 回饋(可編輯 input)\n//   display  — 純展示(無 input chrome、無 affordance);語意「read-only 內容,展示給人看」。\n//              對齊 Carbon read-only / PatternFly inline-edit hidden-input。\n//   readonly — bg-disabled(neutral-2), 無邊框, 文字正常色(input chrome 但鎖定)\n//   disabled — bg-disabled(neutral-2), 無邊框, 文字灰化\n//\n// 2 種視覺外殼(variant):\n//   default — 完整 chrome(form input 場景)\n//   bare    — 透明 chrome(cell-as-input substrate / Toolbar inline editing)\n//\n// 高度:固定 h = field-height token(rem),與 Button 共用同一組 token。\n\nexport const fieldWrapperStyles = cva(\n  [\n    // K10 fix(2026-05-04):`group/field` 讓 inner placeholder/text 可透過 `group-data-[field-mode=...]/field:` 變體\n    //   各 Field 元件 wrapper 同時加 `data-field-mode={resolvedMode}` 屬性,bareInputStyles 即可\n    //   依 mode 切 placeholder color。User canonical:disabled 顯著性優於 muted。\n    'group/field',\n    // 2026-05-15 H1 root cause fix(user #1 verbatim 拍板「照你跟codex有共識的最佳建議做」+ codex round 1 verify cite 5/5):\n    // 加 `min-w-0` 於 base — Field wrapper 為 cell-as-input substrate(DataTable / Form 上下文),\n    // parent grid/flex cell 限寬時 wrapper 子 flex children 需 min-w-0 才能縮 + truncate。\n    // 之前 SSOT 缺 → `selectedItemRenderer` / value text / Multi tag area 在 narrow cell 無法\n    // truncate-with-ellipsis(`Alexander Hamilton Zhang` 直接被 cell overflow-hidden 硬裁無 `...`\n    // 甚至蓋住相鄰 cell `—` indicator,圖二 user round 2 直接抓 trigger 越界證據)。\n    // 修一處全 Field family 跟動(Input/Select/Combobox/DatePicker/TimePicker/LinkInput/\n    // Textarea/NumberInput/PeoplePicker)— 對齊 M17/M19/M23 一處 SSOT + data-table.spec.md:233\n    // 「禁硬裁無 ellipsis」DS canonical + MUI X DataGrid / Ant Table column.ellipsis 共識。\n    'inline-flex items-center w-full min-w-0 rounded-md',\n    'text-foreground font-normal',\n    'transition-colors duration-150',\n  ],\n  {\n    variants: {\n      mode: {\n        edit: '',\n        display: '',\n        readonly: '',\n        disabled: '',\n      },\n      variant: {\n        // default — 完整 Field wrapper chrome(bg-surface、明顯 border、hover/focus 回饋)\n        default: '',\n        // bare — 透明 variant,hover / focus 才出現 border。適用 Toolbar inline editing\n        // (FileViewer zoom input / chart config / rich text toolbar number input 等)。\n        // 世界級對照:VS Code settings / Figma toolbar number / Notion prop input。\n        bare: '',\n        // naked — 完全無 variant,hover/focus 也不出 border。適用 cell-as-input\n        // (host cell 自管 border + focus visual,內部 input 純文字承載)。\n        // 世界級對照:Airtable / Notion / Excel / Google Sheets cell editing。\n        naked: '',\n      },\n      size: {\n        sm: 'text-body h-field-sm px-3 gap-2',\n        md: 'text-body h-field-md px-3 gap-2',\n        lg: 'text-body-lg h-field-lg px-3 gap-2',\n      },\n    },\n    // mode x variant 交叉:visual chrome 由 compoundVariants 決定\n    //\n    // Overlay trigger active state(canonical 2026-05-02):當 Field 是 Popover/DropdownMenu/\n    // Combobox trigger 用 asChild,Radix 自動 set `data-state=\"open\"` on trigger root → trigger\n    // 視覺維持 hover 樣式直到浮層關閉(對齊 inline-action.spec.md「狀態極簡派」)。\n    compoundVariants: [\n      // default variant chrome by mode\n      {\n        mode: 'edit',\n        variant: 'default',\n        className: [\n          'bg-surface border border-border',\n          'hover:border-border-hover',\n          // 2026-05-06 v13.3 SSOT canonical:focus-within `!important` 強制勝過 data-state attribute\n          // selector(specificity tie at 0,2,0;source order 後者勝)。\n          //\n          // 設計原則:**focus dominates everything**(M11 fix「focus-dominates-hover」延伸成\n          // 「focus-dominates-{hover,open,error-rest}」)。Cursor 在輸入框 = user 編輯中 = 必藍。\n          //\n          // 對齊世界級三家共識:\n          //   - Material Design 3:focus → primary line color\n          //   - Polaris(Shopify):focus state border-focus(藍)overrides hover/open\n          //   - Ant Design 5:`.ant-select-focused` blue,popover open + select option close 後\n          //     trigger 仍 focused → blue stays(focus return canonical via Radix `onCloseAutoFocus`)\n          //\n          // 副作用 — Ant 風「選後藍 / 取消灰」自動達成:\n          //   - 選 option close popover → Radix focus return to trigger → focus-within fires → 藍\n          //   - 點外取消 close popover → focus 移外 → focus-within 不 fire → 灰\n          'focus-within:!border-primary focus-within:hover:!border-primary',\n          'data-[state=open]:border-border-hover',\n        ],\n      },\n      {\n        mode: 'display',\n        variant: 'default',\n        // 2026-05-13 Q3 Path Ⅰ(user 拍板 Path Ⅰ 全 zero chrome + codex V2 verdict + field-controls.spec.md (d)):\n        // default display = zero chrome — !px-0 !py-0 override size token 的 px-3,跟 Select / Combobox\n        // / DatePicker / TimePicker / LinkInput non-D-path bare-span idiom 一致(Carbon read-only / Stripe\n        // display / Notion property / Polaris readonly TextField 全 zero chrome)。\n        className: 'bg-transparent border border-transparent !px-0 !py-0',\n      },\n      {\n        mode: 'readonly',\n        variant: 'default',\n        className: 'bg-disabled border border-transparent',\n      },\n      {\n        // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):\n        // 移除 `opacity-disabled` blanket — Avatar 已 fieldCtx-aware self-dim(avatar.tsx self-managed\n        // via `isDisabledInField` derivation)。Field wrapper 不再 host-control Avatar opacity。\n        // Inner content(text-fg-disabled / Avatar self-opacity)走具體 disabled token per color.spec.md:729。\n        mode: 'disabled',\n        variant: 'default',\n        className: 'bg-disabled border border-transparent cursor-not-allowed',\n      },\n      // bare variant chrome by mode\n      {\n        mode: 'edit',\n        variant: 'bare',\n        className: [\n          'bg-transparent border border-transparent',\n          'hover:border-border',\n          // 同 default chrome v13.3 SSOT:focus-within !important 強制勝過 data-state\n          'focus-within:!border-primary focus-within:hover:!border-primary',\n          'data-[state=open]:border-border',\n        ],\n      },\n      {\n        mode: 'display',\n        variant: 'bare',\n        // bare + display:cell-as-input default state(無 variant,完全融入 cell;hover/focus 才有 affordance 等 user 點下去切 edit mode)\n        className: 'bg-transparent border border-transparent',\n      },\n      {\n        mode: 'readonly',\n        variant: 'bare',\n        className: 'bg-transparent border border-transparent',\n      },\n      {\n        // 2026-05-13 R3.5:移除 `opacity-disabled` blanket(per Avatar self-dim canonical)\n        mode: 'disabled',\n        variant: 'bare',\n        className: 'bg-transparent border border-transparent cursor-not-allowed',\n      },\n      // naked variant — cell-as-input substrate(Notion / Airtable / Excel canonical)\n      //\n      // ── 2026-05-06 v14:revert v12 → v9 baseline + keep v13.3 ──\n      // v12 `!absolute -inset-px` autoRowHeight 不相容(Field 抽 layout flow → cell 塌 42px;\n      // user production 報「Field 沒撐滿 cell, 比沒改之前還糟糕一百萬倍」)→ revert。\n      //\n      // v14 = v9 baseline border-based state machine + v13.3 focus !important。\n      // 暫接受視覺:Field.border-l 跟 prev cell.border-r 視覺 2px 雙線(待另案研究 seamless\n      // 方案,約束:SSOT 留 Field state machine + ring 顏色自動跟 border state 同步)。\n      // Phase 9 Issue 5 fix(2026-05-10 user 撞 + codex 重比稿 verdict ADOPT):\n      //   Field naked variant 之前全寫 `!gap-0` strip Field family slot gap → indicator(chevron /\n      //   calendar / clock)緊連 value 沒間距。違反 item-anatomy slot SSOT。\n      //   Codex verdict:「naked 把 chrome stripping 跟 slot anatomy stripping 混在一起。\n      //   chrome stripping 合理(去 padding / border / rounded);slot anatomy stripping 不合理\n      //   (prefix / content / suffix gap 仍是 item anatomy slot canonical `gap-2`)」\n      //   Fix:移除 `!gap-0`,讓 Field family base `gap-2`(field-wrapper.tsx:50)透出來。\n      //   Cite:item-anatomy.spec.md L46-50 / L113-122 partial consumer canonical;\n      //   field-controls.spec.md L22 Field Controls 視覺對齊 Family 1 Menu item layout。\n      //   特殊 stack / multi-pill 場景若需 zero-gap,該 component spec 明文例外,不全域 strip。\n      {\n        mode: 'edit',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !h-full',\n          '!px-[var(--table-cell-px)] !py-[var(--table-cell-py)]',\n          'border border-border',\n          'hover:border-border-hover',\n          // v13.3 SSOT canonical:focus-within !important(同 default + bare)\n          'focus-within:!border-primary focus-within:hover:!border-primary',\n          'data-[state=open]:border-border-hover',\n          'group-data-[row-mode=auto]/cell:!items-start',\n        ],\n      },\n      {\n        // 2026-05-12 fix v2(M32 root invariant audit):\n        //   Q1 root invariant?:cell-as-input display 視覺位置 = `cell.items-{X}` × `Field.height`\n        //                       兩變數函數;canonical = autoRow → Field intrinsic + cell.items-start\n        //                       (text 在 cell top + cellPadding-y),fixed → Field h-field-md +\n        //                       cell.items-center(text 在 cell vertical center)。\n        //   Q2 symptom?:`h-field-md` 32px 在 autoRow tall cell + cell items-start → Field 32px\n        //              sitting at top,inside items-center default → text center = top+15 ≠ top。\n        //              即使 `group-data-[row-mode=auto]/cell:!items-start` 加進來,Field height\n        //              還是 32 → text 在 Field 內 top,但 Field 自己 height ≠ 0,offset 13~32px。\n        //   Q3 fix layer?:root-layer fix = Field 在 autoRow context 必 `h-auto` 才能讓 text 真正\n        //                  flush 到 cell.top + padding。前 v1 只 remove `!h-full` 是 surface-fix\n        //                  (沒解決 h-field-md 32px persistence)。v2 真根因 fix:加 `!h-auto`\n        //                  override h-field-md → Field intrinsic line-height → cell items-start\n        //                  真實 anchor text at cell.top + padding。\n        // Edit mode 不動(`!h-full` 保留 — border 必滿格對齊 cell border)。\n        mode: 'display',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n      {\n        mode: 'readonly',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n      {\n        // 2026-05-13 Q3 fix(per codex Q3 verdict + color.spec.md:729 逃生艙 rule):\n        // 移除 `opacity-disabled` blanket — naked wrapper 只負責 substrate(透明 border + 抑制 cursor),\n        // 內部 content(text / icon / avatar)各自 disabled context 處理(text-fg-disabled / Avatar opacity 等具體 token)。\n        // 對齊 DataTable cell-disabled TD 加 `bg-disabled` 表達 cell-level disabled state 的 SSOT 分權。\n        // **default/bare disabled variant(line 107, 135)deferred R3.5** — 仍依賴 wrapper opacity-disabled\n        // for Avatar dim(Avatar 尚未 fieldCtx-aware self-dim);Avatar self-dim 實作後再連帶移除。\n        mode: 'disabled',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none cursor-not-allowed !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n    ],\n    defaultVariants: {\n      mode: 'edit',\n      variant: 'default',\n      size: 'md',\n    },\n  }\n)\n\n// ── Bare Input Styles ───────────────────────────────────────────────────────\n\nexport const bareInputStyles = [\n  // 2026-05-15 Q1 真 root cause fix(per codex Round 4 cite-based verdict):\n  // 加 `truncate` — 原 bareInputStyles 含 `flex-1 min-w-0` 但無 `truncate / text-overflow` policy。\n  // 當 Select `searchable && open` 切 raw `<input placeholder=...>` branch(select.tsx:178),\n  // bareInputStyles 套上,placeholder 無 ellipsis → narrow cell(<160px)硬裁無 `...`(user round 3\n  // 圖一證據)。加 truncate 後 `<input>` `text-overflow: ellipsis` 啟動,符合 user 「placeholder 直接被截掉沒有變...」\n  // 該顯 ellipsis 的 SSOT。對齊 data-table.spec.md:233「禁硬裁無 ellipsis」+ field-controls.spec.md:286\n  // 共享 contract(a)「display/readonly/disabled/edit 4 mode 共享同一 renderer」semantic 對齊。\n  'flex-1 min-w-0 truncate bg-transparent',\n  'outline-none border-none p-0',\n  'text-[inherit] font-[inherit] leading-[inherit]',\n  // A3 fix(2026-05-05):`<input>` UA stylesheet 強制 `text-align: start`,阻斷 parent 的\n  //   `text-right`/`text-center` 繼承。顯式 `text-align: inherit` 復原(對齊 NumberCell /\n  //   CurrencyCell right-align canonical:column meta.align='right' → cell text-right →\n  //   input 跟著 right-align)。\n  '[text-align:inherit]',\n  'placeholder:text-fg-muted',\n  // K10 fix(2026-05-04):wrapper data-field-mode=disabled 時,placeholder/text 都切 fg-disabled\n  //   依賴 fieldWrapperStyles 的 `group/field` + 各 Field 元件 wrapper 加 `data-field-mode={resolvedMode}`\n  //   User canonical:disabled state 顯著性優於 muted(neutral-6 > neutral-7)\n  'group-data-[field-mode=disabled]/field:placeholder:text-fg-disabled',\n  'group-data-[field-mode=disabled]/field:text-fg-disabled',\n].join(' ')\n\n// ── Naked Variant Cell Row-Mode Alignment Propagation ──────────────────────\n// SSOT canonical(M19 / 2026-05-05):cell-as-input naked variant 元件**所有內部\n// wrapper**(`<span>` 包 Avatar+name 等)必 import + apply 此 SSOT,host cell\n// `data-row-mode` 屬性自動 propagate alignment(autoRow → items-start / fixed → items-center)。\n//\n// 不 propagate 的後果:autoRow 場景下 People / Select / Combobox 內部用\n// `inline-flex items-center` hardcode → 視覺垂直置中於 wrapper 自身高度,**沒**頂對齊\n// → 跟其他純文字 cell baseline 視覺漂移。\n//\n// 世界級對照:\n//   - HTML <td> default `vertical-align: baseline`(瀏覽器自動 first-baseline align)\n//   - AG Grid `cellStyle` + `cellRendererSelector`,row context 共享(closed source 部分)\n//   - Material X-Grid `gridClasses.cell` wrapper 不允許 cell content override alignment\n//   - Notion / Airtable cell content 從 host 繼承,不 hardcode self alignment\n//\n// Hook:`check_naked_row_mode_propagation.sh`(write-time BLOCKER)\n// Audit:design-system-audit Group N M27(periodic batch verify)\nexport const nakedCellRowModeAlign = 'group-data-[row-mode=auto]/cell:items-start'\n\n// ── Cell-as-input Display Hover Ring(2026-05-05 v9 — sole remaining ring const)─\n// editable cell **display mode hover 提示**(「這 cell 可編,點 → 進 edit」affordance 信號)。\n// 對齊 Notion / Airtable hover-cell-shows-border canonical。\n//\n// **為何只剩這一個**:Field naked **edit/focus/open state ring 已下沉到 Field default state\n// machine**(border-based,2026-05-05 v9 architectural rewrite),不需 outline 平行系統;\n// 但 display mode 沒 Field state(display = 純展示無互動),hover 提示需 cell wrapper 自加。\n//\n// **2026-05-09 v15.17 revert v15.16(user 未同意 ship)— 維持 v15.13 outline+offset:-1**\n//\n// User 2026-05-09 後續 message:「設計決策的東西你應該要先問過我讓我決策吧?為什麼就直接開跑」\n// 我 commit 698ff58 ship v15.16(box-shadow inset Spec 2 不蓋 grid)= 設計決策結論未 user 同意\n// 直接 ship = workflow 違反。Revert 回 v15.13 outline+offset:-1(原 user-accepted 路徑),\n// 等 user 拍板 4-邊覆蓋路徑才 ship。\n//\n// User 並指出我視覺分析又錯:「我就是只有看到只有右邊被蓋掉,上面下面左邊都會露出 cell 的邊框」\n// 我之前錯說「right + bottom 都覆蓋」,bottom 真實 row border-b 在 cell.outer 外 1px,outline 蓋不到。\n//\n// 真實 4-邊狀態(re-verified):\n//   - right: outline 199-200 = cell own border-r 199-200 → 蓋 1 條線 ✓\n//   - top: outline 0-1,前一 row border-b 在 cell.outer 外 → 露 2 條線\n//   - bottom: outline 38-39 在 cell 內,row border-b 在 row.outer 內 = cell.outer 外 1px → 露 2 條線\n//   - left: outline 0-1,前一 cell border-r 在 cell.outer 外 → 露 2 條線\n//\n// User 想要 4 邊都覆蓋 = 等 codex unframed brief + user 拍板,本次不 ship。\n//\n// 之前 v15.13 / 14 / 16 / 17 緣由 → tsc comment 之前版本 + planning RFC\n// (跑錯方向 4 次 = 沒 1 次 verify 全面向 + 沒 user 拍板 set design)。\n//\n// Color `--border-hover` 對齊 Field default hover state token。\n//\n// **2026-05-10 Slice D Step 2 — Cell host CSS variable suppression**:\n// outline color 改用 `var(--cell-hover-outline-color, var(--border-hover))`,\n// allow DataTable cell host(spreadsheet overlay enabled 時)set `--cell-hover-outline-color: transparent`\n// 抑制 outline,讓 overlay layer 接管 hover ring paint(per RFC Contract 8 「one geometry owner, two paint owners」)。\n// Backward-compat:flag 關時 default `--border-hover`,既有行為不變。\nexport const nakedCellEditableDisplayHover = 'hover:outline hover:outline-1 hover:outline-offset-[-1px] hover:outline-[var(--cell-hover-outline-color,var(--border-hover))]'\n\n// ── Cell-as-input Edge Slot SSOT(2026-05-05 v8 — retire 平行 SSOT,改 L1 消費)───\n//\n// 前身 `nakedCellPrefixSlot` / `nakedCellSuffixSlot` 是 M1+M17 違反:平行 SSOT 跟\n// `patterns/element-anatomy` 的 `<ItemPrefix>` / `<ItemSuffix>` primitive 撞 home。\n// 已 retire — Field naked variant 內 prefix / suffix slot 直接消費 L1 primitive:\n//\n//   import { ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'\n//   <ItemPrefix><StartIcon /></ItemPrefix>     // 對 Input.startIcon / Select.startIcon\n//   <ItemSuffix>{chevron}</ItemSuffix>          // 對 Combobox / DatePicker / PeoplePicker chevron\n//\n// **`h-[1lh]` 普世正確**(item-anatomy.spec.md:190-191 verbatim):\n//   - 單行 wrapper items-center → slot 1lh 在 cell 高度中心 = 第一行中線(視覺 = items-center)\n//   - 多行 wrapper items-start  → slot 1lh 鎖頂 = 第一行中線\n//   不需 conditional `group-data-[row-mode=auto]/cell:` — 我前 v4 自加的 conditional 是過度設計。\n//\n// State ring 3 const 仍留(下方)— 是 Field naked 專屬,MenuItem / TreeView 用 bg hover 不用 outline。\n// `nakedCellRowModeAlign`(wrapper 級)仍留 — 是 cell-context row-mode → wrapper alignment 適配,正交 slot 級。\n\n// ── Empty Value Display ─────────────────────────────────────────────────────\n\nexport const EMPTY_DISPLAY = '—'\n\n/**\n * 2026-05-14 I2 fix(per field-controls.spec.md contract (e) display typography canonical):\n * Field family display path bare-span helper — `sm/md → text-body` / `lg → text-body-lg`,\n * 跨 9 元件 display 視覺尺寸統一(user 抓 LinkInput 字體跟其他 Field 不一致 = SSOT 違反)。\n * Consumer:LinkInput / Select / Combobox / DatePicker / TimePicker non-D-path bare-span 套此 class。\n */\nexport const fieldDisplayTextClass = (size: 'sm' | 'md' | 'lg'): string =>\n  size === 'lg' ? 'text-body-lg' : 'text-body'\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"field-wrapper.js","sources":["../../../src/components/Field/field-wrapper.tsx"],"sourcesContent":["// @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.\nimport { cva } from 'class-variance-authority'\n\n// ── Field Wrapper Styles ────────────────────────────────────────────────────\n// 所有 Field 元件共用的 input wrapper 樣式。\n//\n// 4 種模式(2026-05-05 expand):\n//   edit     — bg-surface, border, hover/focus 回饋(可編輯 input)\n//   display  — 純展示(無 input chrome、無 affordance);語意「read-only 內容,展示給人看」。\n//              對齊 Carbon read-only / PatternFly inline-edit hidden-input。\n//   readonly — bg-readonly(neutral-2), 無邊框, 文字正常色(input chrome 但鎖定;token 獨立於 disabled)\n//   disabled — bg-disabled(neutral-2), 無邊框, 文字灰化\n//\n// 2 種視覺外殼(variant):\n//   default — 完整 chrome(form input 場景)\n//   bare    — 透明 chrome(cell-as-input substrate / Toolbar inline editing)\n//\n// 高度:固定 h = field-height token(rem),與 Button 共用同一組 token。\n\nexport const fieldWrapperStyles = cva(\n  [\n    // K10 fix(2026-05-04):`group/field` 讓 inner placeholder/text 可透過 `group-data-[field-mode=...]/field:` 變體\n    //   各 Field 元件 wrapper 同時加 `data-field-mode={resolvedMode}` 屬性,bareInputStyles 即可\n    //   依 mode 切 placeholder color。User canonical:disabled 顯著性優於 muted。\n    'group/field',\n    // 2026-05-15 H1 root cause fix(user #1 verbatim 拍板「照你跟codex有共識的最佳建議做」+ codex round 1 verify cite 5/5):\n    // 加 `min-w-0` 於 base — Field wrapper 為 cell-as-input substrate(DataTable / Form 上下文),\n    // parent grid/flex cell 限寬時 wrapper 子 flex children 需 min-w-0 才能縮 + truncate。\n    // 之前 SSOT 缺 → `selectedItemRenderer` / value text / Multi tag area 在 narrow cell 無法\n    // truncate-with-ellipsis(`Alexander Hamilton Zhang` 直接被 cell overflow-hidden 硬裁無 `...`\n    // 甚至蓋住相鄰 cell `—` indicator,圖二 user round 2 直接抓 trigger 越界證據)。\n    // 修一處全 Field family 跟動(Input/Select/Combobox/DatePicker/TimePicker/LinkInput/\n    // Textarea/NumberInput/PeoplePicker)— 對齊 M17/M19/M23 一處 SSOT + data-table.spec.md:233\n    // 「禁硬裁無 ellipsis」DS canonical + MUI X DataGrid / Ant Table column.ellipsis 共識。\n    'inline-flex items-center w-full min-w-0 rounded-md',\n    'text-foreground font-normal',\n    'transition-colors duration-150',\n  ],\n  {\n    variants: {\n      mode: {\n        edit: '',\n        display: '',\n        readonly: '',\n        disabled: '',\n      },\n      variant: {\n        // default — 完整 Field wrapper chrome(bg-surface、明顯 border、hover/focus 回饋)\n        default: '',\n        // bare — 透明 variant,hover / focus 才出現 border。適用 Toolbar inline editing\n        // (FileViewer zoom input / chart config / rich text toolbar number input 等)。\n        // 世界級對照:VS Code settings / Figma toolbar number / Notion prop input。\n        bare: '',\n        // naked — 完全無 variant,hover/focus 也不出 border。適用 cell-as-input\n        // (host cell 自管 border + focus visual,內部 input 純文字承載)。\n        // 世界級對照:Airtable / Notion / Excel / Google Sheets cell editing。\n        naked: '',\n      },\n      size: {\n        sm: 'text-body h-field-sm px-[var(--field-px)] gap-2',\n        md: 'text-body h-field-md px-[var(--field-px)] gap-2',\n        lg: 'text-body-lg h-field-lg px-[var(--field-px)] gap-2',\n      },\n    },\n    // mode x variant 交叉:visual chrome 由 compoundVariants 決定\n    //\n    // Overlay trigger active state(canonical 2026-05-02):當 Field 是 Popover/DropdownMenu/\n    // Combobox trigger 用 asChild,Radix 自動 set `data-state=\"open\"` on trigger root → trigger\n    // 視覺維持 hover 樣式直到浮層關閉(對齊 inline-action.spec.md「狀態極簡派」)。\n    compoundVariants: [\n      // default variant chrome by mode\n      {\n        mode: 'edit',\n        variant: 'default',\n        className: [\n          'bg-surface border border-border',\n          'hover:border-border-hover',\n          // 2026-05-06 v13.3 SSOT canonical:focus-within `!important` 強制勝過 data-state attribute\n          // selector(specificity tie at 0,2,0;source order 後者勝)。\n          //\n          // 設計原則:**focus dominates everything**(M11 fix「focus-dominates-hover」延伸成\n          // 「focus-dominates-{hover,open,error-rest}」)。Cursor 在輸入框 = user 編輯中 = 必藍。\n          //\n          // 對齊世界級三家共識:\n          //   - Material Design 3:focus → primary line color\n          //   - Polaris(Shopify):focus state border-focus(藍)overrides hover/open\n          //   - Ant Design 5:`.ant-select-focused` blue,popover open + select option close 後\n          //     trigger 仍 focused → blue stays(focus return canonical via Radix `onCloseAutoFocus`)\n          //\n          // 副作用 — Ant 風「選後藍 / 取消灰」自動達成:\n          //   - 選 option close popover → Radix focus return to trigger → focus-within fires → 藍\n          //   - 點外取消 close popover → focus 移外 → focus-within 不 fire → 灰\n          'focus-within:!border-primary focus-within:hover:!border-primary',\n          'data-[state=open]:border-border-hover',\n        ],\n      },\n      {\n        mode: 'display',\n        variant: 'default',\n        // 2026-05-13 Q3 Path Ⅰ(user 拍板 Path Ⅰ 全 zero chrome + codex V2 verdict + field-controls.spec.md (d)):\n        // default display = zero chrome — !px-0 !py-0 override size token 的 px-[var(--field-px)],跟 Select / Combobox\n        // / DatePicker / TimePicker / LinkInput non-D-path bare-span idiom 一致(Carbon read-only / Stripe\n        // display / Notion property / Polaris readonly TextField 全 zero chrome)。\n        className: 'bg-transparent border border-transparent !px-0 !py-0',\n      },\n      {\n        mode: 'readonly',\n        variant: 'default',\n        className: 'bg-readonly border border-transparent',\n      },\n      {\n        // 2026-05-13 R3.5(per codex Q3 verdict + user 拍「想盡辦法 auto-handle prereq」):\n        // 移除 `opacity-disabled` blanket — Avatar 已 fieldCtx-aware self-dim(avatar.tsx self-managed\n        // via `isDisabledInField` derivation)。Field wrapper 不再 host-control Avatar opacity。\n        // Inner content(text-fg-disabled / Avatar self-opacity)走具體 disabled token per color.spec.md:729。\n        mode: 'disabled',\n        variant: 'default',\n        className: 'bg-disabled border border-transparent cursor-not-allowed',\n      },\n      // bare variant chrome by mode\n      {\n        mode: 'edit',\n        variant: 'bare',\n        className: [\n          'bg-transparent border border-transparent',\n          'hover:border-border',\n          // 同 default chrome v13.3 SSOT:focus-within !important 強制勝過 data-state\n          'focus-within:!border-primary focus-within:hover:!border-primary',\n          'data-[state=open]:border-border',\n        ],\n      },\n      {\n        mode: 'display',\n        variant: 'bare',\n        // bare + display:cell-as-input default state(無 variant,完全融入 cell;hover/focus 才有 affordance 等 user 點下去切 edit mode)\n        className: 'bg-transparent border border-transparent',\n      },\n      {\n        mode: 'readonly',\n        variant: 'bare',\n        className: 'bg-transparent border border-transparent',\n      },\n      {\n        // 2026-05-13 R3.5:移除 `opacity-disabled` blanket(per Avatar self-dim canonical)\n        mode: 'disabled',\n        variant: 'bare',\n        className: 'bg-transparent border border-transparent cursor-not-allowed',\n      },\n      // naked variant — cell-as-input substrate(Notion / Airtable / Excel canonical)\n      //\n      // ── 2026-05-06 v14:revert v12 → v9 baseline + keep v13.3 ──\n      // v12 `!absolute -inset-px` autoRowHeight 不相容(Field 抽 layout flow → cell 塌 42px;\n      // user production 報「Field 沒撐滿 cell, 比沒改之前還糟糕一百萬倍」)→ revert。\n      //\n      // v14 = v9 baseline border-based state machine + v13.3 focus !important。\n      // 暫接受視覺:Field.border-l 跟 prev cell.border-r 視覺 2px 雙線(待另案研究 seamless\n      // 方案,約束:SSOT 留 Field state machine + ring 顏色自動跟 border state 同步)。\n      // Phase 9 Issue 5 fix(2026-05-10 user 撞 + codex 重比稿 verdict ADOPT):\n      //   Field naked variant 之前全寫 `!gap-0` strip Field family slot gap → indicator(chevron /\n      //   calendar / clock)緊連 value 沒間距。違反 item-anatomy slot SSOT。\n      //   Codex verdict:「naked 把 chrome stripping 跟 slot anatomy stripping 混在一起。\n      //   chrome stripping 合理(去 padding / border / rounded);slot anatomy stripping 不合理\n      //   (prefix / content / suffix gap 仍是 item anatomy slot canonical `gap-2`)」\n      //   Fix:移除 `!gap-0`,讓 Field family base `gap-2`(field-wrapper.tsx:50)透出來。\n      //   Cite:item-anatomy.spec.md L46-50 / L113-122 partial consumer canonical;\n      //   field-controls.spec.md L22 Field Controls 視覺對齊 Family 1 Menu item layout。\n      //   特殊 stack / multi-pill 場景若需 zero-gap,該 component spec 明文例外,不全域 strip。\n      {\n        mode: 'edit',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !h-full',\n          '!px-[var(--table-cell-px)] !py-[var(--table-cell-py)]',\n          'border border-border',\n          'hover:border-border-hover',\n          // v13.3 SSOT canonical:focus-within !important(同 default + bare)\n          'focus-within:!border-primary focus-within:hover:!border-primary',\n          'data-[state=open]:border-border-hover',\n          'group-data-[row-mode=auto]/cell:!items-start',\n        ],\n      },\n      {\n        // 2026-05-12 fix v2(M32 root invariant audit):\n        //   Q1 root invariant?:cell-as-input display 視覺位置 = `cell.items-{X}` × `Field.height`\n        //                       兩變數函數;canonical = autoRow → Field intrinsic + cell.items-start\n        //                       (text 在 cell top + cellPadding-y),fixed → Field h-field-md +\n        //                       cell.items-center(text 在 cell vertical center)。\n        //   Q2 symptom?:`h-field-md` 32px 在 autoRow tall cell + cell items-start → Field 32px\n        //              sitting at top,inside items-center default → text center = top+15 ≠ top。\n        //              即使 `group-data-[row-mode=auto]/cell:!items-start` 加進來,Field height\n        //              還是 32 → text 在 Field 內 top,但 Field 自己 height ≠ 0,offset 13~32px。\n        //   Q3 fix layer?:root-layer fix = Field 在 autoRow context 必 `h-auto` 才能讓 text 真正\n        //                  flush 到 cell.top + padding。前 v1 只 remove `!h-full` 是 surface-fix\n        //                  (沒解決 h-field-md 32px persistence)。v2 真根因 fix:加 `!h-auto`\n        //                  override h-field-md → Field intrinsic line-height → cell items-start\n        //                  真實 anchor text at cell.top + padding。\n        // Edit mode 不動(`!h-full` 保留 — border 必滿格對齊 cell border)。\n        mode: 'display',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n      {\n        mode: 'readonly',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n      {\n        // 2026-05-13 Q3 fix(per codex Q3 verdict + color.spec.md:729 逃生艙 rule):\n        // 移除 `opacity-disabled` blanket — naked wrapper 只負責 substrate(透明 border + 抑制 cursor),\n        // 內部 content(text / icon / avatar)各自 disabled context 處理(text-fg-disabled / Avatar opacity 等具體 token)。\n        // 對齊 DataTable cell-disabled TD 加 `bg-disabled` 表達 cell-level disabled state 的 SSOT 分權。\n        // **default/bare disabled variant(line 107, 135)deferred R3.5** — 仍依賴 wrapper opacity-disabled\n        // for Avatar dim(Avatar 尚未 fieldCtx-aware self-dim);Avatar self-dim 實作後再連帶移除。\n        mode: 'disabled',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none cursor-not-allowed !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n    ],\n    defaultVariants: {\n      mode: 'edit',\n      variant: 'default',\n      size: 'md',\n    },\n  }\n)\n\n// ── Bare Input Styles ───────────────────────────────────────────────────────\n\nexport const bareInputStyles = [\n  // 2026-05-15 Q1 真 root cause fix(per codex Round 4 cite-based verdict):\n  // 加 `truncate` — 原 bareInputStyles 含 `flex-1 min-w-0` 但無 `truncate / text-overflow` policy。\n  // 當 Select `searchable && open` 切 raw `<input placeholder=...>` branch(select.tsx:178),\n  // bareInputStyles 套上,placeholder 無 ellipsis → narrow cell(<160px)硬裁無 `...`(user round 3\n  // 圖一證據)。加 truncate 後 `<input>` `text-overflow: ellipsis` 啟動,符合 user 「placeholder 直接被截掉沒有變...」\n  // 該顯 ellipsis 的 SSOT。對齊 data-table.spec.md:233「禁硬裁無 ellipsis」+ field-controls.spec.md:286\n  // 共享 contract(a)「display/readonly/disabled/edit 4 mode 共享同一 renderer」semantic 對齊。\n  'flex-1 min-w-0 truncate bg-transparent',\n  'outline-none border-none p-0',\n  'text-[inherit] font-[inherit] leading-[inherit]',\n  // A3 fix(2026-05-05):`<input>` UA stylesheet 強制 `text-align: start`,阻斷 parent 的\n  //   `text-right`/`text-center` 繼承。顯式 `text-align: inherit` 復原(對齊 NumberCell /\n  //   CurrencyCell right-align canonical:column meta.align='right' → cell text-right →\n  //   input 跟著 right-align)。\n  '[text-align:inherit]',\n  'placeholder:text-fg-muted',\n  // K10 fix(2026-05-04):wrapper data-field-mode=disabled 時,placeholder/text 都切 fg-disabled\n  //   依賴 fieldWrapperStyles 的 `group/field` + 各 Field 元件 wrapper 加 `data-field-mode={resolvedMode}`\n  //   User canonical:disabled state 顯著性優於 muted(neutral-6 > neutral-7)\n  'group-data-[field-mode=disabled]/field:placeholder:text-fg-disabled',\n  'group-data-[field-mode=disabled]/field:text-fg-disabled',\n].join(' ')\n\n// ── Naked Variant Cell Row-Mode Alignment Propagation ──────────────────────\n// SSOT canonical(M19 / 2026-05-05):cell-as-input naked variant 元件**所有內部\n// wrapper**(`<span>` 包 Avatar+name 等)必 import + apply 此 SSOT,host cell\n// `data-row-mode` 屬性自動 propagate alignment(autoRow → items-start / fixed → items-center)。\n//\n// 不 propagate 的後果:autoRow 場景下 People / Select / Combobox 內部用\n// `inline-flex items-center` hardcode → 視覺垂直置中於 wrapper 自身高度,**沒**頂對齊\n// → 跟其他純文字 cell baseline 視覺漂移。\n//\n// 世界級對照:\n//   - HTML <td> default `vertical-align: baseline`(瀏覽器自動 first-baseline align)\n//   - AG Grid `cellStyle` + `cellRendererSelector`,row context 共享(closed source 部分)\n//   - Material X-Grid `gridClasses.cell` wrapper 不允許 cell content override alignment\n//   - Notion / Airtable cell content 從 host 繼承,不 hardcode self alignment\n//\n// Hook:`check_naked_row_mode_propagation.sh`(write-time BLOCKER)\n// Audit:design-system-audit Group N M27(periodic batch verify)\nexport const nakedCellRowModeAlign = 'group-data-[row-mode=auto]/cell:items-start'\n\n// ── Cell-as-input Display Hover Ring(2026-05-05 v9 — sole remaining ring const)─\n// editable cell **display mode hover 提示**(「這 cell 可編,點 → 進 edit」affordance 信號)。\n// 對齊 Notion / Airtable hover-cell-shows-border canonical。\n//\n// **為何只剩這一個**:Field naked **edit/focus/open state ring 已下沉到 Field default state\n// machine**(border-based,2026-05-05 v9 architectural rewrite),不需 outline 平行系統;\n// 但 display mode 沒 Field state(display = 純展示無互動),hover 提示需 cell wrapper 自加。\n//\n// **2026-05-09 v15.17 revert v15.16(user 未同意 ship)— 維持 v15.13 outline+offset:-1**\n//\n// User 2026-05-09 後續 message:「設計決策的東西你應該要先問過我讓我決策吧?為什麼就直接開跑」\n// 我 commit 698ff58 ship v15.16(box-shadow inset Spec 2 不蓋 grid)= 設計決策結論未 user 同意\n// 直接 ship = workflow 違反。Revert 回 v15.13 outline+offset:-1(原 user-accepted 路徑),\n// 等 user 拍板 4-邊覆蓋路徑才 ship。\n//\n// User 並指出我視覺分析又錯:「我就是只有看到只有右邊被蓋掉,上面下面左邊都會露出 cell 的邊框」\n// 我之前錯說「right + bottom 都覆蓋」,bottom 真實 row border-b 在 cell.outer 外 1px,outline 蓋不到。\n//\n// 真實 4-邊狀態(re-verified):\n//   - right: outline 199-200 = cell own border-r 199-200 → 蓋 1 條線 ✓\n//   - top: outline 0-1,前一 row border-b 在 cell.outer 外 → 露 2 條線\n//   - bottom: outline 38-39 在 cell 內,row border-b 在 row.outer 內 = cell.outer 外 1px → 露 2 條線\n//   - left: outline 0-1,前一 cell border-r 在 cell.outer 外 → 露 2 條線\n//\n// User 想要 4 邊都覆蓋 = 等 codex unframed brief + user 拍板,本次不 ship。\n//\n// 之前 v15.13 / 14 / 16 / 17 緣由 → tsc comment 之前版本 + planning RFC\n// (跑錯方向 4 次 = 沒 1 次 verify 全面向 + 沒 user 拍板 set design)。\n//\n// Color `--border-hover` 對齊 Field default hover state token。\n//\n// **2026-05-10 Slice D Step 2 — Cell host CSS variable suppression**:\n// outline color 改用 `var(--cell-hover-outline-color, var(--border-hover))`,\n// allow DataTable cell host(spreadsheet overlay enabled 時)set `--cell-hover-outline-color: transparent`\n// 抑制 outline,讓 overlay layer 接管 hover ring paint(per RFC Contract 8 「one geometry owner, two paint owners」)。\n// Backward-compat:flag 關時 default `--border-hover`,既有行為不變。\nexport const nakedCellEditableDisplayHover = 'hover:outline hover:outline-1 hover:outline-offset-[-1px] hover:outline-[var(--cell-hover-outline-color,var(--border-hover))]'\n\n// ── Cell-as-input Edge Slot SSOT(2026-05-05 v8 — retire 平行 SSOT,改 L1 消費)───\n//\n// 前身 `nakedCellPrefixSlot` / `nakedCellSuffixSlot` 是 M1+M17 違反:平行 SSOT 跟\n// `patterns/element-anatomy` 的 `<ItemPrefix>` / `<ItemSuffix>` primitive 撞 home。\n// 已 retire — Field naked variant 內 prefix / suffix slot 直接消費 L1 primitive:\n//\n//   import { ItemPrefix, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'\n//   <ItemPrefix><StartIcon /></ItemPrefix>     // 對 Input.startIcon / Select.startIcon\n//   <ItemSuffix>{chevron}</ItemSuffix>          // 對 Combobox / DatePicker / PeoplePicker chevron\n//\n// **`h-[1lh]` 普世正確**(item-anatomy.spec.md:190-191 verbatim):\n//   - 單行 wrapper items-center → slot 1lh 在 cell 高度中心 = 第一行中線(視覺 = items-center)\n//   - 多行 wrapper items-start  → slot 1lh 鎖頂 = 第一行中線\n//   不需 conditional `group-data-[row-mode=auto]/cell:` — 我前 v4 自加的 conditional 是過度設計。\n//\n// State ring 3 const 仍留(下方)— 是 Field naked 專屬,MenuItem / TreeView 用 bg hover 不用 outline。\n// `nakedCellRowModeAlign`(wrapper 級)仍留 — 是 cell-context row-mode → wrapper alignment 適配,正交 slot 級。\n\n// ── Empty Value Display ─────────────────────────────────────────────────────\n\nexport const EMPTY_DISPLAY = '—'\n\n/**\n * 2026-05-14 I2 fix(per field-controls.spec.md contract (e) display typography canonical):\n * Field family display path bare-span helper — `sm/md → text-body` / `lg → text-body-lg`,\n * 跨 9 元件 display 視覺尺寸統一(user 抓 LinkInput 字體跟其他 Field 不一致 = SSOT 違反)。\n * Consumer:LinkInput / Select / Combobox / DatePicker / TimePicker non-D-path bare-span 套此 class。\n */\nexport const fieldDisplayTextClass = (size: 'sm' | 'md' | 'lg'): string =>\n  size === 'lg' ? 'text-body-lg' : 'text-body'\n"],"names":[],"mappings":"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"}

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

@@ -66,8 +66,8 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     /**
      * Control area 佈局模型(逃生艙)。
      *
-     * 預設由 Field 自動偵測——讀第一個 control child 的 `type.fieldLayout` static 屬性,
-     * primitive 沒宣告時視為 `'inline'`。
+     * 預設由 Field 自動偵測——迭代全部 control child 的 `type.fieldLayout` static 屬性,
+     * 任一宣告為 `'block'` 即整個 area 切 block(first-block-wins);全部缺宣告時視為 `'inline'`。
      *
      * 只有兩種情況需要手動指定:
      * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`
@@ -124,4 +124,6 @@ export declare const fieldMeta: {
     };
 };
 export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup };
+export { useFormValidation } from './use-form-validation';
+export type { UseFormValidationOptions, UseFormValidationReturn, FormFieldInputProps } from './use-form-validation';
 //# sourceMappingURL=field.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAA;AAqDlI,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAClF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAA;CACnC;AAWD,QAAA,MAAM,KAAK,mFA2JV,CAAA;AAKD,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC;IAClF;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAGD,QAAA,MAAM,UAAU,0FA2Ff,CAAA;AAKD,QAAA,MAAM,gBAAgB,yHAsBpB,CAAA;AAKF,QAAA,MAAM,UAAU,yHAqBd,CAAA;AAOF,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC3E,uCAAuC;IACvC,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IACpC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,QAAA,MAAM,UAAU,wFAkBf,CAAA;AAKD,eAAO,MAAM,SAAS;;;;;;;;;;;CAeZ,CAAA;AAEV,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAA;AAqDlI,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAClF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAA;CACnC;AAWD,QAAA,MAAM,KAAK,mFA2JV,CAAA;AAKD,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC;IAClF;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAGD,QAAA,MAAM,UAAU,0FA8Ff,CAAA;AAKD,QAAA,MAAM,gBAAgB,yHAsBpB,CAAA;AAKF,QAAA,MAAM,UAAU,yHAqBd,CAAA;AAOF,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC3E,uCAAuC;IACvC,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IACpC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,QAAA,MAAM,UAAU,wFAkBf,CAAA;AAKD,eAAO,MAAM,SAAS;;;;;;;;;;;CAeZ,CAAA;AAEV,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,CAAA;AAGtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/components/Field/field.js

@@ -184,6 +184,7 @@ const FieldLabel = React.forwardRef(
         style: { ...horizontalBlockStyle, ...style },
         "data-field-slot": "label",
         "data-field-disabled": disabled ? "" : void 0,
+        "aria-disabled": disabled || void 0,
         ...props,
         children: /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1", children: [
           /* @__PURE__ */ jsxs("span", { children: [

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

@@ -1 +1 @@
-{"version":3,"file":"field.js","sources":["../../../src/components/Field/field.tsx"],"sourcesContent":["// code-quality-allow: file-size — foundational composite(Field + FieldLabel + FieldDescription + FieldError + context + 8 layout variants),拆檔會讓 Field 家族互相 import 循環\nimport * as React from 'react'\nimport { Info as InfoIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'\n\n/**\n * Field — 表單欄位佈局容器（shadcn Field 風格）\n *\n * ── 定位 ────────────────────────────────────────────────────────────────\n * Field 只負責 **佈局 + 狀態 context**，不擁有任何資料型別邏輯。\n * 每個資料型別對應的 Control（Input、NumberInput、Checkbox、Switch 等）\n * 維持自己的 edit / readonly / disabled 三態，Field 透過 context 把\n * mode / disabled / required / invalid / id 傳給子元件，由子元件決定\n * 如何反映。\n *\n * ── 結構 ────────────────────────────────────────────────────────────────\n *   <Field orientation=\"vertical | horizontal\" labelWidth=\"120px\">\n *     <FieldLabel>姓名</FieldLabel>\n *     <Input value={...} onChange={...} />         ← Control（任何非 label/desc/error 的 child）\n *     <FieldDescription>...</FieldDescription>\n *     <FieldError>{errors.name}</FieldError>\n *   </Field>\n *\n *   Control 會自動包在 control area slot（min-h-field-* + items-center），\n *   確保 Checkbox / Switch / Radio 等高度 < field-height 的 primitive\n *   垂直對齊 Input 中線；Input 等自身為 field-height 的 primitive 填滿。\n *\n * ── Horizontal mode 的 label 垂直對齊 ───────────────────────────────────\n * FieldLabel 在 horizontal 模式下使用公式：\n *     padding-top: calc((var(--field-height-{size}) - 1lh) / 2)\n *\n * 單行 label → 文字第一行與 input 中線對齊（視覺置中）\n * 多行 label → 第一行仍與 input 中線對齊，其餘行往下流（label 高度超過\n *              input 時視覺上仍保持與 input 內容同一基準線）\n *\n * 此公式 tracks field-height 和 line-height 的變動，size 切換或字體\n * 調整時自動連動，不需 JS 測量。\n *\n * ── Horizontal mode 的 label 寬度 ───────────────────────────────────────\n * 透過 labelWidth prop → --field-label-width CSS variable，可以是任何\n * CSS length（\"120px\"、\"10rem\"、\"30%\" 等）。預設 \"auto\" 由 label 內容撐開。\n *\n * ── Required 星號 ──────────────────────────────────────────────────────\n * Field 的 required prop 會透過 context 傳給 FieldLabel 自動渲染 *，\n * 星號為 neutral-7（fg-muted），貼齊 label 文字（無 gap），disabled\n * 時降為 fg-disabled。也可在個別 FieldLabel 覆寫。\n */\n\n// ── Types & Context ──\n// Context 定義在 field-context.ts(打斷 circular import)。\n// field.tsx 只 import 不 re-export——consumer 直接從 field-context.ts import useFieldContext。\n\nimport type { FieldMode, FieldVariant, FieldOrientation, FieldSize, FieldControlLayout, FieldContextValue } from './field-context'\nimport { FieldContext, useFieldContext } from './field-context'\n\n// ── Internal helpers ────────────────────────────────────────────────────────\n\nconst MIN_H_CLASS: Record<FieldSize, string> = {\n  sm: 'min-h-field-sm',\n  md: 'min-h-field-md',\n  lg: 'min-h-field-lg',\n}\n\nconst FIELD_HEIGHT_VAR: Record<FieldSize, string> = {\n  sm: 'var(--field-height-sm)',\n  md: 'var(--field-height-md)',\n  lg: 'var(--field-height-lg)',\n}\n\n// Label / Description / Error 的字體固定 text-body (14px)，不隨 field size 變。\n// 世界級共識：field size 只影響 input 高度，不影響表單佈局元素的 typography。\nconst FIELD_TEXT_CLASS = 'text-body'\n\ntype SlotKind = 'label' | 'description' | 'error' | 'control'\n\nfunction resolveSlotKind(node: React.ReactNode): SlotKind {\n  if (!React.isValidElement(node)) return 'control'\n  const displayName = (node.type as { displayName?: string } | null | undefined)?.displayName\n  if (displayName === 'FieldLabel') return 'label'\n  if (displayName === 'FieldDescription') return 'description'\n  if (displayName === 'FieldError') return 'error'\n  return 'control'\n}\n\n/**\n * 偵測 control children 的 fieldLayout——任一 control 宣告為 'block' 即整個 area 切 block 模式。\n *\n * Convention：block primitive 在自己的元件檔案掛 static `fieldLayout = 'block'` 屬性,\n * Field 在 render 時讀 `child.type.fieldLayout`。預設 'inline'。\n *\n * 為什麼是「任一」而非「全部」：實務上 Field 一個 control area 通常只有一個 control,\n * 但若 consumer 同時放多個 child(例如 RadioGroup + 一段補充文字節點),只要其中有 block\n * primitive,整個 area 就應該以 block 模式佈局,確保第一行對齊正確。\n */\nfunction detectControlLayout(controlNodes: React.ReactNode[]): FieldControlLayout {\n  for (const node of controlNodes) {\n    if (!React.isValidElement(node)) continue\n    const layout = (node.type as { fieldLayout?: FieldControlLayout } | null | undefined)?.fieldLayout\n    if (layout === 'block') return 'block'\n  }\n  return 'inline'\n}\n\n// ── Field ───────────────────────────────────────────────────────────────────\n\nexport interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {\n  id?: string\n  mode?: FieldMode\n  /**\n   * 視覺外殼(2026-05-05)。\n   * - `default`(預設)— 含 border + bg(一般 form input)\n   * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)\n   *\n   * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。\n   */\n  variant?: FieldVariant\n  orientation?: FieldOrientation\n  size?: FieldSize\n  required?: boolean\n  disabled?: boolean\n  invalid?: boolean\n  /**\n   * Horizontal mode 的 label 欄寬度。支援任何 CSS length 值（\"120px\"、\"10rem\"、\"30%\"...）。\n   * 預設 'auto' 由 label 內容撐開。\n   */\n  labelWidth?: string\n  /**\n   * Control area 佈局模型(逃生艙)。\n   *\n   * 預設由 Field 自動偵測——讀第一個 control child 的 `type.fieldLayout` static 屬性,\n   * primitive 沒宣告時視為 `'inline'`。\n   *\n   * 只有兩種情況需要手動指定:\n   * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`\n   * 2. 想覆寫 primitive 的預設(如把 RadioGroup 強制 inline 呈現,罕見)\n   */\n  controlLayout?: FieldControlLayout\n}\n\n// ── FieldGroup Context(cascade horizontal labelWidth)──\n// 同一畫面多個 horizontal Field,label 寬度應統一對齊 → FieldGroup 提供 SSOT。\n// 下面 Field 組件自動 consume,consumer 可用 Field 的 labelWidth prop 覆寫單行。\ninterface FieldGroupContextValue {\n  horizontalLabelWidth?: string\n}\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FieldGroupContext = React.createContext<FieldGroupContextValue>({})\n\nconst Field = React.forwardRef<HTMLDivElement, FieldProps>(\n  (\n    {\n      id: idProp,\n      mode = 'edit',\n      variant = 'default',\n      orientation = 'vertical',\n      size = 'md',\n      required = false,\n      disabled: disabledProp = false,\n      invalid = false,\n      labelWidth,\n      controlLayout: controlLayoutProp,\n      className,\n      style,\n      children,\n      ...props\n    },\n    ref\n  ) => {\n    const generatedId = React.useId()\n    const id = idProp ?? generatedId\n    const labelId = `${id}-label`\n    const descriptionId = `${id}-description`\n    const errorId = `${id}-error`\n\n    // FieldGroup cascade:group 的 horizontalLabelWidth 是 fallback,單行 labelWidth 覆寫\n    const groupCtx = React.useContext(FieldGroupContext)\n    const effectiveLabelWidth = labelWidth ?? groupCtx.horizontalLabelWidth\n\n    // mode=disabled 與 disabled prop 任一為 true 即視為 disabled\n    const disabled = disabledProp || mode === 'disabled'\n\n    // 把 children 依 slot 類型分組\n    const labelNodes: React.ReactNode[] = []\n    const controlNodes: React.ReactNode[] = []\n    const descriptionNodes: React.ReactNode[] = []\n    const errorNodes: React.ReactNode[] = []\n\n    React.Children.forEach(children, (child) => {\n      const slot = resolveSlotKind(child)\n      if (slot === 'label') labelNodes.push(child)\n      else if (slot === 'description') descriptionNodes.push(child)\n      else if (slot === 'error') errorNodes.push(child)\n      else controlNodes.push(child)\n    })\n\n    // 解析 control layout：consumer 顯式指定 > primitive 自我宣告 > 預設 inline\n    const controlLayout: FieldControlLayout =\n      controlLayoutProp ?? detectControlLayout(controlNodes)\n\n    const contextValue = React.useMemo<FieldContextValue>(\n      () => ({\n        id,\n        labelId,\n        descriptionId,\n        errorId,\n        mode,\n        variant,\n        disabled,\n        required,\n        invalid,\n        size,\n        orientation,\n        controlLayout,\n        hasFieldWrapper: true,\n      }),\n      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]\n    )\n\n    // Control area：兩種佈局模型,「第一行內容中線」都錨在 field-height/2,\n    // 跟 FieldLabel 在 horizontal 模式下的 padding-top 公式自然對齊。\n    //\n    // - inline: min-h-field-{size} + items-center\n    //   單行 control(Input、Button 等)中線置中於 min-h box。\n    //\n    // - block:  flex-col + items-start + padding-top: calc((field-height - 1lh) / 2)\n    //   多行 control(RadioGroup 等),第一行往下推到 field-height 中線,\n    //   後續 item 自然往下流。不設 min-h(內容自己決定高度)。\n    // Block control area 不加額外 paddingTop——block primitive(RadioGroup 等)\n    // 的子元件(SelectionItem)已自帶 py = calc((field-height - 1lh) / 2),\n    // 第一個 item 的文字自然落在 field-height/2。額外加 paddingTop 會 double padding。\n    const controlArea =\n      controlLayout === 'block' ? (\n        <div\n          className=\"flex flex-col items-start min-w-0\"\n          data-field-slot=\"control\"\n          data-field-control-layout=\"block\"\n        >\n          {controlNodes}\n        </div>\n      ) : (\n        <div\n          className={cn('flex items-center min-w-0', MIN_H_CLASS[size])}\n          data-field-slot=\"control\"\n          data-field-control-layout=\"inline\"\n        >\n          {controlNodes}\n        </div>\n      )\n\n    // Horizontal：grid 兩欄，label 在左、content 欄堆疊（control → description → error）\n    if (orientation === 'horizontal') {\n      return (\n        <FieldContext.Provider value={contextValue}>\n          <div\n            ref={ref}\n            className={cn('grid gap-x-3 items-start', className)}\n            style={{\n              gridTemplateColumns: 'var(--field-label-width, auto) minmax(0, 1fr)',\n              ...(effectiveLabelWidth !== undefined\n                ? ({ ['--field-label-width' as string]: effectiveLabelWidth } as React.CSSProperties)\n                : undefined),\n              ...style,\n            }}\n            data-field-orientation=\"horizontal\"\n            data-field-mode={mode}\n            data-field-size={size}\n            data-field-disabled={disabled ? '' : undefined}\n            data-field-invalid={invalid ? '' : undefined}\n            {...props}\n          >\n            {labelNodes}\n            <div className=\"flex flex-col gap-1 min-w-0\">\n              {controlArea}\n              {descriptionNodes}\n              {errorNodes}\n            </div>\n          </div>\n        </FieldContext.Provider>\n      )\n    }\n\n    // Vertical（預設）：單欄 flex-col\n    return (\n      <FieldContext.Provider value={contextValue}>\n        <div\n          ref={ref}\n          className={cn('flex flex-col gap-1 min-w-0', className)}\n          style={style}\n          data-field-orientation=\"vertical\"\n          data-field-mode={mode}\n          data-field-size={size}\n          data-field-disabled={disabled ? '' : undefined}\n          data-field-invalid={invalid ? '' : undefined}\n          {...props}\n        >\n          {labelNodes}\n          {controlArea}\n          {descriptionNodes}\n          {errorNodes}\n        </div>\n      </FieldContext.Provider>\n    )\n  }\n)\nField.displayName = 'Field'\n\n// ── FieldLabel ──────────────────────────────────────────────────────────────\n\nexport interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {\n  /**\n   * 強制渲染 required 星號（覆寫 Field context 的 required）。\n   * 若未設定，預設讀 context。\n   */\n  required?: boolean\n  /**\n   * 在 label 文字後方顯示 info icon (ℹ)，hover 出現 tooltip 說明。\n   * 傳 string → tooltip 內容。\n   *\n   * Info icon 用 inline action pattern（補充工具，視覺退後），\n   * 因為 label 的 primary interaction 是 input，info 是補充說明。\n   */\n  info?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(\n  ({ className, required: requiredProp, info, htmlFor: htmlForProp, style, children, ...props }, ref) => {\n    const ctx = useFieldContext()\n    const required = requiredProp ?? ctx?.required ?? false\n    const disabled = ctx?.disabled ?? false\n    const htmlFor = htmlForProp ?? ctx?.id\n    const isHorizontal = ctx?.orientation === 'horizontal'\n    const controlLayout = ctx?.controlLayout ?? 'inline'\n    const size: FieldSize = ctx?.size ?? 'md'\n\n    // Horizontal 模式對齊策略 — 依 controlLayout 分兩套 (CSS-only, 不需 JS 測量)\n    //\n    // ── Inline control (Input / Button / Switch / SegmentedControl) ──\n    //   Control 有固定單行高度 = field-height,可以對齊中線。\n    //   策略: min-h-field-{size} + flex flex-col + justify-content: center\n    //\n    //   1) 短 label (總高 ≤ field-height):\n    //      min-h 生效 → 容器 = field-height → justify-center 把 label 垂直置中\n    //      第一行 top = (field-height - 1lh)/2 → 第一行中線對齊 control 中線 ✓\n    //   2) 長 label (總高 > field-height):\n    //      min-h 被內容撐大 → 容器 = label 總高 → justify-center 無作用(內容已填滿)\n    //      第一行 top = 0 → label top 對齊 control top ✓\n    //\n    // ── Block control (RadioGroup / CheckboxGroup) ──\n    //   Control 是多行群組,沒有「整體中線」可以對齊;錨點是「第一個 item 的第一行\n    //   中線永遠在 field-height/2」,由 SelectionItem 的 py 維持。\n    //   策略: padding-top = (field-height - 1lh)/2 — 把 label 第一行推到同樣位置。\n    //\n    //   這個策略對任何 label 長度都正確:label 第一行永遠與第一個 item 第一行對齊,\n    //   label 超出 control 時往下流(因為 block control 通常本來就很高,不會有\n    //   inline 模式那種「label 比 control 高」的視覺問題)。\n    //\n    // 內層 <span>: 只有 inline 策略需要(flex-col 會把 * 星號和 label 文字縱向堆疊,\n    // 必須包一層讓兩者 inline 同行)。block 策略可以不包,但為了 DOM 一致性一律包。\n    const horizontalInlineClass =\n      isHorizontal && controlLayout === 'inline'\n        ? cn('flex flex-col justify-center', MIN_H_CLASS[size])\n        : undefined\n\n    const horizontalBlockStyle: React.CSSProperties | undefined =\n      isHorizontal && controlLayout === 'block'\n        ? { paddingTop: `calc((${FIELD_HEIGHT_VAR[size]} - 1lh) / 2)` }\n        : undefined\n\n    return (\n      <label\n        ref={ref}\n        id={ctx?.labelId}\n        htmlFor={htmlFor}\n        className={cn(\n          FIELD_TEXT_CLASS,\n          'font-normal select-none',\n          disabled ? 'text-fg-disabled' : 'text-foreground',\n          horizontalInlineClass,\n          className\n        )}\n        style={{ ...horizontalBlockStyle, ...style }}\n        data-field-slot=\"label\"\n        data-field-disabled={disabled ? '' : undefined}\n        {...props}\n      >\n        <span className=\"inline-flex items-center gap-1\">\n          <span>\n            {required && (\n              <span\n                aria-hidden=\"true\"\n                className={disabled ? 'text-fg-disabled' : 'text-fg-muted'}\n              >\n                *\n              </span>\n            )}\n            {children}\n          </span>\n          {info && !disabled && (\n            <Tooltip>\n              <TooltipTrigger asChild>\n                <button\n                  type=\"button\"\n                  aria-label={info}\n                  className=\"inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer\"\n                >\n                  <InfoIcon size={16} aria-hidden />\n                </button>\n              </TooltipTrigger>\n              <TooltipContent>{info}</TooltipContent>\n            </Tooltip>\n          )}\n        </span>\n      </label>\n    )\n  }\n)\nFieldLabel.displayName = 'FieldLabel'\n\n// ── FieldDescription ────────────────────────────────────────────────────────\n\nconst FieldDescription = React.forwardRef<\n  HTMLParagraphElement,\n  React.HTMLAttributes<HTMLParagraphElement>\n>(({ className, children, id: idProp, ...props }, ref) => {\n  const ctx = useFieldContext()\n  const disabled = ctx?.disabled ?? false\n\n  return (\n    <p\n      ref={ref}\n      id={idProp ?? ctx?.descriptionId}\n      className={cn(\n        FIELD_TEXT_CLASS,\n        disabled ? 'text-fg-disabled' : 'text-fg-secondary',\n        className\n      )}\n      data-field-slot=\"description\"\n      {...props}\n    >\n      {children}\n    </p>\n  )\n})\nFieldDescription.displayName = 'FieldDescription'\n\n// ── FieldError ──────────────────────────────────────────────────────────────\n\nconst FieldError = React.forwardRef<\n  HTMLParagraphElement,\n  React.HTMLAttributes<HTMLParagraphElement>\n>(({ className, children, id: idProp, ...props }, ref) => {\n  const ctx = useFieldContext()\n\n  // 無內容不渲染，避免空殼佔位\n  if (children == null || children === false || children === '') return null\n\n  return (\n    <p\n      ref={ref}\n      id={idProp ?? ctx?.errorId}\n      className={cn(FIELD_TEXT_CLASS, 'text-error-text', className)}\n      data-field-slot=\"error\"\n      role=\"alert\"\n      {...props}\n    >\n      {children}\n    </p>\n  )\n})\nFieldError.displayName = 'FieldError'\n\n// ── FieldGroup ──────────────────────────────────────────────────────────────\n// 垂直堆疊多個 Field，共用 gap 節奏。\n// 用於表單中多個欄位排列。\n\nexport interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Field 之間的垂直間距，預設 'normal'（gap-4） */\n  gap?: 'compact' | 'normal' | 'loose'\n  /**\n   * 同一 group 內所有 horizontal Field 共用的 label 欄寬度。\n   *\n   * 支援任何 CSS length(`\"140px\"` / `\"10rem\"` / `\"30%\"` 等)。預設不指定——\n   * 每個 Field 自動以 label 內容撐開(容易歪七扭八)。\n   *\n   * 世界級 idiom:macOS System Settings / iOS Settings / GitHub Settings 的\n   * setting list 一律 label 固定寬、control 右對齊,列與列整齊對齊。\n   *\n   * 單一 Field 可以用自己的 `labelWidth` prop 覆寫 cascade 值。\n   */\n  horizontalLabelWidth?: string\n}\n\nconst FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(\n  ({ className, gap = 'normal', horizontalLabelWidth, ...props }, ref) => {\n    const gapClass = gap === 'compact' ? 'gap-3' : gap === 'loose' ? 'gap-6' : 'gap-4'\n    const groupCtxValue = React.useMemo(\n      () => ({ horizontalLabelWidth }),\n      [horizontalLabelWidth],\n    )\n    return (\n      <FieldGroupContext.Provider value={groupCtxValue}>\n        <div\n          ref={ref}\n          className={cn('flex flex-col min-w-0', gapClass, className)}\n          data-field-group=\"\"\n          {...props}\n        />\n      </FieldGroupContext.Provider>\n    )\n  }\n)\nFieldGroup.displayName = 'FieldGroup'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const fieldMeta = {\n  component: 'Field',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Field, FieldLabel, FieldDescription, FieldError, FieldGroup }\n"],"names":["InfoIcon"],"mappings":"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"}
+{"version":3,"file":"field.js","sources":["../../../src/components/Field/field.tsx"],"sourcesContent":["// code-quality-allow: file-size — foundational composite(Field + FieldLabel + FieldDescription + FieldError + context + 8 layout variants),拆檔會讓 Field 家族互相 import 循環\nimport * as React from 'react'\nimport { Info as InfoIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'\n\n/**\n * Field — 表單欄位佈局容器（shadcn Field 風格）\n *\n * ── 定位 ────────────────────────────────────────────────────────────────\n * Field 只負責 **佈局 + 狀態 context**，不擁有任何資料型別邏輯。\n * 每個資料型別對應的 Control（Input、NumberInput、Checkbox、Switch 等）\n * 維持自己的 edit / readonly / disabled 三態，Field 透過 context 把\n * mode / disabled / required / invalid / id 傳給子元件，由子元件決定\n * 如何反映。\n *\n * ── 結構 ────────────────────────────────────────────────────────────────\n *   <Field orientation=\"vertical | horizontal\" labelWidth=\"120px\">\n *     <FieldLabel>姓名</FieldLabel>\n *     <Input value={...} onChange={...} />         ← Control（任何非 label/desc/error 的 child）\n *     <FieldDescription>...</FieldDescription>\n *     <FieldError>{errors.name}</FieldError>\n *   </Field>\n *\n *   Control 會自動包在 control area slot（min-h-field-* + items-center），\n *   確保 Checkbox / Switch / Radio 等高度 < field-height 的 primitive\n *   垂直對齊 Input 中線；Input 等自身為 field-height 的 primitive 填滿。\n *\n * ── Horizontal mode 的 label 垂直對齊 ───────────────────────────────────\n * FieldLabel 在 horizontal 模式下使用公式：\n *     padding-top: calc((var(--field-height-{size}) - 1lh) / 2)\n *\n * 單行 label → 文字第一行與 input 中線對齊（視覺置中）\n * 多行 label → 第一行仍與 input 中線對齊，其餘行往下流（label 高度超過\n *              input 時視覺上仍保持與 input 內容同一基準線）\n *\n * 此公式 tracks field-height 和 line-height 的變動，size 切換或字體\n * 調整時自動連動，不需 JS 測量。\n *\n * ── Horizontal mode 的 label 寬度 ───────────────────────────────────────\n * 透過 labelWidth prop → --field-label-width CSS variable，可以是任何\n * CSS length（\"120px\"、\"10rem\"、\"30%\" 等）。預設 \"auto\" 由 label 內容撐開。\n *\n * ── Required 星號 ──────────────────────────────────────────────────────\n * Field 的 required prop 會透過 context 傳給 FieldLabel 自動渲染 *，\n * 星號為 neutral-7（fg-muted），貼齊 label 文字（無 gap），disabled\n * 時降為 fg-disabled。也可在個別 FieldLabel 覆寫。\n */\n\n// ── Types & Context ──\n// Context 定義在 field-context.ts(打斷 circular import)。\n// field.tsx 只 import 不 re-export——consumer 直接從 field-context.ts import useFieldContext。\n\nimport type { FieldMode, FieldVariant, FieldOrientation, FieldSize, FieldControlLayout, FieldContextValue } from './field-context'\nimport { FieldContext, useFieldContext } from './field-context'\n\n// ── Internal helpers ────────────────────────────────────────────────────────\n\nconst MIN_H_CLASS: Record<FieldSize, string> = {\n  sm: 'min-h-field-sm',\n  md: 'min-h-field-md',\n  lg: 'min-h-field-lg',\n}\n\nconst FIELD_HEIGHT_VAR: Record<FieldSize, string> = {\n  sm: 'var(--field-height-sm)',\n  md: 'var(--field-height-md)',\n  lg: 'var(--field-height-lg)',\n}\n\n// Label / Description / Error 的字體固定 text-body (14px)，不隨 field size 變。\n// 世界級共識：field size 只影響 input 高度，不影響表單佈局元素的 typography。\nconst FIELD_TEXT_CLASS = 'text-body'\n\ntype SlotKind = 'label' | 'description' | 'error' | 'control'\n\nfunction resolveSlotKind(node: React.ReactNode): SlotKind {\n  if (!React.isValidElement(node)) return 'control'\n  const displayName = (node.type as { displayName?: string } | null | undefined)?.displayName\n  if (displayName === 'FieldLabel') return 'label'\n  if (displayName === 'FieldDescription') return 'description'\n  if (displayName === 'FieldError') return 'error'\n  return 'control'\n}\n\n/**\n * 偵測 control children 的 fieldLayout——任一 control 宣告為 'block' 即整個 area 切 block 模式。\n *\n * Convention：block primitive 在自己的元件檔案掛 static `fieldLayout = 'block'` 屬性,\n * Field 在 render 時讀 `child.type.fieldLayout`。預設 'inline'。\n *\n * 為什麼是「任一」而非「全部」：實務上 Field 一個 control area 通常只有一個 control,\n * 但若 consumer 同時放多個 child(例如 RadioGroup + 一段補充文字節點),只要其中有 block\n * primitive,整個 area 就應該以 block 模式佈局,確保第一行對齊正確。\n */\nfunction detectControlLayout(controlNodes: React.ReactNode[]): FieldControlLayout {\n  for (const node of controlNodes) {\n    if (!React.isValidElement(node)) continue\n    const layout = (node.type as { fieldLayout?: FieldControlLayout } | null | undefined)?.fieldLayout\n    if (layout === 'block') return 'block'\n  }\n  return 'inline'\n}\n\n// ── Field ───────────────────────────────────────────────────────────────────\n\nexport interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {\n  id?: string\n  mode?: FieldMode\n  /**\n   * 視覺外殼(2026-05-05)。\n   * - `default`(預設)— 含 border + bg(一般 form input)\n   * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)\n   *\n   * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。\n   */\n  variant?: FieldVariant\n  orientation?: FieldOrientation\n  size?: FieldSize\n  required?: boolean\n  disabled?: boolean\n  invalid?: boolean\n  /**\n   * Horizontal mode 的 label 欄寬度。支援任何 CSS length 值（\"120px\"、\"10rem\"、\"30%\"...）。\n   * 預設 'auto' 由 label 內容撐開。\n   */\n  labelWidth?: string\n  /**\n   * Control area 佈局模型(逃生艙)。\n   *\n   * 預設由 Field 自動偵測——迭代全部 control child 的 `type.fieldLayout` static 屬性,\n   * 任一宣告為 `'block'` 即整個 area 切 block(first-block-wins);全部缺宣告時視為 `'inline'`。\n   *\n   * 只有兩種情況需要手動指定:\n   * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`\n   * 2. 想覆寫 primitive 的預設(如把 RadioGroup 強制 inline 呈現,罕見)\n   */\n  controlLayout?: FieldControlLayout\n}\n\n// ── FieldGroup Context(cascade horizontal labelWidth)──\n// 同一畫面多個 horizontal Field,label 寬度應統一對齊 → FieldGroup 提供 SSOT。\n// 下面 Field 組件自動 consume,consumer 可用 Field 的 labelWidth prop 覆寫單行。\ninterface FieldGroupContextValue {\n  horizontalLabelWidth?: string\n}\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FieldGroupContext = React.createContext<FieldGroupContextValue>({})\n\nconst Field = React.forwardRef<HTMLDivElement, FieldProps>(\n  (\n    {\n      id: idProp,\n      mode = 'edit',\n      variant = 'default',\n      orientation = 'vertical',\n      size = 'md',\n      required = false,\n      disabled: disabledProp = false,\n      invalid = false,\n      labelWidth,\n      controlLayout: controlLayoutProp,\n      className,\n      style,\n      children,\n      ...props\n    },\n    ref\n  ) => {\n    const generatedId = React.useId()\n    const id = idProp ?? generatedId\n    const labelId = `${id}-label`\n    const descriptionId = `${id}-description`\n    const errorId = `${id}-error`\n\n    // FieldGroup cascade:group 的 horizontalLabelWidth 是 fallback,單行 labelWidth 覆寫\n    const groupCtx = React.useContext(FieldGroupContext)\n    const effectiveLabelWidth = labelWidth ?? groupCtx.horizontalLabelWidth\n\n    // mode=disabled 與 disabled prop 任一為 true 即視為 disabled\n    const disabled = disabledProp || mode === 'disabled'\n\n    // 把 children 依 slot 類型分組\n    const labelNodes: React.ReactNode[] = []\n    const controlNodes: React.ReactNode[] = []\n    const descriptionNodes: React.ReactNode[] = []\n    const errorNodes: React.ReactNode[] = []\n\n    React.Children.forEach(children, (child) => {\n      const slot = resolveSlotKind(child)\n      if (slot === 'label') labelNodes.push(child)\n      else if (slot === 'description') descriptionNodes.push(child)\n      else if (slot === 'error') errorNodes.push(child)\n      else controlNodes.push(child)\n    })\n\n    // 解析 control layout：consumer 顯式指定 > primitive 自我宣告 > 預設 inline\n    const controlLayout: FieldControlLayout =\n      controlLayoutProp ?? detectControlLayout(controlNodes)\n\n    const contextValue = React.useMemo<FieldContextValue>(\n      () => ({\n        id,\n        labelId,\n        descriptionId,\n        errorId,\n        mode,\n        variant,\n        disabled,\n        required,\n        invalid,\n        size,\n        orientation,\n        controlLayout,\n        hasFieldWrapper: true,\n      }),\n      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]\n    )\n\n    // Control area：兩種佈局模型,「第一行內容中線」都錨在 field-height/2,\n    // 跟 FieldLabel 在 horizontal 模式下的 padding-top 公式自然對齊。\n    //\n    // - inline: min-h-field-{size} + items-center\n    //   單行 control(Input、Button 等)中線置中於 min-h box。\n    //\n    // - block:  flex-col + items-start(不設 min-h、不加 padding-top,內容自己決定高度)\n    //   多行 control(RadioGroup 等),第一行中線由 block primitive 自帶 py 推到\n    //   field-height/2,後續 item 自然往下流。\n    // Block control area 不加額外 paddingTop——block primitive(RadioGroup 等)\n    // 的子元件(SelectionItem)已自帶 py = calc((field-height - 1lh) / 2),\n    // 第一個 item 的文字自然落在 field-height/2。額外加 paddingTop 會 double padding。\n    const controlArea =\n      controlLayout === 'block' ? (\n        <div\n          className=\"flex flex-col items-start min-w-0\"\n          data-field-slot=\"control\"\n          data-field-control-layout=\"block\"\n        >\n          {controlNodes}\n        </div>\n      ) : (\n        <div\n          className={cn('flex items-center min-w-0', MIN_H_CLASS[size])}\n          data-field-slot=\"control\"\n          data-field-control-layout=\"inline\"\n        >\n          {controlNodes}\n        </div>\n      )\n\n    // Horizontal：grid 兩欄，label 在左、content 欄堆疊（control → description → error）\n    if (orientation === 'horizontal') {\n      return (\n        <FieldContext.Provider value={contextValue}>\n          <div\n            ref={ref}\n            className={cn('grid gap-x-3 items-start', className)}\n            style={{\n              gridTemplateColumns: 'var(--field-label-width, auto) minmax(0, 1fr)',\n              ...(effectiveLabelWidth !== undefined\n                ? ({ ['--field-label-width' as string]: effectiveLabelWidth } as React.CSSProperties)\n                : undefined),\n              ...style,\n            }}\n            data-field-orientation=\"horizontal\"\n            data-field-mode={mode}\n            data-field-size={size}\n            data-field-disabled={disabled ? '' : undefined}\n            data-field-invalid={invalid ? '' : undefined}\n            {...props}\n          >\n            {labelNodes}\n            <div className=\"flex flex-col gap-1 min-w-0\">\n              {controlArea}\n              {descriptionNodes}\n              {errorNodes}\n            </div>\n          </div>\n        </FieldContext.Provider>\n      )\n    }\n\n    // Vertical（預設）：單欄 flex-col\n    return (\n      <FieldContext.Provider value={contextValue}>\n        <div\n          ref={ref}\n          className={cn('flex flex-col gap-1 min-w-0', className)}\n          style={style}\n          data-field-orientation=\"vertical\"\n          data-field-mode={mode}\n          data-field-size={size}\n          data-field-disabled={disabled ? '' : undefined}\n          data-field-invalid={invalid ? '' : undefined}\n          {...props}\n        >\n          {labelNodes}\n          {controlArea}\n          {descriptionNodes}\n          {errorNodes}\n        </div>\n      </FieldContext.Provider>\n    )\n  }\n)\nField.displayName = 'Field'\n\n// ── FieldLabel ──────────────────────────────────────────────────────────────\n\nexport interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {\n  /**\n   * 強制渲染 required 星號（覆寫 Field context 的 required）。\n   * 若未設定，預設讀 context。\n   */\n  required?: boolean\n  /**\n   * 在 label 文字後方顯示 info icon (ℹ)，hover 出現 tooltip 說明。\n   * 傳 string → tooltip 內容。\n   *\n   * Info icon 用 inline action pattern（補充工具，視覺退後），\n   * 因為 label 的 primary interaction 是 input，info 是補充說明。\n   */\n  info?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(\n  ({ className, required: requiredProp, info, htmlFor: htmlForProp, style, children, ...props }, ref) => {\n    const ctx = useFieldContext()\n    const required = requiredProp ?? ctx?.required ?? false\n    const disabled = ctx?.disabled ?? false\n    const htmlFor = htmlForProp ?? ctx?.id\n    const isHorizontal = ctx?.orientation === 'horizontal'\n    const controlLayout = ctx?.controlLayout ?? 'inline'\n    const size: FieldSize = ctx?.size ?? 'md'\n\n    // Horizontal 模式對齊策略 — 依 controlLayout 分兩套 (CSS-only, 不需 JS 測量)\n    //\n    // ── Inline control (Input / Button / Switch / SegmentedControl) ──\n    //   Control 有固定單行高度 = field-height,可以對齊中線。\n    //   策略: min-h-field-{size} + flex flex-col + justify-content: center\n    //\n    //   1) 短 label (總高 ≤ field-height):\n    //      min-h 生效 → 容器 = field-height → justify-center 把 label 垂直置中\n    //      第一行 top = (field-height - 1lh)/2 → 第一行中線對齊 control 中線 ✓\n    //   2) 長 label (總高 > field-height):\n    //      min-h 被內容撐大 → 容器 = label 總高 → justify-center 無作用(內容已填滿)\n    //      第一行 top = 0 → label top 對齊 control top ✓\n    //\n    // ── Block control (RadioGroup / CheckboxGroup) ──\n    //   Control 是多行群組,沒有「整體中線」可以對齊;錨點是「第一個 item 的第一行\n    //   中線永遠在 field-height/2」,由 SelectionItem 的 py 維持。\n    //   策略: padding-top = (field-height - 1lh)/2 — 把 label 第一行推到同樣位置。\n    //\n    //   這個策略對任何 label 長度都正確:label 第一行永遠與第一個 item 第一行對齊,\n    //   label 超出 control 時往下流(因為 block control 通常本來就很高,不會有\n    //   inline 模式那種「label 比 control 高」的視覺問題)。\n    //\n    // 內層 <span>: 只有 inline 策略需要(flex-col 會把 * 星號和 label 文字縱向堆疊,\n    // 必須包一層讓兩者 inline 同行)。block 策略可以不包,但為了 DOM 一致性一律包。\n    const horizontalInlineClass =\n      isHorizontal && controlLayout === 'inline'\n        ? cn('flex flex-col justify-center', MIN_H_CLASS[size])\n        : undefined\n\n    const horizontalBlockStyle: React.CSSProperties | undefined =\n      isHorizontal && controlLayout === 'block'\n        ? { paddingTop: `calc((${FIELD_HEIGHT_VAR[size]} - 1lh) / 2)` }\n        : undefined\n\n    return (\n      <label\n        ref={ref}\n        id={ctx?.labelId}\n        htmlFor={htmlFor}\n        className={cn(\n          FIELD_TEXT_CLASS,\n          'font-normal select-none',\n          disabled ? 'text-fg-disabled' : 'text-foreground',\n          horizontalInlineClass,\n          className\n        )}\n        style={{ ...horizontalBlockStyle, ...style }}\n        data-field-slot=\"label\"\n        data-field-disabled={disabled ? '' : undefined}\n        // 2026-06-10 a11y:styled-disabled label 必明告 inactive(WCAG 1.4.3 inactive-UI 豁免需可機判;\n        // axe 對無 aria-disabled 的 fg-disabled 文字誤報 color-contrast — deep-audit 抓 8 筆)\n        aria-disabled={disabled || undefined}\n        {...props}\n      >\n        <span className=\"inline-flex items-center gap-1\">\n          <span>\n            {required && (\n              <span\n                aria-hidden=\"true\"\n                className={disabled ? 'text-fg-disabled' : 'text-fg-muted'}\n              >\n                *\n              </span>\n            )}\n            {children}\n          </span>\n          {info && !disabled && (\n            <Tooltip>\n              <TooltipTrigger asChild>\n                <button\n                  type=\"button\"\n                  aria-label={info}\n                  className=\"inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer\"\n                >\n                  <InfoIcon size={16} aria-hidden />\n                </button>\n              </TooltipTrigger>\n              <TooltipContent>{info}</TooltipContent>\n            </Tooltip>\n          )}\n        </span>\n      </label>\n    )\n  }\n)\nFieldLabel.displayName = 'FieldLabel'\n\n// ── FieldDescription ────────────────────────────────────────────────────────\n\nconst FieldDescription = React.forwardRef<\n  HTMLParagraphElement,\n  React.HTMLAttributes<HTMLParagraphElement>\n>(({ className, children, id: idProp, ...props }, ref) => {\n  const ctx = useFieldContext()\n  const disabled = ctx?.disabled ?? false\n\n  return (\n    <p\n      ref={ref}\n      id={idProp ?? ctx?.descriptionId}\n      className={cn(\n        FIELD_TEXT_CLASS,\n        disabled ? 'text-fg-disabled' : 'text-fg-secondary',\n        className\n      )}\n      data-field-slot=\"description\"\n      {...props}\n    >\n      {children}\n    </p>\n  )\n})\nFieldDescription.displayName = 'FieldDescription'\n\n// ── FieldError ──────────────────────────────────────────────────────────────\n\nconst FieldError = React.forwardRef<\n  HTMLParagraphElement,\n  React.HTMLAttributes<HTMLParagraphElement>\n>(({ className, children, id: idProp, ...props }, ref) => {\n  const ctx = useFieldContext()\n\n  // 無內容不渲染，避免空殼佔位\n  if (children == null || children === false || children === '') return null\n\n  return (\n    <p\n      ref={ref}\n      id={idProp ?? ctx?.errorId}\n      className={cn(FIELD_TEXT_CLASS, 'text-error-text', className)}\n      data-field-slot=\"error\"\n      role=\"alert\"\n      {...props}\n    >\n      {children}\n    </p>\n  )\n})\nFieldError.displayName = 'FieldError'\n\n// ── FieldGroup ──────────────────────────────────────────────────────────────\n// 垂直堆疊多個 Field，共用 gap 節奏。\n// 用於表單中多個欄位排列。\n\nexport interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Field 之間的垂直間距，預設 'normal'（gap-4） */\n  gap?: 'compact' | 'normal' | 'loose'\n  /**\n   * 同一 group 內所有 horizontal Field 共用的 label 欄寬度。\n   *\n   * 支援任何 CSS length(`\"140px\"` / `\"10rem\"` / `\"30%\"` 等)。預設不指定——\n   * 每個 Field 自動以 label 內容撐開(容易歪七扭八)。\n   *\n   * 世界級 idiom:macOS System Settings / iOS Settings / GitHub Settings 的\n   * setting list 一律 label 固定寬、control 右對齊,列與列整齊對齊。\n   *\n   * 單一 Field 可以用自己的 `labelWidth` prop 覆寫 cascade 值。\n   */\n  horizontalLabelWidth?: string\n}\n\nconst FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(\n  ({ className, gap = 'normal', horizontalLabelWidth, ...props }, ref) => {\n    const gapClass = gap === 'compact' ? 'gap-3' : gap === 'loose' ? 'gap-6' : 'gap-4'\n    const groupCtxValue = React.useMemo(\n      () => ({ horizontalLabelWidth }),\n      [horizontalLabelWidth],\n    )\n    return (\n      <FieldGroupContext.Provider value={groupCtxValue}>\n        <div\n          ref={ref}\n          className={cn('flex flex-col min-w-0', gapClass, className)}\n          data-field-group=\"\"\n          {...props}\n        />\n      </FieldGroupContext.Provider>\n    )\n  }\n)\nFieldGroup.displayName = 'FieldGroup'\n\n// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)\n// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs\nexport const fieldMeta = {\n  component: 'Field',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Field, FieldLabel, FieldDescription, FieldError, FieldGroup }\n\n// form-validation.spec.md 可執行層(per-component index gen 只 re-export 主檔,故經此公開)\nexport { useFormValidation } from './use-form-validation'\nexport type { UseFormValidationOptions, UseFormValidationReturn, FormFieldInputProps } from './use-form-validation'\n"],"names":["InfoIcon"],"mappings":"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"}

package/dist/components/Field/index.d.ts

@@ -0,0 +1,2 @@
+export * from './field';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Field/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Field/index.ts"],"names":[],"mappings":"AAIA,cAAc,SAAS,CAAA"}

package/dist/components/Field/index.js

@@ -0,0 +1,12 @@
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel, fieldMeta } from "./field.js";
+import { useFormValidation } from "./use-form-validation.js";
+export {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  fieldMeta,
+  useFormValidation
+};
+//# sourceMappingURL=index.js.map

package/dist/components/Field/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/components/Field/use-form-validation.d.ts

@@ -0,0 +1,88 @@
+/**
+ * useFormValidation — form-validation.spec.md 方法論的可執行層(SSOT executable arm)
+ *
+ * ── 定位 ──
+ * 把 `form-validation.spec.md` 的 9 條驗證方法論編成**不可配置的預設**——consumer 拿到就是
+ * canonical 行為,沒有 API 可以違反(M17「SSOT 必可傳播」:方法論從 prose 變 executable)。
+ *
+ * ── 實作基礎 ──
+ * 基於 react-hook-form(direct dependency,完全 wrapped 不外露——對齊 DS「基於 X」引擎慣例:
+ * DataTable 基於 TanStack / DatePicker 基於 react-day-picker / Toast 基於 sonner)。
+ * Consumer 不 install、不 import、看不到 RHF API。RHF 提供 values state / dirty 深比對 /
+ * errors store / resetField;驗證「時機」由本 hook own(RHF 的 mode/reValidateMode 不外露)。
+ *
+ * ── 與 Field 家族的關係(engine-agnostic 分層,field.spec.md「定位」段)──
+ * Field 保持純 layout + context(MUI FormControl 派,可用於 cell / display / 無引擎場景);
+ * 本 hook 住 form 層,錯誤經 consumer 一行 `<Field invalid={!!form.errors.x}>` 接入——
+ * Field 層零耦合。這是「A 派的自由 + B 派的 DX」混合位置。
+ *
+ * ── 方法論對應(form-validation.spec.md 規則 1-9)──
+ * 1 Focus 中不顯示錯誤     → 驗證只在 blur / submit 跑(無 onChange 驗證路徑)
+ * 2 Blur 時驗證            → getInputProps().onBlur 跑 validate[name]
+ * 3 Enter 等同 blur        → form 內 Enter 觸發 submit(全驗,超集);單行控件原生行為
+ * 4 Escape 取消回復原值    → getInputProps().onKeyDown Escape → resetField + 清 error
+ * 5 開始編輯立即清除 error → onChange 先清 errors[name](不論新值合法與否)
+ * 6 Blur 重新驗證          → 同 2(離開時重判)
+ * 7 Submit 驗證全部        → handleSubmit 對所有 validate keys 全跑(不依賴 blur 狀態)
+ * 8 Anchor 到第一個錯誤    → focus + scrollIntoView({block:'center'});每次 submit 重算
+ * 9 Async / 跨欄位 defer 到 submit → onSubmit 回傳 field-keyed errors → 同 8 anchor
+ * + Submit button:Create 永遠 enabled / Update disabled-until-dirty → `submitDisabled`
+ *
+ * ── v1 邊界(spec「可執行層」段 documented)──
+ * - getInputProps 支援 value/onChange 型控件(Input / Textarea / NumberInput / Select /
+ *   Combobox / DatePicker / TimePicker;onChange 收 event 或裸值皆可)。Checkbox / Switch
+ *   (onCheckedChange)consumer 自接 setFieldValue。
+ * - focus-first-error 以 DOM `name` 屬性定位(native input 生效;非 native 控件 fallback
+ *   scroll 略過,errors 視覺仍由 Field 紅框 + FieldError 呈現)。
+ */
+import * as React from 'react';
+import type { FieldValues } from 'react-hook-form';
+export interface UseFormValidationOptions<T extends FieldValues> {
+    /** 表單初始值(Update 場景 = 現有資料;dirty 比對基準) */
+    initialValues: T;
+    /**
+     * 表單意圖,驅動 submit button 狀態(form-validation.spec.md「Submit Button 狀態」):
+     * - 'create'(default):submitDisabled 永遠 false(不讓使用者猜「為什麼按不了」)
+     * - 'update':submitDisabled = !isDirty(沒改就不用存;變更還原回 pristine 即再 disabled)
+     */
+    intent?: 'create' | 'update';
+    /**
+     * 格式驗證(blur 層,規則 2):single-field 純 syntax(email 格式 / 必填 / URL)。
+     * 回傳 error 訊息字串 = 不合法;undefined = 合法。
+     * 業務 / async / 跨欄位驗證**不要**放這裡——放 onSubmit 回傳(規則 9)。
+     */
+    validate?: Partial<Record<keyof T, (value: T[keyof T], values: T) => string | undefined>>;
+    /**
+     * Submit handler(格式驗證全過後呼叫)。業務驗證(名稱重複 API / 跨欄位)在此判斷,
+     * 回傳 field-keyed error object(如 `{ name: '名稱已存在' }`)→ hook 自動 setError +
+     * anchor 到第一個錯誤(規則 9);回傳 undefined = 成功。
+     */
+    onSubmit: (values: T) => void | Partial<Record<keyof T, string>> | Promise<void | Partial<Record<keyof T, string>>>;
+}
+export interface FormFieldInputProps<V = unknown> {
+    name: string;
+    value: V;
+    onChange: (eventOrValue: unknown) => void;
+    onBlur: () => void;
+    onKeyDown: (e: React.KeyboardEvent) => void;
+}
+export interface UseFormValidationReturn<T extends FieldValues> {
+    /** 當前表單值(即時) */
+    values: T;
+    /** field-keyed 錯誤訊息(餵 `<Field invalid>` + `<FieldError>`) */
+    errors: Partial<Record<keyof T, string>>;
+    /** 任一欄位偏離 initialValues(深比對,還原回原值 = false) */
+    isDirty: boolean;
+    /** Submit button disabled 狀態(intent 驅動,見 options.intent) */
+    submitDisabled: boolean;
+    /** Spread 到 value/onChange 型控件:`<Input {...form.getInputProps('name')} />` */
+    getInputProps: <K extends keyof T & string>(name: K) => FormFieldInputProps<T[K]>;
+    /** 接 `<form onSubmit={form.handleSubmit}>`(規則 7/8/9) */
+    handleSubmit: (e?: React.FormEvent) => Promise<void>;
+    /** 整表重置回 initialValues(清 errors + dirty) */
+    reset: () => void;
+    /** Escape hatch:非 value/onChange 控件(Checkbox/Switch)手動寫值 */
+    setFieldValue: (name: keyof T & string, value: unknown) => void;
+}
+export declare function useFormValidation<T extends FieldValues>(options: UseFormValidationOptions<T>): UseFormValidationReturn<T>;
+//# sourceMappingURL=use-form-validation.d.ts.map

package/dist/components/Field/use-form-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-form-validation.d.ts","sourceRoot":"","sources":["../../../src/components/Field/use-form-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAkC,MAAM,iBAAiB,CAAA;AAElF,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,WAAW;IAC7D,yCAAyC;IACzC,aAAa,EAAE,CAAC,CAAA;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC,CAAA;IACzF;;;;OAIG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAA;CACpH;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,EAAE,CAAC,YAAY,EAAE,OAAO,KAAK,IAAI,CAAA;IACzC,MAAM,EAAE,MAAM,IAAI,CAAA;IAClB,SAAS,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAA;CAC5C;AAED,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,WAAW;IAC5D,gBAAgB;IAChB,MAAM,EAAE,CAAC,CAAA;IACT,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IACxC,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAA;IAChB,4DAA4D;IAC5D,cAAc,EAAE,OAAO,CAAA;IACvB,8EAA8E;IAC9E,aAAa,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACjF,wDAAwD;IACxD,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,4DAA4D;IAC5D,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CAChE;AA+BD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACrD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,uBAAuB,CAAC,CAAC,CAAC,CAuH5B"}

package/dist/components/Field/use-form-validation.js

@@ -0,0 +1,127 @@
+import * as React from "react";
+import { useForm } from "../../node_modules/react-hook-form/dist/index.esm.js";
+function extractValue(eventOrValue) {
+  if (eventOrValue && typeof eventOrValue === "object" && "target" in eventOrValue && eventOrValue.target && typeof eventOrValue.target === "object" && "value" in eventOrValue.target) {
+    return eventOrValue.target.value;
+  }
+  return eventOrValue;
+}
+function focusFirstError(errorNames) {
+  for (const name of errorNames) {
+    const el = document.getElementsByName(name)[0];
+    if (el) {
+      el.focus();
+      el.scrollIntoView({ block: "center", behavior: "smooth" });
+      return;
+    }
+  }
+}
+function useFormValidation(options) {
+  const { initialValues, intent = "create", validate, onSubmit } = options;
+  const form = useForm({
+    defaultValues: initialValues,
+    mode: "onSubmit",
+    shouldFocusError: false
+    // 規則 8 自己 focus(RHF 依賴 register ref,本 hook 不走 register)
+  });
+  const values = form.watch();
+  const { errors: rhfErrors, isDirty } = form.formState;
+  const errors = React.useMemo(() => {
+    var _a;
+    const out = {};
+    for (const key of Object.keys(rhfErrors)) {
+      const msg = (_a = rhfErrors[key]) == null ? void 0 : _a.message;
+      if (msg) out[key] = msg;
+    }
+    return out;
+  }, [rhfErrors]);
+  const validateField = React.useCallback(
+    (name) => {
+      const fn = validate == null ? void 0 : validate[name];
+      if (!fn) return;
+      const current = form.getValues();
+      const message = fn(current[name], current);
+      if (message) form.setError(name, { type: "format", message });
+      else form.clearErrors(name);
+    },
+    [form, validate]
+  );
+  const getInputProps = React.useCallback(
+    (name) => {
+      const path = name;
+      return {
+        name,
+        value: form.watch(path),
+        onChange: (eventOrValue) => {
+          if (form.getFieldState(path).error) form.clearErrors(path);
+          form.setValue(path, extractValue(eventOrValue), {
+            shouldDirty: true
+          });
+        },
+        // 規則 2:blur 驗證(focus 中永不驗 = 規則 1 自然成立)
+        onBlur: () => validateField(name),
+        // 規則 4:Escape 回復原值,不觸發驗證
+        onKeyDown: (e) => {
+          if (e.key === "Escape") {
+            form.resetField(path);
+            form.clearErrors(path);
+          }
+        }
+      };
+    },
+    [form, validateField]
+  );
+  const handleSubmit = React.useCallback(
+    async (e) => {
+      e == null ? void 0 : e.preventDefault();
+      const current = form.getValues();
+      const formatErrors = [];
+      if (validate) {
+        for (const name of Object.keys(validate)) {
+          const fn = validate[name];
+          if (!fn) continue;
+          const message = fn(current[name], current);
+          if (message) {
+            form.setError(name, { type: "format", message });
+            formatErrors.push(name);
+          } else {
+            form.clearErrors(name);
+          }
+        }
+      }
+      if (formatErrors.length > 0) {
+        focusFirstError(formatErrors);
+        return;
+      }
+      const businessErrors = await onSubmit(current);
+      if (businessErrors && typeof businessErrors === "object") {
+        const names = Object.keys(businessErrors).filter(
+          (k) => businessErrors[k] != null
+        );
+        for (const name of names) {
+          form.setError(name, {
+            type: "business",
+            message: businessErrors[name]
+          });
+        }
+        if (names.length > 0) focusFirstError(names);
+      }
+    },
+    [form, validate, onSubmit]
+  );
+  return {
+    values,
+    errors,
+    isDirty,
+    // Submit Button 狀態 canonical:Create 永遠 enabled / Update disabled-until-dirty
+    submitDisabled: intent === "update" ? !isDirty : false,
+    getInputProps,
+    handleSubmit,
+    reset: () => form.reset(),
+    setFieldValue: (name, value) => form.setValue(name, value, { shouldDirty: true })
+  };
+}
+export {
+  useFormValidation
+};
+//# sourceMappingURL=use-form-validation.js.map