npm - @qijenchen/design-system - Versions diffs - 0.1.0-beta.82 → 0.1.0-beta.84 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (612) hide show

package/dist/components/RadioGroup/radio-group.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"radio-group.js","sources":["../../../src/components/RadioGroup/radio-group.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 * as React from \"react\"\nimport * as RadioGroupPrimitive from \"@radix-ui/react-radio-group\"\nimport { Circle } from \"lucide-react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport type { FieldMode, FieldVariant } from \"@/design-system/components/Field/field-types\"\nimport { useFieldContext, useResolvedFieldMode, useResolvedFieldDisabled, useResolvedFieldSize } from \"@/design-system/components/Field/field-context\"\nimport { SelectionItem } from \"@/design-system/components/SelectionControl/selection-item\"\nimport type { LucideIcon } from \"lucide-react\"\nimport type { AvatarData } from \"@/design-system/components/Avatar/avatar\"\nimport { EMPTY_DISPLAY, fieldWrapperStyles } from \"@/design-system/components/Field/field-wrapper\"\n\n// ── RadioGroup display mode ─────────────────────────────────────────────────\n// RadioGroup mode='display' 時:Group 不渲染 Radix primitive(無 radio 視覺),\n// 改由 RadioGroup 本體 walk props.children,找 control.value === selectedValue 的\n// SelectionItem,把它的 label 渲染為單一純文字 span(其他選項不顯示)。\n// 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。\n// 實作在 RadioGroup forwardRef 內(見下方 mode === 'display' 分支)。\n\n// ── RadioGroup ──────────────────────────────────────────────────────────────\n\nexport interface RadioGroupProps\n extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {\n /*\n Field mode(2026-05-05 Phase B3 align):\n * edit — 一般可互動 RadioGroup(預設)\n * display — 純展示:不渲染 Radix Root / 任何 radio 視覺;RadioGroup 本體 walk\n * children,僅 control.value === group.value 那筆把 label 渲染為純文字 span。\n * 對齊 Carbon read-only / DataTable single-select cell read mode。\n * readonly — standalone:ReadonlyContext 傳 items 鎖互動保留視覺;Field 內:灰框 + 選中項 label(不渲染 radio 群組)\n * disabled — 同 RadioGroupPrimitive.Root disabled 屬性\n /\n mode?: FieldMode\n /\n Visual chrome — RadioGroup 本體無 input wrapper variant,本 prop 對主體無視覺影響;\n * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n /\n variant?: FieldVariant\n}\n\n// RadioGroup mode='readonly' → 透過 context 把 readOnly 傳給所有 child RadioGroupItem\n// (item 已支援 readOnly prop + data-[readonly] 樣式;Radix Root 無 readOnly,故用 context)。\nconst RadioGroupReadonlyContext = React.createContext(false)\n\n// walk children 找 control.value === selectedValue 的 SelectionItem label(display / readonly-in-Field 共用)\nfunction findSelectedRadioLabel(children: React.ReactNode, selectedValue: string \| undefined): React.ReactNode {\n let selectedLabel: React.ReactNode = null\n React.Children.forEach(children, (child) => {\n if (!React.isValidElement(child)) return\n const cProps = child.props as { control?: unknown; label?: React.ReactNode; value?: unknown }\n // 形狀 1:<RadioGroupItem value label>(主用法)— value/label 直掛 props\n if (cProps.value === selectedValue && cProps.value !== undefined) {\n selectedLabel = cProps.label ?? selectedValue\n return\n }\n // 形狀 2:<SelectionItem control={<RadioGroupItem value/>} label>(組合用法)\n const control = cProps.control\n if (React.isValidElement(control)) {\n const controlValue = (control.props as { value?: unknown }).value\n if (controlValue === selectedValue) {\n selectedLabel = cProps.label ?? selectedValue\n }\n }\n })\n return selectedLabel\n}\n\nconst RadioGroup = React.forwardRef<\n React.ElementRef<typeof RadioGroupPrimitive.Root>,\n RadioGroupProps\n>(({ className, mode, variant: _chrome, value, defaultValue, ...props }, ref) => {\n // 2026-06-08 SSOT cascade:resolvedMode 經 resolver hook 讀 fieldCtx(原 root 完全不讀 → <Field disabled>/<Field mode> 失效)\n const resolvedMode = useResolvedFieldMode({ mode, disabled: (props as { disabled?: boolean }).disabled })\n const fieldCtx = useFieldContext()\n // readonly 灰框 size:走 SSOT resolver(RadioGroup 無 size prop → ctx > 'md')\n const resolvedBoxSize = useResolvedFieldSize(undefined, 'md') as 'sm' \| 'md' \| 'lg'\n // mode='display' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。\n // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。\n // 實作:walk children 找 control.value === selectedValue 的 SelectionItem,render label plain text。\n // (不用 context dispatch 給 RadioGroupItem — SelectionItem layout wrapper 仍會渲染所有 item label)\n // 2026-07-04 修:display / readonly-in-Field 分支的 <div> 原丟棄剩餘 props(id/data-/aria-)\n // 且不轉發 forwardRef ref → 自家 radio-group.stories.tsx display demo 傳的 aria-label 都靜默失效。\n // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Checkbox/Switch 同修);\n // edit 主路徑不受影響(Root 仍 spread 完整 props)。\n const {\n onValueChange: _onValueChange,\n disabled: _disabled,\n required: _required,\n name: _name,\n orientation: _orientation,\n dir: _dir,\n loop: _loop,\n asChild: _asChild,\n children: _children,\n ...restDomProps\n } = props as RadioGroupProps & { asChild?: boolean }\n\n if (resolvedMode === 'display') {\n const selectedValue = (value ?? defaultValue) as string \| undefined\n if (!selectedValue) {\n return <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} role=\"group\" className={cn('grid', className)}><span className=\"text-fg-muted\">{EMPTY_DISPLAY}</span></div>\n }\n const selectedLabel = findSelectedRadioLabel(props.children, selectedValue)\n return (\n <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} role=\"group\" className={cn('grid', className)}>\n <span className=\"text-foreground\">{selectedLabel ?? selectedValue}</span>\n </div>\n )\n }\n\n // ── mode='readonly' in Field(2026-06-12 user 拍板,與 Checkbox/Switch 灰框模型一致)──\n // Field 內 readonly 單選 = fieldWrapperStyles readonly 灰框 + 選中項 label 文字\n // (= Select readonly 同款呈現:同為「單選資料」,鎖定時呈現一致)。\n // standalone readonly(無 Field)維持原樣鎖互動(ReadonlyContext 路徑)。\n if (resolvedMode === 'readonly' && fieldCtx?.hasFieldWrapper === true) {\n const selectedValue = (value ?? defaultValue) as string \| undefined\n const selectedLabel = selectedValue ? findSelectedRadioLabel(props.children, selectedValue) : null\n const boxSize = resolvedBoxSize\n return (\n <div\n {...restDomProps}\n ref={ref as React.Ref<HTMLDivElement>}\n role=\"radiogroup\"\n aria-readonly=\"true\"\n aria-labelledby={fieldCtx?.labelId}\n aria-invalid={fieldCtx?.invalid \|\| undefined}\n data-readonly=\"true\"\n tabIndex={0}\n className={cn(\n fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',\n className,\n )}\n >\n {selectedValue\n ? <span className=\"text-foreground\">{selectedLabel ?? selectedValue}</span>\n : <span className=\"text-fg-muted\">{EMPTY_DISPLAY}</span>}\n </div>\n )\n }\n\n // mode='disabled' → Radix Root disabled(原生 propagate 給所有 item);\n // mode='readonly' → context 傳 readOnly 給 items(item 渲染為 data-[readonly] 鎖互動 + aria-readonly)。\n return (\n <RadioGroupReadonlyContext.Provider value={resolvedMode === 'readonly'}>\n <RadioGroupPrimitive.Root\n className={cn(\"grid\", className)}\n value={value}\n defaultValue={defaultValue}\n {...props}\n disabled={resolvedMode === 'disabled'}\n ref={ref}\n />\n </RadioGroupReadonlyContext.Provider>\n )\n})\nRadioGroup.displayName = 'RadioGroup'\n// Field layout 宣告：RadioGroup 是 block primitive（多項堆疊），\n// 進入 <Field> 時 control area 自動切 items-start + padding-top 公式對齊。\n// Convention 詳見 components/Field/field.spec.md「Control area:Inline vs Block」段落。\n;(RadioGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'\n\n// ── RadioGroupItem Variants ─────────────────────────────────────────────────\n// 與 Checkbox 完全對齊：sm/md=16px, lg=20px。差異只有形狀（rounded-full）和指示器（filled dot）。\n\nconst radioItemVariants = cva(\n [\n 'grid place-content-center shrink-0 rounded-full',\n 'border border-border bg-surface',\n 'transition-colors duration-150',\n 'hover:border-border-hover',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n 'data-[state=checked]:border-primary data-[state=checked]:text-primary',\n 'data-[state=checked]:hover:border-primary-hover data-[state=checked]:hover:text-primary-hover',\n 'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',\n 'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:border-transparent disabled:data-[state=checked]:text-fg-disabled',\n // readOnly：鎖定互動但維持 checked/unchecked 視覺\n 'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n 'data-[readonly=true]:hover:border-border',\n ],\n {\n variants: {\n size: {\n sm: 'h-4 w-4',\n md: 'h-4 w-4',\n lg: 'h-5 w-5',\n },\n },\n defaultVariants: {\n size: 'md',\n },\n }\n)\n\n// ── Dot Size ────────────────────────────────────────────────────────────────\nconst dotSize: Record<string, number> = { sm: 8, md: 8, lg: 10 }\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\ntype RadioItemPrimitiveProps = React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>\n\nexport interface RadioGroupItemProps\n extends RadioItemPrimitiveProps,\n VariantProps<typeof radioItemVariants> {\n /\n Inline label。提供時 RadioGroupItem 自動透過 SelectionItem 包裝，\n * 套用 codified 樣式（text-body / text-foreground / disabled 色）。\n * 在 <Field> context 內時此 prop 仍然生效（Radio 的 label 是每個 item\n * 各自的，不是整組 Field 的；FieldLabel 是 RadioGroup 整體的 label）。\n /\n label?: React.ReactNode\n /\n Inline description（secondary 文字）。須與 label 搭配使用。\n * 套用 text-body / text-fg-secondary 樣式。\n /\n description?: React.ReactNode\n /* 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc SSOT;與 avatar 互斥)/\n icon?: LucideIcon\n /* 可選左側 avatar(label 前)— 同上 /\n avatar?: AvatarData\n /\n readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。\n * 通常整個 RadioGroup 一起設 readonly（由 parent RadioGroup 的 disabled\n * 或 readonly 行為決定），個別 item 也可設。\n */\n readOnly?: boolean\n}\n\n// ── RadioGroupItem ──────────────────────────────────────────────────────────\n\nconst RadioGroupItem = React.forwardRef<\n React.ElementRef<typeof RadioGroupPrimitive.Item>,\n RadioGroupItemProps\n>(\n (\n {\n className,\n size,\n label,\n icon,\n avatar,\n description,\n readOnly = false,\n disabled,\n id: idProp,\n ...props\n },\n ref\n ) => {\n const sizeKey = size ?? 'md'\n const dotPx = dotSize[sizeKey]\n\n // 注意:RadioGroup mode='display' 的純文字渲染由 RadioGroup 本體 walk-children 處理\n // (見上方 RadioGroup forwardRef 的 mode === 'display' 分支),RadioGroupItem 在 display\n // mode 下不會被獨立 render,故此處無 display 分支。\n\n // 注意：Radio 的 label 語意與 Checkbox/Switch 不同——\n // Checkbox/Switch 的 label 就是該 control 的唯一 label（被 Field context 接管），\n // RadioGroupItem 的 label 是「該選項」的 label（每 item 各自擁有），\n // FieldLabel 則是整個 RadioGroup 的 label。\n // 因此 RadioGroupItem 的 label 不因 Field context 被忽略。\n const resolvedDisabled = useResolvedFieldDisabled(disabled)\n // group-level readonly(RadioGroup mode='readonly')或 item-level readOnly,任一 true 即鎖互動。\n const groupReadonly = React.useContext(RadioGroupReadonlyContext)\n const effectiveReadonly = readOnly \|\| groupReadonly\n\n const generatedId = React.useId()\n const inputId = idProp ?? generatedId\n\n const rootEl = (\n <RadioGroupPrimitive.Item\n id={inputId}\n ref={ref}\n disabled={resolvedDisabled}\n aria-readonly={effectiveReadonly \|\| undefined}\n data-readonly={effectiveReadonly \|\| undefined}\n tabIndex={effectiveReadonly ? -1 : undefined}\n className={cn(radioItemVariants({ size }), className)}\n {...props}\n // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click\n // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍選中。\n // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 onCheck;\n // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(與 Checkbox/Switch 同修)。\n // 同時攔 Radix roving-focus 的 arrow-key onFocus → click() 路徑(同為 click event)。\n onClick={(event) => {\n if (effectiveReadonly) {\n event.preventDefault()\n return\n }\n props.onClick?.(event)\n }}\n >\n <RadioGroupPrimitive.Indicator className=\"grid place-content-center\">\n <Circle\n style={{ width: dotPx, height: dotPx }}\n className=\"fill-current text-current\"\n />\n </RadioGroupPrimitive.Indicator>\n </RadioGroupPrimitive.Item>\n )\n\n // 無 label → 只渲染 radio 本體\n if (label == null) return rootEl\n\n // 有 label → 透過 SelectionItem 包裝，與 Checkbox 一致（disabled 已於上方 useResolvedFieldDisabled 解析）\n return (\n <SelectionItem\n control={rootEl}\n label={label}\n description={description}\n icon={icon}\n avatar={avatar}\n htmlFor={inputId}\n disabled={resolvedDisabled}\n size={sizeKey}\n />\n )\n }\n)\nRadioGroupItem.displayName = 'RadioGroupItem'\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 radioGroupMeta = {\n component: 'RadioGroup',\n family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4 — field-controls.spec.md 成員名單不含 RadioGroup)\n variants: {\n\n },\n sizes: {\n // iconSize = 渲染指示器尺寸(對齊 checkbox/switch meta 慣例:checkbox iconSize=真 Check glyph 12/12/16)。\n // Radio 指示器是 filled dot 非 glyph,真值 = dotSize 8/8/10(radio-group.tsx:179);\n // 控件框 16/16/20 與 Checkbox 對齊但那是 box 非「指示器」,不入此鍵(避免 metadata 語意 drift)。\n sm: { fieldHeight: 28, iconSize: 8, typography: 'body' },\n md: { fieldHeight: 32, iconSize: 8, typography: 'body' },\n lg: { fieldHeight: 36, iconSize: 10, typography: 'body-lg' },\n },\n // 2026-07-04 修 stale meta:移除 'active' — radioItemVariants cva 無 active-state 樣式,\n // Radix radio 也無 data-state=active(對照 checkboxMeta 正確不含 active)\n // 'checked' = 選定持續態(card 式 = border+text primary;2026-07-07 meta 詞彙統一補列)\n states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],\n tokens: {\n bg: ['bg-disabled', 'bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],\n ring: ['ring-ring'],\n },\n defaultSize: 'md',\n} as const\n\nexport { RadioGroup, RadioGroupItem, radioItemVariants }\n"],"names":[],"mappings":"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"}
1	+ {"version":3,"file":"radio-group.js","sources":["../../../src/components/RadioGroup/radio-group.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 * as React from \"react\"\nimport * as RadioGroupPrimitive from \"@radix-ui/react-radio-group\"\nimport { Circle } from \"lucide-react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\n\nimport { cn } from \"@/lib/utils\"\nimport type { FieldMode, FieldVariant } from \"@/design-system/components/Field/field-types\"\nimport { useFieldContext, useResolvedFieldMode, useResolvedFieldDisabled, useResolvedFieldSize } from \"@/design-system/components/Field/field-context\"\nimport { SelectionItem } from \"@/design-system/components/SelectionControl/selection-item\"\nimport type { LucideIcon } from \"lucide-react\"\nimport type { AvatarData } from \"@/design-system/components/Avatar/avatar\"\nimport { fieldWrapperStyles } from \"@/design-system/components/Field/field-wrapper\"\nimport { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'\n\n// ── RadioGroup display mode ─────────────────────────────────────────────────\n// RadioGroup mode='display' 時:Group 不渲染 Radix primitive(無 radio 視覺),\n// 改由 RadioGroup 本體 walk props.children,找 control.value === selectedValue 的\n// SelectionItem,把它的 label 渲染為單一純文字 span(其他選項不顯示)。\n// 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。\n// 實作在 RadioGroup forwardRef 內(見下方 mode === 'display' 分支)。\n\n// ── RadioGroup ──────────────────────────────────────────────────────────────\n\nexport interface RadioGroupProps\n extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {\n /*\n Field mode(2026-05-05 Phase B3 align):\n * edit — 一般可互動 RadioGroup(預設)\n * display — 純展示:不渲染 Radix Root / 任何 radio 視覺;RadioGroup 本體 walk\n * children,僅 control.value === group.value 那筆把 label 渲染為純文字 span。\n * 對齊 Carbon read-only / DataTable single-select cell read mode。\n * readonly — standalone:ReadonlyContext 傳 items 鎖互動保留視覺;Field 內:灰框 + 選中項 label(不渲染 radio 群組)\n * disabled — 同 RadioGroupPrimitive.Root disabled 屬性\n /\n mode?: FieldMode\n /\n Visual chrome — RadioGroup 本體無 input wrapper variant,本 prop 對主體無視覺影響;\n * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n /\n variant?: FieldVariant\n}\n\n// RadioGroup mode='readonly' → 透過 context 把 readOnly 傳給所有 child RadioGroupItem\n// (item 已支援 readOnly prop + data-[readonly] 樣式;Radix Root 無 readOnly,故用 context)。\nconst RadioGroupReadonlyContext = React.createContext(false)\n\n// group-level disabled(standalone <RadioGroup disabled>)→ context 傳給 items,讓 SelectionItem\n// label/description 也降 text-fg-disabled(Radix Root disabled 只 propagate 給 radio 圈、不碰 label 色)。\n// 對齊本檔 RadioGroupReadonlyContext 既有模式 + spec「Disabled」邊界案例(Group-level disabled 視覺繼承 SelectionItem SSOT text-fg-disabled)。\nconst RadioGroupDisabledContext = React.createContext(false)\n\n// walk children 找 control.value === selectedValue 的 SelectionItem label(display / readonly-in-Field 共用)\nfunction findSelectedRadioLabel(children: React.ReactNode, selectedValue: string \| undefined): React.ReactNode {\n let selectedLabel: React.ReactNode = null\n React.Children.forEach(children, (child) => {\n if (!React.isValidElement(child)) return\n const cProps = child.props as { control?: unknown; label?: React.ReactNode; value?: unknown }\n // 形狀 1:<RadioGroupItem value label>(主用法)— value/label 直掛 props\n if (cProps.value === selectedValue && cProps.value !== undefined) {\n selectedLabel = cProps.label ?? selectedValue\n return\n }\n // 形狀 2:<SelectionItem control={<RadioGroupItem value/>} label>(組合用法)\n const control = cProps.control\n if (React.isValidElement(control)) {\n const controlValue = (control.props as { value?: unknown }).value\n if (controlValue === selectedValue) {\n selectedLabel = cProps.label ?? selectedValue\n }\n }\n })\n return selectedLabel\n}\n\nconst RadioGroup = React.forwardRef<\n React.ElementRef<typeof RadioGroupPrimitive.Root>,\n RadioGroupProps\n>(({ className, mode, variant: _chrome, value, defaultValue, ...props }, ref) => {\n // 2026-06-08 SSOT cascade:resolvedMode 經 resolver hook 讀 fieldCtx(原 root 完全不讀 → <Field disabled>/<Field mode> 失效)\n const resolvedMode = useResolvedFieldMode({ mode, disabled: (props as { disabled?: boolean }).disabled })\n const emptyDisplay = useFieldEmptyDisplay()\n const fieldCtx = useFieldContext()\n // readonly 灰框 size:走 SSOT resolver(RadioGroup 無 size prop → ctx > 'md')\n const resolvedBoxSize = useResolvedFieldSize(undefined, 'md') as 'sm' \| 'md' \| 'lg'\n // mode='display' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。\n // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。\n // 實作:walk children 找 control.value === selectedValue 的 SelectionItem,render label plain text。\n // (不用 context dispatch 給 RadioGroupItem — SelectionItem layout wrapper 仍會渲染所有 item label)\n // 2026-07-04 修:display / readonly-in-Field 分支的 <div> 原丟棄剩餘 props(id/data-/aria-)\n // 且不轉發 forwardRef ref → 自家 radio-group.stories.tsx display demo 傳的 aria-label 都靜默失效。\n // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Checkbox/Switch 同修);\n // edit 主路徑不受影響(Root 仍 spread 完整 props)。\n const {\n onValueChange: _onValueChange,\n disabled: _disabled,\n required: _required,\n name: _name,\n orientation: _orientation,\n dir: _dir,\n loop: _loop,\n asChild: _asChild,\n children: _children,\n ...restDomProps\n } = props as RadioGroupProps & { asChild?: boolean }\n\n if (resolvedMode === 'display') {\n const selectedValue = (value ?? defaultValue) as string \| undefined\n if (!selectedValue) {\n return <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} role=\"group\" className={cn('grid', className)}><span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span></div>\n }\n const selectedLabel = findSelectedRadioLabel(props.children, selectedValue)\n return (\n <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} role=\"group\" className={cn('grid', className)}>\n <span className=\"text-foreground\">{selectedLabel ?? selectedValue}</span>\n </div>\n )\n }\n\n // ── mode='readonly' in Field(2026-06-12 user 拍板,與 Checkbox/Switch 灰框模型一致)──\n // Field 內 readonly 單選 = fieldWrapperStyles readonly 灰框 + 選中項 label 文字\n // (= Select readonly 同款呈現:同為「單選資料」,鎖定時呈現一致)。\n // standalone readonly(無 Field)維持原樣鎖互動(ReadonlyContext 路徑)。\n if (resolvedMode === 'readonly' && fieldCtx?.hasFieldWrapper === true) {\n const selectedValue = (value ?? defaultValue) as string \| undefined\n const selectedLabel = selectedValue ? findSelectedRadioLabel(props.children, selectedValue) : null\n const boxSize = resolvedBoxSize\n return (\n <div\n {...restDomProps}\n ref={ref as React.Ref<HTMLDivElement>}\n role=\"radiogroup\"\n aria-readonly=\"true\"\n aria-labelledby={fieldCtx?.labelId}\n aria-invalid={fieldCtx?.invalid \|\| undefined}\n data-readonly=\"true\"\n tabIndex={0}\n className={cn(\n fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',\n className,\n )}\n >\n {selectedValue\n ? <span className=\"text-foreground\">{selectedLabel ?? selectedValue}</span>\n : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>}\n </div>\n )\n }\n\n // mode='disabled' → Radix Root disabled(原生 propagate 給所有 item);\n // mode='readonly' → context 傳 readOnly 給 items(item 渲染為 data-[readonly] 鎖互動 + aria-readonly)。\n return (\n <RadioGroupReadonlyContext.Provider value={resolvedMode === 'readonly'}>\n <RadioGroupDisabledContext.Provider value={resolvedMode === 'disabled'}>\n <RadioGroupPrimitive.Root\n className={cn(\"grid\", className)}\n value={value}\n defaultValue={defaultValue}\n // Field 內:role=\"radiogroup\" 的 <div> 無法被 <label for> 命名 → 自讀 fieldCtx 接\n // aria-labelledby / aria-invalid / aria-describedby(field-context.ts「下游 control 需自讀\n // labelId」;對齊 slider.tsx / Rating / TimePicker 的 fieldLabelId 接線 + 上方 readonly-in-Field 分支)。\n // standalone(無 Field)時皆 undefined,consumer 的 {...props} aria- 照舊生效(置於 spread 前故可被覆蓋)。\n aria-labelledby={fieldCtx?.labelId}\n aria-invalid={fieldCtx?.invalid \|\| undefined}\n aria-describedby={fieldCtx?.descriptionId}\n // a11y(2026-07-14 dim-10):readonly 語意放 radiogroup(aria-readonly 合法 role;\n // 對齊上方 readonly-in-Field 分支 L133)。item(role=radio)不帶 aria-readonly —\n // axe 實證 radio 不允許該屬性,item 靠 data-readonly + tabIndex + click guard 鎖互動。\n aria-readonly={resolvedMode === 'readonly' \|\| undefined}\n {...props}\n disabled={resolvedMode === 'disabled'}\n ref={ref}\n />\n </RadioGroupDisabledContext.Provider>\n </RadioGroupReadonlyContext.Provider>\n )\n})\nRadioGroup.displayName = 'RadioGroup'\n// Field layout 宣告：RadioGroup 是 block primitive（多項堆疊），\n// 進入 <Field> 時 control area 自動切 items-start（block 分支不設 min-h、不加 padding-top,\n// 高度由內容決定;額外加 paddingTop 會 double padding — field.tsx block control area SSOT）。\n// Convention 詳見 components/Field/field.spec.md「Control area:Inline vs Block」段落。\n;(RadioGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'\n\n// ── RadioGroupItem Variants ─────────────────────────────────────────────────\n// 與 Checkbox 完全對齊：sm/md=16px, lg=20px。差異只有形狀（rounded-full）和指示器（filled dot）。\n\nconst radioItemVariants = cva(\n [\n 'grid place-content-center shrink-0 rounded-full',\n 'border border-border bg-surface',\n 'transition-colors duration-150',\n 'hover:border-border-hover',\n 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n 'data-[state=checked]:border-primary data-[state=checked]:text-primary',\n 'data-[state=checked]:hover:border-primary-hover data-[state=checked]:hover:text-primary-hover',\n 'disabled:cursor-not-allowed disabled:bg-disabled disabled:border-transparent disabled:hover:border-transparent',\n 'disabled:data-[state=checked]:bg-disabled disabled:data-[state=checked]:border-transparent disabled:data-[state=checked]:text-fg-disabled',\n // readOnly：鎖定互動但維持 checked/unchecked 視覺\n 'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n 'data-[readonly=true]:hover:border-border',\n ],\n {\n variants: {\n size: {\n sm: 'h-4 w-4',\n md: 'h-4 w-4',\n lg: 'h-5 w-5',\n },\n },\n defaultVariants: {\n size: 'md',\n },\n }\n)\n\n// ── Dot Size ────────────────────────────────────────────────────────────────\nconst dotSize: Record<string, number> = { sm: 8, md: 8, lg: 10 }\n\n// ── Types ───────────────────────────────────────────────────────────────────\n\ntype RadioItemPrimitiveProps = React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>\n\nexport interface RadioGroupItemProps\n extends RadioItemPrimitiveProps,\n VariantProps<typeof radioItemVariants> {\n /*\n Inline label。提供時 RadioGroupItem 自動透過 SelectionItem 包裝，\n * 套用 codified 樣式（text-body / text-foreground / disabled 色）。\n * 在 <Field> context 內時此 prop 仍然生效（Radio 的 label 是每個 item\n * 各自的，不是整組 Field 的；FieldLabel 是 RadioGroup 整體的 label）。\n /\n label?: React.ReactNode\n /\n Inline description（secondary 文字）。須與 label 搭配使用。\n * 套用 text-body / text-fg-secondary 樣式。\n /\n description?: React.ReactNode\n /* 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc SSOT;與 avatar 互斥)/\n icon?: LucideIcon\n /* 可選左側 avatar(label 前)— 同上 /\n avatar?: AvatarData\n /\n readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。\n * 通常整個 RadioGroup 一起設 readonly（由 parent RadioGroup 的 disabled\n * 或 readonly 行為決定），個別 item 也可設。\n */\n readOnly?: boolean\n}\n\n// ── RadioGroupItem ──────────────────────────────────────────────────────────\n\nconst RadioGroupItem = React.forwardRef<\n React.ElementRef<typeof RadioGroupPrimitive.Item>,\n RadioGroupItemProps\n>(\n (\n {\n className,\n size,\n label,\n icon,\n avatar,\n description,\n readOnly = false,\n disabled,\n id: idProp,\n ...props\n },\n ref\n ) => {\n const sizeKey = size ?? 'md'\n const dotPx = dotSize[sizeKey]\n\n // 注意:RadioGroup mode='display' 的純文字渲染由 RadioGroup 本體 walk-children 處理\n // (見上方 RadioGroup forwardRef 的 mode === 'display' 分支),RadioGroupItem 在 display\n // mode 下不會被獨立 render,故此處無 display 分支。\n\n // 注意：Radio 的 label 語意與 Checkbox/Switch 不同——\n // Checkbox/Switch 的 label 就是該 control 的唯一 label（被 Field context 接管），\n // RadioGroupItem 的 label 是「該選項」的 label（每 item 各自擁有），\n // FieldLabel 則是整個 RadioGroup 的 label。\n // 因此 RadioGroupItem 的 label 不因 Field context 被忽略。\n // group-level disabled(standalone <RadioGroup disabled>)也要降 label/description 色 —— Radix Root\n // disabled 只 propagate 給 radio 圈,label 色由 SelectionItem disabled 決定,故讀 RadioGroupDisabledContext 補上。\n const groupDisabled = React.useContext(RadioGroupDisabledContext)\n const resolvedDisabled = useResolvedFieldDisabled(disabled) \|\| groupDisabled\n // group-level readonly(RadioGroup mode='readonly')或 item-level readOnly,任一 true 即鎖互動。\n const groupReadonly = React.useContext(RadioGroupReadonlyContext)\n const effectiveReadonly = readOnly \|\| groupReadonly\n\n const generatedId = React.useId()\n const inputId = idProp ?? generatedId\n\n const rootEl = (\n <RadioGroupPrimitive.Item\n id={inputId}\n ref={ref}\n disabled={resolvedDisabled}\n // a11y(2026-07-14 dim-10):item(role=radio)不帶 aria-readonly — axe 實證 radio 不允許\n // 該屬性(readonly 語意由 Root role=radiogroup 宣告,見上方 L167-170)。item 靠\n // data-readonly + tabIndex + click guard 鎖互動。\n data-readonly={effectiveReadonly \|\| undefined}\n tabIndex={effectiveReadonly ? -1 : undefined}\n className={cn(radioItemVariants({ size }), className)}\n {...props}\n // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click\n // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍選中。\n // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 onCheck;\n // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(與 Checkbox/Switch 同修)。\n // 同時攔 Radix roving-focus 的 arrow-key onFocus → click() 路徑(同為 click event)。\n onClick={(event) => {\n if (effectiveReadonly) {\n event.preventDefault()\n return\n }\n props.onClick?.(event)\n }}\n >\n <RadioGroupPrimitive.Indicator className=\"grid place-content-center\">\n <Circle\n style={{ width: dotPx, height: dotPx }}\n className=\"fill-current text-current\"\n />\n </RadioGroupPrimitive.Indicator>\n </RadioGroupPrimitive.Item>\n )\n\n // 無 label → 只渲染 radio 本體\n if (label == null) return rootEl\n\n // 有 label → 透過 SelectionItem 包裝，與 Checkbox 一致（disabled 已於上方 useResolvedFieldDisabled 解析）\n return (\n <SelectionItem\n control={rootEl}\n label={label}\n description={description}\n icon={icon}\n avatar={avatar}\n htmlFor={inputId}\n disabled={resolvedDisabled}\n size={sizeKey}\n />\n )\n }\n)\nRadioGroupItem.displayName = 'RadioGroupItem'\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 radioGroupMeta = {\n component: 'RadioGroup',\n family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4 — field-controls.spec.md 成員名單不含 RadioGroup)\n variants: {\n\n },\n sizes: {\n // iconSize = 渲染指示器尺寸(對齊 checkbox/switch meta 慣例:checkbox iconSize=真 Check glyph 12/12/16)。\n // Radio 指示器是 filled dot 非 glyph,真值 = 上方 `const dotSize` map 8/8/10;\n // 控件框 16/16/20 與 Checkbox 對齊但那是 box 非「指示器」,不入此鍵(避免 metadata 語意 drift)。\n sm: { fieldHeight: 28, iconSize: 8, typography: 'body' },\n md: { fieldHeight: 32, iconSize: 8, typography: 'body' },\n lg: { fieldHeight: 36, iconSize: 10, typography: 'body-lg' },\n },\n // 2026-07-04 修 stale meta:移除 'active' — radioItemVariants cva 無 active-state 樣式,\n // Radix radio 也無 data-state=active(對照 checkboxMeta 正確不含 active)\n // 'checked' = 選定持續態(card 式 = border+text primary;2026-07-07 meta 詞彙統一補列)\n states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],\n tokens: {\n bg: ['bg-disabled', 'bg-surface'],\n fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],\n ring: ['ring-ring'],\n },\n defaultSize: 'md',\n} as const\n\nexport { RadioGroup, RadioGroupItem, radioItemVariants }\n"],"names":[],"mappings":"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"}

