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

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":["// @internal — DS-internal 單元(Field 家族 chrome 基底,consumer 用 Field/Input 等 wrapper 不直用);不隨 index.ts re-export 進 npm public surface。\n// @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'\nimport { cn } from '@/lib/utils'\n\n// ── Field Wrapper Styles ────────────────────────────────────────────────────\n// 所有 Field 元件共用的 input wrapper 樣式。\n//\n// 4 種模式(2026-05-05 expand;2026-07-16 round16 `display`→`view` 更名 + Model A):\n//   edit     — bg-surface, border, hover/focus 回饋(可編輯 input)\n//   view     — 純展示值(非表單);**Model A = edit 幾何減 chrome**(透明 bg/border,**保留 px 內距 + 高度**),\n//              故 read↔edit 零跳。對齊 Atlassian inline-edit(read=edit 幾何)+ Bootstrap plaintext(留 padding)。\n//   readonly — bg-readonly(neutral-2), 無邊框, 文字正常色(input chrome 但鎖定;token 獨立於 disabled)\n//   disabled — bg-disabled(neutral-2), 無邊框, 文字灰化\n//\n// 2 種視覺外殼(variant;2026-07-09 `bare` 退役後):\n//   default — 完整 chrome(form input 場景);view×default = edit 幾何減 chrome(留 px/py)\n//   naked   — cell-as-input substrate(DataTable);**edit×naked 自畫 border-based state machine**\n//              (border-border → hover:border-border-hover → focus-within:border-primary → error 紅框);\n//              view×naked = bare(host TD 給 padding)。**view×default ≠ view×naked**(不 collapse)。\n//              (2026-07-16 cell disabled 態廢除 → readonly×naked/disabled×naked 死格已移除)\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    // 2026-07-08 width 軸:`w-full` 從 base 移入 `width` variant(fill = 原行為 default,\n    // 零回歸;hug = w-fit 依內容收縮)。詳 field-controls.spec.md「寬度軸(width: fill / hug)」。\n    'inline-flex items-center min-w-0 rounded-md',\n    'text-foreground font-normal',\n    'transition-colors duration-150',\n  ],\n  {\n    variants: {\n      mode: {\n        edit: '',\n        view: '',\n        readonly: '',\n        disabled: '',\n      },\n      variant: {\n        // default — 完整 Field wrapper chrome(bg-surface、明顯 border、hover/focus 回饋)\n        default: '',\n        // naked — cell-as-input(Notion / Airtable / Excel canonical)。**edit×naked 自畫** border +\n        // hover:border-border-hover + focus-within:border-primary + error 紅框(v14 border-based state\n        // machine,見下方 compoundVariants L182-196);view×naked 用 transparent\n        // border 由 host cell 提供視覺邊框,內部 input 純文字承載。\n        // 世界級對照:Airtable / Notion / Excel / Google Sheets cell editing。\n        // (2026-07-09 `bare` variant 已退役 — 見 field-types.ts FieldVariant 註解;\n        //  被 import 的 `bareInputStyles` 常數是內層 input 重置樣式、與此不同物、保留。)\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      // width(2026-07-08 user 拍板,正交軸):寬度軸 — 只改寬度,chrome / hover / focus /\n      // error / mode compoundVariants 全部不動(user verbatim「框線和互動和樣式都不變,\n      // 只有寬度有變而已 … 把 field 和 value 的寬度都改成 hug」)。\n      //   fill(default)— `w-full` 填滿容器 = 與移軸前 base 完全等價(零回歸不變量)\n      //   hug — `w-fit` 依內容收縮:value 寬 + 各 slot 元素寬 + gap + field 內 padding;\n      //         `max-w-full` 保證窄容器不溢出(min-w-0 保留,仍可 truncate)\n      // Benchmark(M22):shadcn v4 SelectTrigger 預設 `w-fit`\n      //   https://raw.githubusercontent.com/shadcn-ui/ui/main/apps/v4/registry/new-york-v4/ui/select.tsx\n      //   Radix Select Trigger intrinsic sizing https://www.radix-ui.com/primitives/docs/components/select\n      width: {\n        fill: 'w-full',\n        hug: 'w-fit max-w-full',\n      },\n      // error(2026-07-04 Q1 拍板,SSOT 集中):原散在各控件的 error border classes 因\n      // focus-within:!border-primary(!important)被蓋 = dead code(聚焦永遠藍)。\n      // Benchmark 實查證偽舊宣稱:MUI(紅框加粗)/ Ant(紅框紅 glow)/ Polaris(紅 border\n      // + 獨立藍 focus ring)聚焦時 error 紅皆保留;唯一切藍的 Carbon 靠 in-field 紅 icon 補償。\n      // DS 邊框是唯一 error 載體 → error 勝 focus 的「顏色」通道。錯誤清除(edit-clears-error,\n      // useFormValidation)後自然回 focus 藍。\n      error: {\n        true: '',\n        false: '',\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          //\n          // 2026-07-04 Q1 拍板修訂:「focus dominates everything」對 error 讓位(見 error variant\n          // 註解)— focus 藍只在 error:false compound(下方),error:true 走 error compound 紅。\n          'data-[state=open]:border-border-hover',\n        ],\n      },\n      { mode: 'edit', variant: 'default', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },\n      {\n        // 2026-07-16 round16 Model A(user GO,推翻 2026-05-13 Path Ⅰ 的 `!px-0 !py-0`):\n        // view×default = **edit 幾何減 chrome** — 保留 size 軸的 `px-[var(--field-px)]` + `h-field-*`,\n        // 只拔 border/bg(透明)。理由 = view 用在 cell/inline-edit/詳情,要對齊的是「edit 的值位置」\n        // (非 label 左緣),故水平垂直都留 → view 與 edit 同一顆控件、只差 chrome → read↔edit 零跳。\n        // 世界級對照:Atlassian inline-edit(read=edit 幾何,靠容器負邊距對齊)+ Bootstrap\n        // `.form-control-plaintext`(`padding: $input-padding-y 0` 留 padding);我們比 Bootstrap 更徹底\n        // (連水平 px 也留),因用例是 align-to-edit 非 align-to-label。詳 field-controls.spec.md「軸一 view mode」\n        // + planning/2026-07-15-inline-edit-field-mode-remediation.md round16。\n        // ⚠️ view×default ≠ view×naked:naked = bare(cell substrate,host TD 給 padding);default = 留幾何。\n        mode: 'view',\n        variant: 'default',\n        className: 'bg-transparent border border-transparent',\n      },\n      {\n        mode: 'readonly',\n        variant: 'default',\n        // 2026-07-09 A11y fix(WCAG 2.4.7 Focus Visible):readonly **有值** 渲染 native `<input readOnly>`\n        // = 可 Tab 聚焦、可選取/複製,但原 compound 無任何 focus 指示 → 鍵盤使用者聚焦不可見 = 違反。\n        // 補 focus ring 採 **ring idiom**(`ring-2 ring-ring ring-offset-1`,與 Button/Checkbox/Tabs/\n        // Switch 同一套 focus-visible canonical;`--ring == --primary` semantic.css:334)而非 edit mode\n        // 的 `border-primary` idiom —— readonly 邊框 transparent 無可染;且 ring 語義 = 「可聚焦但非文字\n        // 輸入」(對齊 button/tab/checkbox 這類 focusable-非-text-entry 控件的視覺語言)。\n        // `:has(:focus-visible)`:readonly 渲 native `<input readOnly>`。⚠️ 瀏覽器對 text-entry 控件的\n        // :focus-visible 啟發式在滑鼠點擊時**亦 match**(text input 恆視為 focus-visible,對齊\n        // field-controls.spec.md「Focus 行為」段『文字輸入永遠 focus-visible、CSS 無法區分點擊與 Tab』),\n        // 故點擊 readonly input 也會顯 ring,勿宣稱僅鍵盤觸發(button 的 focus-visible 才滑鼠不觸發,\n        // input 不同;真要滑鼠抑制需 JS 追蹤 input modality,屬 API 擴充)。\n        className: 'bg-readonly border border-transparent [&:has(:focus-visible)]:ring-2 [&:has(:focus-visible)]:ring-ring [&:has(:focus-visible)]:ring-offset-1',\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      // (2026-07-09 `bare` variant 退役:原 edit×bare / edit×bare×error compounds 已移除。)\n      // error chrome(mode=edit 限定,variant 不分 — naked cell 內 error 同樣紅框,保留既有控件層行為):\n      {\n        mode: 'edit',\n        error: true,\n        className: 'border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error',\n      },\n      // (2026-07-09 `bare` variant 退役:原 display×bare / readonly×bare / disabled×bare compounds 已移除。)\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          // 2026-07-04 Q1:focus 藍移到 error:false compound,error:true 走共用 error compound)\n          'data-[state=open]:border-border-hover',\n          'group-data-[row-mode=auto]/cell:!items-start',\n        ],\n      },\n      { mode: 'edit', variant: 'naked', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },\n      {\n        // 2026-05-12 fix v2(M32 root invariant audit):\n        //   Q1 root invariant?:cell-as-input view 視覺位置 = `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        // 2026-07-16 round16:view×naked 保持 bare(cell substrate,host TD 給 padding)— 與 view×default\n        // (edit 幾何減 chrome、留 px/py)本質不同用途,**不 collapse**(round14 合併是錯的)。\n        mode: 'view',\n        variant: 'naked',\n        className: [\n          'bg-transparent !rounded-none !px-0 !py-0 !h-auto',\n          'border border-transparent',\n        ],\n      },\n      // 2026-07-16 round16:`readonly×naked` / `disabled×naked` 死格移除 —— DataTable cell 廢除\n      //   disabled 態(view 一律 mode=\"view\";displayOrDisabled helper 已刪)+ readonly 從不入 naked\n      //   路徑(全庫 0 消費)。軸對稱靠 cva 省略即天然覆蓋(base+size+透明),不需 dead compound 佔位。\n    ],\n    defaultVariants: {\n      mode: 'edit',\n      variant: 'default',\n      size: 'md',\n      width: 'fill',\n      error: false,\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)「view/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_field_family_invariants.sh` A.1(原 check_naked_row_mode_propagation.sh 已 folded,write-time BLOCKER)\n// Audit:design-system-audit Group N(periodic batch verify)\nexport const nakedCellRowModeAlign = 'group-data-[row-mode=auto]/cell:items-start'\n\n// ── Cell-as-input View Hover Ring(2026-05-05 v9 — sole remaining ring const)─\n// editable cell **view 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// 但 view mode 沒 Field state(view = 純展示無互動),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 唯一 const `nakedCellEditableDisplayHover` 仍留(下方 L332,見其自述「sole remaining ring const」)— 是 Field naked 專屬,MenuItem / TreeView 用 bg hover 不用 outline。\n// `nakedCellRowModeAlign`(wrapper 級)仍留 — 是 cell-context row-mode → wrapper alignment 適配,正交 slot 級。\n\n// ── Empty Value Display ─────────────────────────────────────────────────────\n\n// 2026-07-08 user 拍板(verbatim「我從頭到尾哪裡有說要用全形的」):空值符號 = **半形 hyphen\n// `-`(U+002D)**，非全形 em dash `—`(U+2014)。不可編輯(readonly / standalone view /\n// table 不可編輯 cell)空值一律此符號 + `text-fg-muted`。分流邏輯 SSOT = field-context.ts\n// `useFieldEmptyDisplay()`(table-cell 可編輯 → 空白；其餘 → 本常數)。\n// 世界級對照:Ant ProTable `columnEmptyText` 預設 `'-'`(U+002D 半形)\n//   https://github.com/ant-design/pro-components/blob/master/src/table/Table.tsx\nexport const EMPTY_DISPLAY = '-'\n\n/**\n * 2026-05-14 I2 fix(per field-controls.spec.md contract (e) view typography canonical):\n * Field family view path bare-span helper — `sm/md → text-body` / `lg → text-body-lg`,\n * 跨 9 元件 view 視覺尺寸統一(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\n/**\n * 2026-07-16 round16 Model A(user GO):Field view mode 幾何 SSOT(= view×default compound 的\n * 幾何部分,抽成 class helper 供 **InlineEdit 純值/標題路徑** 消費,避免 InlineEdit 自帶重複的\n * geometry cva〔M17 消重〕)。\n *\n * 回傳「edit 幾何減 chrome」的排版盒:\n *   - 水平:`px-[var(--field-px)]`(= edit 內距,靠 InlineEdit `-mx` 拉回欄左緣後,值落 edit 值位置)\n *   - 單行:`min-h-[var(--field-height-N)]` N∈{sm,md,lg} + `items-center`(垂直置中於 field 高度,= edit 單行)\n *   - 多行:`items-start` + `py-2`(頂對齊 + 上下內距,**= Textarea edit `py-2`**,textarea.tsx base;\n *     read↔edit 零跳)。⚠️ py-2 與 Textarea 同值 = SSOT 契約,`scripts/inline-edit-view-geometry-invariant.mjs`\n *     機械鎖(Textarea py 一改即紅)。\n *\n * 值-格式化路徑(Select→Tag / Date / avatar)**不用**此 helper —— 直接委派 `<Control mode=\"view\">`,\n * 幾何 + 內部間距皆由控件 view×default 提供(read=edit 同一顆 → 天生一致)。\n */\nexport const fieldViewGeometry = (size: 'sm' | 'md' | 'lg', multiline?: boolean): string =>\n  cn(\n    'flex w-full min-w-0 px-[var(--field-px)]',\n    size === 'sm' && 'min-h-[var(--field-height-sm)]',\n    size === 'md' && 'min-h-[var(--field-height-md)]',\n    size === 'lg' && 'min-h-[var(--field-height-lg)]',\n    // 多行 view py 必等於 Textarea edit py(同一 --field-control-py-* token),否則\n    // InlineEdit 多行 read↔edit 垂直跳位;scripts/inline-edit-view-geometry-invariant.mjs 機械鎖。\n    multiline && 'items-start',\n    multiline && size === 'sm' && 'py-[var(--field-control-py-sm)]',\n    multiline && size === 'md' && 'py-[var(--field-control-py-md)]',\n    multiline && size === 'lg' && 'py-[var(--field-control-py-lg)]',\n    !multiline && 'items-center',\n  )\n"],"names":[],"mappings":"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"}

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

