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

package/src/components/Checkbox/checkbox.tsx

@@ -6,8 +6,13 @@ 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, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from "@/design-system/components/Field/field-context"
+import { useControllable } from "@/design-system/hooks/use-controllable"
+import { fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
 import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
+import { BooleanValueIcon } from "@/design-system/components/SelectionControl/boolean-value"
+import type { LucideIcon } from "lucide-react"
+import type { AvatarData } from "@/design-system/components/Avatar/avatar"
 import { CheckboxGroupContext } from "./checkbox-group"
 
 // ── Variants ────────────────────────────────────────────────────────────────
@@ -68,25 +73,41 @@ const checkIconSize: Record<string, number> = { sm: 12, md: 12, lg: 16 }
 // - 原 {3.5, 3.5, 2.5} → effective render thickness 1.75 / 1.75 / 1.67 = 跨 size 差 0.08px(視覺看不出)
 // - 改 {3, 3, 2.5} 保留 sm/md 小尺寸 legibility insurance(per iOS HIG / Material 3 cite)
 //   + lg 仍稍粗於 Lucide default 2(保留 compensation 主旨,但不過度差異化)
+// ⚠️ 2026-06-12:發現 base.css `.lucide{stroke-width:1.75}` 全域規則自 2026-04-08 起
+// 無條件蓋掉本 prop(CSS class > SVG attribute)→ 本表從未真渲染過,上述 05-18 視覺
+// 測試兩者實為 0.875px(證據污染)。base.css 已改 `[stroke-width='2']` 限定,本表自此
+// 真實生效(pixel 驗證 1.50px)。SSOT → packages/design-system/ds-canonical/references/ui-dev-rules.md「小尺寸 icon stroke 補償」
 const checkStrokeWidth: Record<string, number> = { sm: 3, md: 3, lg: 2.5 }
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
+// asChild / children 從公開型別 Omit(2026-07-17 d9i6):Checkbox 有**固定 anatomy** —
+// 內部恆渲染 Indicator(Check / Minus 兩子節點),非 Slot host。若保留 Radix `asChild`,
+// consumer 傳入的元素會被 Radix Slot `React.Children.only` 因多子節點在執行期拋錯(失敗記憶索引
+// 已 codify 此 asChild 多子節點 bug class);`children` 同理會被固定 Indicator 覆蓋。需自訂佈局
+// 請用 `label` / `description` / `icon` / `avatar` 一級 props(內部自動包 SelectionItem)。
 export interface CheckboxProps
-  extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>,
+  extends Omit<React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, 'asChild' | 'children'>,
     VariantProps<typeof checkboxVariants> {
   /**
    * Inline label。提供時 Checkbox 自動透過 SelectionItem 包裝，
    * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。
-   * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。
+   * 在 <Field> context 內且不在 CheckboxGroup 內時，此 prop 會被忽略（由 FieldLabel 接管）；
+   * CheckboxGroup 內每個 checkbox 的 label 是它自己的選項名，必保留
+   * （同檔 shouldSuppressLabel = insideField && !insideGroup，AR50 anchor）。
    */
   label?: React.ReactNode
   /**
    * Inline description（secondary 文字）。須與 label 搭配使用。
    * 套用 text-body / text-fg-secondary 樣式。
-   * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。
+   * 在 <Field> context 內且不在 CheckboxGroup 內時，此 prop 會被忽略（由 FieldDescription 接管）；
+   * CheckboxGroup 內的 description 屬各選項自有，必保留（同 label 的 group 例外）。
    */
   description?: React.ReactNode
+  /** 可選左側 icon(label 前)— 2026-06-12 M30 修:轉發 SelectionItem 既有 canonical 槽(selection-item.tsx jsDoc 為 SSOT;與 avatar 互斥)*/
+  icon?: LucideIcon
+  /** 可選左側 avatar(label 前)— 同上,SelectionItem 槽轉發 */
+  avatar?: AvatarData
   /**
    * readonly 模式：鎖定互動但維持 checked/unchecked 視覺正確。
    * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
@@ -96,7 +117,7 @@ export interface CheckboxProps
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 checkbox(預設)
-   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);
+   *   view     — **純展示**:渲染 Check / X icon(true=勾 / false=叉,無互動 primitive、無 input chrome);
    *              對齊 Carbon read-only / DataTable boolean cell 場景。取代既有 BooleanDisplay。
    *   readonly — 同 readOnly prop:checkbox 視覺保留 + 鎖互動 + a11y readonly signal
    *   disabled — 同 disabled prop:降色 + 鎖互動
@@ -120,12 +141,21 @@ const Checkbox = React.forwardRef<
       className,
       size,
       label,
+      icon,
+      avatar,
       description,
       readOnly = false,
       disabled,
       mode,
       // chrome 對 Checkbox 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。
       variant: _chrome,
+      // controllable checked triplet(2026-07-17 d26i0):於 wrapper 層取出,交由 useControllable 持有
+      // resolved 值,供 edit / view / readonly 三分支共用。原本 view / readonly 分支各自讀 raw prop →
+      // uncontrolled(只傳 defaultChecked)在 edit 態 toggle 後切 mode 會丟失目前值(Radix 內部狀態
+      // wrapper 讀不到)。移出 props 後 edit 主路徑改由 checked={resolvedChecked} 受控(見下方 rootEl)。
+      checked: checkedProp,
+      defaultChecked: defaultCheckedProp,
+      onCheckedChange,
       id: idProp,
       ...props
     },
@@ -135,18 +165,9 @@ const Checkbox = React.forwardRef<
     const iconPx = checkIconSize[sizeKey]
     const iconStrokeWidth = checkStrokeWidth[sizeKey]
 
-    // ── mode='display' ─────────────────────────────────────────────────────
-    // 純展示模式:無互動 primitive、無 input variant,渲染 ✓ / —。
-    // 取代既有 BooleanDisplay(2026-05-05 Phase B3 retire)— 該 helper 已併入 Checkbox。
-    // 顯示規則:checked=true → ✓(foreground);其他(false / null / undefined / indeterminate)→ —(fg-muted)
-    if (mode === 'display') {
-      const isChecked = props.checked === true
-      return isChecked
-        ? <span className="text-foreground">✓</span>
-        : <span className="text-fg-muted">—</span>
-    }
-
     // Field context:Checkbox 單獨塞進 Field(binary toggle)時,忽略自己的 label 讓 FieldLabel 接管
+    // 2026-05-31 #35:hooks(useFieldContext / useContext / useId)必在任何 conditional return 前呼叫(Rules of Hooks)。
+    // 原 mode='view' early return 寫在 hooks 之上 → runtime 切 mode 會 hook count 不一致 crash;已下移至 hooks 後。
     //
     // **例外**:Checkbox 是 CheckboxGroup 的 child 時(multi-select 情境),**每個 checkbox
     // 的 label 是它自己的選項名**,FieldLabel 只是群組名稱 — 此時 label **必須保留**,
@@ -173,23 +194,155 @@ const Checkbox = React.forwardRef<
     const generatedId = React.useId()
     const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx?.id ?? generatedId))
 
+    // 2026-06-08 SSOT cascade:disabled + mode 經 resolver hook(原 raw prop → <Field disabled>/<Field mode="view"> 漏 cascade)
+    const resolvedDisabled = useResolvedFieldDisabled(disabled)
+    const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly })
+    const effectiveReadOnly = readOnly || resolvedMode === 'readonly'
+    // mode='disabled'(如 DataTable disabled cell 直傳)必須落到真 disabled chrome —
+    // 2026-06-12 修:原本只看 resolvedDisabled(prop/fieldCtx),mode='disabled' 無人消費
+    // → disabled boolean cell 渲出可 focus 的正常外觀 checkbox(違 field-controls.spec L286)
+    const effectiveDisabled = resolvedDisabled || resolvedMode === 'disabled'
+    // readonly 灰框 size:走 SSOT resolver(prop > ctx > 'md',field-context.ts:150-161)
+    const resolvedBoxSize = useResolvedFieldSize(size ?? undefined, 'md') as 'sm' | 'md' | 'lg'
+
+    // 2026-07-04 修:view / readonly-in-Field 分支的裸 span/div 原丟棄剩餘 props
+    // (id/data-*/aria-*)且不轉發 forwardRef ref → consumer 的 aria-label 等靜默失效。
+    // 抽出 Radix 專屬 form props(required/name/value 不可落到裸 span/div),其餘 DOM props 於兩分支
+    // spread 轉發(與 Switch/RadioGroup 同修);edit 主路徑不受影響(rootEl 仍 spread 完整 props)。
+    // (checked/defaultChecked/onCheckedChange 已於上方 top-level destructure 取出交 useControllable;
+    //  asChild/children 已從 CheckboxProps 型別 Omit — 固定 anatomy 非 Slot host,見型別註解。)
+    const {
+      required: _required,
+      name: _name,
+      value: _value,
+      ...restDomProps
+    } = props
+
+    // ── Resolved checked SSOT(controlled / uncontrolled dual-mode,2026-07-17 d26i0)──────────
+    // 對齊 Input / Textarea 既有 canonical(field-controls.spec.md「有值判定」:useControllable 內部
+    // resolved value + form.reset bridge)。修 view / readonly 分支原各自讀 raw prop 導致「uncontrolled
+    // 切 mode 丟失目前值」的 dual-mode 缺口。controlled(傳 checked)時 useControllable 純 passthrough,
+    // edit 行為 Δ=0。
+    const isControlled = checkedProp !== undefined
+    const [resolvedChecked, setResolvedChecked] = useControllable<boolean | 'indeterminate'>({
+      value: checkedProp,
+      defaultValue: defaultCheckedProp ?? false,
+    })
+
+    // form.reset() bridge(uncontrolled only):wrapper 取得 controllable 主導後,HTML 標準 reset 不發
+    // 變更事件 → 手動把 resolvedChecked 歸位 defaultChecked(對齊 input.tsx 同名 bridge)。keyed on
+    // resolvedMode:切回 edit 重掛 native Root 時 effect 重跑補掛 listener;view / readonly(Root
+    // unmount)時 innerRef 為 null → early return 不掛。
+    const innerRef = React.useRef<HTMLButtonElement | null>(null)
+    React.useEffect(() => {
+      if (isControlled) return
+      const form = innerRef.current?.form
+      if (!form) return
+      const handleReset = () => setResolvedChecked(defaultCheckedProp ?? false)
+      form.addEventListener('reset', handleReset)
+      return () => form.removeEventListener('reset', handleReset)
+    }, [isControlled, resolvedMode, defaultCheckedProp, setResolvedChecked])
+    // Merge refs(input.tsx setRef idiom):innerRef 供 reset bridge 取 form,同時轉發 forwardRef ref。
+    const setRef = React.useCallback((el: HTMLButtonElement | null) => {
+      innerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLButtonElement | null>).current = el
+    }, [ref])
+
+    // ── mode='view'(下移至所有 hooks 之後,per #35 Rules of Hooks)──────────
+    // 純展示模式:無互動 primitive、渲染 Check / X icon(true=勾 / false=叉,中性 foreground 色)。
+    // boolean 值展示符號 SSOT = SelectionControl/boolean-value.tsx(勾/叉 icon + 中性色 + M22 世界級對照)。取代 BooleanDisplay。
+    if (resolvedMode === 'view') {
+      const isChecked = resolvedChecked === true
+      // a11y(2026-07-17 d10i2):BooleanValueIcon 帶 aria-hidden → 裸 span 在 a11y tree 無名,
+      // 布林值對螢幕閱讀器完全消失。給 view 容器 role="img" + aria-label 承載值語意(對齊 MUI X
+      // DataGrid boolean cell 的 icon role/label 世界級做法);consumer 若自帶 aria-label 則優先。
+      const viewAriaLabel = (restDomProps as { 'aria-label'?: string })['aria-label'] ?? (isChecked ? '是' : '否')
+      return (
+        <span
+          {...restDomProps}
+          ref={ref as React.Ref<HTMLSpanElement>}
+          role="img"
+          aria-label={viewAriaLabel}
+          className="inline-flex"
+        >
+          <BooleanValueIcon checked={isChecked} size={resolvedBoxSize} />
+        </span>
+      )
+    }
+
+    // ── mode='readonly' in Field(2026-06-12 拍板「灰框 + 勾/叉」;2026-07-09 ✓/— glyph → Check/X icon)─
+    // Field 內 readonly boolean = readonly 灰框 chrome + view 同款值語言(勾/叉 icon)。
+    // 灰框消費 fieldWrapperStyles 同一 cva = 與 Input readonly 字面同源(SSOT,改一處全動)。
+    // 理由:同一張 readonly 表單裡文字控件有 bg-readonly 灰框鎖定訊號,boolean 保留全彩
+    // 控件會誤導「仍可操作」(世界級 0/4 用原樣鎖互動:Salesforce=✓ 靜態 glyph /
+    // SAP=靜態文字 / Atlassian=readView / Ant Pro=文字)。
+    // Scope:僅 Field 內且無 inline label(FieldLabel 接管 label 的表單欄位場景);
+    // standalone readOnly(settings list / SelectionItem row)維持原樣鎖互動不變。
+    if (effectiveReadOnly && insideField && effectiveLabel == null) {
+      const isChecked = resolvedChecked === true
+      const boxSize = resolvedBoxSize
+      return (
+        <div
+          {...(restDomProps as React.HTMLAttributes<HTMLDivElement>)}
+          ref={ref as React.Ref<HTMLDivElement>}
+          role="checkbox"
+          aria-checked={isChecked}
+          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,
+          )}
+        >
+          <BooleanValueIcon checked={isChecked} size={boxSize} />
+        </div>
+      )
+    }
+
     const rootEl = (
       <CheckboxPrimitive.Root
         id={inputId}
-        ref={ref}
-        disabled={disabled}
-        aria-readonly={readOnly || undefined}
-        data-readonly={readOnly || undefined}
-        tabIndex={readOnly ? -1 : undefined}
+        ref={setRef}
+        disabled={effectiveDisabled}
+        // controllable checked SSOT(2026-07-17 d26i0):Root 受 wrapper resolvedChecked 主導,
+        // onCheckedChange 先同步 wrapper 內部 state 再 forward consumer → uncontrolled(只傳
+        // defaultChecked)toggle 後切 mode(view / readonly)仍保留目前值。controlled(傳 checked)
+        // 時 useControllable 純 passthrough,edit 行為 Δ=0。
+        checked={resolvedChecked}
+        onCheckedChange={(next) => {
+          setResolvedChecked(next)
+          onCheckedChange?.(next)
+        }}
+        aria-readonly={effectiveReadOnly || undefined}
+        data-readonly={effectiveReadOnly || undefined}
+        tabIndex={effectiveReadOnly ? -1 : undefined}
         aria-describedby={fieldCtx?.descriptionId}
         className={cn(checkboxVariants({ size }), className)}
         {...props}
-      >
-        <CheckboxPrimitive.Indicator className="grid place-content-center text-current">
-          {props.checked === 'indeterminate'
-            ? <Minus style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
-            : <Check style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
+        // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click
+        // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍 toggle。
+        // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 toggle;
+        // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(readOnly 時 consumer onClick 一併鎖,
+        // 與 pointer-events-none 擋直接點擊的行為一致)。
+        onClick={(event) => {
+          if (effectiveReadOnly) {
+            event.preventDefault()
+            return
           }
+          props.onClick?.(event)
+        }}
+      >
+        {/* 圖示切換走 Radix data-state(CSS),非 props.checked(JS)—— uncontrolled
+            defaultChecked="indeterminate" 時 props.checked=undefined,JS 判斷會錯渲 Check;
+            data-state 涵蓋 controlled/uncontrolled 全部轉換(Radix 為 SSOT)。 */}
+        <CheckboxPrimitive.Indicator className="group/indicator grid place-content-center text-current">
+          <Minus className="hidden group-data-[state=indeterminate]/indicator:block" style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
+          <Check className="hidden group-data-[state=checked]/indicator:block" style={{ width: iconPx, height: iconPx }} strokeWidth={iconStrokeWidth} />
         </CheckboxPrimitive.Indicator>
       </CheckboxPrimitive.Root>
     )
@@ -203,8 +356,10 @@ const Checkbox = React.forwardRef<
         control={rootEl}
         label={effectiveLabel}
         description={effectiveDescription}
+        icon={icon}
+        avatar={avatar}
         htmlFor={inputId}
-        disabled={disabled}
+        disabled={effectiveDisabled}
         size={sizeKey}
       />
     )
