@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

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

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

package/dist/components/Switch/index.js

@@ -0,0 +1,7 @@
+import { Switch, switchMeta, switchVariants } from "./switch.js";
+export {
+  Switch,
+  switchMeta,
+  switchVariants
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/Switch/switch.d.ts

@@ -0,0 +1,112 @@
+import * as React from 'react';
+import * as SwitchPrimitives from '@radix-ui/react-switch';
+import { type VariantProps } from 'class-variance-authority';
+import type { FieldMode, FieldVariant } from '../../components/Field/field-types';
+/**
+ * Switch — 開關控件
+ *
+ * ── 結構 ──
+ *   Track（pill 形容器）→ Thumb（白色圓 + 2px border + check icon）
+ *   Track 寬 = 2 × 高，thumb 直徑 = track 高度
+ *
+ * ── 尺寸（sm = md）──
+ *   sm/md: track 20×40, thumb 20, 白色圓 16, check 12（= checkbox sm/md）
+ *   lg:    track 24×48, thumb 24, 白色圓 20, check 16（= checkbox lg）
+ *
+ * ── 視覺狀態 ──
+ *   OFF: track border (neutral-5), thumb 白色無 border 無 check
+ *   ON:  track primary, thumb 白色 + 2px primary border + primary check icon
+ *   disabled: opacity-disabled（整體透明度）
+ *   readOnly: 視覺同一般態，但 pointer-events-none + aria-readonly
+ *
+ * ── label / description / readOnly ──
+ * Switch 可以透過 `label` 和 `description` props 在元件內直接渲染緊鄰的文字，
+ * 樣式全部 codify 在元件內（text-body、foreground/fg-secondary、disabled 色）。
+ *
+ * 單獨使用時：
+ *   <Switch label="啟用通知" description="收到新訊息時提醒" />
+ *
+ * Form 內使用（在 <Field> context 內）：
+ *   <Field>
+ *     <FieldLabel>啟用通知</FieldLabel>
+ *     <Switch />                      ← label/description prop 會被自動忽略
+ *     <FieldDescription>收到新訊息時提醒</FieldDescription>
+ *   </Field>
+ *
+ * Field context 透過 useFieldContext() 偵測，避免雙層 label。
+ *
+ * readOnly 模式：
+ *   <Switch readOnly checked={true} label="..." />
+ *   視覺維持 ON/OFF 正確狀態，但無法互動、不在 tab order 內、寫入 aria-readonly。
+ *   與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
+ */
+declare const switchVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface SwitchProps extends React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>, VariantProps<typeof switchVariants> {
+    /**
+     * Inline label。提供時 Switch 自動包一個 <label> 並連結 htmlFor，
+     * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。
+     * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。
+     */
+    label?: React.ReactNode;
+    /**
+     * Inline description（secondary 文字）。須與 label 搭配使用，
+     * 單獨設定 description 無效果。套用 text-body / text-fg-secondary 樣式。
+     * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。
+     */
+    description?: React.ReactNode;
+    /**
+     * readonly 模式：鎖定互動但維持 ON/OFF 視覺正確。
+     * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。
+     * 用於表單 readonly 呈現、DataTable cell 非編輯態。
+     */
+    readOnly?: boolean;
+    /**
+     * Field mode(2026-05-05 Phase B3 align):
+     *   edit     — 一般可互動 Switch(預設)
+     *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);
+     *              對齊 Carbon read-only / DataTable boolean cell。
+     *              `readonly` 保留 toggle 視覺 + 鎖互動;`display` 完全無 toggle 形體 — 兩者語意分離(field-types.ts)。
+     *   readonly — 同 readOnly prop
+     *   disabled — 同 disabled prop
+     */
+    mode?: FieldMode;
+    /**
+     * Visual chrome — Switch 本體無 input wrapper variant,本 prop 對 Switch 主體無視覺影響;
+     * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。
+     */
+    variant?: FieldVariant;
+}
+declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const switchMeta: {
+    readonly component: "Switch";
+    readonly family: 4;
+    readonly variants: {};
+    readonly sizes: {
+        readonly sm: {
+            readonly fieldHeight: 28;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly md: {
+            readonly fieldHeight: 32;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly lg: {
+            readonly fieldHeight: 40;
+            readonly iconSize: 20;
+            readonly typography: "body";
+        };
+    };
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-primary"];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground", "text-primary"];
+        readonly ring: readonly ["ring-ring"];
+    };
+    readonly defaultSize: "md";
+};
+export { Switch, switchVariants };
+//# sourceMappingURL=switch.d.ts.map

package/dist/components/Switch/switch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"switch.d.ts","sourceRoot":"","sources":["../../../src/components/Switch/switch.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,gBAAgB,MAAM,wBAAwB,CAAA;AAE1D,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAEjE,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,8CAA8C,CAAA;AAG3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,QAAA,MAAM,cAAc;;8EAsBnB,CAAA;AAcD,MAAM,WAAW,WACf,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,gBAAgB,CAAC,IAAI,CAAC,EAClE,YAAY,CAAC,OAAO,cAAc,CAAC;IACrC;;;;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;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB;AAED,QAAA,MAAM,MAAM,uFAyIX,CAAA;AAKD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBb,CAAA;AAEV,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,CAAA"}

package/dist/components/Switch/switch.js

@@ -0,0 +1,179 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import * as SwitchPrimitives from "@radix-ui/react-switch";
+import { Check } from "lucide-react";
+import { cva } from "class-variance-authority";
+import { cn } from "../../lib/utils.js";
+import { useFieldContext } from "../Field/field-context.js";
+const switchVariants = cva(
+  [
+    "group peer inline-flex shrink-0 cursor-pointer items-center rounded-full",
+    "transition-colors duration-150",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1",
+    "disabled:cursor-not-allowed disabled:opacity-disabled",
+    // readOnly：鎖定互動但視覺正常
+    "data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default",
+    // OFF → ON 背景色
+    "data-[state=unchecked]:bg-border",
+    "data-[state=checked]:bg-primary"
+  ],
+  {
+    variants: {
+      size: {
+        sm: "h-5 w-10",
+        // 20×40
+        md: "h-5 w-10",
+        // 20×40
+        lg: "h-6 w-12"
+        // 24×48
+      }
+    },
+    defaultVariants: { size: "md" }
+  }
+);
+const SPECS = {
+  // checkStroke:16px 以下 icon 視覺不夠顯眼 → 加粗 stroke 補償(跟 Checkbox 共用原則,
+  // 見 checkbox.tsx 的 checkStrokeWidth 註解)。12px 用 3.5(render ≈ 1.75px 線寬,比 Lucide
+  // 預設的 1px render 明顯更粗,視覺跟 16px 預設 stroke 的 1.33px 有足夠區別),16px 用 2.5
+  // (render ≈ 1.67px,比預設 1.33px 稍粗讓 toggle check 夠顯眼)。跨 size 配對值由 checkbox.tsx 共用。
+  // 2026-05-18 簡化 per user 視覺證 + Checkbox 同步(3.5 → 3 sm/md):effective render 差
+  // 0.08px 視覺看不出,保留 compensation 主旨但不過度差異化。
+  sm: { thumb: 20, check: 12, checkStroke: 3, translate: "translateX(20px)" },
+  md: { thumb: 20, check: 12, checkStroke: 3, translate: "translateX(20px)" },
+  lg: { thumb: 24, check: 16, checkStroke: 2.5, translate: "translateX(24px)" }
+};
+const Switch = React.forwardRef(
+  ({
+    className,
+    size,
+    label,
+    description,
+    readOnly = false,
+    disabled,
+    mode,
+    // chrome 對 Switch 主體無視覺影響(無 input wrapper)— 接收純為 prop 一致性;destructure 防 leak 到 DOM。
+    variant: _chrome,
+    id: idProp,
+    ...props
+  }, ref) => {
+    const sizeKey = size ?? "md";
+    const spec = SPECS[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 insideField = (fieldCtx == null ? void 0 : fieldCtx.hasFieldWrapper) === true;
+    const effectiveLabel = insideField ? void 0 : label;
+    const effectiveDescription = insideField ? void 0 : description;
+    const alignRightInField = insideField && (fieldCtx == null ? void 0 : fieldCtx.orientation) === "horizontal" ? "ml-auto" : "";
+    const generatedId = React.useId();
+    const inputId = idProp ?? (fieldCtx == null ? void 0 : fieldCtx.id) ?? generatedId;
+    const rootEl = /* @__PURE__ */ jsx(
+      SwitchPrimitives.Root,
+      {
+        id: inputId,
+        className: cn(switchVariants({ size }), alignRightInField, className),
+        ref,
+        disabled,
+        "aria-readonly": readOnly || void 0,
+        "data-readonly": readOnly || void 0,
+        tabIndex: readOnly ? -1 : void 0,
+        "aria-describedby": fieldCtx == null ? void 0 : fieldCtx.descriptionId,
+        ...props,
+        children: /* @__PURE__ */ jsx(
+          SwitchPrimitives.Thumb,
+          {
+            className: cn(
+              "pointer-events-none flex items-center justify-center rounded-full bg-on-emphasis border-2",
+              "transition-all duration-150",
+              "data-[state=unchecked]:translate-x-0 data-[state=unchecked]:border-border",
+              "data-[state=checked]:border-primary",
+              sizeKey === "lg" ? "data-[state=checked]:translate-x-6" : "data-[state=checked]:translate-x-5"
+            ),
+            style: { width: spec.thumb, height: spec.thumb },
+            children: /* @__PURE__ */ jsx(
+              Check,
+              {
+                size: spec.check,
+                strokeWidth: spec.checkStroke,
+                className: "text-primary opacity-0 transition-opacity duration-150 group-data-[state=checked]:opacity-100",
+                "aria-hidden": true
+              }
+            )
+          }
+        )
+      }
+    );
+    if (effectiveLabel == null) return rootEl;
+    return /* @__PURE__ */ jsxs(
+      "label",
+      {
+        htmlFor: inputId,
+        className: cn(
+          "inline-flex items-start gap-3 select-none",
+          disabled ? "cursor-not-allowed" : readOnly ? "cursor-default" : "cursor-pointer"
+        ),
+        children: [
+          /* @__PURE__ */ jsxs(
+            "span",
+            {
+              className: cn(
+                "flex-1 min-w-0 flex flex-col",
+                sizeKey === "lg" ? "gap-[var(--item-gap-label-desc-reading-lg)]" : "gap-[var(--item-gap-label-desc-reading)]"
+              ),
+              children: [
+                /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: cn(
+                      // Reading mode 字級:lg → text-body-lg (16px),sm/md → text-body (14px)
+                      sizeKey === "lg" ? "text-body-lg" : "text-body",
+                      disabled ? "text-fg-disabled" : "text-foreground"
+                    ),
+                    children: effectiveLabel
+                  }
+                ),
+                effectiveDescription != null && /* @__PURE__ */ jsx(
+                  "span",
+                  {
+                    className: cn(
+                      disabled ? "text-fg-disabled" : "text-fg-secondary"
+                    ),
+                    style: { fontSize: "var(--font-body-size)" },
+                    children: effectiveDescription
+                  }
+                )
+              ]
+            }
+          ),
+          /* @__PURE__ */ jsx("span", { className: "h-[1lh] flex items-center shrink-0", children: rootEl })
+        ]
+      }
+    );
+  }
+);
+Switch.displayName = SwitchPrimitives.Root.displayName;
+const switchMeta = {
+  component: "Switch",
+  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" }
+  },
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: ["bg-primary"],
+    fg: ["text-fg-disabled", "text-fg-secondary", "text-foreground", "text-primary"],
+    ring: ["ring-ring"]
+  },
+  defaultSize: "md"
+};
+export {
+  Switch,
+  switchMeta,
+  switchVariants
+};
+//# sourceMappingURL=switch.js.map