@@ -48,7 +48,8 @@ export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, '
     /**
      * 視覺外殼(2026-05-05)。
      * - `default`(預設)— 含 border + bg(一般 form input)
-     * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)
+     * - `naked` — cell-as-input(@internal;不在公開 FieldVariant 型別 — 2026-07-14 收窄至 FieldVariantInternal;2026-07-09 `bare` 退役)。edit×naked 自畫 border-based state
+     *   machine(rest/hover/focus/error);view×naked 用 transparent border,host cell 提供視覺邊框
      *
      * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。
      */
@@ -66,8 +67,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'`
@@ -116,7 +117,7 @@ export declare const fieldMeta: {
     readonly family: null;
     readonly variants: {};
     readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default", "hover", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly [];
         readonly fg: readonly ["text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"];
@@ -124,4 +125,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;AAM9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAA;AAmElI,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;;;;;;;OAOG;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,mFA0KV,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,0FA+Ff,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;AAgBD,QAAA,MAAM,UAAU,wFAiBf,CAAA;AAKD,eAAO,MAAM,SAAS;;;;;;;;;;;CAgBZ,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

@@ -1,5 +1,6 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
+import { cva } from "class-variance-authority";
 import { Info } from "lucide-react";
 import { cn } from "../../lib/utils.js";
 import { Tooltip, TooltipTrigger, TooltipContent } from "../Tooltip/tooltip.js";
@@ -33,6 +34,15 @@ function detectControlLayout(controlNodes) {
   }
   return "inline";
 }
