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

package/dist/components/Checkbox/checkbox-group.js

@@ -1,23 +1,30 @@
 import { jsx } from "react/jsx-runtime";
 import * as React from "react";
 import { cn } from "../../lib/utils.js";
+import { useFieldContext } from "../Field/field-context.js";
 const CheckboxGroupContext = React.createContext(null);
 const CHECKBOX_GROUP_CTX_VALUE = { inGroup: true };
 const CheckboxGroup = React.forwardRef(
-  ({ className, orientation = "vertical", ...props }, ref) => /* @__PURE__ */ jsx(CheckboxGroupContext.Provider, { value: CHECKBOX_GROUP_CTX_VALUE, children: /* @__PURE__ */ jsx(
-    "div",
-    {
-      ref,
-      role: "group",
-      className: cn(
-        // 垂直 CheckboxGroup:zero gap(間距由 SelectionItem py 獨家擁有,見 docblock canonical)
-        // 水平:短 label 並排需水平 gap-4(label 沒有 py 擴散,需要顯式 gap)
-        orientation === "vertical" ? "grid" : "flex flex-wrap gap-4",
-        className
-      ),
-      ...props
-    }
-  ) })
+  ({ className, orientation = "vertical", ...props }, ref) => {
+    const fieldCtx = useFieldContext();
+    return /* @__PURE__ */ jsx(CheckboxGroupContext.Provider, { value: CHECKBOX_GROUP_CTX_VALUE, children: /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        role: "group",
+        "aria-labelledby": fieldCtx == null ? void 0 : fieldCtx.labelId,
+        "aria-describedby": fieldCtx == null ? void 0 : fieldCtx.descriptionId,
+        "aria-invalid": (fieldCtx == null ? void 0 : fieldCtx.invalid) || void 0,
+        className: cn(
+          // 垂直 CheckboxGroup:zero gap(間距由 SelectionItem py 獨家擁有,見 docblock canonical)
+          // 水平:短 label 並排需水平 gap-4(label 沒有 py 擴散,需要顯式 gap)
+          orientation === "vertical" ? "grid" : "flex flex-wrap gap-4",
+          className
+        ),
+        ...props
+      }
+    ) });
+  }
 );
 CheckboxGroup.displayName = "CheckboxGroup";
 CheckboxGroup.fieldLayout = "block";