package/dist/components/Switch/switch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"switch.js","sources":["../../../src/components/Switch/switch.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 SwitchPrimitives from '@radix-ui/react-switch'\nimport { Check } from 'lucide-react'\nimport { cva, type VariantProps } from 'class-variance-authority'\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'\n\n/**\n * Switch — 開關控件\n *\n * ── 結構 ──\n *   Track（pill 形容器）→ Thumb（白色圓 + 2px border + check icon）\n *   Track 寬 = 2 × 高，thumb 直徑 = track 高度\n *\n * ── 尺寸（sm = md）──\n *   sm/md: track 20×40, thumb 20, 白色圓 16, check 12（= checkbox sm/md）\n *   lg:    track 24×48, thumb 24, 白色圓 20, check 16（= checkbox lg）\n *\n * ── 視覺狀態 ──\n *   OFF: track border (neutral-5), thumb 白色無 border 無 check\n *   ON:  track primary, thumb 白色 + 2px primary border + primary check icon\n *   disabled: opacity-disabled（整體透明度）\n *   readOnly: 視覺同一般態，但 pointer-events-none + aria-readonly\n *\n * ── label / description / readOnly ──\n * Switch 可以透過 `label` 和 `description` props 在元件內直接渲染緊鄰的文字，\n * 樣式全部 codify 在元件內（text-body、foreground/fg-secondary、disabled 色）。\n *\n * 單獨使用時：\n *   <Switch label=\"啟用通知\" description=\"收到新訊息時提醒\" />\n *\n * Form 內使用（在 <Field> context 內）：\n *   <Field>\n *     <FieldLabel>啟用通知</FieldLabel>\n *     <Switch />                      ← label/description prop 會被自動忽略\n *     <FieldDescription>收到新訊息時提醒</FieldDescription>\n *   </Field>\n *\n * Field context 透過 useFieldContext() 偵測，避免雙層 label。\n *\n * readOnly 模式：\n *   <Switch readOnly checked={true} label=\"...\" />\n *   視覺維持 ON/OFF 正確狀態，但無法互動、不在 tab order 內、寫入 aria-readonly。\n *   與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。\n */\n\nconst switchVariants = cva(\n  [\n    'group peer inline-flex shrink-0 cursor-pointer items-center rounded-full',\n    'transition-colors duration-150',\n    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',\n    'disabled:cursor-not-allowed disabled:opacity-disabled',\n    // readOnly：鎖定互動但視覺正常\n    'data-[readonly=true]:pointer-events-none data-[readonly=true]:cursor-default',\n    // OFF → ON 背景色\n    'data-[state=unchecked]:bg-border',\n    'data-[state=checked]:bg-primary',\n  ],\n  {\n    variants: {\n      size: {\n        sm: 'h-5 w-10',   // 20×40\n        md: 'h-5 w-10',   // 20×40\n        lg: 'h-6 w-12',   // 24×48\n      },\n    },\n    defaultVariants: { size: 'md' },\n  }\n)\n\nconst SPECS: Record<string, { thumb: number; check: number; checkStroke: number; translate: string }> = {\n  // checkStroke:16px 以下 icon 視覺不夠顯眼 → 加粗 stroke 補償(跟 Checkbox 共用原則,\n  // 見 checkbox.tsx 的 checkStrokeWidth 註解)。12px 用 3.5(render ≈ 1.75px 線寬,比 Lucide\n  // 預設的 1px render 明顯更粗,視覺跟 16px 預設 stroke 的 1.33px 有足夠區別),16px 用 2.5\n  // (render ≈ 1.67px,比預設 1.33px 稍粗讓 toggle check 夠顯眼)。跨 size 配對值由 checkbox.tsx 共用。\n  // 2026-05-18 簡化 per user 視覺證 + Checkbox 同步(3.5 → 3 sm/md):effective render 差\n  // 0.08px 視覺看不出,保留 compensation 主旨但不過度差異化。\n  sm: { thumb: 20, check: 12, checkStroke: 3, translate: 'translateX(20px)' },\n  md: { thumb: 20, check: 12, checkStroke: 3, translate: 'translateX(20px)' },\n  lg: { thumb: 24, check: 16, checkStroke: 2.5, translate: 'translateX(24px)' },\n}\n\nexport interface SwitchProps\n  extends React.ComponentPropsWithoutRef<typeof SwitchPrimitives.Root>,\n    VariantProps<typeof switchVariants> {\n  /**\n   * Inline label。提供時 Switch 自動包一個 <label> 並連結 htmlFor，\n   * 套用 text-body / text-foreground / disabled 色 的 codified 樣式。\n   * 在 <Field> context 內時此 prop 會被忽略（由 FieldLabel 接管）。\n   */\n  label?: React.ReactNode\n  /**\n   * Inline description（secondary 文字）。須與 label 搭配使用，\n   * 單獨設定 description 無效果。套用 text-body / text-fg-secondary 樣式。\n   * 在 <Field> context 內時此 prop 會被忽略（由 FieldDescription 接管）。\n   */\n  description?: React.ReactNode\n  /**\n   * readonly 模式：鎖定互動但維持 ON/OFF 視覺正確。\n   * 與 disabled 的差異：readonly 不降色（可讀），disabled 降色（弱化）。\n   * 用於表單 readonly 呈現、DataTable cell 非編輯態。\n   */\n  readOnly?: boolean\n  /**\n   * Field mode(2026-05-05 Phase B3 align):\n   *   edit     — 一般可互動 Switch(預設)\n   *   display  — **純展示**:渲染 ✓ / —(無互動 primitive、無 input chrome);\n   *              對齊 Carbon read-only / DataTable boolean cell。\n   *              `readonly` 保留 toggle 視覺 + 鎖互動;`display` 完全無 toggle 形體 — 兩者語意分離(field-types.ts)。\n   *   readonly — 同 readOnly prop\n   *   disabled — 同 disabled prop\n   */\n  mode?: FieldMode\n  /**\n   * Visual chrome — Switch 本體無 input wrapper variant,本 prop 對 Switch 主體無視覺影響;\n   * 為對齊 Field 4-mode + chrome 透傳契約而保留(M19 一致性)。\n   */\n  variant?: FieldVariant\n}\n\nconst Switch = React.forwardRef<\n  React.ElementRef<typeof SwitchPrimitives.Root>,\n  SwitchProps\n>(\n  (\n    {\n      className,\n      size,\n      label,\n      description,\n      readOnly = false,\n      disabled,\n      mode,\n      // chrome 對 Switch 主體無視覺影響(無 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 spec = SPECS[sizeKey]\n\n    // ── mode='display' ─────────────────────────────────────────────────────\n    // 純展示模式:無互動 toggle、無 input variant,渲染 ✓ / —。\n    // 與 Checkbox display 對齊(同為 boolean primitive)— DataTable boolean cell 場景共用。\n    // 與 readonly 差異:readonly 保留 toggle 視覺 + 鎖互動;display 完全無 toggle 形體。\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 偵測：在 Field 內時忽略自己的 label/description，避免雙層\n    const fieldCtx = useFieldContext()\n    const insideField = fieldCtx?.hasFieldWrapper === true\n    const effectiveLabel = insideField ? undefined : label\n    const effectiveDescription = insideField ? undefined : description\n\n    // 在 horizontal Field 內自動齊右(iOS / macOS Settings canonical):\n    // horizontal Field 的 layout 是 label(固定寬)| control area(fill),Switch 作為\n    // trailing control 應靠右(對齊 horizontal DescriptionItem 的「label 左 / value 右」模式)。\n    // 世界級對照:iOS Settings / macOS System Settings / GitHub Settings / Figma prefs\n    // 一律 switch 齊右 — 視覺掃描快、對齊一致。\n    const alignRightInField =\n      insideField && fieldCtx?.orientation === 'horizontal' ? 'ml-auto' : ''\n\n    // Id 連結：優先使用 prop，再退到 Field context 的 id，最後用 useId 生成\n    const generatedId = React.useId()\n    const inputId = idProp ?? fieldCtx?.id ?? generatedId\n\n    const rootEl = (\n      <SwitchPrimitives.Root\n        id={inputId}\n        className={cn(switchVariants({ size }), alignRightInField, className)}\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        {...props}\n      >\n        <SwitchPrimitives.Thumb\n          className={cn(\n            'pointer-events-none flex items-center justify-center rounded-full bg-on-emphasis border-2',\n            'transition-all duration-150',\n            'data-[state=unchecked]:translate-x-0 data-[state=unchecked]:border-border',\n            'data-[state=checked]:border-primary',\n            sizeKey === 'lg' ? 'data-[state=checked]:translate-x-6' : 'data-[state=checked]:translate-x-5',\n          )}\n          style={{ width: spec.thumb, height: spec.thumb }}\n        >\n          {/* Check icon — Radix Thumb inherits data-state from Root */}\n          <Check\n            size={spec.check}\n            strokeWidth={spec.checkStroke}\n            className=\"text-primary opacity-0 transition-opacity duration-150 group-data-[state=checked]:opacity-100\"\n            aria-hidden\n          />\n        </SwitchPrimitives.Thumb>\n      </SwitchPrimitives.Root>\n    )\n\n    // 無 label → 只渲染 switch 本體\n    if (effectiveLabel == null) return rootEl\n\n    // 有 label → 包 <label> + codified 樣式\n    // Switch 慣例：label 在左、switch 在右（對齊 iOS / Polaris / Material 標準）\n    // label 行第一行對齊 switch 中線：容器用 items-start + switch 包 h-[1lh] flex-center\n    return (\n      <label\n        htmlFor={inputId}\n        className={cn(\n          'inline-flex items-start gap-3 select-none',\n          disabled ? 'cursor-not-allowed' : readOnly ? 'cursor-default' : 'cursor-pointer'\n        )}\n      >\n        {/* Label↔desc gap typography-mode-aware:\n            sm/md = reading(body+body 14/1.5),lg = reading-lg(body-lg+body 14/1.5) */}\n        <span\n          className={cn(\n            'flex-1 min-w-0 flex flex-col',\n            sizeKey === 'lg'\n              ? 'gap-[var(--item-gap-label-desc-reading-lg)]'\n              : 'gap-[var(--item-gap-label-desc-reading)]',\n          )}\n        >\n          <span\n            className={cn(\n              // Reading mode 字級:lg → text-body-lg (16px),sm/md → text-body (14px)\n              sizeKey === 'lg' ? 'text-body-lg' : 'text-body',\n              disabled ? 'text-fg-disabled' : 'text-foreground'\n            )}\n          >\n            {effectiveLabel}\n          </span>\n          {effectiveDescription != null && (\n            <span\n              className={cn(\n                disabled ? 'text-fg-disabled' : 'text-fg-secondary'\n              )}\n              // Reading mode description:**最小 14px**(spec 14→14px, 16→14px),lh 預設 1.5。\n              // 用 inline style 直接繞過 tailwind-merge 對 text-body / text-fg-* 的潛在衝突。\n              style={{ fontSize: 'var(--font-body-size)' }}\n            >\n              {effectiveDescription}\n            </span>\n          )}\n        </span>\n        <span className=\"h-[1lh] flex items-center shrink-0\">\n          {rootEl}\n        </span>\n      </label>\n    )\n  }\n)\nSwitch.displayName = SwitchPrimitives.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 switchMeta = {\n  component: 'Switch',\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-primary'],\n    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],\n    ring: ['ring-ring'],\n  },\n  defaultSize: 'md',\n} as const\n\nexport { Switch, switchVariants }\n"],"names":[],"mappings":"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"}

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

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

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

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