+function detectPreferredSize(controlNodes) {
+  var _a;
+  for (const node of controlNodes) {
+    if (!React.isValidElement(node)) continue;
+    const pref = (_a = node.type) == null ? void 0 : _a.fieldPreferredSize;
+    if (pref) return pref;
+  }
+  return null;
+}
 const FieldGroupContext = React.createContext({});
 const Field = React.forwardRef(
   ({
@@ -40,7 +50,7 @@ const Field = React.forwardRef(
     mode = "edit",
     variant = "default",
     orientation = "vertical",
-    size = "md",
+    size: sizeProp,
     required = false,
     disabled: disabledProp = false,
     invalid = false,
@@ -71,6 +81,14 @@ const Field = React.forwardRef(
       else controlNodes.push(child);
     });
     const controlLayout = controlLayoutProp ?? detectControlLayout(controlNodes);
+    const [registeredSize, setRegisteredSize] = React.useState(null);
+    const registerPreferredSize = React.useCallback((preferred) => {
+      setRegisteredSize((current) => current === preferred ? current : preferred);
+    }, []);
+    const detectedSize = detectPreferredSize(controlNodes);
+    const resolvedPreferredSize = sizeProp ?? detectedSize ?? registeredSize;
+    const size = resolvedPreferredSize ?? "md";
+    const sizeExplicit = resolvedPreferredSize != null;
     const contextValue = React.useMemo(
       () => ({
         id,
@@ -83,11 +101,13 @@ const Field = React.forwardRef(
         required,
         invalid,
         size,
+        sizeExplicit,
+        registerPreferredSize,
         orientation,
         controlLayout,
         hasFieldWrapper: true
       }),
-      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]
+      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, sizeExplicit, registerPreferredSize, orientation, controlLayout]
     );
     const controlArea = controlLayout === "block" ? /* @__PURE__ */ jsx(
       "div",
@@ -184,6 +204,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: [
@@ -203,7 +224,7 @@ const FieldLabel = React.forwardRef(
               {
                 type: "button",
                 "aria-label": info,
-                className: "inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer",
+                className: "inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer focus-visible:outline-2 focus-visible:outline-ring",
                 children: /* @__PURE__ */ jsx(Info, { size: 16, "aria-hidden": true })
               }
             ) }),
@@ -252,9 +273,20 @@ const FieldError = React.forwardRef(({ className, children, id: idProp, ...props
   );
 });
 FieldError.displayName = "FieldError";
+const fieldGroupVariants = cva("flex flex-col min-w-0", {
+  variants: {
+    gap: {
+      compact: "gap-3",
+      normal: "gap-4",
+      loose: "gap-6"
+    }
+  },
+  defaultVariants: {
+    gap: "normal"
+  }
+});
 const FieldGroup = React.forwardRef(
   ({ className, gap = "normal", horizontalLabelWidth, ...props }, ref) => {
-    const gapClass = gap === "compact" ? "gap-3" : gap === "loose" ? "gap-6" : "gap-4";
     const groupCtxValue = React.useMemo(
       () => ({ horizontalLabelWidth }),
       [horizontalLabelWidth]
@@ -263,7 +295,7 @@ const FieldGroup = React.forwardRef(
       "div",
       {
         ref,
-        className: cn("flex flex-col min-w-0", gapClass, className),
+        className: cn(fieldGroupVariants({ gap }), className),
         "data-field-group": "",
         ...props
       }
@@ -277,7 +309,8 @@ const fieldMeta = {
   // non-family composite / overlay / layout
   variants: {},
   sizes: {},
-  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  // 'active' 移除 — field-wrapper compoundVariants 無按壓態(TimePicker 2026-07-04 audit 同結論)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。
+  states: ["default", "hover", "focus-visible", "disabled"],
   tokens: {
     bg: [],
     fg: ["text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"],

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 { cva } from 'class-variance-authority'\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/**\n * 偵測 control child 的偏好尺寸——control primitive 在自己的檔案掛 static `fieldPreferredSize`\n * (如 InlineEdit = 'sm',view 態無邊框,md 過大會讓版面鬆散),Field 未顯式指定 size 時收此偏好。\n * 對齊 detectControlLayout 讀 `type.fieldLayout` 的機制(first-declared-wins);全部缺宣告 → null。\n */\nfunction detectPreferredSize(controlNodes: React.ReactNode[]): FieldSize | null {\n  for (const node of controlNodes) {\n    if (!React.isValidElement(node)) continue\n    const pref = (node.type as { fieldPreferredSize?: FieldSize } | null | undefined)?.fieldPreferredSize\n    if (pref) return pref\n  }\n  return null\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   * - `naked` — cell-as-input(@internal;不在公開 FieldVariant 型別 — 2026-07-14 收窄至 FieldVariantInternal;2026-07-09 `bare` 退役)。edit×naked 自畫 border-based state\n   *   machine(rest/hover/focus/error);view×naked 用 transparent border,host cell 提供視覺邊框\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: sizeProp,\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    // 解析 size：consumer 顯式 > control primitive 偏好(如 InlineEdit='sm')> 預設 md\n    //   (對齊 controlLayout 三層優先序;InlineEdit 進 Field 不指定 size 時自動收 sm)\n    // 靜態偵測只看得到直接子元件;包 wrapper / memo / HOC 時由 control 於掛載時註冊補位,\n    // 讓 Field 的控件槽高度也跟上(control 自身尺寸走 useResolvedFieldSize 同步解析)。\n    const [registeredSize, setRegisteredSize] = React.useState<FieldSize | null>(null)\n    const registerPreferredSize = React.useCallback((preferred: FieldSize) => {\n      setRegisteredSize((current) => (current === preferred ? current : preferred))\n    }, [])\n    const detectedSize = detectPreferredSize(controlNodes)\n    const resolvedPreferredSize = sizeProp ?? detectedSize ?? registeredSize\n    const size: FieldSize = resolvedPreferredSize ?? 'md'\n    const sizeExplicit = resolvedPreferredSize != null\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        sizeExplicit,\n        registerPreferredSize,\n        orientation,\n        controlLayout,\n        hasFieldWrapper: true,\n      }),\n      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, sizeExplicit, registerPreferredSize, 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                  // 弱化 icon hover 一階(inline-action.spec.md「Icon 色彩」;2026-07-30 前全 DS 唯一合規處)\n                  className=\"inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer focus-visible:outline-2 focus-visible:outline-ring\"\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\n// gap variant 收進 cva(className-only 差異 → cva,per ui-development.md「cva 適用」);值仍走 Tailwind gap utility。\nconst fieldGroupVariants = cva('flex flex-col min-w-0', {\n  variants: {\n    gap: {\n      compact: 'gap-3',\n      normal: 'gap-4',\n      loose: 'gap-6',\n    },\n  },\n  defaultVariants: {\n    gap: 'normal',\n  },\n})\n\nconst FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(\n  ({ className, gap = 'normal', horizontalLabelWidth, ...props }, ref) => {\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(fieldGroupVariants({ gap }), 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  // 'active' 移除 — field-wrapper compoundVariants 無按壓態(TimePicker 2026-07-04 audit 同結論)(2026-07-07 詞彙統一 DS-wide 按壓訊號盤點:檔內 0 active: utility / 0 *-active token)。\n  states: ['default', 'hover', '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,3 @@
+export * from './field';
+export * from './field-types';
+//# 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;AACvB,cAAc,eAAe,CAAA"}

package/dist/components/Field/index.js

@@ -0,0 +1,14 @@
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel, fieldMeta } from "./field.js";
+import { getMenuListMinHeight } from "./field-types.js";
+import { useFormValidation } from "./use-form-validation.js";
+export {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  fieldMeta,
+  getMenuListMinHeight,
+  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,92 @@
+/**
+ * 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 / view / 無引擎場景);
+ * 本 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`
+ * + Double-submit 防護(2026-07-05 D4):await onSubmit 期間重入直接忽略;`isSubmitting`
+ *   暴露餵 Button loading / disabled;onSubmit reject 先復位再原樣上拋(不吞錯)
+ *
+ * ── 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;submit 進行中一併 disabled) */
+    submitDisabled: boolean;
+    /** Submit 進行中(await onSubmit 期間 true)— 餵 Button loading;double-submit 防護的 state 面 */
+    isSubmitting: 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;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,kFAAkF;IAClF,cAAc,EAAE,OAAO,CAAA;IACvB,qFAAqF;IACrF,YAAY,EAAE,OAAO,CAAA;IACrB,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;AAoCD,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,EACrD,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GACnC,uBAAuB,CAAC,CAAC,CAAC,CA0I5B"}