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

package/src/components/FieldControlGroup/field-control-group.anatomy.stories.tsx

@@ -0,0 +1,119 @@
+// @anatomy-rationale: Inspector + ColorMatrix N/A — FieldControlGroup 是
+// self-contained layout-primitive(border-collapse 接合 N 個 Field child),
+// spec frontmatter `variants: {}` / `sizes: {}` / `traits: []`(明示 layout-primitive 無 trait variants)。
+// 無 cva color variant → ColorMatrix N/A;無 interactive prop control(僅 children layout)→ Inspector N/A。
+// 對齊 design-system-audit Dim 13 `@anatomy-rationale` 例外 marker(audit-prompts.md Dim 13;
+// 2026-07-04 修:原誤用 @story-trait-rationale — 那是 R3 trait escape,Dim 13 機械檢查認不得)。
+import type { Meta, StoryObj } from '@storybook/react'
+import { FieldControlGroup } from './field-control-group'
+import { Select } from '@/design-system/components/Select/select'
+import { Input } from '@/design-system/components/Input/input'
+import { OPERATOR_REGISTRY } from '@/design-system/components/DataTable/filter-operators'
+
+const meta: Meta<typeof FieldControlGroup> = {
+  title: 'Design System/Components/FieldControlGroup/設計規格',
+  component: FieldControlGroup,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof FieldControlGroup>
+
+const FIELDS = [
+  { value: 'sku', label: 'SKU' },
+  { value: 'name', label: '名稱' },
+]
+// op 選項消費 OPERATOR_REGISTRY SSOT(audit dim 32 — 禁 hardcode op 字串)
+const OPS = OPERATOR_REGISTRY.string
+  .filter((o) => ['is', 'contains'].includes(o.op))
+  .map((o) => ({ value: o.op, label: o.label }))
+
+/* Overview */
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-6 w-[520px]">
+      <section>
+        <h3 className="text-body font-bold mb-2">接合機制</h3>
+        <ul className="text-body text-fg-secondary list-disc pl-5 space-y-1">
+          <li>子 controls 保留自身 border + radius(不 strip)</li>
+          <li>鄰接子用 <code>margin-left: -1px</code> 重疊 border → 視覺 1 條線</li>
+          <li>z-index:default 2 / hover/focus 3 / disabled 0</li>
+          <li>first child 右 radii=0;middle 全 radii=0;last child 左 radii=0</li>
+        </ul>
+      </section>
+      <section>
+        <h3 className="text-body font-bold mb-2">範例</h3>
+        <FieldControlGroup block>
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Select className="!w-[100px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
+          <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
+        </FieldControlGroup>
+      </section>
+    </div>
+  ),
+}
+
+/* Export id 保留 corpus 穩定；此矩陣只改 child size，FieldControlGroup 本身沒有 size API。 */
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-6 w-[420px]">
+      {(['sm', 'md', 'lg'] as const).map(size => (
+        <div key={size}>
+          <p className="text-caption text-fg-muted mb-2">children size="{size}"（group 無 size prop）</p>
+          <FieldControlGroup block>
+            <Select size={size} className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+            <Input size={size} className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
+          </FieldControlGroup>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/* StateBehavior */
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-6 w-[420px]">
+      <div>
+        <p className="text-caption text-fg-muted mb-2">default</p>
+        <FieldControlGroup block>
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
+        </FieldControlGroup>
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-2">disabled(整 group children 各自 disabled)</p>
+        <FieldControlGroup block>
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} disabled aria-label="篩選欄位" />
+          <Input className="flex-1" defaultValue="無線滑鼠" disabled aria-label="篩選值" />
+        </FieldControlGroup>
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-2">cell error(其中一 child invalid → border-error;聚焦該 child 時才提升到 z-3 蓋過鄰接 border)</p>
+        <FieldControlGroup block>
+          <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Input className="flex-1" defaultValue="無線滑鼠" error aria-label="篩選值" />
+        </FieldControlGroup>
+      </div>
+    </div>
+  ),
+}
+
+/* Accessibility */
+export const Accessibility: Story = {
+  name: '無障礙與鍵盤',
+  render: () => (
+    <div className="flex flex-col gap-3 w-[420px]">
+      <p className="text-body">
+        Container 不加 ARIA role(透明 wrapper);children 各自 aria-label。Tab 鍵在 children 之間正常移動,no focus trap。
+      </p>
+      <FieldControlGroup block>
+        <Select className="!w-[120px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+        <Select className="!w-[100px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
+        <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
+      </FieldControlGroup>
+    </div>
+  ),
+}

package/src/components/FieldControlGroup/field-control-group.principles.stories.tsx

@@ -0,0 +1,121 @@
+// @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.
+import type { Meta, StoryObj } from '@storybook/react'
+import { Search } from 'lucide-react'
+import { FieldControlGroup } from './field-control-group'
+import { Field, FieldLabel, FieldGroup } from '@/design-system/components/Field/field'
+import { Select } from '@/design-system/components/Select/select'
+import { Input } from '@/design-system/components/Input/input'
+import { Button } from '@/design-system/components/Button/button'
+import { OPERATOR_REGISTRY } from '@/design-system/components/DataTable/filter-operators'
+
+const meta: Meta<typeof FieldControlGroup> = {
+  title: 'Design System/Components/FieldControlGroup/設計原則',
+  component: FieldControlGroup,
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof FieldControlGroup>
+
+const CODES = [{ value: '+886', label: '+886' }, { value: '+1', label: '+1' }]
+const FIELDS = [{ value: 'sku', label: 'SKU' }, { value: 'name', label: '名稱' }]
+// op 選項消費 OPERATOR_REGISTRY SSOT(audit dim 32 — 禁 hardcode op 字串)
+const OPS = OPERATOR_REGISTRY.string
+  .filter((o) => ['is', 'contains'].includes(o.op))
+  .map((o) => ({ value: o.op, label: o.label }))
+
+/* WhenToUse + WhenNotToUse + VsRule + ContentGuidelines = single UsageGuidance */
+export const UsageGuidance: Story = {
+  name: '使用準則',
+  render: () => (
+    <div className="flex flex-col gap-10 w-[640px]">
+      <section>
+        <h2 className="text-body-lg font-bold mb-3">何時用 ✓</h2>
+        <ul className="text-body text-fg-secondary list-disc pl-5 space-y-1">
+          <li>兩個語意連動的 control 視覺一體(電話 = 國碼 + 號碼)</li>
+          <li>Filter row(field + op + value)</li>
+          <li>Search input + Submit button</li>
+          <li>Range input(start + end + 中介符號)</li>
+        </ul>
+        <div className="mt-3">
+          <FieldControlGroup block>
+            <Input className="flex-1" startIcon={Search} placeholder="搜尋..." aria-label="搜尋" />
+            <Button variant="primary">搜尋</Button>
+          </FieldControlGroup>
+        </div>
+      </section>
+
+      <section>
+        <h2 className="text-body-lg font-bold mb-3">何時不用 ✗</h2>
+        <div className="grid grid-cols-2 gap-6">
+          <div>
+            <p className="text-body font-medium mb-2 text-error-text">❌ 多 fields 垂直排列</p>
+            <FieldGroup>
+              <Field><FieldLabel>姓名</FieldLabel><Input /></Field>
+              <Field><FieldLabel>Email</FieldLabel><Input /></Field>
+            </FieldGroup>
+            <p className="text-caption text-fg-muted mt-1">→ 用 FieldGroup,不是 FieldControlGroup</p>
+          </div>
+          <div>
+            <p className="text-body font-medium mb-2 text-error-text">❌ 不相關 controls 強行接合</p>
+            <p className="text-caption text-fg-muted">姓名 + 公司電話放同一 group 語意混亂 — 用 separate Field</p>
+          </div>
+        </div>
+      </section>
+
+      <section>
+        <h2 className="text-body-lg font-bold mb-3">FieldControlGroup vs FieldGroup</h2>
+        <div className="grid grid-cols-2 gap-4">
+          <div className="border border-divider rounded-md p-4">
+            <p className="text-body font-bold mb-2">FieldGroup(垂直堆疊)</p>
+            <ul className="text-body text-fg-secondary space-y-1">
+              <li>Scope:多個 Field</li>
+              <li>Direction:vertical</li>
+              <li>視覺:gap 分離</li>
+              <li>語意:表單 section</li>
+            </ul>
+          </div>
+          <div className="border border-divider rounded-md p-4">
+            <p className="text-body font-bold mb-2">FieldControlGroup(橫向接合)</p>
+            <ul className="text-body text-fg-secondary space-y-1">
+              <li>Scope:多個 control(1 Field 內)</li>
+              <li>Direction:horizontal</li>
+              <li>視覺:border collapse 接合</li>
+              <li>語意:複合 input(視覺一體)</li>
+            </ul>
+          </div>
+        </div>
+      </section>
+
+      <section>
+        <h2 className="text-body-lg font-bold mb-3">內容準則</h2>
+        <ul className="text-body text-fg-secondary list-disc pl-5 space-y-1">
+          <li>Children 同 size — 不混用 sm/md/lg(視覺高度需一致)</li>
+          <li>Children 自管 width — fixed selects + flex input 是典型 pattern</li>
+          <li>繼承 Field 尺寸(包進 Field):size 從 Field context 自動繼承,children 不傳 size</li>
+          <li>Children scope:Input / NumberInput / Select / Combobox / DatePicker / Button(對齊 Ant 限定 list)</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2 className="text-body-lg font-bold mb-3">繼承 Field 尺寸 — 包進 Field 當 control slot</h2>
+        <Field>
+          <FieldLabel>聯絡電話</FieldLabel>
+          <FieldControlGroup block>
+            <Select className="!w-[88px]" options={CODES} value="+886" onChange={() => {}} aria-label="國碼" />
+            <Input className="flex-1" placeholder="912 345 678" aria-label="電話號碼" />
+          </FieldControlGroup>
+        </Field>
+        <p className="text-caption text-fg-muted mt-2">Field label / description / error 對 group 整體生效;children 的 size 各自從外層 Field context 繼承(FCG 不傳遞 size)。</p>
+      </section>
+
+      <section>
+        <h2 className="text-body-lg font-bold mb-3">Standalone 逐一設尺寸 — Filter row 場景</h2>
+        <FieldControlGroup block>
+          <Select className="!w-[140px]" options={FIELDS} value="name" onChange={() => {}} aria-label="篩選欄位" />
+          <Select className="!w-[120px]" options={OPS} value="contains" onChange={() => {}} aria-label="篩選運算子" />
+          <Input className="flex-1" defaultValue="無線滑鼠" aria-label="篩選值" />
+        </FieldControlGroup>
+      </section>
+    </div>
+  ),
+}

package/src/components/FieldControlGroup/field-control-group.spec.md

@@ -12,15 +12,14 @@ benchmark:
   - Chakra UI Group + InputGroup: github.com/chakra-ui/chakra-ui/blob/main/apps/www/content/docs/components/input.mdx
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — Ant Space.Compact + Bootstrap input-group + Chakra Group claims verified via WebFetch + inline URL. -->
 
-# FieldControlGroup spec
+# FieldControlGroup 設計原則
 
 ## 定位
 
 **Layout Family**:self-contained(form composition layout-primitive,非 4-Family element layout — 對齊 frontmatter `family: self-contained`)。
 
-**多個 Field controls 視覺接合成一個 input frame**(border-collapse pattern)。對齊 ButtonGroup 同類接合 idiom — `<X>Group` 命名一致(X = button → ButtonGroup;X = field control → FieldControlGroup)。
+**多個 Field controls 視覺接合成一個 input frame**(border-collapse pattern)。命名對齊 ButtonGroup 的 `<X>Group` idiom(X = button → ButtonGroup;X = field control → FieldControlGroup),**但兩者機制不同**:ButtonGroup 是 gap 分離群組(`flex gap-2`,子按鈕之間留 8px),本元件才是 border-collapse 接合(負 margin 重疊 border,子無 gap)。
 
 **自建 + 理由**:無單一 Radix / shadcn 對應 primitive(shadcn 沒提供;Radix 沒對應)。對齊 [Ant `Space.Compact`](https://ant.design/components/space#spacecompact)(verified source)mechanism + [Bootstrap `.input-group`](https://getbootstrap.com/docs/5.3/forms/input-group/)(verified SCSS)idiom 自建。
 
@@ -46,13 +45,12 @@ benchmark:
 | `FieldGroup` | 多 Field 垂直堆疊 | gap 分離 | layout primitive |
 | **`FieldControlGroup`** | 多 control 橫向接合 | border collapse | layout primitive(本元件)|
 | `RadioGroup` / `CheckboxGroup` | 1 question 多 options | 各自獨立 | semantic group(ARIA role)|
-| `ButtonGroup` | 多 Button 接合 | border collapse | layout primitive(同 mechanism) |
+| `ButtonGroup` | 多 Button 分組 | gap 分離(`flex gap-2`) | layout primitive(**不同 mechanism**,非 border-collapse 接合) |
 
 ## API
 
 ```ts
 interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
-  size?: 'sm' | 'md' | 'lg'  // default 'md',Mode A 從 Field context 來
   block?: boolean             // 對齊 Ant Space.Compact `block`,默 false=inline-flex
 }
 ```
@@ -79,33 +77,36 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 ## Width 配置 canonical(W-A,對齊 Ant)
 
 **子 controls 自管 width**:
-- Fixed:`<Select className="w-[140px]">`
+- Fixed:`<Select className="!w-[140px]">`
 - Flex:`<Input className="flex-1">`
 - 混合 OK(filter row 典型:fixed + fixed + flex)
 
 **禁止**:不開 `Cell` wrapper(指 indirection 不必要;Ant Space.Compact 同樣不開)。
 
-## Size cascade
+## Size
 
-**Mode A**(包進 Field 當 control slot):
+**FCG 不暴露 `size` prop**:本元件只負責 border-collapse 接合(border / radius / z-index),不傳遞 size 給 children(無 Context Provider / 無 cloneElement)。未實作的 group-level size 不預佔 API。Children 的尺寸完全由 child 自己決定 — 以下三種來源:
+
+**繼承 Field 尺寸**(包進 Field 當 control slot):children 各自透過 `useFieldContext().size` 讀外層 `<Field>` 的 size(是 Field 的 context,不是 FCG 的)。
 ```tsx
-<Field>
+<Field size="lg">
   <FieldLabel>電話</FieldLabel>
-  <FieldControlGroup>  {/* size 自動繼承 Field context */}
-    <Select className="w-[80px]" options={codes} />
+  <FieldControlGroup>  {/* 各 child 自動繼承外層 Field context size */}
+    <Select className="!w-[80px]" options={codes} />
     <Input className="flex-1" />
   </FieldControlGroup>
 </Field>
 ```
 
-**Mode B**(standalone):
+**Standalone 逐一設尺寸**:**逐一給每個 child 設 `size`**。
 ```tsx
-<FieldControlGroup size="md">  {/* 顯式 size,默 md */}
-  ...
+<FieldControlGroup>
+  <Select size="md" className="!w-[120px]" options={fields} />
+  <Input size="md" className="flex-1" />
 </FieldControlGroup>
 ```
 
-**Mode C**(進 Popover,density 鎖 md):children 自然吃 md(Popover density canonical)。
+**Popover 鎖 md**(進 Popover,density 鎖 md):children 自然吃 md(Popover density canonical)。
 
 ## A11y 預設
 
@@ -135,9 +136,10 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 | default | 各 child 自身 border | 2 |
 | hover(子)| 該 child border-hover | 3 |
 | focus / focus-within(子)| 該 child focus ring | 3 |
-| disabled(子)| 該 child disabled style + **FCG-local override `border-input`**(K12,2026-05-04) | 0 |
+| disabled(子)| 該 child disabled style + **FCG-local override `border-[var(--border-opaque)]`**(K12,2026-05-04) | 0 |
+| error(子)| 該 child border-error | 2(預設層;聚焦該 child 時才升 3 蓋過鄰接 border)|
 
-**Disabled border integrity canonical(K12,2026-05-04)**:全域 disabled = `border-transparent`(讓 standalone field 視覺輕量),但**FCG context 下,disabled child 強制 `border-input`** — 確保:(a) FCG 整體外圈 border 健在,(b) inner divider 健在(不會因兩相鄰 disabled cells 都 transparent 而消失)。bg-disabled 仍區分狀態,border 維護群組視覺整合性。對齊 [Bootstrap input-group](https://getbootstrap.com/docs/5.3/forms/input-group/) / [Ant Space.Compact](https://ant.design/components/space#spacecompact) disabled idiom。
+**Disabled border integrity canonical(K12,2026-05-04)**:全域 disabled = `border-transparent`(讓 standalone field 視覺輕量),但**FCG context 下,disabled child 強制 `border-[var(--border-opaque)]`** — 確保:(a) FCG 整體外圈 border 健在,(b) inner divider 健在(不會因兩相鄰 disabled cells 都 transparent 而消失)。bg-disabled 仍區分狀態,border 維護群組視覺整合性。對齊 [Bootstrap input-group](https://getbootstrap.com/docs/5.3/forms/input-group/) / [Ant Space.Compact](https://ant.design/components/space#spacecompact) disabled idiom。
 
 實作(v7 — semantic token):
 ```tsx
@@ -145,12 +147,16 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 ```
 保留 global `bg-disabled`(neutral-2 灰底)— disabled state 視覺主要由 bg 承載。
 
+**⚠️ 選擇器覆蓋範圍(2026-07-13 誠實標註 — code 現況,非 uniform)**:disabled state 的兩道視覺處理走**不同選擇器、覆蓋不同 child 類型**,並非對所有 disabled 子一致生效:
+- **z-index 降 0**:`[&>*[disabled]]:z-0` + `[&>*:has([disabled])]:z-0` — 認**原生 `[disabled]` 屬性**。覆蓋 Button(原生 `<button disabled>`)、Input / NumberInput(wrapper 內含原生 `<input disabled>`,`:has()` 命中)。
+- **border-opaque override**:`[&>*[data-field-mode="disabled"]]` — 認 **Field 家族 wrapper 的 `data-field-mode="disabled"`**。覆蓋所有 Field controls(Select / Input / Combobox / DatePicker…)。
+- **覆蓋落差(已知)**:disabled **Select**(桌機自訂 trigger = `<div>`,無原生 `[disabled]`)→ 得 border-opaque 但**不降 z-0**;disabled **Button**(無 `data-field-mode`)→ 降 z-0 但**不得 border-opaque**。要讓兩道處理對所有 disabled 子一致覆蓋需統一兩選擇器(視覺行為改動 → 走設計拍板,非本文件範圍)。
+
 **為什麼用 `--border-opaque` 而非 `--border`**:`--border`(neutral-5 = 15% alpha)會跟 cell bg compositing — 灰底上 composite 略深(物理對比結果)。**`--border-opaque`** semantic token(其 primitive 後盾為 `--color-neutral-5-opaque`,solid #D9D9D9)不分 bg 永遠同色,divider 在 white edit cell 跟 grey disabled cell 上視覺完全一致。
 
-**Token 系統設計**:`--border-opaque` 在 `semantic.css` L289 新增,語意「視覺等同 `--border` 但 alpha-immune」。對齊 [Ant Design `colorBorderSecondary`](https://ant.design/docs/react/customize-theme#seedtoken) solid idiom — Ant 用此 token 在 table 外框 + row divider(non-white bg 場景),跟 input alpha border 視覺層級分。
+**Token 系統設計**:`--border-opaque` 在 `semantic.css` 新增(grep `--border-opaque:` 查定義行,不寫死行號避免漂移),語意「視覺等同 `--border` 但 alpha-immune」。對齊 [Ant Design `colorBorderSecondary`](https://ant.design/docs/react/customize-theme#seedtoken) solid idiom — Ant 用此 token 在 table 外框 + row divider(non-white bg 場景),跟 input alpha border 視覺層級分。
 
 **為什麼不 override bg**:user 明確要求 disabled cells 有底色(辨識 state)。bg 灰底是 disabled state 的主要視覺載體,FCG context 不應抹除。
-| error(子)| 該 child border-error | 3(error 視覺在最上)|
 
 **整 row error**:目前 v1 不支援 row-level error(走 cell-level)。未來若需可走 outer border-error wrapper,但 v1 follow Ant 不做。
 
@@ -159,6 +165,15 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 - Loading:子 control 各自處理(Input loading state / Select loading)
 - Empty:N/A(layout primitive,無資料概念)
 - 驗證:子 control 自管(form library 透過 Field 處理)
+- 「子必 direct child」規則**無 runtime 偵測**——違反(多包 wrapper div)時的症狀是圓角破圖(CSS `[&>*]` 命中 wrapper),見禁止事項 2026-05-04 #2;靠 review + Storybook 目視抓
+- a11y 驗證:Storybook a11y addon panel 0 critical violation;Tab 順序 = children DOM 順序
+
+## 邊界案例
+
+- **子高度不一**:容器 `items-stretch`,但 field controls 自帶固定 `h-field-*`,不會被拉齊——混 size 即視覺高低差(故禁止,見禁止事項)
+- **某子 disabled、某子 edit**:機制上可行(disabled 子降 z-0 + K12 border 維持 divider,實際覆蓋依 child 類型而異 — 見 K12「選擇器覆蓋範圍」note),但語意一體應一致(見禁止事項);**全組 disabled** 走 K12 canonical(見 States)
+- **極窄容器**:無特化處理——固定寬 children(`w-[Xpx]`)溢出容器、`flex-1` children 壓縮;子自管 width 的對價,consumer 自行配置
+- **單一 child**:radius 選擇器 `:first-child:not(:last-child)` 不命中,圓角完整保留(等同未包 group,但此時應直接用 Field)
 
 ## 世界級對照
 
@@ -171,6 +186,13 @@ interface FieldControlGroupProps extends HTMLAttributes<HTMLDivElement> {
 
 3/4 共識 → 我們的實作對齊 Ant + Bootstrap 主軸。
 
+## 相關
+
+- `../Field/field.spec.md` — FieldGroup(多 Field 垂直堆疊近親,gap 分離)的 home
+- `../Button/button-group.tsx` — 命名 idiom 近親(`<X>Group`);但 ButtonGroup 是 **gap 分離**(`flex gap-2`),非 border-collapse 接合,兩者機制不同(無獨立 spec)
+- `../Field/field-controls.spec.md` — children(Input / Select / DatePicker 等)共用 Field control 規則
+- `../Checkbox/checkbox.spec.md` / `../RadioGroup/radio-group.spec.md` — semantic group 近親(1 question 多 options,非本元件 scope)
+
 ## 變更紀錄
 
 - 2026-05-04 v1:Initial。基於 Ant compact-item.ts source verify 訂機制。Filter / Sort 對齊 Ant W-A 子自管 width。

package/src/components/FieldControlGroup/field-control-group.stories.tsx

@@ -0,0 +1,162 @@
+// @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.
+import React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Phone, Search } from 'lucide-react'
+import { FieldControlGroup } from './field-control-group'
+import { Field, FieldLabel, FieldDescription } from '@/design-system/components/Field/field'
+import { Select } from '@/design-system/components/Select/select'
+import { Input } from '@/design-system/components/Input/input'
+import { NumberInput } from '@/design-system/components/NumberInput/number-input'
+import { Button } from '@/design-system/components/Button/button'
+import { OPERATOR_REGISTRY } from '@/design-system/components/DataTable/filter-operators'
+
+const meta: Meta<typeof FieldControlGroup> = {
+  title: 'Design System/Components/FieldControlGroup/展示',
+  component: FieldControlGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: '用於將同一答案的多個 control 接合成一個視覺輸入框，例如國碼＋電話或幣別＋金額。彼此獨立的表單問題改用 FieldGroup，一題多選項改用 RadioGroup / Checkbox，只有單一 control 時直接用 Field。',
+      },
+    },
+    layout: 'padded',
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof FieldControlGroup>
+
+const COUNTRY_CODES = [
+  { value: '+886', label: '+886' },
+  { value: '+1',   label: '+1' },
+  { value: '+81',  label: '+81' },
+  { value: '+86',  label: '+86' },
+  { value: '+852', label: '+852' },
+]
+
+const CURRENCIES = [
+  { value: 'TWD', label: 'TWD' },
+  { value: 'USD', label: 'USD' },
+  { value: 'JPY', label: 'JPY' },
+  { value: 'EUR', label: 'EUR' },
+]
+
+/* ── 電話輸入(國碼 + 號碼)── */
+export const PhoneNumber: Story = {
+  name: '電話',
+  render: () => {
+    const [code, setCode] = React.useState('+886')
+    const [num, setNum] = React.useState('')
+    return (
+      <div className="w-[360px]">
+        <Field>
+          <FieldLabel>聯絡電話</FieldLabel>
+          {/* `!w-[]` important override Select 內 trigger w-full;w-120px 容「+886」+ phone icon + chevron */}
+          <FieldControlGroup block>
+            <Select
+              className="!w-[120px] flex-shrink-0"
+              options={COUNTRY_CODES}
+              value={code}
+              onChange={setCode}
+              startIcon={Phone}
+            />
+            <Input
+              className="!flex-1 !min-w-0"
+              value={num}
+              onChange={(e) => setNum(e.target.value)}
+              placeholder="912 345 678"
+            />
+          </FieldControlGroup>
+          <FieldDescription>含國碼,例如 +886 912 345 678</FieldDescription>
+        </Field>
+      </div>
+    )
+  },
+}
+
+/* ── 金額輸入(幣別 + 數字)── */
+export const CurrencyAmount: Story = {
+  name: '金額',
+  render: () => {
+    const [currency, setCurrency] = React.useState('TWD')
+    const [amount, setAmount] = React.useState<number | null>(null)
+    return (
+      <div className="w-[320px]">
+        <Field>
+          <FieldLabel>採購金額</FieldLabel>
+          <FieldControlGroup block>
+            <Select
+              className="!w-[88px] flex-shrink-0"
+              options={CURRENCIES}
+              value={currency}
+              onChange={setCurrency}
+            />
+            <NumberInput
+              className="!flex-1 !min-w-0"
+              value={amount}
+              onChange={setAmount}
+              placeholder="0"
+            />
+          </FieldControlGroup>
+        </Field>
+      </div>
+    )
+  },
+}
+
+/* ── 搜尋 + 提交按鈕 ── */
+export const SearchSubmit: Story = {
+  name: '搜尋與提交',
+  render: () => {
+    const [q, setQ] = React.useState('')
+    return (
+      <div className="w-[440px]">
+        <FieldControlGroup block>
+          <Input
+            className="!flex-1 !min-w-0"
+            startIcon={Search}
+            value={q}
+            onChange={(e) => setQ(e.target.value)}
+            placeholder="搜尋商品或關鍵字"
+          />
+          <Button variant="primary">搜尋</Button>
+        </FieldControlGroup>
+      </div>
+    )
+  },
+}
+
+/* ── DataTable Filter row(Field + Op + Value)── */
+const FILTER_FIELDS = [
+  { value: 'sku', label: 'SKU' },
+  { value: 'name', label: '名稱' },
+  { value: 'category', label: '類別' },
+  { value: 'stock', label: '庫存' },
+]
+// op 選項消費 OPERATOR_REGISTRY SSOT(DataTable/filter-operators.ts;audit dim 32 — 禁 hardcode op 字串)
+const STRING_OPS = OPERATOR_REGISTRY.string
+  .filter((o) => o.valueShape === 'text')
+  .map((o) => ({ value: o.op, label: o.label }))
+
+export const FilterRow: Story = {
+  name: '篩選列（資料表進階篩選實例）',
+  render: () => {
+    const [field, setField] = React.useState('name')
+    const [op, setOp] = React.useState('contains')
+    const [value, setValue] = React.useState('')
+    return (
+      <div className="w-[640px]">
+        <p className="text-caption text-fg-muted mb-3">DataTable 進階篩選 row 是 FieldControlGroup 的典型 consumer。</p>
+        <FieldControlGroup block>
+          <Select className="!w-[160px] flex-shrink-0" options={FILTER_FIELDS} value={field} onChange={setField} />
+          <Select className="!w-[120px] flex-shrink-0" options={STRING_OPS} value={op} onChange={setOp} />
+          <Input className="!flex-1 !min-w-0" value={value} onChange={(e) => setValue(e.target.value)} placeholder="輸入值..." />
+        </FieldControlGroup>
+      </div>
+    )
+  },
+}
+
+/* @story-history: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx 的
+   ChildSizeAlignment 只展示 children 尺寸接合；FieldControlGroup 本身不擁有 size API。 */

package/src/components/FieldControlGroup/field-control-group.tsx

@@ -9,14 +9,13 @@
 //
 import * as React from 'react'
 import { cn } from '@/lib/utils'
-import type { FieldSize } from '@/design-system/components/Field/field-context'
 
 /**
  * FieldControlGroup — 多個 Field controls 視覺接合成一個 input frame
  *
  * **Naming rationale**(2026-05-04):
  * - Taxonomic 一致:FieldGroup(多 Field 堆疊)/ FieldControlGroup(多 control 接合)— scope 區分
- * - Idiom 一致:ButtonGroup(多 Button 接合)同 pattern,只是 X = field control
+ * - 命名 idiom 一致:與 ButtonGroup 共享 <X>Group 命名(X = field control);但**機制不同** — ButtonGroup 是 gap 分離群組(flex gap-2),本元件才是 border-collapse 接合(負 margin 重疊 border)
  * - 不撞 RadioGroup/CheckboxGroup(那是 1-question 多 options semantic group)
  *
  * **Behavior canonical**(verified Ant compact-item.ts L21-58):
@@ -26,10 +25,10 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  * - z-index:default 2 / hover|focus|focus-within 3 / disabled 0
  * - Container `display: inline-flex`(Ant default)/ `block` prop → `display: flex; width: 100%`
  *
- * **Size cascade**(對齊 Field family):
- * - `size` prop default = md;cascade 到 children via implicit context inheritance(children 自管 size 或繼承 useFieldContext)
- * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,size 自動從 Field context 來
- * - Mode B:standalone 用,size 由 prop 控制
+ * **Size**(FCG 不擁有 size API；不傳遞 size 給 children,無 Context Provider / 無 cloneElement;見 spec「Size」段):
+ * - children 尺寸完全由 child 自己決定;FCG 只負責 border-collapse 接合(border / radius / z-index)
+ * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,children 各自讀外層 `<Field>` 的 context size(是 Field 的 context,不是 FCG 的)
+ * - Mode B:standalone 用,逐一給每個 child 設 `size`
  *
  * **Width 配置**(Ant Space.Compact W-A canonical):
  * - 子 controls 自管 width(`className="w-[140px]"` / `style={{width:120}}` / `flex-1` etc.)
@@ -39,8 +38,8 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  * ```tsx
  * // Filter row: 2 fixed select + 1 flex value
  * <FieldControlGroup>
- *   <Select className="w-[140px]" options={fields} />
- *   <Select className="w-[120px]" options={ops} />
+ *   <Select className="!w-[140px]" options={fields} />
+ *   <Select className="!w-[120px]" options={ops} />
  *   <Input className="flex-1" placeholder="輸入值..." />
  * </FieldControlGroup>
  *
@@ -48,7 +47,7 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  * <Field>
  *   <FieldLabel>電話</FieldLabel>
  *   <FieldControlGroup>
- *     <Select className="w-[80px]" options={codes} />
+ *     <Select className="!w-[80px]" options={codes} />
  *     <Input className="flex-1" />
  *   </FieldControlGroup>
  * </Field>
@@ -62,14 +61,12 @@ import type { FieldSize } from '@/design-system/components/Field/field-context'
  */
 
 export interface FieldControlGroupProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** Children size cascade(Mode B);Mode A 從 Field context 來 */
-  size?: FieldSize
   /** Block 模式:width 100% 撐滿 parent(對齊 Ant Space.Compact `block` prop) */
   block?: boolean
 }
 
 const FieldControlGroup = React.forwardRef<HTMLDivElement, FieldControlGroupProps>(
-  ({ size: _size = 'md', block = false, className, children, ...props }, ref) => {
+  ({ block = false, className, children, ...props }, ref) => {
     return (
       <div
         ref={ref}
@@ -116,13 +113,14 @@ FieldControlGroup.displayName = 'FieldControlGroup'
 // Story auto-compile metadata — Phase 4 migration(2026-05-10 #12 task complete)
 // Per scripts/compile-stories.mjs --check。FieldControlGroup is self-contained
 // structural wrapper(border-collapse pattern for Field controls)。
-// **No own sizes** — size prop is cascade-only(passes through to children Field controls,
-// not own visual variants),so sizes:{} matches spec frontmatter (no sizes declared)。
+// **No own sizes** — 不暴露 size prop(不傳遞給 children,無 Context Provider /
+// 無 cloneElement;children 尺寸自管,見上方 docblock「Size」段),
+// so sizes:{} matches spec frontmatter (no sizes declared)。
 export const fieldControlGroupMeta = {
   component: 'FieldControlGroup',
   family: 'self-contained',
   variants: {},
-  sizes: {},  // self-contained wrapper, sizes cascade to children only
+  sizes: {},  // self-contained wrapper;children 尺寸自管
   states: ['default', 'children-hover', 'children-focus', 'children-disabled'],
   tokens: {
     bg: [],  // structural wrapper has no own bg

package/src/components/FieldControlGroup/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './field-control-group'