package/dist/components/ScrollArea/scroll-area.d.ts CHANGED Viewed

@@ -27,7 +27,17 @@ import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
  * - 單行 truncate(用 text-overflow:ellipsis 就夠)
  * - 極短內容(不會捲動 → 不需 wrapper)
  */
-declare const ScrollArea: React.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+declare const ScrollArea: React.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaProps & React.RefAttributes<HTMLDivElement>, "ref"> & {
+    /** 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;
+} & React.RefAttributes<HTMLDivElement>>;
 declare const ScrollBar: React.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaScrollbarProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 export declare const scrollAreaMeta: {
     readonly component: "ScrollArea";

package/dist/components/ScrollArea/scroll-area.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"scroll-area.d.ts","sourceRoot":"","sources":["../../../src/components/ScrollArea/scroll-area.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,mBAAmB,MAAM,6BAA6B,CAAA;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,QAAA,MAAM,UAAU~~,+JA2Bd~~,CAAA;AAGF,QAAA,MAAM,SAAS,wKAwBb,CAAA;AAKF,eAAO,MAAM,cAAc;;;;;;;;;;;CAejB,CAAA;AAEV,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAA"}
1	+ {"version":3,"file":"scroll-area.d.ts","sourceRoot":"","sources":["../../../src/components/ScrollArea/scroll-area.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,mBAAmB,MAAM,6BAA6B,CAAA;AAGlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,QAAA,MAAM,UAAU;IAGZ;;;qDAGiD;YACzC,OAAO;IACf;;8DAE0D;uBACvC,CAAC,GAAG,CAAC,CAAC;wCA6B3B,CAAA;AAGF,QAAA,MAAM,SAAS,wKAwBb,CAAA;AAKF,eAAO,MAAM,cAAc;;;;;;;;;;;CAejB,CAAA;AAEV,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAA"}

package/dist/components/ScrollArea/scroll-area.js CHANGED Viewed

@@ -2,7 +2,7 @@ import { jsxs, jsx } from "react/jsx-runtime";
 import * as React from "react";
 import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
 import { cn } from "../../lib/utils.js";
-const ScrollArea = React.forwardRef(({ className, children, ...props }, ref) => /* @__PURE__ */ jsxs(
+const ScrollArea = React.forwardRef(({ className, children, fillX, viewportTabIndex = 0, ...props }, ref) => /* @__PURE__ */ jsxs(
   ScrollAreaPrimitive.Root,
   {
     ref,
@@ -12,8 +12,11 @@ const ScrollArea = React.forwardRef(({ className, children, ...props }, ref) =>
       /* @__PURE__ */ jsx(
         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
         }
       ),

package/dist/components/ScrollArea/scroll-area.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"scroll-area.js","sources":["../../../src/components/ScrollArea/scroll-area.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 * as React from 'react'\nimport * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area'\nimport { cn } from '@/lib/utils'\n\n/*\n ScrollArea — 自訂樣式的捲動區(Radix ScrollArea primitive 包裝)\n \n 世界級對照:shadcn `ScrollArea` / Ant Design scrollable 容器的 pattern。\n \n ── 為什麼需要 ScrollArea ──\n * Native scrollbar 跨 OS 不一致:\n * macOS: overlay(不吃寬度,預設隱藏,滾動時浮出)\n * Windows / Linux: always-visible(永遠吃 ~15-17px 寬度)\n \n 結果:同一個 DataTable / Sheet / Dialog 內容在 macOS 看起來對齊,在 Windows\n * 右側被吃 17px 跑版(「Left pinned + Row Actions」那張圖的問題)。\n \n ScrollArea 用 Radix 包裝自建 overlay 捲軸 → 跨 OS 一致不吃寬度,\n * 捲動時浮現(hover / scroll 自動顯示)。\n \n ── 何時用 ──\n * - DataTable 橫向捲動(水平跑版最明顯場景)\n * - Sheet / Dialog 垂直內容捲動(body 太長)\n * - Sidebar nav 長列表\n * - 任何「內容可能溢出容器」且「跨 OS 視覺必須一致」的場景\n \n ── 何時不用 ──\n * - 全頁捲動(瀏覽器 document scroll,保持 native 即可;ScrollArea 是 sub-region)\n * - 單行 truncate(用 text-overflow:ellipsis 就夠)\n * - 極短內容(不會捲動 → 不需 wrapper)\n /\n\nconst ScrollArea = React.forwardRef<\n React.ElementRef<typeof ScrollAreaPrimitive.Root>,\n React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>\n>(({ className, children, ...props }, ref) => (\n <ScrollAreaPrimitive.Root\n ref={ref}\n className={cn('relative flex flex-col overflow-hidden', className)}\n {...props}\n >\n {/ Viewport canonical(2026-04-23):Root 用 `flex flex-col`,Viewport 用 `flex-1 min-h-0`。\n 原 `h-full` 在 Root 為 flex item(外層 flex-1 min-h-0)時失效 — Chrome 不把\n flex-computed 高度視為 `height: 100%` 的 definite anchor,導致 Viewport 撐成\n content height 而非 parent height → 失去 scroll 能力。\n 改 Root 為 flex container,Viewport 成 flex item,flex algorithm 給 definite height。\n `w-full` 保留(水平維度不受影響)。 /}\n {/ a11y(2026-04-25 axe scrollable-region-focusable fix):Viewport 需 tabIndex=0\n 才能 keyboard focus(Safari 不自動把 scroll container 標 focusable)。focus-\n visible:outline 用 DS focus ring,不破壞視覺。 /}\n <ScrollAreaPrimitive.Viewport\n tabIndex={0}\n className~~=\"~~flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring\"\n >\n {children}\n </ScrollAreaPrimitive.Viewport>\n <ScrollBar />\n <ScrollAreaPrimitive.Corner />\n </ScrollAreaPrimitive.Root>\n))\nScrollArea.displayName = 'ScrollArea'\n\nconst ScrollBar = React.forwardRef<\n React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,\n React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>\n>(({ className, orientation = 'vertical', ...props }, ref) => (\n <ScrollAreaPrimitive.ScrollAreaScrollbar\n ref={ref}\n orientation={orientation}\n className={cn(\n 'flex touch-none select-none transition-colors',\n orientation === 'vertical' && 'h-full w-2.5 border-l border-l-transparent p-[1px]',\n orientation === 'horizontal' && 'h-2.5 flex-col border-t border-t-transparent p-[1px]',\n className,\n )}\n {...props}\n >\n {/ Thumb 用 scrollbar-thumb / -hover semantic alias(2026-05-09 抽 SSOT,跟 DataTable fake scrollbar\n 共享 token)。Token 值仍 = `--border` / `--border-hover`(neutral-5/-6)— 世界級 SaaS\n (Linear / Notion / Figma / macOS)scrollbar thumb 慣例「很淡、幾乎看不見,hover 略深」。\n 前身直接 `bg-border` borrowing(2026-04 ship)→ semantic alias 收斂 SSOT(避免 thumb 視覺\n 未來演化時誤動 Field/Input/Checkbox border 視覺)。對齊 shadcn ScrollArea source `bg-border`。 */}\n <ScrollAreaPrimitive.ScrollAreaThumb\n className={cn('relative flex-1 rounded-full bg-[var(--scrollbar-thumb)] hover:bg-[var(--scrollbar-thumb-hover)] transition-colors')}\n />\n </ScrollAreaPrimitive.ScrollAreaScrollbar>\n))\nScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName\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 scrollAreaMeta = {\n component: 'ScrollArea',\n family: 'self-contained', // 對齊 scroll-area.spec.md frontmatter(SSOT;同 Separator/OverflowIndicator meta 寫法)\n variants: {\n\n },\n sizes: {\n\n },\n states: ['default'],\n tokens: {\n bg: [],\n fg: [],\n ring: [],\n },\n} as const\n\nexport { ScrollArea, ScrollBar }\n"],"names":[],"mappings":";;;;AAiCA,MAAM,aAAa,MAAM,~~WAGvB~~,CAAC,EAAE,WAAW,UAAU,GAAG,~~SAAS~~,~~QACpC~~;AAAA,EAAC,oBAAoB;AAAA,EAApB;AAAA,IACC;AAAA,IACA,WAAW,GAAG,0CAA0C,SAAS;AAAA,IAChE,GAAG;AAAA,IAWJ,UAAA;AAAA,MAAA;AAAA,QAAC,oBAAoB;AAAA,QAApB;AAAA,UACC,UAAU;AAAA,UACV,~~WAAU~~;AAAA,~~UAET~~;AAAA,QAAA;AAAA,MAAA;AAAA,0BAEF,WAAA,EAAU;AAAA,MACX,oBAAC,oBAAoB,QAApB,CAAA,CAA2B;AAAA,IAAA;AAAA,EAAA;AAC9B,CACD;AACD,WAAW,cAAc;AAEzB,MAAM,YAAY,MAAM,WAGtB,CAAC,EAAE,WAAW,cAAc,YAAY,GAAG,SAAS,QACpD;AAAA,EAAC,oBAAoB;AAAA,EAApB;AAAA,IACC;AAAA,IACA;AAAA,IACA,WAAW;AAAA,MACT;AAAA,MACA,gBAAgB,cAAc;AAAA,MAC9B,gBAAgB,gBAAgB;AAAA,MAChC;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,IAOJ,UAAA;AAAA,MAAC,oBAAoB;AAAA,MAApB;AAAA,QACC,WAAW,GAAG,oHAAoH;AAAA,MAAA;AAAA,IAAA;AAAA,EACpI;AACF,CACD;AACD,UAAU,cAAc,oBAAoB,oBAAoB;AAIzD,MAAM,iBAAiB;AAAA,EAC5B,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,SAAS;AAAA,EAClB,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAA;AAAA,IACJ,MAAM,CAAA;AAAA,EAAC;AAEX;"}
1	+ {"version":3,"file":"scroll-area.js","sources":["../../../src/components/ScrollArea/scroll-area.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 * as React from 'react'\nimport * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area'\nimport { cn } from '@/lib/utils'\n\n/*\n ScrollArea — 自訂樣式的捲動區(Radix ScrollArea primitive 包裝)\n \n 世界級對照:shadcn `ScrollArea` / Ant Design scrollable 容器的 pattern。\n \n ── 為什麼需要 ScrollArea ──\n * Native scrollbar 跨 OS 不一致:\n * macOS: overlay(不吃寬度,預設隱藏,滾動時浮出)\n * Windows / Linux: always-visible(永遠吃 ~15-17px 寬度)\n \n 結果:同一個 DataTable / Sheet / Dialog 內容在 macOS 看起來對齊,在 Windows\n * 右側被吃 17px 跑版(「Left pinned + Row Actions」那張圖的問題)。\n \n ScrollArea 用 Radix 包裝自建 overlay 捲軸 → 跨 OS 一致不吃寬度,\n * 捲動時浮現(hover / scroll 自動顯示)。\n \n ── 何時用 ──\n * - DataTable 橫向捲動(水平跑版最明顯場景)\n * - Sheet / Dialog 垂直內容捲動(body 太長)\n * - Sidebar nav 長列表\n * - 任何「內容可能溢出容器」且「跨 OS 視覺必須一致」的場景\n \n ── 何時不用 ──\n * - 全頁捲動(瀏覽器 document scroll,保持 native 即可;ScrollArea 是 sub-region)\n * - 單行 truncate(用 text-overflow:ellipsis 就夠)\n * - 極短內容(不會捲動 → 不需 wrapper)\n /\n\nconst ScrollArea = React.forwardRef<\n React.ElementRef<typeof ScrollAreaPrimitive.Root>,\n React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> & {\n /* 2026-07-08(WM 戰役 R2):Radix Viewport 內建 wrapper `display:table; min-width:100%`\n * 讓垂直捲動容器內的 flex 多欄佈局以 max-content 佈局、突破 100% 寬(WM 兩欄 dialog\n * 右欄被裁 33px 實證)。垂直捲動場景 opt-in 此 prop 中和為 block/w-full(水平捲動\n * 場景勿開 — table wrapper 是其 min-content 溢出機制)。 /\n fillX?: boolean\n /* Viewport tabIndex(預設 0 = axe scrollable-region-focusable fix)。內容已有自帶\n * focusable 元素(如 TimePicker role=listbox tabIndex=0)時傳 -1 消除雙 tab stop —\n * axe 由內部 focusable 內容滿足,焦點直接落在有 keydown 的 listbox 上。 /\n viewportTabIndex?: 0 \| -1\n }\n>(({ className, children, fillX, viewportTabIndex = 0, ...props }, ref) => (\n <ScrollAreaPrimitive.Root\n ref={ref}\n className={cn('relative flex flex-col overflow-hidden', className)}\n {...props}\n >\n {/ Viewport canonical(2026-04-23):Root 用 `flex flex-col`,Viewport 用 `flex-1 min-h-0`。\n 原 `h-full` 在 Root 為 flex item(外層 flex-1 min-h-0)時失效 — Chrome 不把\n flex-computed 高度視為 `height: 100%` 的 definite anchor,導致 Viewport 撐成\n content height 而非 parent height → 失去 scroll 能力。\n 改 Root 為 flex container,Viewport 成 flex item,flex algorithm 給 definite height。\n `w-full` 保留(水平維度不受影響)。 /}\n {/ a11y(2026-04-25 axe scrollable-region-focusable fix):Viewport 需 tabIndex=0\n 才能 keyboard focus(Safari 不自動把 scroll container 標 focusable)。focus-\n visible:outline 用 DS focus ring,不破壞視覺。 /}\n <ScrollAreaPrimitive.Viewport\n tabIndex={viewportTabIndex}\n className={cn(\n 'flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring',\n fillX && '[&>div]:!block [&>div]:!w-full [&>div]:!min-w-0',\n )}\n >\n {children}\n </ScrollAreaPrimitive.Viewport>\n <ScrollBar />\n <ScrollAreaPrimitive.Corner />\n </ScrollAreaPrimitive.Root>\n))\nScrollArea.displayName = 'ScrollArea'\n\nconst ScrollBar = React.forwardRef<\n React.ElementRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,\n React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>\n>(({ className, orientation = 'vertical', ...props }, ref) => (\n <ScrollAreaPrimitive.ScrollAreaScrollbar\n ref={ref}\n orientation={orientation}\n className={cn(\n 'flex touch-none select-none transition-colors',\n orientation === 'vertical' && 'h-full w-2.5 border-l border-l-transparent p-[1px]',\n orientation === 'horizontal' && 'h-2.5 flex-col border-t border-t-transparent p-[1px]',\n className,\n )}\n {...props}\n >\n {/ Thumb 用 scrollbar-thumb / -hover semantic alias(2026-05-09 抽 SSOT,跟 DataTable fake scrollbar\n 共享 token)。Token 值仍 = `--border` / `--border-hover`(neutral-5/-6)— 世界級 SaaS\n (Linear / Notion / Figma / macOS)scrollbar thumb 慣例「很淡、幾乎看不見,hover 略深」。\n 前身直接 `bg-border` borrowing(2026-04 ship)→ semantic alias 收斂 SSOT(避免 thumb 視覺\n 未來演化時誤動 Field/Input/Checkbox border 視覺)。對齊 shadcn ScrollArea source `bg-border`。 */}\n <ScrollAreaPrimitive.ScrollAreaThumb\n className={cn('relative flex-1 rounded-full bg-[var(--scrollbar-thumb)] hover:bg-[var(--scrollbar-thumb-hover)] transition-colors')}\n />\n </ScrollAreaPrimitive.ScrollAreaScrollbar>\n))\nScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName\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 scrollAreaMeta = {\n component: 'ScrollArea',\n family: 'self-contained', // 對齊 scroll-area.spec.md frontmatter(SSOT;同 Separator/OverflowIndicator meta 寫法)\n variants: {\n\n },\n sizes: {\n\n },\n states: ['default'],\n tokens: {\n bg: [],\n fg: [],\n ring: [],\n },\n} as const\n\nexport { ScrollArea, ScrollBar }\n"],"names":[],"mappings":";;;;AAiCA,MAAM,aAAa,MAAM,WAavB,CAAC,EAAE,WAAW,UAAU,OAAO,mBAAmB,GAAG,GAAG,MAAA,GAAS,QACjE;AAAA,EAAC,oBAAoB;AAAA,EAApB;AAAA,IACC;AAAA,IACA,WAAW,GAAG,0CAA0C,SAAS;AAAA,IAChE,GAAG;AAAA,IAWJ,UAAA;AAAA,MAAA;AAAA,QAAC,oBAAoB;AAAA,QAApB;AAAA,UACC,UAAU;AAAA,UACV,WAAW;AAAA,YACT;AAAA,YACA,SAAS;AAAA,UAAA;AAAA,UAGV;AAAA,QAAA;AAAA,MAAA;AAAA,0BAEF,WAAA,EAAU;AAAA,MACX,oBAAC,oBAAoB,QAApB,CAAA,CAA2B;AAAA,IAAA;AAAA,EAAA;AAC9B,CACD;AACD,WAAW,cAAc;AAEzB,MAAM,YAAY,MAAM,WAGtB,CAAC,EAAE,WAAW,cAAc,YAAY,GAAG,SAAS,QACpD;AAAA,EAAC,oBAAoB;AAAA,EAApB;AAAA,IACC;AAAA,IACA;AAAA,IACA,WAAW;AAAA,MACT;AAAA,MACA,gBAAgB,cAAc;AAAA,MAC9B,gBAAgB,gBAAgB;AAAA,MAChC;AAAA,IAAA;AAAA,IAED,GAAG;AAAA,IAOJ,UAAA;AAAA,MAAC,oBAAoB;AAAA,MAApB;AAAA,QACC,WAAW,GAAG,oHAAoH;AAAA,MAAA;AAAA,IAAA;AAAA,EACpI;AACF,CACD;AACD,UAAU,cAAc,oBAAoB,oBAAoB;AAIzD,MAAM,iBAAiB;AAAA,EAC5B,WAAW;AAAA,EACX,QAAQ;AAAA;AAAA,EACR,UAAU,CAAA;AAAA,EAGV,OAAO,CAAA;AAAA,EAGP,QAAQ,CAAC,SAAS;AAAA,EAClB,QAAQ;AAAA,IACN,IAAI,CAAA;AAAA,IACJ,IAAI,CAAA;AAAA,IACJ,MAAM,CAAA;AAAA,EAAC;AAEX;"}

package/dist/components/Select/select.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { LucideIcon } from 'lucide-react';
-import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
+import type { FieldMode, FieldVariant, FieldWidth } from '../../components/Field/field-types';
 import { type SelectMenuOption } from '../../components/SelectMenu/select-menu';
 /**
  * Select 用的 option schema(2026-05-10 Issue 4 + post-prune unify):**explicit extends
@@ -27,10 +27,48 @@ export interface SelectGroupConfig {
     key: string;
     label: string;
 }
-export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'size' | 'value' | 'defaultValue' | 'onChange'> {
+/**
+ * 原生 `<select>` 屬性 allowlist(2026-07-14 API 策展 D,user 拍板「全部收窄」)。
+ *
+ * 舊契約 `extends Omit<SelectHTMLAttributes, ...>` 型別承諾**全部**原生 select 屬性,但桌機
+ * 自訂 combobox(div trigger + hidden input mirror)只有部分真生效 — 其餘 silent no-op /
+ * 被元件內部覆寫,「型別承諾 ≠ 實作出口」= footgun。改 `Pick<>` 顯式 allowlist,**只承諾
+ * 兩路徑(desktop CustomSelect / mobile NativeSelect)皆有實作出口的屬性**,盤點以 code 為準:
+ *
+ * - `id` — 桌機 trigger div / mobile `<select>`,皆 `idProp ?? fieldCtx?.id`
+ * - `name` / `form` / `required` — 桌機經 hidden input mirror(D2 2026-07-13,見 hiddenInputEl
+ *   docblock)/ mobile 原生 `<select>` spread
+ * - `disabled` — 兩路徑 `useResolvedFieldDisabled` cascade → mode 分流
+ * - `className` / `style` — 兩路徑 field wrapper
+ * - `onFocus` / `onBlur` — 桌機 rest spread 到 focusable trigger(tabIndex=0)/ mobile spread
+ * - `onKeyDown` — 桌機 consumer handler 先跑再走元件導覽(dim-9)/ mobile 原生
+ * - `aria-label` / `aria-describedby` / `aria-errormessage` — 兩路徑顯式接線(fieldCtx fallback)
+ * - `autoFocus` / `autoComplete` — **mobile-only**:NativeSelect 原生 `<select>` 生效;桌機
+ *   custom combobox 無原生對應 = documented no-op(桌機 autofill 由 hidden input mirror 的
+ *   option-match onChange guard 承擔)
+ * - `data-*` — 兩路徑 spread passthrough(dim-9 契約;index signature 顯式承諾,見下)
+ *
+ * 被砍者(原 extends 承諾但從未生效 / 被元件覆寫,不再進型別):`multiple` / `children` /
+ * `tabIndex`(桌機恆 0)/ `aria-labelledby`(桌機由 fieldCtx.labelId / aria-label 管理,
+ * consumer 值會被覆寫)/ 其餘 generic HTMLAttributes(title / dir / onClick 等)。
+ * 需要時先接線(兩路徑等效)再入表,**不回 extends 全開**。
+ *
+ * 世界級對照:自訂 combobox 皆走 curated 原生屬性子集,無人 extends 全部 SelectHTMLAttributes —
+ * Radix Select.Root 顯式列舉 name/disabled/required/form/autoComplete
+ * (radix-ui.com/primitives/docs/components/select#root)/ Headless UI Listbox name/form/disabled
+ * (headlessui.com/react/listbox#using-with-html-forms)/ React Aria Select name/autoComplete/
+ * isDisabled/isRequired(react-spectrum.adobe.com/react-aria/Select.html)。
+ */
+export interface SelectProps extends Pick<React.SelectHTMLAttributes<HTMLSelectElement>, 'id' | 'className' | 'style' | 'name' | 'form' | 'required' | 'disabled' | 'onFocus' | 'onBlur' | 'onKeyDown' | 'aria-label' | 'aria-describedby' | 'aria-errormessage' | 'autoFocus' | 'autoComplete'> {
+    /** `data-*` passthrough(桌機 trigger div rest spread / mobile `<select>` spread;dim-9 契約)。 */
+    [dataAttribute: `data-${string}`]: unknown;
     mode?: FieldMode;
     /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
     variant?: FieldVariant;
+    /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮:value 寬 + slot 元素寬 + gap +
+     *  field 內 padding;chrome 與互動不變。場景 = detail pane inline metadata。
+     *  SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+    width?: FieldWidth;
     error?: boolean;
     size?: 'sm' | 'md' | 'lg';
     options: SelectOption[];
@@ -76,13 +114,16 @@ export interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectE
      */
     showDisplayEndIcon?: boolean;
     /**
-     * Trigger 內「已選項目」客製 render(2026-05-07 v15.5)。
+     * 「已選項目」客製 render(2026-05-07 v15.5;2026-07-08 A 案回歸修正擴及 4 mode)。
      *
-     * 設了 → trigger 不走純文字 / Tag 預設 path,改用 consumer 提供的 ReactNode(收 selectedOpt)。
+     * 設了 → 已選值不走純文字 / Tag 預設 path,改用 consumer 提供的 ReactNode(收 selectedOpt)。
+     * **display / readonly / disabled / edit 4 mode 共享同一 renderer**(field-controls.spec.md
+     * 共享 contract (a),禁 edit-only)— renderer 輸出屬「值內容」(status icon+text 等語意呈現),
+     * display 態照常渲染;A 案撤的是 affordance(chevron/outline),非值內容(field.spec.md L6 分層)。
      * Searchable+open 仍走 input(搜尋優先)。Empty value(no selection)仍走 placeholder。
      *
      * 用例:PeoplePicker 用此 slot 把 single 選中的 person render 成 PersonDisplay
-     * (avatar + name)而非純文字 label。對齊 PeoplePicker = Select wrapper SSOT。
+     * (avatar + name)而非純文字 label;DataTable status 欄 icon+text。對齊 PeoplePicker = Select wrapper SSOT。
      */
     selectedItemRenderer?: (selectedOpt: SelectOption) => React.ReactNode;
     /** 搜尋無結果提示(2026-07-04 Q4 拍板接線 — 原 spec 宣稱可覆寫但 prop 從未轉發)。

package/dist/components/Select/select.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/Select/select.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;~~AAK3F~~,OAAO,EAAwD,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAc/I;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAID,MAAM,WAAW,WACf,SAAQ,IAAI,~~CAAC~~,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,~~EAAE~~,~~MAAM~~,GAAG,OAAO,GAAG,~~cAAc~~,GAAG,UAAU,CAAC;~~IAC3G~~,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB;;;;kGAI8F;IAC9F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;IACzB,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;4CAGwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;0EAEsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;yFACqF;IACrF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B~~;;;;;;;;OAQG~~;IACH,oBAAoB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAA;IACrE;;;qFAGiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;~~AAwjBD~~,QAAA,MAAM,MAAM,wGAUX,CAAA;AAKD,eAAO,MAAM,UAAU;;;;;;;;;;;CAgBb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}
1	+ {"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../../src/components/Select/select.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAwB,UAAU,EAAE,MAAM,8CAA8C,CAAA;AAK7H,OAAO,EAAwD,KAAK,gBAAgB,EAAE,MAAM,mDAAmD,CAAA;AAc/I;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAa,SAAQ,gBAAgB;IACpD,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,2CAA2C;AAC3C,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,WAAW,WACf,SAAQ,IAAI,CACV,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EAE3C,IAAI,GAAG,WAAW,GAAG,OAAO,GAC5B,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GACzC,SAAS,GAAG,QAAQ,GAAG,WAAW,GAClC,YAAY,GAAG,kBAAkB,GAAG,mBAAmB,GAEvD,WAAW,GAAG,cAAc,CAC/B;IACD,4FAA4F;IAC5F,CAAC,aAAa,EAAE,QAAQ,MAAM,EAAE,GAAG,OAAO,CAAA;IAC1C,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uFAAuF;IACvF,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB;;iEAE6D;IAC7D,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;IACzB,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,iBAAiB,EAAE,CAAA;IAC5B,qFAAqF;IACrF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB;;;;kGAI8F;IAC9F,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,OAAO,CAAC,EAAE,OAAO,GAAG,KAAK,CAAA;IACzB,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;4CAGwC;IACxC,OAAO,CAAC,EAAE,OAAO,CAAA;IAEjB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;0EAEsE;IACtE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;yFACqF;IACrF,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACtC;;;;;;;;OAQG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,oBAAoB,CAAC,EAAE,CAAC,WAAW,EAAE,YAAY,KAAK,KAAK,CAAC,SAAS,CAAA;IACrE;;;qFAGiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAgqBD,QAAA,MAAM,MAAM,wGAUX,CAAA;AAKD,eAAO,MAAM,UAAU;;;;;;;;;;;CAgBb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,CAAA"}

package/dist/components/Select/select.js CHANGED Viewed

@@ -2,10 +2,10 @@ import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import * as React from "react";
 import { ChevronDown, X } from "lucide-react";
 import { cn } from "../../lib/utils.js";
-import { bareInputStyles, fieldWrapperStyles, EMPTY_DISPLAY, fieldDisplayTextClass, nakedCellRowModeAlign } from "../Field/field-wrapper.js";
+import { bareInputStyles, fieldWrapperStyles, fieldDisplayTextClass, nakedCellRowModeAlign } from "../Field/field-wrapper.js";
 import { Tag } from "../Tag/tag.js";
 import { ItemPrefix, ItemSuffix, ICON_SIZE, ItemInlineAction } from "../../patterns/element-anatomy/item-anatomy.js";
-import { useFieldContext, useResolvedFieldInvalid, useResolvedFieldDisabled, useResolvedFieldSize, useResolvedFieldMode, useResolvedFieldVariant } from "../Field/field-context.js";
+import { useFieldContext, useResolvedFieldInvalid, useResolvedFieldDisabled, useResolvedFieldSize, useResolvedFieldMode, useResolvedFieldVariant, useFieldEmptyDisplay, fieldEmptyColorClass } from "../Field/field-context.js";
 import { useActiveDescendant, forwardKeyToListbox, SelectMenu } from "../SelectMenu/select-menu.js";
 import { useIsTouchDevice } from "../../hooks/use-is-touch-device.js";
 import { useControllable } from "../../hooks/use-controllable.js";
@@ -114,6 +114,7 @@ CustomSelectTriggerContent.displayName = "CustomSelectTriggerContent";
 function ReadonlyDisplay({
   mode,
   variant: variantProp,
+  width,
   size,
   options,
   value,
@@ -121,35 +122,41 @@ function ReadonlyDisplay({
   startIcon: StartIcon,
   className,
   placeholder,
-  showDisplayEndIcon
+  showDisplayEndIcon,
+  selectedItemRenderer
 }) {
-  var _a;
   const resolvedMode = mode ?? "readonly";
+  const emptyDisplay = useFieldEmptyDisplay();
   const variant = variantProp ?? "default";
   const sz = size ?? "md";
   const iconSize = getIconSize(sz);
-  const label = ((_a = options == null ? void 0 : options.find((o) => o.value === value)) == null ? void 0 : _a.label) ?? value;
+  const selectedOpt = options == null ? void 0 : options.find((o) => o.value === value);
+  const label = (selectedOpt == null ? void 0 : selectedOpt.label) ?? value;
   const iconColor = resolvedMode === "disabled" ? "text-fg-disabled" : "text-fg-muted";
   const isTextDisplay = display !== "tag";
-  const emptyColorCls = resolvedMode === "disabled" ? "text-fg-disabled" : "text-fg-muted";
-  const emptyText = placeholder ?? EMPTY_DISPLAY;
+  const emptyColorCls = fieldEmptyColorClass(resolvedMode);
+  const emptyText = placeholder ?? emptyDisplay;
   if (resolvedMode === "display") {
     if (!showDisplayEndIcon) {
-      if (!value) return /* @__PURE__ */ jsx("span", { className: cn(fieldDisplayTextClass(sz), "text-fg-muted", className), children: emptyText });
+      if (!value) return /* @__PURE__ */ jsx("span", { className: cn(fieldDisplayTextClass(sz), emptyColorCls, className), children: emptyText });
+      if (selectedItemRenderer && selectedOpt) {
+        return /* @__PURE__ */ jsx("span", { className: cn(fieldDisplayTextClass(sz), "inline-flex items-center min-w-0", nakedCellRowModeAlign, className), children: selectedItemRenderer(selectedOpt) });
+      }
       if (isTextDisplay) return /* @__PURE__ */ jsx("span", { className: cn(fieldDisplayTextClass(sz), "truncate", className), children: label });
-      const selOpt2 = options == null ? void 0 : options.find((o) => o.value === value);
-      const tVariant2 = selOpt2 == null ? void 0 : selOpt2.tagVariant;
+      const tVariant2 = selectedOpt == null ? void 0 : selectedOpt.tagVariant;
       return /* @__PURE__ */ jsx(Tag, { size: sz, color: tVariant2, className, children: label });
     }
-    const selOpt = options == null ? void 0 : options.find((o) => o.value === value);
-    const tVariant = selOpt == null ? void 0 : selOpt.tagVariant;
+    const tVariant = selectedOpt == null ? void 0 : selectedOpt.tagVariant;
     return /* @__PURE__ */ jsxs(
       "div",
       {
-        className: cn(fieldWrapperStyles({ mode: "display", variant, size: sz }), value && !isTextDisplay && tagPadding[sz], className),
+        className: cn(fieldWrapperStyles({ mode: "display", variant, width, size: sz }), value && !isTextDisplay && tagPadding[sz], className),
         "data-field-mode": "display",
         children: [
-          isTextDisplay ? /* @__PURE__ */ jsx("span", { className: cn(bareInputStyles, "flex-1 min-w-0 truncate", !value && emptyColorCls), children: value ? label : emptyText }) : value ? /* @__PURE__ */ jsx(Tag, { size: sz, color: tVariant, children: label }) : /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0", emptyColorCls), children: emptyText }),
+          selectedItemRenderer && value && selectedOpt ? (
+            // renderer 優先(同 CustomSelectTriggerContent 優先序):值內容歸 renderer,chevron 歸 D-path chrome
+            /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 inline-flex items-center", nakedCellRowModeAlign), children: selectedItemRenderer(selectedOpt) })
+          ) : isTextDisplay ? /* @__PURE__ */ jsx("span", { className: cn(bareInputStyles, "flex-1 min-w-0 truncate", !value && emptyColorCls), children: value ? label : emptyText }) : value ? /* @__PURE__ */ jsx(Tag, { size: sz, color: tVariant, children: label }) : /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0", emptyColorCls), children: emptyText }),
           /* @__PURE__ */ jsx(ItemSuffix, { children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: "text-fg-muted pointer-events-none", "aria-hidden": true }) })
         ]
       }
@@ -157,16 +164,22 @@ function ReadonlyDisplay({
   }
   const showIndicator = variant === "naked" ? !!showDisplayEndIcon : resolvedMode === "disabled";
   const ariaDisabled = resolvedMode === "disabled" ? true : void 0;
+  if (selectedItemRenderer && value && selectedOpt) {
+    return /* @__PURE__ */ jsxs("div", { className: cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), className), "data-field-mode": resolvedMode, "aria-disabled": ariaDisabled, children: [
+      StartIcon && /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(StartIcon, { size: iconSize, className: cn("pointer-events-none", iconColor), "aria-hidden": true }) }),
+      /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 inline-flex items-center", nakedCellRowModeAlign, resolvedMode === "disabled" && "text-fg-disabled"), children: selectedItemRenderer(selectedOpt) }),
+      showIndicator && /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0", iconColor), "aria-hidden": true }) })
+    ] });
+  }
   if (isTextDisplay) {
-    return /* @__PURE__ */ jsxs("div", { className: cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), className), "data-field-mode": resolvedMode, "aria-disabled": ariaDisabled, children: [
+    return /* @__PURE__ */ jsxs("div", { className: cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), className), "data-field-mode": resolvedMode, "aria-disabled": ariaDisabled, children: [
       StartIcon && /* @__PURE__ */ jsx(ItemPrefix, { children: /* @__PURE__ */ jsx(StartIcon, { size: iconSize, className: cn("pointer-events-none", iconColor), "aria-hidden": true }) }),
       /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 truncate", resolvedMode === "disabled" && "text-fg-disabled"), children: value ? label : /* @__PURE__ */ jsx("span", { className: emptyColorCls, children: emptyText }) }),
       showIndicator && /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0", iconColor), "aria-hidden": true }) })
     ] });
   }
