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

package/src/components/RadioGroup/radio-group.tsx

@@ -6,34 +6,35 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "@/lib/utils"
 import type { FieldMode, FieldVariant } from "@/design-system/components/Field/field-types"
-import { useFieldContext } from "@/design-system/components/Field/field-context"
+import { useFieldContext, useResolvedFieldMode, useResolvedFieldDisabled, useResolvedFieldSize } from "@/design-system/components/Field/field-context"
 import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
-import { EMPTY_DISPLAY } from "@/design-system/components/Field/field-wrapper"
+import type { LucideIcon } from "lucide-react"
+import type { AvatarData } from "@/design-system/components/Avatar/avatar"
+import { fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
+import { useControllable } from '@/design-system/hooks/use-controllable'
 
-// ── RadioGroup display context ──────────────────────────────────────────────
-// RadioGroup mode='display' 時:Group 不渲染 Radix primitive(無 radio 視覺),
-// 改透過 Context 通知 child RadioGroupItem「我在 display mode、selected value 是 X」;
-// item 自決 — 命中 selected 渲染 label 純文字,未命中 render null。
-// 為什麼用 context(不是 RadioGroup 自己解析 children):children 可能是任意巢狀
-// (Field 包 RadioGroup,內含 RadioGroupItem 散在 fragment / 條件式內),強行 walk children
-// 會破壞 React composability;用 context 讓 item 自己判定是 idiom 對齊 Radix 原生模型。
-interface RadioGroupDisplayContextValue {
-  displayMode: true
-  selectedValue?: string
-}
-const RadioGroupDisplayContext = React.createContext<RadioGroupDisplayContextValue | null>(null)
+// ── RadioGroup view mode ────────────────────────────────────────────────────
+// RadioGroup mode='view' 時:Group 不渲染 Radix primitive(無 radio 視覺),
+// 改由 RadioGroup 本體 walk props.children,找 control.value === selectedValue 的
+// SelectionItem,把它的 label 渲染為單一純文字 span(其他選項不顯示)。
+// 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。
+// 實作在 RadioGroup forwardRef 內(見下方 mode === 'view' 分支)。
 
 // ── RadioGroup ──────────────────────────────────────────────────────────────
 
 export interface RadioGroupProps
-  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {
+  // asChild Omit(2026-07-18 決策2):RadioGroup 恆持有多個 radio item → <Root asChild> 的
+  // Radix Slot React.Children.only crash;view/readonly 模式更直接渲染固定 <div> 忽略之。
+  // children 保留(edit 容器內容 + view/readonly 走訪選中 label,見 body cast @line ~105)。
+  extends Omit<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>, 'asChild'> {
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 RadioGroup(預設)
-   *   display  — **純展示**:不渲染 Radix Root / 任何 radio 視覺,僅 child item 中
-   *              value === group.value 那筆把 label 渲染為純文字 span;其他 item render null。
+   *   view     — **純展示**:不渲染 Radix Root / 任何 radio 視覺;RadioGroup 本體 walk
+   *              children,僅 control.value === group.value 那筆把 label 渲染為純文字 span。
    *              對齊 Carbon read-only / DataTable single-select cell read mode。
-   *   readonly — 同 child item 各自 readOnly:radio 視覺保留 + 鎖互動
+   *   readonly — standalone:ReadonlyContext 傳 items 鎖互動保留視覺;Field 內:灰框 + 選中項 label(不渲染 radio 群組)
    *   disabled — 同 RadioGroupPrimitive.Root disabled 屬性
    */
   mode?: FieldMode
@@ -44,51 +45,174 @@ export interface RadioGroupProps
   variant?: FieldVariant
 }
 
+// RadioGroup mode='readonly' → 透過 context 把 readOnly 傳給所有 child RadioGroupItem
+// (item 已支援 readOnly prop + data-[readonly] 樣式;Radix Root 無 readOnly,故用 context)。
+const RadioGroupReadonlyContext = React.createContext(false)
+
+// group-level disabled(standalone <RadioGroup disabled>)→ context 傳給 items,讓 SelectionItem
+// label/description 也降 text-fg-disabled(Radix Root disabled 只 propagate 給 radio 圈、不碰 label 色)。
+// 對齊本檔 RadioGroupReadonlyContext 既有模式 + spec「Disabled」邊界案例(Group-level disabled 視覺繼承 SelectionItem SSOT text-fg-disabled)。
+const RadioGroupDisabledContext = React.createContext(false)
+
+// walk children 找 control.value === selectedValue 的 SelectionItem label(view / readonly-in-Field 共用)
+function findSelectedRadioLabel(children: React.ReactNode, selectedValue: string | undefined): React.ReactNode {
+  let selectedLabel: React.ReactNode = null
+  React.Children.forEach(children, (child) => {
+    if (!React.isValidElement(child)) return
+    const cProps = child.props as { control?: unknown; label?: React.ReactNode; value?: unknown }
+    // 形狀 1:<RadioGroupItem value label>(主用法)— value/label 直掛 props
+    if (cProps.value === selectedValue && cProps.value !== undefined) {
+      selectedLabel = cProps.label ?? selectedValue
+      return
+    }
+    // 形狀 2:<SelectionItem control={<RadioGroupItem value/>} label>(組合用法)
+    const control = cProps.control
+    if (React.isValidElement(control)) {
+      const controlValue = (control.props as { value?: unknown }).value
+      if (controlValue === selectedValue) {
+        selectedLabel = cProps.label ?? selectedValue
+      }
+    }
+  })
+  return selectedLabel
+}
+
 const RadioGroup = React.forwardRef<
   React.ElementRef<typeof RadioGroupPrimitive.Root>,
   RadioGroupProps
->(({ className, mode, variant: _chrome, value, defaultValue, ...props }, ref) => {
-  // mode='display' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。
+>(({ className, mode, variant: _chrome, value, defaultValue, onValueChange, children, ...props }, ref) => {
+  // 2026-06-08 SSOT cascade:resolvedMode 經 resolver hook 讀 fieldCtx(原 root 完全不讀 → <Field disabled>/<Field mode> 失效)
+  const resolvedMode = useResolvedFieldMode({ mode, disabled: (props as { disabled?: boolean }).disabled })
+  const emptyDisplay = useFieldEmptyDisplay()
+  const fieldCtx = useFieldContext()
+  // readonly 灰框 size:走 SSOT resolver(RadioGroup 無 size prop → ctx > 'md')
+  const resolvedBoxSize = useResolvedFieldSize(undefined, 'md') as 'sm' | 'md' | 'lg'
+
+  // Wrapper 持有 value 的單一 resolved state，讓 uncontrolled edit 內的選擇在切換
+  // view / readonly 時仍可讀取；否則值只住在 Radix Root，非 edit 分支會退回 defaultValue。
+  // Radix 一律收到 controlled value，避免 mode remount 後重建另一份 internal state。
+  const isControlled = value !== undefined
+  const [resolvedValue, setResolvedValue] = useControllable<string>({
+    value: value === null ? '' : value,
+    defaultValue: defaultValue ?? '',
+    onChange: onValueChange,
+  })
+
+  // form.reset() 不會觸發 Radix onValueChange；uncontrolled wrapper 取得狀態所有權後，
+  // 需把 resolved value 明確歸回 defaultValue。resolvedMode 進 deps，切回 edit 時會
+  // 重新綁定目前 Root 所在的 form；view/readonly 分支仍在同一 form 時也能保持 reset 語意。
+  const innerRef = React.useRef<HTMLDivElement | null>(null)
+  React.useEffect(() => {
+    if (isControlled) return
+    const form = innerRef.current?.closest('form')
+    if (!form) return
+    const handleReset = () => setResolvedValue(defaultValue ?? '')
+    form.addEventListener('reset', handleReset)
+    return () => form.removeEventListener('reset', handleReset)
+  }, [defaultValue, isControlled, resolvedMode, setResolvedValue])
+  const setRef = React.useCallback((element: HTMLDivElement | null) => {
+    innerRef.current = element
+    if (typeof ref === 'function') ref(element)
+    else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = element
+  }, [ref])
+  // mode='view' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。
   // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。
   // 實作:walk children 找 control.value === selectedValue 的 SelectionItem,render label plain text。
   // (不用 context dispatch 給 RadioGroupItem — SelectionItem layout wrapper 仍會渲染所有 item label)
-  if (mode === 'display') {
-    const selectedValue = (value ?? defaultValue) as string | undefined
+  // 2026-07-04 修:view / readonly-in-Field 分支的 <div> 原丟棄剩餘 props(id/data-*/aria-*)
+  // 且不轉發 forwardRef ref → 自家 radio-group.stories.tsx view demo 傳的 aria-label 都靜默失效。
+  // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Checkbox/Switch 同修);
+  // edit 主路徑不受影響(Root 仍 spread 完整 props)。
+  const {
+    onValueChange: _onValueChange,
+    disabled: _disabled,
+    required: _required,
+    name: _name,
+    orientation: _orientation,
+    dir: _dir,
+    loop: _loop,
+    asChild: _asChild,
+    ...restDomProps
+  } = props as RadioGroupProps & { asChild?: boolean }
+
+  if (resolvedMode === 'view') {
+    const selectedValue = resolvedValue || undefined
     if (!selectedValue) {
-      return <div role="group" className={cn('grid', className)}><span className="text-fg-muted">{EMPTY_DISPLAY}</span></div>
+      return <div {...restDomProps} ref={setRef} role="group" className={cn('grid', className)}><span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span></div>
     }
-    let selectedLabel: React.ReactNode = null
-    React.Children.forEach(props.children, (child) => {
-      if (!React.isValidElement(child)) return
-      const cProps = child.props as { control?: unknown; label?: React.ReactNode }
-      const control = cProps.control
-      if (React.isValidElement(control)) {
-        const controlValue = (control.props as { value?: unknown }).value
-        if (controlValue === selectedValue) {
-          selectedLabel = cProps.label ?? selectedValue
-        }
-      }
-    })
+    const selectedLabel = findSelectedRadioLabel(children, selectedValue)
     return (
-      <div role="group" className={cn('grid', className)}>
+      <div {...restDomProps} ref={setRef} role="group" className={cn('grid', className)}>
         <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
       </div>
     )
   }
 
+  // ── mode='readonly' in Field(2026-06-12 user 拍板,與 Checkbox/Switch 灰框模型一致)──
+  // Field 內 readonly 單選 = fieldWrapperStyles readonly 灰框 + 選中項 label 文字
+  // (= Select readonly 同款呈現:同為「單選資料」,鎖定時呈現一致)。
+  // standalone readonly(無 Field)維持原樣鎖互動(ReadonlyContext 路徑)。
+  if (resolvedMode === 'readonly' && fieldCtx?.hasFieldWrapper === true) {
+    const selectedValue = resolvedValue || undefined
+    const selectedLabel = selectedValue ? findSelectedRadioLabel(children, selectedValue) : null
+    const boxSize = resolvedBoxSize
+    return (
+      <div
+        {...restDomProps}
+        ref={setRef}
+        role="radiogroup"
+        aria-readonly="true"
+        aria-labelledby={fieldCtx?.labelId}
+        aria-invalid={fieldCtx?.invalid || undefined}
+        data-readonly="true"
+        tabIndex={0}
+        className={cn(
+          fieldWrapperStyles({ size: boxSize, mode: 'readonly', variant: 'default' }),
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          className,
+        )}
+      >
+        {selectedValue
+          ? <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
+          : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>}
+      </div>
+    )
+  }
+
+  // mode='disabled' → Radix Root disabled(原生 propagate 給所有 item);
+  // mode='readonly' → context 傳 readOnly 給 items(item 渲染為 data-[readonly] 鎖互動 + aria-readonly)。
   return (
-    <RadioGroupPrimitive.Root
-      className={cn("grid", className)}
-      value={value}
-      defaultValue={defaultValue}
-      {...props}
-      ref={ref}
-    />
+    <RadioGroupReadonlyContext.Provider value={resolvedMode === 'readonly'}>
+      <RadioGroupDisabledContext.Provider value={resolvedMode === 'disabled'}>
+        <RadioGroupPrimitive.Root
+          className={cn("grid", className)}
+          value={resolvedValue}
+          onValueChange={setResolvedValue}
+          // Field 內:role="radiogroup" 的 <div> 無法被 <label for> 命名 → 自讀 fieldCtx 接
+          // aria-labelledby / aria-invalid / aria-describedby(field-context.ts「下游 control 需自讀
+          // labelId」;對齊 slider.tsx / Rating / TimePicker 的 fieldLabelId 接線 + 上方 readonly-in-Field 分支)。
+          // standalone(無 Field)時皆 undefined,consumer 的 {...props} aria-* 照舊生效(置於 spread 前故可被覆蓋)。
+          aria-labelledby={fieldCtx?.labelId}
+          aria-invalid={fieldCtx?.invalid || undefined}
+          aria-describedby={fieldCtx?.descriptionId}
+          // a11y(2026-07-14 dim-10):readonly 語意放 radiogroup(aria-readonly 合法 role;
+          // 對齊上方 readonly-in-Field 分支 L133)。item(role=radio)不帶 aria-readonly —
+          // axe 實證 radio 不允許該屬性,item 靠 data-readonly + tabIndex + click guard 鎖互動。
+          aria-readonly={resolvedMode === 'readonly' || undefined}
+          {...props}
+          disabled={resolvedMode === 'disabled'}
+          ref={setRef}
+        >
+          {children}
+        </RadioGroupPrimitive.Root>
+      </RadioGroupDisabledContext.Provider>
+    </RadioGroupReadonlyContext.Provider>
   )
 })
 RadioGroup.displayName = 'RadioGroup'
 // Field layout 宣告：RadioGroup 是 block primitive（多項堆疊），
-// 進入 <Field> 時 control area 自動切 items-start + padding-top 公式對齊。
+// 進入 <Field> 時 control area 自動切 items-start（block 分支不設 min-h、不加 padding-top,
+// 高度由內容決定;額外加 paddingTop 會 double padding — field.tsx block control area SSOT）。
 // Convention 詳見 components/Field/field.spec.md「Control area:Inline vs Block」段落。
 ;(RadioGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'
 
@@ -132,7 +256,9 @@ const dotSize: Record<string, number> = { sm: 8, md: 8, lg: 10 }
 type RadioItemPrimitiveProps = React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
 
 export interface RadioGroupItemProps
-  extends RadioItemPrimitiveProps,
+  // asChild / children Omit(2026-07-18 決策2):item 固定渲染 Indicator dot(<Circle/>)—
+  // children 被固定 Indicator 靜默覆蓋,asChild 破壞 radio 結構。對齊 Checkbox 收窄。label 走 `label` prop。
+  extends Omit<RadioItemPrimitiveProps, 'asChild' | 'children'>,
     VariantProps<typeof radioItemVariants> {
   /**
    * Inline label。提供時 RadioGroupItem 自動透過 SelectionItem 包裝，
@@ -146,6 +272,10 @@ export interface RadioGroupItemProps
    * 套用 text-body / text-fg-secondary 樣式。
    */
   description?: React.ReactNode
+  /** 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc SSOT;與 avatar 互斥)*/
+  icon?: LucideIcon
+  /** 可選左側 avatar(label 前)— 同上 */
+  avatar?: AvatarData
   /**
    * readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。
    * 通常整個 RadioGroup 一起設 readonly（由 parent RadioGroup 的 disabled
@@ -165,6 +295,8 @@ const RadioGroupItem = React.forwardRef<
       className,
       size,
       label,
+      icon,
+      avatar,
       description,
       readOnly = false,
       disabled,
@@ -176,21 +308,22 @@ const RadioGroupItem = React.forwardRef<
     const sizeKey = size ?? 'md'
     const dotPx = dotSize[sizeKey]
 
-    // ── RadioGroup mode='display' branch ──────────────────────────────────
-    // 命中 selected → 渲染 label 純文字 span;未命中 → render null(group 內只剩 selected 的 label)。
-    // 設計理由:對齊 Carbon read-only single-select 「只顯示 selected 內容、不列其他選項」原則。
-    const displayCtx = React.useContext(RadioGroupDisplayContext)
-    if (displayCtx?.displayMode) {
-      if (displayCtx.selectedValue !== props.value) return null
-      return <span className="text-foreground">{label ?? props.value}</span>
-    }
+    // 注意:RadioGroup mode='view' 的純文字渲染由 RadioGroup 本體 walk-children 處理
+    // (見上方 RadioGroup forwardRef 的 mode === 'view' 分支),RadioGroupItem 在 view
+    // mode 下不會被獨立 render,故此處無 view 分支。
 
     // 注意：Radio 的 label 語意與 Checkbox/Switch 不同——
     // Checkbox/Switch 的 label 就是該 control 的唯一 label（被 Field context 接管），
     // RadioGroupItem 的 label 是「該選項」的 label（每 item 各自擁有），
     // FieldLabel 則是整個 RadioGroup 的 label。
     // 因此 RadioGroupItem 的 label 不因 Field context 被忽略。
-    const fieldCtx = useFieldContext()
+    // group-level disabled(standalone <RadioGroup disabled>)也要降 label/description 色 —— Radix Root
+    // disabled 只 propagate 給 radio 圈,label 色由 SelectionItem disabled 決定,故讀 RadioGroupDisabledContext 補上。
+    const groupDisabled = React.useContext(RadioGroupDisabledContext)
+    const resolvedDisabled = useResolvedFieldDisabled(disabled) || groupDisabled
+    // group-level readonly(RadioGroup mode='readonly')或 item-level readOnly,任一 true 即鎖互動。
+    const groupReadonly = React.useContext(RadioGroupReadonlyContext)
+    const effectiveReadonly = readOnly || groupReadonly
 
     const generatedId = React.useId()
     const inputId = idProp ?? generatedId
@@ -199,12 +332,26 @@ const RadioGroupItem = React.forwardRef<
       <RadioGroupPrimitive.Item
         id={inputId}
         ref={ref}
-        disabled={disabled}
-        aria-readonly={readOnly || undefined}
-        data-readonly={readOnly || undefined}
-        tabIndex={readOnly ? -1 : undefined}
+        disabled={resolvedDisabled}
+        // a11y(2026-07-14 dim-10):item(role=radio)不帶 aria-readonly — axe 實證 radio 不允許
+        // 該屬性(readonly 語意由 Root role=radiogroup 宣告,見上方 L167-170)。item 靠
+        // data-readonly + tabIndex + click guard 鎖互動。
+        data-readonly={effectiveReadonly || undefined}
+        tabIndex={effectiveReadonly ? -1 : undefined}
         className={cn(radioItemVariants({ size }), className)}
         {...props}
+        // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click
+        // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍選中。
+        // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 onCheck;
+        // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(與 Checkbox/Switch 同修)。
+        // 同時攔 Radix roving-focus 的 arrow-key onFocus → click() 路徑(同為 click event)。
+        onClick={(event) => {
+          if (effectiveReadonly) {
+            event.preventDefault()
+            return
+          }
+          props.onClick?.(event)
+        }}
       >
         <RadioGroupPrimitive.Indicator className="grid place-content-center">
           <Circle
@@ -218,15 +365,14 @@ const RadioGroupItem = React.forwardRef<
     // 無 label → 只渲染 radio 本體
     if (label == null) return rootEl
 
-    // 有 label → 透過 SelectionItem 包裝，與 Checkbox 一致
-    // 同時繼承 Field context 的 disabled（若 RadioGroup 在 Field disabled 內）
-    const resolvedDisabled = disabled ?? fieldCtx?.disabled ?? false
-
+    // 有 label → 透過 SelectionItem 包裝，與 Checkbox 一致（disabled 已於上方 useResolvedFieldDisabled 解析）
     return (
       <SelectionItem
         control={rootEl}
         label={label}
         description={description}
+        icon={icon}
+        avatar={avatar}
         htmlFor={inputId}
         disabled={resolvedDisabled}
         size={sizeKey}
@@ -240,16 +386,22 @@ RadioGroupItem.displayName = 'RadioGroupItem'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const radioGroupMeta = {
   component: 'RadioGroup',
-  family: 4,
+  family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4 — field-controls.spec.md 成員名單不含 RadioGroup)
   variants: {
 
   },
   sizes: {
-    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
-    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
-    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+    // iconSize = 渲染指示器尺寸(對齊 checkbox/switch meta 慣例:checkbox iconSize=真 Check glyph 12/12/16)。
+    // Radio 指示器是 filled dot 非 glyph,真值 = 上方 `const dotSize` map 8/8/10;
+    // 控件框 16/16/20 與 Checkbox 對齊但那是 box 非「指示器」,不入此鍵(避免 metadata 語意 drift)。
+    sm: { fieldHeight: 28, iconSize: 8, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 8, typography: 'body' },
+    lg: { fieldHeight: 36, iconSize: 10, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 修 stale meta:移除 'active' — radioItemVariants cva 無 active-state 樣式,
+  // Radix radio 也無 data-state=active(對照 checkboxMeta 正確不含 active)
+  // 'checked' = 選定持續態(card 式 = border+text primary;2026-07-07 meta 詞彙統一補列)
+  states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],

package/src/components/Rating/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 './rating'