package/dist/components/Checkbox/checkbox-group.js.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox-group.js","sources":["../../../src/components/Checkbox/checkbox-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 { cn } from '@/lib/utils'\n\n// ── CheckboxGroupContext ────────────────────────────────────────────────────\n// 讓內部 `<Checkbox>` 知道「我在 CheckboxGroup 裡」→ 即使 Field context 也存在,\n// checkbox 仍然保留自己的 label(每個 checkbox 是 group 的一個選項,FieldLabel 只是群組名稱)。\n//\n// 反之:Checkbox **單獨**塞進 Field(無 CheckboxGroup 包)時,Checkbox 才忽略自己的 label\n// 讓 FieldLabel 接管 —— 那是「binary toggle in Field」的場景。\n//\n// 這是 AR50 的根因:沒這個 context 前,CheckboxGroup 內部的 Checkbox 會誤以為「被 Field 包了」\n// 就把 label 全丟掉,導致 Sheet 範例的 Checkboxes 全部沒 label。\nexport const CheckboxGroupContext = React.createContext<{ inGroup: true } | null>(null)\n\n/**\n * CheckboxGroup — 多選 Checkbox 的 layout primitive\n *\n * ── Canonical 鐵律(2026-04-21 user 明示 + codified)──\n *\n * **垂直 CheckboxGroup 的 item 之間沒有外部 gap**。間距完全靠每個 Checkbox 內部的\n * `SelectionItem py = (field-height - 1lh) / 2` 公式生成 —— 單行高度對齊 field-height,\n * 多 row stacked 時 row-to-row 自然有 py × 2 的呼吸空間。\n *\n * **禁止**外層加 `gap-y-*` / `space-y-*` / margin —— 會 double padding,違反 canonical。\n *\n * ── 對齊 RadioGroup canonical ──\n * Radix `RadioGroup.Root` 預設用 `grid` (無 gap);本元件垂直也用 `grid`(無 gap),\n * horizontal 用 `flex flex-wrap gap-4`(短 label 並排才需水平 gap)。\n *\n * ── 為什麼 vertical 不給 gap 也能好看 ──\n * SelectionItem py 的公式讓每個 Checkbox row 的「單行高度 = field-height」。row 堆疊時\n * 相鄰 row 的 py 相加 = 2×py ≈ 10-12px 真實 row-to-row 視覺呼吸空間。Atlassian / Ant /\n * Chakra / GitHub CheckboxGroup 皆同流派 —— row 高度定義 gap,不加外部 gap。\n *\n * ── 本 session 曾經的錯誤 + 釐清 ──\n * 早先曾以為「gap 要加」是因為「row 黏在一起」——但實際根因是 `Checkbox` 在 Field\n * context 內誤吞自己的 label(見 checkbox.tsx 的 CheckboxGroupContext 修正)。\n * label 回來後 row 自然撐開,不需要 gap。修正後的 canonical 鐵律:**zero gap,\n * 間距由 SelectionItem py 獨家擁有**。\n *\n * ── fieldLayout:block ──\n * 在 `<Field orientation=\"horizontal\">` 內,control area auto `items-start` +\n * padding-top 公式對齊第一個 item 的 label 第一行(見 field.spec.md)。\n *\n * ── 用法範例 ──\n *   <CheckboxGroup>\n *     <Checkbox label=\"待處理\" defaultChecked />\n *     <Checkbox label=\"進行中\" defaultChecked />\n *     <Checkbox label=\"已完成\" />\n *   </CheckboxGroup>\n *\n *   <CheckboxGroup orientation=\"horizontal\">\n *     <Checkbox label=\"Email\" />\n *     <Checkbox label=\"Push\" />\n *     <Checkbox label=\"SMS\" />\n *   </CheckboxGroup>\n */\n\nexport interface CheckboxGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /**\n   * 排列方向。\n   * - `vertical`(預設):多選項目堆疊,row 間距由 SelectionItem 擁有(外層 0 gap)\n   * - `horizontal`:選項並排,gap-4 分隔(短 label 場景,如「Email / Push / SMS」)\n   */\n  orientation?: 'vertical' | 'horizontal'\n}\n\n// Module-level 常數(2026-04-22 D3 perf audit):provider value 無狀態,hoist 避免 render 重建\nconst CHECKBOX_GROUP_CTX_VALUE = { inGroup: true } as const\n\nconst CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(\n  ({ className, orientation = 'vertical', ...props }, ref) => (\n    <CheckboxGroupContext.Provider value={CHECKBOX_GROUP_CTX_VALUE}>\n      <div\n        ref={ref}\n        role=\"group\"\n        className={cn(\n          // 垂直 CheckboxGroup:zero gap(間距由 SelectionItem py 獨家擁有,見 docblock canonical)\n          // 水平:短 label 並排需水平 gap-4(label 沒有 py 擴散,需要顯式 gap)\n          orientation === 'vertical' ? 'grid' : 'flex flex-wrap gap-4',\n          className\n        )}\n        {...props}\n      />\n    </CheckboxGroupContext.Provider>\n  )\n)\nCheckboxGroup.displayName = 'CheckboxGroup'\n// Field layout declaration:block primitive(多項堆疊)——進入 <Field> 時\n// control area 自動切 items-start + padding-top 公式。對齊 RadioGroup 做法。\n;(CheckboxGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'\n\nexport { CheckboxGroup }\n"],"names":[],"mappings":";;;AAaO,MAAM,uBAAuB,MAAM,cAAwC,IAAI;AAwDtF,MAAM,2BAA2B,EAAE,SAAS,KAAA;AAE5C,MAAM,gBAAgB,MAAM;AAAA,EAC1B,CAAC,EAAE,WAAW,cAAc,YAAY,GAAG,MAAA,GAAS,QAClD,oBAAC,qBAAqB,UAArB,EAA8B,OAAO,0BACpC,UAAA;AAAA,IAAC;AAAA,IAAA;AAAA,MACC;AAAA,MACA,MAAK;AAAA,MACL,WAAW;AAAA;AAAA;AAAA,QAGT,gBAAgB,aAAa,SAAS;AAAA,QACtC;AAAA,MAAA;AAAA,MAED,GAAG;AAAA,IAAA;AAAA,EAAA,EACN,CACF;AAEJ;AACA,cAAc,cAAc;AAG1B,cAAsD,cAAc;"}
+{"version":3,"file":"checkbox-group.js","sources":["../../../src/components/Checkbox/checkbox-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 { cn } from '@/lib/utils'\nimport { useFieldContext } from '@/design-system/components/Field/field-context'\n\n// ── CheckboxGroupContext ────────────────────────────────────────────────────\n// 讓內部 `<Checkbox>` 知道「我在 CheckboxGroup 裡」→ 即使 Field context 也存在,\n// checkbox 仍然保留自己的 label(每個 checkbox 是 group 的一個選項,FieldLabel 只是群組名稱)。\n//\n// 反之:Checkbox **單獨**塞進 Field(無 CheckboxGroup 包)時,Checkbox 才忽略自己的 label\n// 讓 FieldLabel 接管 —— 那是「binary toggle in Field」的場景。\n//\n// 這是 AR50 的根因:沒這個 context 前,CheckboxGroup 內部的 Checkbox 會誤以為「被 Field 包了」\n// 就把 label 全丟掉,導致 Sheet 範例的 Checkboxes 全部沒 label。\nexport const CheckboxGroupContext = React.createContext<{ inGroup: true } | null>(null)\n\n/**\n * CheckboxGroup — 多選 Checkbox 的 layout primitive\n *\n * ── Canonical 鐵律(2026-04-21 user 明示 + codified)──\n *\n * **垂直 CheckboxGroup 的 item 之間沒有外部 gap**。間距完全靠每個 Checkbox 內部的\n * `SelectionItem py = (field-height - 1lh) / 2` 公式生成 —— 單行高度對齊 field-height,\n * 多 row stacked 時 row-to-row 自然有 py × 2 的呼吸空間。\n *\n * **禁止**外層加 `gap-y-*` / `space-y-*` / margin —— 會 double padding,違反 canonical。\n *\n * ── 對齊 RadioGroup canonical ──\n * 本 DS `RadioGroup` wrapper 用 `grid`(無 gap;radio-group.tsx 自加——Radix primitive\n * 本身 unstyled,無預設 layout);本元件垂直也用 `grid`(無 gap),\n * horizontal 用 `flex flex-wrap gap-4`(短 label 並排才需水平 gap)。\n *\n * ── 為什麼 vertical 不給 gap 也能好看 ──\n * SelectionItem py 的公式讓每個 Checkbox row 的「單行高度 = field-height」。row 堆疊時\n * 相鄰 row 的 py 相加 = 2×py ≈ 10-12px 真實 row-to-row 視覺呼吸空間。Atlassian / Ant /\n * Chakra / GitHub CheckboxGroup 皆同流派 —— row 高度定義 gap,不加外部 gap。\n *\n * ── 本 session 曾經的錯誤 + 釐清 ──\n * 早先曾以為「gap 要加」是因為「row 黏在一起」——但實際根因是 `Checkbox` 在 Field\n * context 內誤吞自己的 label(見 checkbox.tsx 的 CheckboxGroupContext 修正)。\n * label 回來後 row 自然撐開,不需要 gap。修正後的 canonical 鐵律:**zero gap,\n * 間距由 SelectionItem py 獨家擁有**。\n *\n * ── fieldLayout:block ──\n * 在 `<Field orientation=\"horizontal\">` 內,control area auto `items-start` +\n * padding-top 公式對齊第一個 item 的 label 第一行(見 field.spec.md)。\n *\n * ── 用法範例 ──\n *   <CheckboxGroup>\n *     <Checkbox label=\"待處理\" defaultChecked />\n *     <Checkbox label=\"進行中\" defaultChecked />\n *     <Checkbox label=\"已完成\" />\n *   </CheckboxGroup>\n *\n *   <CheckboxGroup orientation=\"horizontal\">\n *     <Checkbox label=\"Email\" />\n *     <Checkbox label=\"Push\" />\n *     <Checkbox label=\"SMS\" />\n *   </CheckboxGroup>\n */\n\nexport interface CheckboxGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /**\n   * 排列方向。\n   * - `vertical`(預設):多選項目堆疊,row 間距由 SelectionItem 擁有(外層 0 gap)\n   * - `horizontal`:選項並排,gap-4 分隔(短 label 場景,如「Email / Push / SMS」)\n   */\n  orientation?: 'vertical' | 'horizontal'\n}\n\n// Module-level 常數(2026-04-22 D3 perf audit):provider value 無狀態,hoist 避免 render 重建\nconst CHECKBOX_GROUP_CTX_VALUE = { inGroup: true } as const\n\nconst CheckboxGroup = React.forwardRef<HTMLDivElement, CheckboxGroupProps>(\n  ({ className, orientation = 'vertical', ...props }, ref) => {\n    // Field 整合 a11y(2026-07-17 d10i1):role=\"group\" 的 <div> 無法被 <FieldLabel htmlFor> 命名 →\n    // 自讀 fieldCtx 接 aria-labelledby / aria-describedby / aria-invalid,讓群組在 accessibility tree\n    // 有名稱、描述與錯誤狀態(對齊 RadioGroup Root 的 fieldCtx 接線,radio-group.tsx L164-166)。\n    // standalone(無 Field)時皆 undefined,consumer 經 {...props} 傳的 aria-* 照舊生效(置於 spread 前故可被覆蓋)。\n    const fieldCtx = useFieldContext()\n    return (\n      <CheckboxGroupContext.Provider value={CHECKBOX_GROUP_CTX_VALUE}>\n        <div\n          ref={ref}\n          role=\"group\"\n          aria-labelledby={fieldCtx?.labelId}\n          aria-describedby={fieldCtx?.descriptionId}\n          aria-invalid={fieldCtx?.invalid || undefined}\n          className={cn(\n            // 垂直 CheckboxGroup:zero gap(間距由 SelectionItem py 獨家擁有,見 docblock canonical)\n            // 水平:短 label 並排需水平 gap-4(label 沒有 py 擴散,需要顯式 gap)\n            orientation === 'vertical' ? 'grid' : 'flex flex-wrap gap-4',\n            className\n          )}\n          {...props}\n        />\n      </CheckboxGroupContext.Provider>\n    )\n  }\n)\nCheckboxGroup.displayName = 'CheckboxGroup'\n// Field layout declaration:block primitive(多項堆疊)——進入 <Field> 時\n// control area 自動切 items-start + padding-top 公式。對齊 RadioGroup 做法。\n;(CheckboxGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'\n\nexport { CheckboxGroup }\n"],"names":[],"mappings":";;;;AAcO,MAAM,uBAAuB,MAAM,cAAwC,IAAI;AAyDtF,MAAM,2BAA2B,EAAE,SAAS,KAAA;AAE5C,MAAM,gBAAgB,MAAM;AAAA,EAC1B,CAAC,EAAE,WAAW,cAAc,YAAY,GAAG,MAAA,GAAS,QAAQ;AAK1D,UAAM,WAAW,gBAAA;AACjB,WACE,oBAAC,qBAAqB,UAArB,EAA8B,OAAO,0BACpC,UAAA;AAAA,MAAC;AAAA,MAAA;AAAA,QACC;AAAA,QACA,MAAK;AAAA,QACL,mBAAiB,qCAAU;AAAA,QAC3B,oBAAkB,qCAAU;AAAA,QAC5B,iBAAc,qCAAU,YAAW;AAAA,QACnC,WAAW;AAAA;AAAA;AAAA,UAGT,gBAAgB,aAAa,SAAS;AAAA,UACtC;AAAA,QAAA;AAAA,QAED,GAAG;AAAA,MAAA;AAAA,IAAA,GAER;AAAA,EAEJ;AACF;AACA,cAAc,cAAc;AAG1B,cAAsD,cAAc;"}

