@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.84

package/src/components/Rating/rating.spec.md

@@ -97,10 +97,18 @@ Rating 的 **container 高度消費 `--field-height-*` token**(sm=28 / md=32 / l
 Rating 可直接塞進 `<Field>`(讓使用者能套 Field label / error / hint 共用機制):
 
 ```tsx
-<Field>
+// 驗證時機走 form-validation.spec.md canonical(blur + submit,不在初始 / 操作中即時報錯)
+// —— error 由 form.errors 驅動,非 `rating === 0` 立即判(那會讓初始未觸碰欄位直接紅框)。
+const form = useFormValidation({
+  initialValues: { rating: 0 },
+  validate: { rating: (v) => (v === 0 ? '請至少給 1 星' : undefined) },
+  onSubmit: async (values) => { /* ... */ },
+})
+
+<Field invalid={!!form.errors.rating}>
   <FieldLabel required>整體滿意度</FieldLabel>
-  <Rating value={rating} onChange={setRating} size="md" />
-  {rating === 0 && <FieldError>請至少給 1 星</FieldError>}
+  <Rating {...form.getInputProps('rating')} size="md" />
+  <FieldError>{form.errors.rating}</FieldError>
 </Field>
 ```
 

package/src/components/ScrollArea/scroll-area.anatomy.stories.tsx

@@ -1,4 +1,4 @@
-// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
 // @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.
 // @anatomy-rationale:
 //   StateBehavior represented as OrientationBehavior — ScrollArea 是 OS chrome

package/src/components/ScrollArea/scroll-area.principles.stories.tsx

@@ -1,4 +1,4 @@
-// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
 // @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 LinkTo from '@storybook/addon-links/react'

package/src/components/ScrollArea/scroll-area.spec.md

@@ -16,7 +16,7 @@ ScrollArea 是**跨 OS 視覺一致的自訂捲動容器**——用 overlay 捲
 
 **Layout Family**:非上述 family — self-contained primitive(純捲動容器,無 slot 結構)。
 
-**實作基礎**:基於 Radix ScrollArea primitive(shadcn passthrough 結構)——由 Radix 處理 viewport / scrollbar / thumb 的 pointer 拖曳與 overflow-detection,本 DS 橋接 token(scrollbar 寬度、thumb bg、hover 反饋)與 a11y 行為(Viewport `tabIndex={0}` + DS focus ring;Radix 不處理 keyboard,亦不自動標 Viewport focusable)。
+**實作基礎**:基於 Radix ScrollArea primitive(shadcn passthrough 結構)——由 Radix 處理 viewport / scrollbar / thumb 的 pointer 拖曳與 overflow-detection,本 DS 橋接 token(scrollbar 寬度、thumb bg、hover 反饋)與 a11y 行為(Viewport `tabIndex={0}` 預設 + `viewportTabIndex={-1}` opt-out + DS focus ring;Radix 不處理 keyboard,亦不自動標 Viewport focusable)。
 
 **世界級對照**:shadcn `ScrollArea` / Radix primitive 本身。Polaris / Carbon 未提供等效元件(預設相信 native scrollbar);我們採用 shadcn / Radix 派:為了跨 OS 視覺一致、避免 DataTable / Sheet / Dialog 遇 Windows always-visible scrollbar 吃寬度跑版。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -100,12 +100,12 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 
 Radix primitive + 本 DS a11y 橋接:
 
-- **鍵盤捲動**:本 DS 在 Viewport 加 `tabIndex={0}` 使其可被鍵盤聚焦(Radix 不自動把 scroll container 標 focusable,Safari 尤其需要;此即 axe `scrollable-region-focusable` fix)。聚焦後 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End` 捲動為瀏覽器原生行為,非 Radix 提供
+- **鍵盤捲動**:本 DS 在 Viewport 加 `tabIndex={0}`(預設)使其可被鍵盤聚焦(Radix 不自動把 scroll container 標 focusable,Safari 尤其需要;此即 axe `scrollable-region-focusable` fix)。聚焦後 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End` 捲動為瀏覽器原生行為,非 Radix 提供。**`viewportTabIndex={-1}` opt-out(2026-07-14)**:內容已有自帶 focusable + 鍵盤處理的元素(如 TimePicker `role="listbox"` `tabIndex={0}`)時傳 `-1`,消除「Viewport+內容雙 tab stop、焦點落 Viewport 時方向鍵觸發原生捲動非元件行為」;axe 由內部 focusable 內容滿足
 - **Focus 可見**:聚焦的 Viewport 顯示 DS focus ring(`focus-visible:outline-ring`,inset 2px),非瀏覽器原生 focus ring
 - **Scrollbar 非 tab stop**:scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動(Radix 內建)
 - **Pointer 支援**:thumb 可拖曳,track 可 click-to-jump(Radix 內建)
 
-本元件已內建 `tabIndex` + focus ring(滿足 axe `scrollable-region-focusable`)。但 Viewport 預設**無 `role` / accessible name**——**若 scroll 區域有具體語意(如「留言列表」「程式碼區塊」),consumer 應提供 `aria-label`**,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。(2026-05-31 #31:修正原「consumer 無需額外處理 a11y」過度宣稱)
+本元件已內建 `tabIndex`(預設 0;`viewportTabIndex={-1}` 可 opt-out,見「鍵盤捲動」)+ focus ring(滿足 axe `scrollable-region-focusable`)。但 Viewport 預設**無 `role` / accessible name**——**若 scroll 區域有具體語意(如「留言列表」「程式碼區塊」),consumer 應提供 `aria-label`**,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。(2026-05-31 #31:修正原「consumer 無需額外處理 a11y」過度宣稱)
 
 ---
 
@@ -126,6 +126,10 @@ ScrollArea 是**捲動容器 primitive**,本身**無互動狀態**(見「邊界
 
 ---
 
+## Radix Viewport `display:table` 陷阱 + `fillX`(2026-07-08 WM 戰役 codify)
+
+Radix Viewport 內建 wrapper `min-width:100%; display:table`——這是**水平捲動的 min-content 溢出機制**,但對「垂直捲動容器內的多欄 flex 佈局」是陷阱:內容以 max-content 佈局突破 100% 寬(WM 兩欄 dialog 右欄被裁 33px 實證)。垂直捲動場景 opt-in `fillX` prop 中和為 block/w-full;**水平捲動勿開**。DialogBody 已預設開啟。
+
 ## 相關
 
 - `../DataTable/data-table.spec.md` — 主要 consumer(橫向捲動跑版問題的解法來源)

package/src/components/ScrollArea/scroll-area.stories.tsx

@@ -1,4 +1,4 @@
-// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
 import type { Meta, StoryObj } from '@storybook/react'
 import { createColumnHelper } from '@tanstack/react-table'
 import { ScrollArea, ScrollBar } from './scroll-area'

package/src/components/ScrollArea/scroll-area.tsx

@@ -33,8 +33,18 @@ import { cn } from '@/lib/utils'
 
 const ScrollArea = React.forwardRef<
   React.ElementRef<typeof ScrollAreaPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>
->(({ className, children, ...props }, ref) => (
+  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> & {
+    /** 2026-07-08(WM 戰役 R2):Radix Viewport 內建 wrapper `display:table; min-width:100%`
+     *  讓垂直捲動容器內的 flex 多欄佈局以 max-content 佈局、突破 100% 寬(WM 兩欄 dialog
+     *  右欄被裁 33px 實證)。垂直捲動場景 opt-in 此 prop 中和為 block/w-full(水平捲動
+     *  場景勿開 — table wrapper 是其 min-content 溢出機制)。 */
+    fillX?: boolean
+    /** Viewport tabIndex(預設 0 = axe scrollable-region-focusable fix)。內容已有自帶
+     *  focusable 元素(如 TimePicker role=listbox tabIndex=0)時傳 -1 消除雙 tab stop —
+     *  axe 由內部 focusable 內容滿足,焦點直接落在有 keydown 的 listbox 上。 */
+    viewportTabIndex?: 0 | -1
+  }
+>(({ className, children, fillX, viewportTabIndex = 0, ...props }, ref) => (
   <ScrollAreaPrimitive.Root
     ref={ref}
     className={cn('relative flex flex-col overflow-hidden', className)}
@@ -50,8 +60,11 @@ const ScrollArea = React.forwardRef<
         才能 keyboard focus(Safari 不自動把 scroll container 標 focusable)。focus-
         visible:outline 用 DS focus ring,不破壞視覺。 */}
     <ScrollAreaPrimitive.Viewport
-      tabIndex={0}
-      className="flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring"
+      tabIndex={viewportTabIndex}
+      className={cn(
+        'flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring',
+        fillX && '[&>div]:!block [&>div]:!w-full [&>div]:!min-w-0',
+      )}
     >
       {children}
     </ScrollAreaPrimitive.Viewport>

package/src/components/Select/select.anatomy.stories.tsx

@@ -305,7 +305,7 @@ export const Overview = {
             <tbody>
               {[
                 ['mode', "'edit'|'display'|'readonly'|'disabled'", "'edit'", 'FieldMode 四模式——edit 可編輯 / display 純展示 / readonly 顯示值不可改 / disabled 灰化'],
-                ['variant', "'default'|'bare'|'naked'", "'default'", 'Field chrome variant(預設繼承 context.variant)'],
+                ['variant', "'default'", "'default'", 'Field chrome variant(預設繼承 context.variant;naked = @internal cell-as-input,2026-07-14 型別收窄至 FieldVariantInternal)'],
                 ['display', "'plain'|'tag'", "'plain'", '顯示模式——plain 純文字，tag 用 Tag 元件呈現'],
                 ['size', "'sm'|'md'|'lg'", "'md'", '尺寸，與 Button 同 size 並排高度一致'],
                 ['options', 'SelectOption[]', '—', '選項列表 { value, label }'],
@@ -322,8 +322,8 @@ export const Overview = {
                 ['error', 'boolean', 'false', '紅色邊框 + aria-invalid（僅 edit 模式有視覺效果）'],
                 ['defaultOpen', 'boolean', 'false', 'uncontrolled 初始開啟(DataTable cell click→1 step open)'],
                 ['onOpenChange', '(open: boolean) => void', '—', 'open 狀態變更 callback'],
-                ['showDisplayEndIcon', 'boolean', 'false', 'display 模式渲 ChevronDown(DataTable cell 對齊)'],
-                ['selectedItemRenderer', '(opt: SelectOption) => ReactNode', '—', 'trigger 已選項目客製 render(PeoplePicker 用)'],
+                ['showDisplayEndIcon', 'boolean', 'false', 'display 模式渲 ChevronDown(opt-in 逃生門;2026-07-08 A 案後 DataTable 預設不傳 — display 態零恆顯 icon)'],
+                ['selectedItemRenderer', '(opt: SelectOption) => ReactNode', '—', '已選項目客製 render;4 mode 共享(edit/display/readonly/disabled,contract (a))— display 態渲值內容無 chrome(PeoplePicker / status 欄用)'],
                 ['disabled', 'boolean', '—', '原生屬性；未傳 mode 時 resolve 為 disabled 樣式（顯式 mode prop 恆優先，見 useResolvedFieldMode）'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>

package/src/components/Select/select.spec.md

@@ -19,6 +19,8 @@ benchmark:
 
 ## 定位
 
+> 寬度軸:`width="fill|hug"`(default fill;hug = 依內容收縮,detail pane inline metadata 用)— SSOT → `Field/field-controls.spec.md`「寬度軸(width: fill / hug)」。
+
 Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個，選項收在 dropdown 內展開。**裝置自適應雙路徑**:觸控裝置(`pointer: coarse`)走原生 `<select>` 取平台原生 picker;桌機走自建 combobox(`role="combobox"` + Radix Popover + Command 渲染 SelectMenu)。詳下方「實作:裝置自適應雙路徑」段。
 
 共用規則見 `field-controls.spec.md`。本文件只記錄 Select 特有的原則。
@@ -36,6 +38,26 @@ Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個
 
 **此分流是「裝置」軸，與 `searchable` 正交**：`searchable` 只決定桌機 combobox 的 trigger 要不要顯搜尋輸入框，**不**決定走原生還是 combobox。一個不可搜尋的桌機 Select 仍是完整自建 combobox（可捲動 / 點選，只是沒搜尋框）。
 
+### 原生表單參與(desktop hidden input mirror,2026-07-13 D2 拍板)
+
+`name` / `required` / `form` 在型別 allowlist 內(`SelectProps` 以 `Pick<SelectHTMLAttributes>` 顯式允收,2026-07-14 API 策展 D),兩路徑提交語義必須一致(歷史上桌機靜默丟棄 name、mobile 生效 — 此不對稱從未被拍板,屬 footgun,2026-07-13 修):
+
+| 路徑 | 機制 |
+|---|---|
+| 觸控(NativeSelect)| 真原生 `<select>`,`name` / `required` / `form` 直接生效 |
+| 桌機(CustomSelect)| **visually-hidden `<input>` 鏡像**(`aria-hidden` + `tabIndex={-1}` + opacity-0,絕對定位於 trigger 內):`value` 單向鏡射受控 state,`name` / `form` forward → 裸 `<form>` submit 收得到值;顯式 `required` prop forward → 原生 required 擋 submit |
+
+**設計規則**:
+
+- **型別 = allowlist,不 extends 全開(2026-07-14 API 策展 D,user 拍板「全部收窄」)**:`SelectProps` 只 `Pick<>` 兩路徑皆有實作出口的原生屬性(`id`/`className`/`style`/`name`/`form`/`required`/`disabled`/`onFocus`/`onBlur`/`onKeyDown`/`aria-label`/`aria-describedby`/`aria-errormessage` + mobile-only `autoFocus`/`autoComplete` + `data-*` passthrough);「型別承諾 ≠ 實作出口」者(`multiple`/`aria-labelledby`/`tabIndex` 等)不進型別,需要時先接線(兩路徑等效)再入表 — 完整盤點依據見 `select.tsx` SelectProps docblock
+- **單向 projection,非第二 SSOT(M17)**:mirror 的 value 恆來自既有 canonical state(`useControllable`);唯一寫回通道是瀏覽器 autofill,且僅在 match 既有非 disabled option 時經 canonical setter 生效(MUI SelectInput 同款 guard)
+- **空值 = `value=''`**:無選擇時送空字串,**不** default 第一項——採 MUI 式**單一 hidden input**而非 Radix BubbleSelect 完整 `<select>` option tree(後者無空 option 時 default 第一項,radix-ui/primitives issue #3521 documented footgun;2026-07-13 codex 辯論 verdict)
+- **原生 required 僅收顯式 `required` prop**(裸表單 opt-in):`<Field required>` 的 context required 續走 `aria-required` + `useFormValidation`(RHF)方法論(`form-validation.spec.md` 規則 1-9),不對既有 Field+RHF consumer 注入瀏覽器原生 bubble
+- **a11y 不變**:mirror `aria-hidden` + 不入 Tab 序,semantics 仍由 `role="combobox"` trigger own;顯式 `required` prop 同步進 trigger `aria-required`(對齊 mobile 原生 `<select required>` 播報)
+- **副作用(升級)**:`useFormValidation` 規則 8(focus-first-error 以 DOM name 定位)桌機 Select 現在可被定位——focus 落 mirror → trigger `focus-within` 顯示 focus 邊框,不再落入「非 native 控件略過」fallback
+
+**世界級對照**:MUI Select 非原生模式同步 opacity-0 hidden input 攜 `name`/`required`(官方測試涵蓋 required 阻止提交 + FormData 值,[github.com/mui/material-ui Select.test.js](https://github.com/mui/material-ui/blob/master/packages/mui-material/src/Select/Select.test.js))/ React Spectrum [HiddenSelect](https://github.com/adobe/react-spectrum/blob/main/packages/%40react-aria/select/src/HiddenSelect.tsx) / Headless UI Listbox `name` → [hidden input kept in sync](https://headlessui.com/react/listbox#using-with-html-forms)。Ant 走純 Form.Item(React state)派;本 DS 因型別已承諾 `name`/`form`/`required`,「同一 public API 依裝置改變提交語義」比補 projection 更危險(codex verdict),故補鏡像。
+
 ---
 
 ## Controlled / Uncontrolled dual-mode(Dim 26,2026-05-21 D3 audit ship)
@@ -44,24 +66,11 @@ Select 是**單選下拉的表單 control**——從 3+ 選項中挑恰好一個
 
 ### Controlled 模式(consumer 自管 state)
 
-傳 `value` + `onChange`,Select **不**自管 state:
-
-```tsx
-const [country, setCountry] = useState('tw')
-<Select value={country} onChange={setCountry} options={...} />
-```
-
-**何時用**:Form library(react-hook-form / Formik)/ Redux / 跨元件 sync / server-state driven。
+傳 `value` + `onChange`(如 `<Select value={country} onChange={setCountry}>`),Select **不**自管 state。**何時用**:Form library(react-hook-form / Formik)/ Redux / 跨元件 sync / server-state driven。
 
 ### Uncontrolled 模式(Select 自管 state)
 
-不傳 `value`(可傳 `defaultValue` 設初始值),Select 內部 `useState`,變更時 fire `onChange` callback 通知 consumer:
-
-```tsx
-<Select defaultValue="tw" onChange={(v) => console.log('changed:', v)} options={...} />
-```
-
-**何時用**:純展示 / 一次性表單 submit / consumer 不需要 read 當前值。
+不傳 `value`(可傳 `defaultValue` 設初始值,如 `<Select defaultValue="tw" onChange={...}>`),Select 內部自管,變更時 fire `onChange` 通知 consumer。**何時用**:純展示 / 一次性表單 submit / consumer 不需要 read 當前值。
 
 ### 為什麼支援 dual-mode(非 controlled-only)
 
@@ -71,8 +80,7 @@ const [country, setCountry] = useState('tw')
 
 ### 歷史
 
-- **2026-05-21 前**:刻意 controlled-only,理由「內部狀態複雜易 race」
-- **2026-05-21 D3 audit**:per Dim 26 verify + user 拍板(「決策三照妳建議」),補 `defaultValue` + 互斥 signal。NativeSelect / CustomSelect 統一走既有 `useControllable` hook,`valueProp !== undefined` 為 controlled signal(對齊 M17 SSOT)
+原刻意 controlled-only(「內部狀態複雜易 race」);**2026-05-21 D3 audit** per Dim 26 verify + user 拍板(「決策三照妳建議」)補 `defaultValue` + 互斥 signal — NativeSelect / CustomSelect 統一走既有 `useControllable` hook,`valueProp !== undefined` 為 controlled signal(M17 SSOT)。
 
 ### Open-pair 例外:open 軸維持 uncontrolled-only(2026-06-12 deep-audit R2 補)
 
@@ -223,6 +231,8 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 **命名 rationale**(2026-05-01 從 `'text'` 改 `'plain'`):跨元件 prop value 衝突防避 — `Button variant="text"` 表「無 chrome 文字按鈕」,跟 Select.display 的「純文字呈現」是兩個不同概念,共用 `'text'` 字面值會造成 consumer 認知衝突(命名三 test 第 3 條)。改 `'plain'` 後語意專屬:plain = 樸素文字呈現,對立 tag = 用 Tag 元件呈現。
 
+**`selectedItemRenderer` 優先於兩種顯示模式**(2026-07-08 A 案回歸修正):設定時已選值改渲 consumer renderer 輸出(status icon+text / PersonDisplay 等),且 **edit / display / readonly / disabled 4 mode 共享同一 renderer**(`field-controls.spec.md` 共享 contract (a),禁 edit-only)。renderer 輸出屬「值內容」— `mode="display"` 照常渲染(無 chrome 無 chevron);與 affordance(chevron/outline)分層見 `field.spec.md` L6。
+
 ### plain 模式
 
 - 原生 select 純文字 + ChevronDown

package/src/components/Select/select.stories.tsx

@@ -64,6 +64,39 @@ export const Modes: Story = {
   },
 }
 
+/* ── 寬度軸 hug(任務詳情 metadata)── */
+export const HugWidth: Story = {
+  name: '寬度貼合內容(詳情欄)',
+  render: () => {
+    const [status, setStatus] = React.useState('in_stock')
+    const [priority, setPriority] = React.useState('medium')
+    return (
+      // 任務詳情右欄場景:label 上、hug 寬 select 下 — 框線互動與一般 field 完全相同,只有寬度依 value 收縮
+      <div className="flex w-72 flex-col gap-[var(--layout-space-loose)]">
+        <div className="flex flex-col gap-1">{/* @layout-space-magic-ok: gap-1 = label↔control 4px 內距 demo */}
+          <span className="text-caption text-fg-secondary">Status</span>
+          <Select width="hug" size="sm" options={statusOptions} value={status} onChange={setStatus} aria-label="Status(hug width demo)" />
+        </div>
+        <div className="flex flex-col gap-1">{/* @layout-space-magic-ok: gap-1 = label↔control 4px 內距 demo */}
+          <span className="text-caption text-fg-secondary">Priority</span>
+          <Select
+            width="hug"
+            size="sm"
+            options={[
+              { value: 'high', label: 'High' },
+              { value: 'medium', label: 'Medium' },
+              { value: 'low', label: 'Low' },
+            ]}
+            value={priority}
+            onChange={setPriority}
+            aria-label="Priority(hug width demo)"
+          />
+        </div>
+      </div>
+    )
+  },
+}
+
 /* ── 顯示模式 ── */
 export const DisplayMode: Story = {
   name: '顯示模式',