@@ -216,16 +371,18 @@ Checkbox.displayName = CheckboxPrimitive.Root.displayName
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const checkboxMeta = {
   component: 'Checkbox',
-  family: 4,
+  family: null, // self-contained primitive(對齊 spec frontmatter self-contained + body L31;非 Family 4)
   variants: {
 
   },
   sizes: {
-    sm: { fieldHeight: 28, iconSize: 16, typography: 'body' },
-    md: { fieldHeight: 32, iconSize: 16, typography: 'body' },
-    lg: { fieldHeight: 40, iconSize: 20, typography: 'body' },
+    // 2026-06-10 修 stale meta:iconSize 對齊 checkIconSize 真值(L49 sm/md=12, lg=16;deep-audit A.1b 抓 metadata drift)
+    sm: { fieldHeight: 28, iconSize: 12, typography: 'body' },
+    md: { fieldHeight: 32, iconSize: 12, typography: 'body' },
+    lg: { fieldHeight: 36, iconSize: 16, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'checked' = 勾選持續態(bg-primary;2026-07-07 meta 詞彙統一補列,含 indeterminate 同族)
+  states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-primary', 'bg-primary-hover', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],

package/src/components/Checkbox/index.ts

@@ -0,0 +1,6 @@
+// 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 './checkbox'
+export * from './checkbox-group'