package/dist/components/Checkbox/checkbox.d.ts

@@ -2,22 +2,31 @@ import * as React from "react";
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
 import { type VariantProps } from "class-variance-authority";
 import type { FieldMode, FieldVariant } from "../../components/Field/field-types";
+import type { LucideIcon } from "lucide-react";
+import type { AvatarData } from "../../components/Avatar/avatar";
 declare const checkboxVariants: (props?: ({
     size?: "sm" | "md" | "lg" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
-export interface CheckboxProps extends React.ComponentPropsWithoutRef<typeof CheckboxPrimitive.Root>, VariantProps<typeof checkboxVariants> {
+export interface CheckboxProps 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 降色（弱化）。
@@ -27,7 +36,7 @@ export interface CheckboxProps extends React.ComponentPropsWithoutRef<typeof Che
     /**
      * 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:降色 + 鎖互動
@@ -42,26 +51,26 @@ export interface CheckboxProps extends React.ComponentPropsWithoutRef<typeof Che
 declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLButtonElement>>;
 export declare const checkboxMeta: {
     readonly component: "Checkbox";
-    readonly family: 4;
+    readonly family: null;
     readonly variants: {};
     readonly sizes: {
         readonly sm: {
             readonly fieldHeight: 28;
-            readonly iconSize: 16;
+            readonly iconSize: 12;
             readonly typography: "body";
         };
         readonly md: {
             readonly fieldHeight: 32;
-            readonly iconSize: 16;
+            readonly iconSize: 12;
             readonly typography: "body";
         };
         readonly lg: {
-            readonly fieldHeight: 40;
-            readonly iconSize: 20;
-            readonly typography: "body";
+            readonly fieldHeight: 36;
+            readonly iconSize: 16;
+            readonly typography: "body-lg";
         };
     };
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly states: readonly ["default", "hover", "checked", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly ["bg-disabled", "bg-primary", "bg-primary-hover", "bg-surface"];
         readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground"];

package/dist/components/Checkbox/checkbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/checkbox.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,iBAAiB,MAAM,0BAA0B,CAAA;AAE7D,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAGjE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAQ3F,QAAA,MAAM,gBAAgB;;8EA8BrB,CAAA;AA6BD,MAAM,WAAW,aACf,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,iBAAiB,CAAC,IAAI,CAAC,EACnE,YAAY,CAAC,OAAO,gBAAgB,CAAC;IACvC;;;;OAIG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB;AAID,QAAA,MAAM,QAAQ,yFAkGb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBf,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAA"}
+{"version":3,"file":"checkbox.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/checkbox.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,iBAAiB,MAAM,0BAA0B,CAAA;AAE7D,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAGjE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAM3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0CAA0C,CAAA;AAM1E,QAAA,MAAM,gBAAgB;;8EA8BrB,CAAA;AAsCD,MAAM,WAAW,aACf,SAAQ,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,OAAO,iBAAiB,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,UAAU,CAAC,EACjG,YAAY,CAAC,OAAO,gBAAgB,CAAC;IACvC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC7B,uHAAuH;IACvH,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,iDAAiD;IACjD,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB;AAID,QAAA,MAAM,QAAQ,yFAwOb,CAAA;AAKD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoBf,CAAA;AAEV,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,CAAA"}

package/dist/components/Checkbox/checkbox.js

@@ -1,11 +1,14 @@
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import * as React from "react";
 import * as CheckboxPrimitive from "@radix-ui/react-checkbox";
 import { Minus, Check } from "lucide-react";
 import { cva } from "class-variance-authority";
 import { cn } from "../../lib/utils.js";
-import { useFieldContext } from "../Field/field-context.js";
+import { useFieldContext, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldSize } from "../Field/field-context.js";
+import { useControllable } from "../../hooks/use-controllable.js";
+import { fieldWrapperStyles } from "../Field/field-wrapper.js";
 import { SelectionItem } from "../SelectionControl/selection-item.js";
+import { BooleanValueIcon } from "../SelectionControl/boolean-value.js";
 import { CheckboxGroupContext } from "./checkbox-group.js";
 const checkboxVariants = cva(
   [
@@ -45,22 +48,27 @@ 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
   }, ref) => {
     const sizeKey = size ?? "md";
     const iconPx = checkIconSize[sizeKey];
     const iconStrokeWidth = checkStrokeWidth[sizeKey];
-    if (mode === "display") {
-      const isChecked = props.checked === true;
-      return isChecked ? /* @__PURE__ */ jsx("span", { className: "text-foreground", children: "✓" }) : /* @__PURE__ */ jsx("span", { className: "text-fg-muted", children: "—" });
-    }
     const fieldCtx = useFieldContext();
     const checkboxGroupCtx = React.useContext(CheckboxGroupContext);
     const insideField = (fieldCtx == null ? void 0 : fieldCtx.hasFieldWrapper) === true;
@@ -70,19 +78,105 @@ const Checkbox = React.forwardRef(
     const effectiveDescription = shouldSuppressLabel ? void 0 : description;
     const generatedId = React.useId();
     const inputId = idProp ?? (insideGroup ? generatedId : (fieldCtx == null ? void 0 : fieldCtx.id) ?? generatedId);
+    const resolvedDisabled = useResolvedFieldDisabled(disabled);
+    const resolvedMode = useResolvedFieldMode({ mode, disabled, readOnly });
+    const effectiveReadOnly = readOnly || resolvedMode === "readonly";
+    const effectiveDisabled = resolvedDisabled || resolvedMode === "disabled";
+    const resolvedBoxSize = useResolvedFieldSize(size ?? void 0, "md");
+    const {
+      required: _required,
+      name: _name,
+      value: _value,
+      ...restDomProps
+    } = props;
+    const isControlled = checkedProp !== void 0;
+    const [resolvedChecked, setResolvedChecked] = useControllable({
+      value: checkedProp,
+      defaultValue: defaultCheckedProp ?? false
+    });
+    const innerRef = React.useRef(null);
+    React.useEffect(() => {
+      var _a;
+      if (isControlled) return;
+      const form = (_a = innerRef.current) == null ? void 0 : _a.form;
+      if (!form) return;
+      const handleReset = () => setResolvedChecked(defaultCheckedProp ?? false);
+      form.addEventListener("reset", handleReset);
+      return () => form.removeEventListener("reset", handleReset);
+    }, [isControlled, resolvedMode, defaultCheckedProp, setResolvedChecked]);
+    const setRef = React.useCallback((el) => {
+      innerRef.current = el;
+      if (typeof ref === "function") ref(el);
+      else if (ref) ref.current = el;
+    }, [ref]);
+    if (resolvedMode === "view") {
+      const isChecked = resolvedChecked === true;
+      const viewAriaLabel = restDomProps["aria-label"] ?? (isChecked ? "是" : "否");
+      return /* @__PURE__ */ jsx(
+        "span",
+        {
+          ...restDomProps,
+          ref,
+          role: "img",
+          "aria-label": viewAriaLabel,
+          className: "inline-flex",
+          children: /* @__PURE__ */ jsx(BooleanValueIcon, { checked: isChecked, size: resolvedBoxSize })
+        }
+      );
+    }
+    if (effectiveReadOnly && insideField && effectiveLabel == null) {
+      const isChecked = resolvedChecked === true;
+      const boxSize = resolvedBoxSize;
+      return /* @__PURE__ */ jsx(
+        "div",
+        {
+          ...restDomProps,
+          ref,
+          role: "checkbox",
+          "aria-checked": isChecked,
+          "aria-readonly": "true",
+          "aria-labelledby": fieldCtx == null ? void 0 : fieldCtx.labelId,
+          "aria-invalid": (fieldCtx == null ? void 0 : fieldCtx.invalid) || void 0,
+          "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
+          ),
+          children: /* @__PURE__ */ jsx(BooleanValueIcon, { checked: isChecked, size: boxSize })
+        }
+      );
+    }
     const rootEl = /* @__PURE__ */ jsx(
       CheckboxPrimitive.Root,
       {
         id: inputId,
-        ref,
-        disabled,
-        "aria-readonly": readOnly || void 0,
-        "data-readonly": readOnly || void 0,
-        tabIndex: readOnly ? -1 : void 0,
+        ref: setRef,
+        disabled: effectiveDisabled,
+        checked: resolvedChecked,
+        onCheckedChange: (next) => {
+          setResolvedChecked(next);
+          onCheckedChange == null ? void 0 : onCheckedChange(next);
+        },
+        "aria-readonly": effectiveReadOnly || void 0,
+        "data-readonly": effectiveReadOnly || void 0,
+        tabIndex: effectiveReadOnly ? -1 : void 0,
         "aria-describedby": fieldCtx == null ? void 0 : fieldCtx.descriptionId,
         className: cn(checkboxVariants({ size }), className),
         ...props,
-        children: /* @__PURE__ */ jsx(CheckboxPrimitive.Indicator, { className: "grid place-content-center text-current", children: props.checked === "indeterminate" ? /* @__PURE__ */ jsx(Minus, { style: { width: iconPx, height: iconPx }, strokeWidth: iconStrokeWidth }) : /* @__PURE__ */ jsx(Check, { style: { width: iconPx, height: iconPx }, strokeWidth: iconStrokeWidth }) })
+        onClick: (event) => {
+          var _a;
+          if (effectiveReadOnly) {
+            event.preventDefault();
+            return;
+          }
+          (_a = props.onClick) == null ? void 0 : _a.call(props, event);
+        },
+        children: /* @__PURE__ */ jsxs(CheckboxPrimitive.Indicator, { className: "group/indicator grid place-content-center text-current", children: [
+          /* @__PURE__ */ jsx(Minus, { className: "hidden group-data-[state=indeterminate]/indicator:block", style: { width: iconPx, height: iconPx }, strokeWidth: iconStrokeWidth }),
+          /* @__PURE__ */ jsx(Check, { className: "hidden group-data-[state=checked]/indicator:block", style: { width: iconPx, height: iconPx }, strokeWidth: iconStrokeWidth })
+        ] })
       }
     );
     if (effectiveLabel == null) return rootEl;
@@ -92,8 +186,10 @@ const Checkbox = React.forwardRef(
         control: rootEl,
         label: effectiveLabel,
         description: effectiveDescription,
+        icon,
+        avatar,
         htmlFor: inputId,
-        disabled,
+        disabled: effectiveDisabled,
         size: sizeKey
       }
     );
@@ -102,14 +198,17 @@ const Checkbox = React.forwardRef(
 Checkbox.displayName = CheckboxPrimitive.Root.displayName;
 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/dist/components/Checkbox/checkbox.js.map

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

package/dist/components/Checkbox/index.d.ts

@@ -0,0 +1,3 @@
+export * from './checkbox';
+export * from './checkbox-group';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Checkbox/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAA;AAC1B,cAAc,kBAAkB,CAAA"}

package/dist/components/Checkbox/index.js

@@ -0,0 +1,10 @@
+import { Checkbox, checkboxMeta, checkboxVariants } from "./checkbox.js";
+import { CheckboxGroup, CheckboxGroupContext } from "./checkbox-group.js";
+export {
+  Checkbox,
+  CheckboxGroup,
+  CheckboxGroupContext,
+  checkboxMeta,
+  checkboxVariants
+};
+//# sourceMappingURL=index.js.map

package/dist/components/Checkbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;"}

package/dist/components/Chip/chip.d.ts

@@ -2,10 +2,14 @@ import * as React from 'react';
 import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';
 import type { LucideIcon } from 'lucide-react';
 /**
- * Chip — Material Design Filter Chip
+ * Chip — Material Design Chips(filter + assist 兩分支)
  *
- * 基於 Radix ToggleGroup，橋接設計系統 token。
- * 必須在 <ChipGroup> 內使用。
+ * filter(預設):基於 Radix ToggleGroup,多/單選 pill;必須在 <ChipGroup> 內使用。
+ * assist(2026-09-02 加,AgentPanel 附件拍板消費):M3 assist chip 分支 —— 按鈕語意、
+ * 無 toggle、無 selected 態(https://m3.material.io/components/chips/guidelines「Assist chips」);
+ * 渲染 plain button,可獨立使用(不需 ChipGroup)。兩分支視覺同款(單一 cva;
+ * assist 無 data-state 故 selected 樣式天然不生效),差異=結構分支(conditional rendering,
+ * 非 cva variant — 對齊 cva-patterns「結構 variant 用 conditional rendering」)。
  *
  * ── 內部結構（鏡射 Button）──
  *   [startIcon?] [<span px-1>label</span>] [<span gap-1>badge? + endIcon?</span>]
@@ -15,15 +19,15 @@ import type { LucideIcon } from 'lucide-react';
  *   對齊 Material 3 / Atlassian / Polaris 世界級共識
  *
  * ── State ──
- *   default   bg-surface border-border text-foreground
- *   hover     border-border-hover（對齊 Input / SegmentedControl）
- *   selected  bg-primary-subtle border-primary-hover text-primary-hover
+ *   default   bg-surface border-border text-fg-secondary
+ *   hover     border-border-hover text-foreground（對齊 Input / SegmentedControl）
+ *   selected  bg-surface（不變） border-primary text-primary
  *   disabled  cursor-not-allowed text-fg-disabled
  *
  * ── 詳見 chip.spec.md ──
  */
 declare const chipVariants: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
-export interface ChipProps extends React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> {
+interface ChipSlotProps {
     /** 左側 icon（LucideIcon），最多一個 */
     startIcon?: LucideIcon;
     /** 右側 badge（通常是計數指示器）*/
@@ -31,6 +35,15 @@ export interface ChipProps extends React.ComponentPropsWithoutRef<typeof ToggleG
     /** 右側 icon（少見，通常是 ChevronDown 指示可展開）*/
     endIcon?: LucideIcon;
 }
+export interface ChipFilterProps extends Omit<React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item>, 'asChild'>, ChipSlotProps {
+    /** filter(預設):Radix ToggleGroup item,必須在 ChipGroup 內。 */
+    variant?: 'filter';
+}
+export interface ChipAssistProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, ChipSlotProps {
+    /** assist:M3 assist chip — 按鈕語意、無 toggle、無 selected 態;可獨立使用。 */
+    variant: 'assist';
+}
+export type ChipProps = ChipFilterProps | ChipAssistProps;
 declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLButtonElement>>;
 export type ChipGroupLayout = 'wrap' | 'scroll' | 'menu';
 export type ChipGroupProps = React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root> & {
@@ -42,11 +55,17 @@ export declare const chipMeta: {
     readonly component: "Chip";
     readonly family: 3;
     readonly variants: {};
-    readonly sizes: {};
-    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly sizes: {
+        readonly sm: {
+            readonly fieldHeight: 28;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+    };
+    readonly states: readonly ["default", "hover", "selected", "focus-visible", "disabled"];
     readonly tokens: {
-        readonly bg: readonly ["bg-primary-subtle", "bg-surface"];
-        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground"];
+        readonly bg: readonly ["bg-surface"];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground", "text-primary"];
         readonly ring: readonly ["ring-ring"];
     };
 };

package/dist/components/Chip/chip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../../src/components/Chip/chip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAA;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAiB9C;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,QAAA,MAAM,YAAY,oFAsBjB,CAAA;AAED,MAAM,WAAW,SACf,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC;IACxE,+BAA+B;IAC/B,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,wBAAwB;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,QAAA,MAAM,IAAI,qFAsBR,CAAA;AAKF,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,wBAAwB,CACzD,OAAO,oBAAoB,CAAC,IAAI,CACjC,GAAG;IACF,qDAAqD;IACrD,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB,CAAA;AAED,QAAA,MAAM,SAAS,uFA2Bd,CAAA;AAuMD,eAAO,MAAM,QAAQ;;;;;;;;;;;CAeX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA"}
+{"version":3,"file":"chip.d.ts","sourceRoot":"","sources":["../../../src/components/Chip/chip.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,oBAAoB,MAAM,8BAA8B,CAAA;AAEpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAiB9C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,QAAA,MAAM,YAAY,oFAkCjB,CAAA;AAED,UAAU,aAAa;IACrB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,wBAAwB;IACxB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,MAAM,WAAW,eAKf,SAAQ,IAAI,CAAC,KAAK,CAAC,wBAAwB,CAAC,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,EACvF,aAAa;IACf,yDAAyD;IACzD,OAAO,CAAC,EAAE,QAAQ,CAAA;CACnB;AAED,MAAM,WAAW,eACf,SAAQ,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC,EACnD,aAAa;IACf,gEAAgE;IAChE,OAAO,EAAE,QAAQ,CAAA;CAClB;AAED,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,eAAe,CAAA;AAEzD,QAAA,MAAM,IAAI,qFAsCT,CAAA;AAKD,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD,MAAM,MAAM,cAAc,GAAG,KAAK,CAAC,wBAAwB,CACzD,OAAO,oBAAoB,CAAC,IAAI,CACjC,GAAG;IACF,qDAAqD;IACrD,MAAM,CAAC,EAAE,eAAe,CAAA;CACzB,CAAA;AAED,QAAA,MAAM,SAAS,uFA2Bd,CAAA;AAwOD,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;CAgBX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,YAAY,EAAE,CAAA"}