package/dist/components/Tabs/index.js

@@ -0,0 +1,10 @@
+import { Tabs, TabsContent, TabsList, TabsTrigger, tabsMeta, tabsTriggerVariants } from "./tabs.js";
+export {
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+  tabsMeta,
+  tabsTriggerVariants
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/Tabs/tabs.d.ts

@@ -0,0 +1,104 @@
+import * as React from 'react';
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+import type { LucideIcon } from 'lucide-react';
+/**
+ * Tabs — 基於 Radix Tabs，橋接設計系統 token
+ *
+ * ── 定位 ──
+ *   同一上下文底下切換平行的 view。切 view（不是切 value）。
+ *   切 value 用 SegmentedControl；切路由用 navigation。
+ *
+ * ── Size ──
+ *   sm   h-tab-sm（32/40），★ 預設(2026-05-17 從 md 改),overlay / chrome / dense
+ *   md   h-tab-md（40/48），future tier 無 recommended use case
+ *   lg   h-tab-lg（48/56），page-level hero / 獨立 tabs 取代 chrome header
+ *
+ * ── 寬度行為 ──
+ *   Trigger 寬度永遠由內容決定（hug content）。
+ *   Triggers 之間 gap 為 --layout-space-loose（16px / 24px lg density）。
+ *
+ * ── Trigger 結構 ──
+ *   [startIcon?] [label] [suffix: badge? + endIcon?]
+ *   slot 間 gap-2，suffix 內 gap-1
+ *
+ * ── Selected underline ──
+ *   使用 ::after 絕對定位在 bottom: -1px，2px primary-hover，
+ *   蓋住 TabsList 的 1px gray border（單一視覺線條，不雙線）。
+ */
+type TabsSize = 'sm' | 'md' | 'lg';
+type TabsOverflow = 'none' | 'scroll' | 'menu';
+interface TabsProps extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root> {
+}
+declare const Tabs: React.ForwardRefExoticComponent<TabsProps & React.RefAttributes<HTMLDivElement>>;
+interface TabsListProps extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.List> {
+    size?: TabsSize;
+    /**
+     * Overflow 處理模式。詳見 tabs.spec.md 的 overflow 段。
+     *   'none'   ★ 預設，不處理，triggers 溢出父容器（適用 tabs 數量可控的情境）
+     *   'scroll' 單行橫向滾動 + 邊緣 fade mask（Material / Polaris / iOS 作法）
+     *   'menu'   塞不下收進 "⋯" dropdown，所有 triggers 仍在 DOM 保留 Radix a11y
+     *            （Ant Design / Atlassian 作法）
+     */
+    overflow?: TabsOverflow;
+}
+declare const TabsList: React.ForwardRefExoticComponent<TabsListProps & React.RefAttributes<HTMLDivElement>>;
+declare const tabsTriggerVariants: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+interface TabsTriggerProps extends React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger> {
+    /** 左側 icon（LucideIcon） */
+    startIcon?: LucideIcon;
+    /** 右側 badge（通常是計數指示器） */
+    badge?: React.ReactNode;
+    /**
+     * 右側純視覺 indicator(LucideIcon)。**僅限方向 / 狀態 indicator**:ChevronDown / Pin / Star。
+     * **不要拼 click 行為** — endIcon 是 tab body 的一部分,點到也是切 tab。
+     * 需要「點該後綴開 dropdown / menu」場景請用 `inlineAction` slot(2026-05-21 拆分)。
+     */
+    endIcon?: LucideIcon;
+    /**
+     * Inline action slot(2026-05-21 v3 加,per user「圖一 後綴應該是 inline action」+「點擊
+     * 該 tab 的 inline action 跟其他地方應該不同反應」directive):
+     * 提供 `<ItemInlineAction>` / `<DropdownMenuTrigger asChild><ItemInlineAction ... /></DropdownMenuTrigger>`
+     * 等獨立 click target。**TabsTrigger 自動 stopPropagation**,inline action 點擊不冒泡到 tab body,
+     * 達成 split-click 行為(對齊 GitHub「Code ▾」/ Linear "Triage..." menu / Atlassian split-tab 共識)。
+     *
+     * 跟 endIcon 區別:endIcon = 純視覺 indicator(無獨立行為,連同 tab 一起 click),
+     * inlineAction = 獨立 click target(自己的 handler,不切 tab)。語意分家明確。
+     */
+    inlineAction?: React.ReactNode;
+}
+declare const TabsTrigger: React.ForwardRefExoticComponent<TabsTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const TabsContent: React.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & React.RefAttributes<HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+export declare const tabsMeta: {
+    readonly component: "Tabs";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {
+        readonly sm: {
+            readonly fieldHeight: 28;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly md: {
+            readonly fieldHeight: 32;
+            readonly iconSize: 16;
+            readonly typography: "body";
+        };
+        readonly lg: {
+            readonly fieldHeight: 40;
+            readonly iconSize: 20;
+            readonly typography: "body";
+        };
+    };
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly ["bg-primary-hover", "bg-transparent"];
+        readonly fg: readonly ["text-fg-disabled", "text-fg-secondary", "text-foreground"];
+        readonly ring: readonly ["ring-ring"];
+    };
+    readonly defaultSize: "sm";
+};
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsTriggerVariants };
+export type { TabsSize, TabsListProps, TabsTriggerProps };
+//# sourceMappingURL=tabs.d.ts.map

package/dist/components/Tabs/tabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../../src/components/Tabs/tabs.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAC9B,OAAO,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAErD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAkB9C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,KAAK,QAAQ,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAClC,KAAK,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAU9C,UAAU,SAAU,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,aAAa,CAAC,IAAI,CAAC;CAAG;AAOxF,QAAA,MAAM,IAAI,kFAkCR,CAAA;AAiBF,UAAU,aACR,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,aAAa,CAAC,IAAI,CAAC;IACjE,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB;AAED,QAAA,MAAM,QAAQ,sFAmCZ,CAAA;AAgMF,QAAA,MAAM,mBAAmB;;8EA0CxB,CAAA;AAED,UAAU,gBACR,SAAQ,KAAK,CAAC,wBAAwB,CAAC,OAAO,aAAa,CAAC,OAAO,CAAC;IACpE,0BAA0B;IAC1B,SAAS,CAAC,EAAE,UAAU,CAAA;IACtB,yBAAyB;IACzB,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC/B;AAED,QAAA,MAAM,WAAW,4FA6Cf,CAAA;AAIF,QAAA,MAAM,WAAW,0JAYf,CAAA;AAKF,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBX,CAAA;AAEV,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAA;AACxE,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAA"}