-  const selectedOpt = options == null ? void 0 : options.find((o) => o.value === value);
   const tagVariant = selectedOpt == null ? void 0 : selectedOpt.tagVariant;
-  return /* @__PURE__ */ jsxs("div", { className: cn(fieldWrapperStyles({ mode: resolvedMode, variant, size: sz }), value && tagPadding[sz], className), style: { paddingRight: "var(--field-px)" }, "data-field-mode": resolvedMode, "aria-disabled": ariaDisabled, children: [
+  return /* @__PURE__ */ jsxs("div", { className: cn(fieldWrapperStyles({ mode: resolvedMode, variant, width, size: sz }), value && tagPadding[sz], className), style: { paddingRight: "var(--field-px)" }, "data-field-mode": resolvedMode, "aria-disabled": ariaDisabled, children: [
     value ? /* @__PURE__ */ jsx(Tag, { size: sz, color: tagVariant, children: label }) : /* @__PURE__ */ jsx("span", { className: emptyColorCls, children: emptyText }),
     showIndicator && /* @__PURE__ */ jsx(ItemSuffix, { className: "pointer-events-none", children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("shrink-0", iconColor), "aria-hidden": true }) })
   ] });
@@ -175,6 +188,7 @@ const NativeSelect = React.forwardRef(
   ({
     mode,
     variant: variantProp,
+    width,
     error: errorProp = false,
     size: sizeProp,
     options,
@@ -193,6 +207,9 @@ const NativeSelect = React.forwardRef(
     "aria-errormessage": ariaErrorMessageProp,
     // 2026-07-04:Custom-path-only props 顯式 destructure 丟棄(不 spread 到原生 <select> 消 React
     // unknown-prop warning);各 prop docblock 已註「僅 Custom path 生效」語意
+    // 2026-07-08 A 案回歸修正:selectedItemRenderer 從丟棄名單移出 — Native path 的
+    // ReadonlyDisplay(display/readonly/disabled)同樣消費值內容 renderer(contract (a) 4-mode
+    // 共享,值內容不因 pointer type 而異);native <select> edit 路徑仍不消費(原生 option 無法客製 render)。
     searchable: _searchable,
     groups: _groups,
     loading: _loading,
@@ -200,7 +217,7 @@ const NativeSelect = React.forwardRef(
     emptyText: _emptyText,
     defaultOpen: _defaultOpen,
     onOpenChange: _onOpenChange,
-    selectedItemRenderer: _selectedItemRenderer,
+    selectedItemRenderer,
     ...props
   }, ref) => {
     const fieldCtx = useFieldContext();
@@ -225,7 +242,7 @@ const NativeSelect = React.forwardRef(
       else if (ref) ref.current = el;
     }, [ref]);
     if (resolvedMode !== "edit") {
-      return /* @__PURE__ */ jsx(ReadonlyDisplay, { mode: resolvedMode, variant, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon });
+      return /* @__PURE__ */ jsx(ReadonlyDisplay, { mode: resolvedMode, variant, width, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon, selectedItemRenderer });
     }
     const selectEl = /* @__PURE__ */ jsxs(
       "select",
@@ -258,7 +275,7 @@ const NativeSelect = React.forwardRef(
         "div",
         {
           className: cn(
-            fieldWrapperStyles({ mode: "edit", variant, size, error }),
+            fieldWrapperStyles({ mode: "edit", variant, width, size, error }),
             value && tagPadding[size],
             "relative",
             className
@@ -280,7 +297,7 @@ const NativeSelect = React.forwardRef(
       "div",
       {
         className: cn(
-          fieldWrapperStyles({ mode: "edit", variant, size, error }),
+          fieldWrapperStyles({ mode: "edit", variant, width, size, error }),
           className
         ),
         "data-field-mode": "edit",
@@ -298,7 +315,46 @@ const NativeSelect = React.forwardRef(
 );
 NativeSelect.displayName = "NativeSelect";
 const CustomSelect = React.forwardRef(
-  ({ mode, variant: variantProp, error: errorProp = false, size: sizeProp, options, groups, value: valueProp, defaultValue, onChange, placeholder, className, disabled: disabledProp, clearable = false, display = "plain", startIcon: StartIcon, searchable = false, loading, minRows, emptyText, defaultOpen = false, onOpenChange, selectedItemRenderer, showDisplayEndIcon, id: idProp, "aria-describedby": ariaDescribedByProp, "aria-errormessage": ariaErrorMessageProp, "aria-label": ariaLabel }, ref) => {
+  ({
+    mode,
+    variant: variantProp,
+    width,
+    error: errorProp = false,
+    size: sizeProp,
+    options,
+    groups,
+    value: valueProp,
+    defaultValue,
+    onChange,
+    placeholder,
+    className,
+    disabled: disabledProp,
+    name,
+    required,
+    form,
+    clearable = false,
+    display = "plain",
+    startIcon: StartIcon,
+    searchable = false,
+    loading,
+    minRows,
+    emptyText,
+    defaultOpen = false,
+    onOpenChange,
+    selectedItemRenderer,
+    showDisplayEndIcon,
+    id: idProp,
+    "aria-describedby": ariaDescribedByProp,
+    "aria-errormessage": ariaErrorMessageProp,
+    "aria-label": ariaLabel,
+    onKeyDown: onKeyDownProp,
+    style: styleProp,
+    // 2026-07-14 API 策展 D:mobile-only props(allowlist 註記)desktop 顯式丟棄 — div trigger 無原生
+    // 對應,不 spread 進 DOM(對稱 NativeSelect 丟棄 custom-path-only props 的既有 pattern)
+    autoFocus: _autoFocus,
+    autoComplete: _autoComplete,
+    ...rest
+  }, ref) => {
     const fieldCtx = useFieldContext();
     const error = useResolvedFieldInvalid(errorProp);
     const disabled = useResolvedFieldDisabled(disabledProp);
@@ -354,10 +410,28 @@ const CustomSelect = React.forwardRef(
       [setValue]
     );
     if (resolvedMode !== "edit") {
-      return /* @__PURE__ */ jsx(ReadonlyDisplay, { mode: resolvedMode, variant, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon });
+      return /* @__PURE__ */ jsx(ReadonlyDisplay, { mode: resolvedMode, variant, width, size, options, value, display, startIcon: StartIcon, className, placeholder, showDisplayEndIcon, selectedItemRenderer });
     }
     const clearEl = showClear ? /* @__PURE__ */ jsx(SelectClearButton, { size: size ?? "md", onClear: () => setValue(""), stopPropagation: true }) : null;
     const chevronEl = /* @__PURE__ */ jsx(ItemSuffix, { children: /* @__PURE__ */ jsx(ChevronDown, { size: iconSize, className: cn("text-fg-muted transition-transform", open && "rotate-180"), "aria-hidden": true }) });
+    const hiddenInputEl = /* @__PURE__ */ jsx(
+      "input",
+      {
+        type: "text",
+        name,
+        form,
+        value: value ?? "",
+        onChange: (e) => {
+          const matched = options.find((o) => o.value === e.target.value && !o.disabled);
+          if (matched) setValue(matched.value);
+        },
+        required: required || void 0,
+        disabled,
+        "aria-hidden": "true",
+        tabIndex: -1,
+        className: "absolute bottom-0 left-0 w-full opacity-0 pointer-events-none"
+      }
+    );
     const triggerContent = /* @__PURE__ */ jsx(
       CustomSelectTriggerContent,
       {
@@ -384,6 +458,7 @@ const CustomSelect = React.forwardRef(
     const trigger = /* @__PURE__ */ jsxs(
       "div",
       {
+        ...rest,
         ref,
         id: idProp ?? (fieldCtx == null ? void 0 : fieldCtx.id),
         role: "combobox",
@@ -393,23 +468,28 @@ const CustomSelect = React.forwardRef(
         "aria-label": ariaLabel,
         "aria-labelledby": ariaLabel ? void 0 : fieldCtx == null ? void 0 : fieldCtx.labelId,
         "aria-invalid": error || void 0,
-        "aria-required": (fieldCtx == null ? void 0 : fieldCtx.required) || void 0,
+        "aria-required": required || (fieldCtx == null ? void 0 : fieldCtx.required) || void 0,
         "aria-describedby": ariaDescribedByProp ?? (fieldCtx == null ? void 0 : fieldCtx.descriptionId),
         "aria-errormessage": ariaErrorMessageProp ?? (error ? fieldCtx == null ? void 0 : fieldCtx.errorId : void 0),
         tabIndex: 0,
         className: cn(
-          fieldWrapperStyles({ mode: "edit", variant, size, error }),
+          fieldWrapperStyles({ mode: "edit", variant, width, size, error }),
           !isTextDisplay && value && !searchable && tagPadding[size],
           // 2026-05-06 v13.3 SSOT retire:per-control `open && 'border-primary'` 移除。Field default
           // state machine `data-[state=open]:border-border-hover`(灰深)處理 open。
           // 2026-07-04 Q1:error border 同樣收進 fieldWrapperStyles error variant(error 勝 focus 色)。
-          "cursor-pointer",
+          // D2(2026-07-13):`relative` = hidden input mirror 的 absolute 定位容器
+          // (fieldWrapperStyles base 無 relative;對齊 NativeSelect tag 分支同款顯式加法)。
+          "relative cursor-pointer",
           className
         ),
-        style: !isTextDisplay ? { paddingRight: "var(--field-px)" } : void 0,
+        style: styleProp || !isTextDisplay ? { ...styleProp, ...!isTextDisplay ? { paddingRight: "var(--field-px)" } : void 0 } : void 0,
         "data-field-mode": "edit",
         "data-error": error ? "" : void 0,
         onKeyDown: (e) => {
+          var _a, _b;
+          onKeyDownProp == null ? void 0 : onKeyDownProp(e);
+          if (e.target !== e.currentTarget && ((_b = (_a = e.target).closest) == null ? void 0 : _b.call(_a, "button"))) return;
           if (open && forwardKeyToListbox(listboxId, e)) return;
           if (e.key === "Enter" || e.key === " ") {
             if (!open) {
@@ -426,7 +506,8 @@ const CustomSelect = React.forwardRef(
         children: [
           triggerContent,
           clearEl,
-          chevronEl
+          chevronEl,
+          hiddenInputEl
         ]
       }
     );