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

package/dist/components/Field/field.d.ts

@@ -0,0 +1,127 @@
+import * as React from 'react';
+/**
+ * Field — 表單欄位佈局容器（shadcn Field 風格）
+ *
+ * ── 定位 ────────────────────────────────────────────────────────────────
+ * Field 只負責 **佈局 + 狀態 context**，不擁有任何資料型別邏輯。
+ * 每個資料型別對應的 Control（Input、NumberInput、Checkbox、Switch 等）
+ * 維持自己的 edit / readonly / disabled 三態，Field 透過 context 把
+ * mode / disabled / required / invalid / id 傳給子元件，由子元件決定
+ * 如何反映。
+ *
+ * ── 結構 ────────────────────────────────────────────────────────────────
+ *   <Field orientation="vertical | horizontal" labelWidth="120px">
+ *     <FieldLabel>姓名</FieldLabel>
+ *     <Input value={...} onChange={...} />         ← Control（任何非 label/desc/error 的 child）
+ *     <FieldDescription>...</FieldDescription>
+ *     <FieldError>{errors.name}</FieldError>
+ *   </Field>
+ *
+ *   Control 會自動包在 control area slot（min-h-field-* + items-center），
+ *   確保 Checkbox / Switch / Radio 等高度 < field-height 的 primitive
+ *   垂直對齊 Input 中線；Input 等自身為 field-height 的 primitive 填滿。
+ *
+ * ── Horizontal mode 的 label 垂直對齊 ───────────────────────────────────
+ * FieldLabel 在 horizontal 模式下使用公式：
+ *     padding-top: calc((var(--field-height-{size}) - 1lh) / 2)
+ *
+ * 單行 label → 文字第一行與 input 中線對齊（視覺置中）
+ * 多行 label → 第一行仍與 input 中線對齊，其餘行往下流（label 高度超過
+ *              input 時視覺上仍保持與 input 內容同一基準線）
+ *
+ * 此公式 tracks field-height 和 line-height 的變動，size 切換或字體
+ * 調整時自動連動，不需 JS 測量。
+ *
+ * ── Horizontal mode 的 label 寬度 ───────────────────────────────────────
+ * 透過 labelWidth prop → --field-label-width CSS variable，可以是任何
+ * CSS length（"120px"、"10rem"、"30%" 等）。預設 "auto" 由 label 內容撐開。
+ *
+ * ── Required 星號 ──────────────────────────────────────────────────────
+ * Field 的 required prop 會透過 context 傳給 FieldLabel 自動渲染 *，
+ * 星號為 neutral-7（fg-muted），貼齊 label 文字（無 gap），disabled
+ * 時降為 fg-disabled。也可在個別 FieldLabel 覆寫。
+ */
+import type { FieldMode, FieldVariant, FieldOrientation, FieldSize, FieldControlLayout } from './field-context';
+export interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {
+    id?: string;
+    mode?: FieldMode;
+    /**
+     * 視覺外殼(2026-05-05)。
+     * - `default`(預設)— 含 border + bg(一般 form input)
+     * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)
+     *
+     * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。
+     */
+    variant?: FieldVariant;
+    orientation?: FieldOrientation;
+    size?: FieldSize;
+    required?: boolean;
+    disabled?: boolean;
+    invalid?: boolean;
+    /**
+     * Horizontal mode 的 label 欄寬度。支援任何 CSS length 值（"120px"、"10rem"、"30%"...）。
+     * 預設 'auto' 由 label 內容撐開。
+     */
+    labelWidth?: string;
+    /**
+     * Control area 佈局模型(逃生艙)。
+     *
+     * 預設由 Field 自動偵測——讀第一個 control child 的 `type.fieldLayout` static 屬性,
+     * primitive 沒宣告時視為 `'inline'`。
+     *
+     * 只有兩種情況需要手動指定:
+     * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`
+     * 2. 想覆寫 primitive 的預設(如把 RadioGroup 強制 inline 呈現,罕見)
+     */
+    controlLayout?: FieldControlLayout;
+}
+declare const Field: React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>>;
+export interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+    /**
+     * 強制渲染 required 星號（覆寫 Field context 的 required）。
+     * 若未設定，預設讀 context。
+     */
+    required?: boolean;
+    /**
+     * 在 label 文字後方顯示 info icon (ℹ)，hover 出現 tooltip 說明。
+     * 傳 string → tooltip 內容。
+     *
+     * Info icon 用 inline action pattern（補充工具，視覺退後），
+     * 因為 label 的 primary interaction 是 input，info 是補充說明。
+     */
+    info?: string;
+}
+declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps & React.RefAttributes<HTMLLabelElement>>;
+declare const FieldDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const FieldError: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+export interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Field 之間的垂直間距，預設 'normal'（gap-4） */
+    gap?: 'compact' | 'normal' | 'loose';
+    /**
+     * 同一 group 內所有 horizontal Field 共用的 label 欄寬度。
+     *
+     * 支援任何 CSS length(`"140px"` / `"10rem"` / `"30%"` 等)。預設不指定——
+     * 每個 Field 自動以 label 內容撐開(容易歪七扭八)。
+     *
+     * 世界級 idiom:macOS System Settings / iOS Settings / GitHub Settings 的
+     * setting list 一律 label 固定寬、control 右對齊,列與列整齊對齊。
+     *
+     * 單一 Field 可以用自己的 `labelWidth` prop 覆寫 cascade 值。
+     */
+    horizontalLabelWidth?: string;
+}
+declare const FieldGroup: React.ForwardRefExoticComponent<FieldGroupProps & React.RefAttributes<HTMLDivElement>>;
+export declare const fieldMeta: {
+    readonly component: "Field";
+    readonly family: null;
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "hover", "active", "focus-visible", "disabled"];
+    readonly tokens: {
+        readonly bg: readonly [];
+        readonly fg: readonly ["text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"];
+        readonly ring: readonly [];
+    };
+};
+export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup };
+//# sourceMappingURL=field.d.ts.map

package/dist/components/Field/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/Field/field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,gBAAgB,EAAE,SAAS,EAAE,kBAAkB,EAAqB,MAAM,iBAAiB,CAAA;AAqDlI,MAAM,WAAW,UAAW,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC;IAClF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAC9B,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAA;CACnC;AAWD,QAAA,MAAM,KAAK,mFA2JV,CAAA;AAKD,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,mBAAmB,CAAC,gBAAgB,CAAC;IAClF;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAGD,QAAA,MAAM,UAAU,0FA2Ff,CAAA;AAKD,QAAA,MAAM,gBAAgB,yHAsBpB,CAAA;AAKF,QAAA,MAAM,UAAU,yHAqBd,CAAA;AAOF,MAAM,WAAW,eAAgB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC3E,uCAAuC;IACvC,GAAG,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;IACpC;;;;;;;;;;OAUG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,QAAA,MAAM,UAAU,wFAkBf,CAAA;AAKD,eAAO,MAAM,SAAS;;;;;;;;;;;CAeZ,CAAA;AAEV,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,UAAU,EAAE,UAAU,EAAE,CAAA"}

package/dist/components/Field/field.js

@@ -0,0 +1,295 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Info } from "lucide-react";
+import { cn } from "../../lib/utils.js";
+import { Tooltip, TooltipTrigger, TooltipContent } from "../Tooltip/tooltip.js";
+import { FieldContext, useFieldContext } from "./field-context.js";
+const MIN_H_CLASS = {
+  sm: "min-h-field-sm",
+  md: "min-h-field-md",
+  lg: "min-h-field-lg"
+};
+const FIELD_HEIGHT_VAR = {
+  sm: "var(--field-height-sm)",
+  md: "var(--field-height-md)",
+  lg: "var(--field-height-lg)"
+};
+const FIELD_TEXT_CLASS = "text-body";
+function resolveSlotKind(node) {
+  var _a;
+  if (!React.isValidElement(node)) return "control";
+  const displayName = (_a = node.type) == null ? void 0 : _a.displayName;
+  if (displayName === "FieldLabel") return "label";
+  if (displayName === "FieldDescription") return "description";
+  if (displayName === "FieldError") return "error";
+  return "control";
+}
+function detectControlLayout(controlNodes) {
+  var _a;
+  for (const node of controlNodes) {
+    if (!React.isValidElement(node)) continue;
+    const layout = (_a = node.type) == null ? void 0 : _a.fieldLayout;
+    if (layout === "block") return "block";
+  }
+  return "inline";
+}
+const FieldGroupContext = React.createContext({});
+const Field = React.forwardRef(
+  ({
+    id: idProp,
+    mode = "edit",
+    variant = "default",
+    orientation = "vertical",
+    size = "md",
+    required = false,
+    disabled: disabledProp = false,
+    invalid = false,
+    labelWidth,
+    controlLayout: controlLayoutProp,
+    className,
+    style,
+    children,
+    ...props
+  }, ref) => {
+    const generatedId = React.useId();
+    const id = idProp ?? generatedId;
+    const labelId = `${id}-label`;
+    const descriptionId = `${id}-description`;
+    const errorId = `${id}-error`;
+    const groupCtx = React.useContext(FieldGroupContext);
+    const effectiveLabelWidth = labelWidth ?? groupCtx.horizontalLabelWidth;
+    const disabled = disabledProp || mode === "disabled";
+    const labelNodes = [];
+    const controlNodes = [];
+    const descriptionNodes = [];
+    const errorNodes = [];
+    React.Children.forEach(children, (child) => {
+      const slot = resolveSlotKind(child);
+      if (slot === "label") labelNodes.push(child);
+      else if (slot === "description") descriptionNodes.push(child);
+      else if (slot === "error") errorNodes.push(child);
+      else controlNodes.push(child);
+    });
+    const controlLayout = controlLayoutProp ?? detectControlLayout(controlNodes);
+    const contextValue = React.useMemo(
+      () => ({
+        id,
+        labelId,
+        descriptionId,
+        errorId,
+        mode,
+        variant,
+        disabled,
+        required,
+        invalid,
+        size,
+        orientation,
+        controlLayout,
+        hasFieldWrapper: true
+      }),
+      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]
+    );
+    const controlArea = controlLayout === "block" ? /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "flex flex-col items-start min-w-0",
+        "data-field-slot": "control",
+        "data-field-control-layout": "block",
+        children: controlNodes
+      }
+    ) : /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: cn("flex items-center min-w-0", MIN_H_CLASS[size]),
+        "data-field-slot": "control",
+        "data-field-control-layout": "inline",
+        children: controlNodes
+      }
+    );
+    if (orientation === "horizontal") {
+      return /* @__PURE__ */ jsx(FieldContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxs(
+        "div",
+        {
+          ref,
+          className: cn("grid gap-x-3 items-start", className),
+          style: {
+            gridTemplateColumns: "var(--field-label-width, auto) minmax(0, 1fr)",
+            ...effectiveLabelWidth !== void 0 ? { ["--field-label-width"]: effectiveLabelWidth } : void 0,
+            ...style
+          },
+          "data-field-orientation": "horizontal",
+          "data-field-mode": mode,
+          "data-field-size": size,
+          "data-field-disabled": disabled ? "" : void 0,
+          "data-field-invalid": invalid ? "" : void 0,
+          ...props,
+          children: [
+            labelNodes,
+            /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-1 min-w-0", children: [
+              controlArea,
+              descriptionNodes,
+              errorNodes
+            ] })
+          ]
+        }
+      ) });
+    }
+    return /* @__PURE__ */ jsx(FieldContext.Provider, { value: contextValue, children: /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ref,
+        className: cn("flex flex-col gap-1 min-w-0", className),
+        style,
+        "data-field-orientation": "vertical",
+        "data-field-mode": mode,
+        "data-field-size": size,
+        "data-field-disabled": disabled ? "" : void 0,
+        "data-field-invalid": invalid ? "" : void 0,
+        ...props,
+        children: [
+          labelNodes,
+          controlArea,
+          descriptionNodes,
+          errorNodes
+        ]
+      }
+    ) });
+  }
+);
+Field.displayName = "Field";
+const FieldLabel = React.forwardRef(
+  ({ className, required: requiredProp, info, htmlFor: htmlForProp, style, children, ...props }, ref) => {
+    const ctx = useFieldContext();
+    const required = requiredProp ?? (ctx == null ? void 0 : ctx.required) ?? false;
+    const disabled = (ctx == null ? void 0 : ctx.disabled) ?? false;
+    const htmlFor = htmlForProp ?? (ctx == null ? void 0 : ctx.id);
+    const isHorizontal = (ctx == null ? void 0 : ctx.orientation) === "horizontal";
+    const controlLayout = (ctx == null ? void 0 : ctx.controlLayout) ?? "inline";
+    const size = (ctx == null ? void 0 : ctx.size) ?? "md";
+    const horizontalInlineClass = isHorizontal && controlLayout === "inline" ? cn("flex flex-col justify-center", MIN_H_CLASS[size]) : void 0;
+    const horizontalBlockStyle = isHorizontal && controlLayout === "block" ? { paddingTop: `calc((${FIELD_HEIGHT_VAR[size]} - 1lh) / 2)` } : void 0;
+    return /* @__PURE__ */ jsx(
+      "label",
+      {
+        ref,
+        id: ctx == null ? void 0 : ctx.labelId,
+        htmlFor,
+        className: cn(
+          FIELD_TEXT_CLASS,
+          "font-normal select-none",
+          disabled ? "text-fg-disabled" : "text-foreground",
+          horizontalInlineClass,
+          className
+        ),
+        style: { ...horizontalBlockStyle, ...style },
+        "data-field-slot": "label",
+        "data-field-disabled": disabled ? "" : void 0,
+        ...props,
+        children: /* @__PURE__ */ jsxs("span", { className: "inline-flex items-center gap-1", children: [
+          /* @__PURE__ */ jsxs("span", { children: [
+            required && /* @__PURE__ */ jsx(
+              "span",
+              {
+                "aria-hidden": "true",
+                className: disabled ? "text-fg-disabled" : "text-fg-muted",
+                children: "*"
+              }
+            ),
+            children
+          ] }),
+          info && !disabled && /* @__PURE__ */ jsxs(Tooltip, { children: [
+            /* @__PURE__ */ jsx(TooltipTrigger, { asChild: true, children: /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                "aria-label": info,
+                className: "inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer",
+                children: /* @__PURE__ */ jsx(Info, { size: 16, "aria-hidden": true })
+              }
+            ) }),
+            /* @__PURE__ */ jsx(TooltipContent, { children: info })
+          ] })
+        ] })
+      }
+    );
+  }
+);
+FieldLabel.displayName = "FieldLabel";
+const FieldDescription = React.forwardRef(({ className, children, id: idProp, ...props }, ref) => {
+  const ctx = useFieldContext();
+  const disabled = (ctx == null ? void 0 : ctx.disabled) ?? false;
+  return /* @__PURE__ */ jsx(
+    "p",
+    {
+      ref,
+      id: idProp ?? (ctx == null ? void 0 : ctx.descriptionId),
+      className: cn(
+        FIELD_TEXT_CLASS,
+        disabled ? "text-fg-disabled" : "text-fg-secondary",
+        className
+      ),
+      "data-field-slot": "description",
+      ...props,
+      children
+    }
+  );
+});
+FieldDescription.displayName = "FieldDescription";
+const FieldError = React.forwardRef(({ className, children, id: idProp, ...props }, ref) => {
+  const ctx = useFieldContext();
+  if (children == null || children === false || children === "") return null;
+  return /* @__PURE__ */ jsx(
+    "p",
+    {
+      ref,
+      id: idProp ?? (ctx == null ? void 0 : ctx.errorId),
+      className: cn(FIELD_TEXT_CLASS, "text-error-text", className),
+      "data-field-slot": "error",
+      role: "alert",
+      ...props,
+      children
+    }
+  );
+});
+FieldError.displayName = "FieldError";
+const FieldGroup = React.forwardRef(
+  ({ className, gap = "normal", horizontalLabelWidth, ...props }, ref) => {
+    const gapClass = gap === "compact" ? "gap-3" : gap === "loose" ? "gap-6" : "gap-4";
+    const groupCtxValue = React.useMemo(
+      () => ({ horizontalLabelWidth }),
+      [horizontalLabelWidth]
+    );
+    return /* @__PURE__ */ jsx(FieldGroupContext.Provider, { value: groupCtxValue, children: /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        className: cn("flex flex-col min-w-0", gapClass, className),
+        "data-field-group": "",
+        ...props
+      }
+    ) });
+  }
+);
+FieldGroup.displayName = "FieldGroup";
+const fieldMeta = {
+  component: "Field",
+  family: null,
+  // non-family composite / overlay / layout
+  variants: {},
+  sizes: {},
+  states: ["default", "hover", "active", "focus-visible", "disabled"],
+  tokens: {
+    bg: [],
+    fg: ["text-error-text", "text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"],
+    ring: []
+  }
+};
+export {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  fieldMeta
+};
+//# sourceMappingURL=field.js.map

package/dist/components/Field/field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.js","sources":["../../../src/components/Field/field.tsx"],"sourcesContent":["// code-quality-allow: file-size — foundational composite(Field + FieldLabel + FieldDescription + FieldError + context + 8 layout variants),拆檔會讓 Field 家族互相 import 循環\nimport * as React from 'react'\nimport { Info as InfoIcon } from 'lucide-react'\nimport { cn } from '@/lib/utils'\nimport { Tooltip, TooltipTrigger, TooltipContent } from '@/design-system/components/Tooltip/tooltip'\n\n/**\n * Field — 表單欄位佈局容器（shadcn Field 風格）\n *\n * ── 定位 ────────────────────────────────────────────────────────────────\n * Field 只負責 **佈局 + 狀態 context**，不擁有任何資料型別邏輯。\n * 每個資料型別對應的 Control（Input、NumberInput、Checkbox、Switch 等）\n * 維持自己的 edit / readonly / disabled 三態，Field 透過 context 把\n * mode / disabled / required / invalid / id 傳給子元件，由子元件決定\n * 如何反映。\n *\n * ── 結構 ────────────────────────────────────────────────────────────────\n *   <Field orientation=\"vertical | horizontal\" labelWidth=\"120px\">\n *     <FieldLabel>姓名</FieldLabel>\n *     <Input value={...} onChange={...} />         ← Control（任何非 label/desc/error 的 child）\n *     <FieldDescription>...</FieldDescription>\n *     <FieldError>{errors.name}</FieldError>\n *   </Field>\n *\n *   Control 會自動包在 control area slot（min-h-field-* + items-center），\n *   確保 Checkbox / Switch / Radio 等高度 < field-height 的 primitive\n *   垂直對齊 Input 中線；Input 等自身為 field-height 的 primitive 填滿。\n *\n * ── Horizontal mode 的 label 垂直對齊 ───────────────────────────────────\n * FieldLabel 在 horizontal 模式下使用公式：\n *     padding-top: calc((var(--field-height-{size}) - 1lh) / 2)\n *\n * 單行 label → 文字第一行與 input 中線對齊（視覺置中）\n * 多行 label → 第一行仍與 input 中線對齊，其餘行往下流（label 高度超過\n *              input 時視覺上仍保持與 input 內容同一基準線）\n *\n * 此公式 tracks field-height 和 line-height 的變動，size 切換或字體\n * 調整時自動連動，不需 JS 測量。\n *\n * ── Horizontal mode 的 label 寬度 ───────────────────────────────────────\n * 透過 labelWidth prop → --field-label-width CSS variable，可以是任何\n * CSS length（\"120px\"、\"10rem\"、\"30%\" 等）。預設 \"auto\" 由 label 內容撐開。\n *\n * ── Required 星號 ──────────────────────────────────────────────────────\n * Field 的 required prop 會透過 context 傳給 FieldLabel 自動渲染 *，\n * 星號為 neutral-7（fg-muted），貼齊 label 文字（無 gap），disabled\n * 時降為 fg-disabled。也可在個別 FieldLabel 覆寫。\n */\n\n// ── Types & Context ──\n// Context 定義在 field-context.ts(打斷 circular import)。\n// field.tsx 只 import 不 re-export——consumer 直接從 field-context.ts import useFieldContext。\n\nimport type { FieldMode, FieldVariant, FieldOrientation, FieldSize, FieldControlLayout, FieldContextValue } from './field-context'\nimport { FieldContext, useFieldContext } from './field-context'\n\n// ── Internal helpers ────────────────────────────────────────────────────────\n\nconst MIN_H_CLASS: Record<FieldSize, string> = {\n  sm: 'min-h-field-sm',\n  md: 'min-h-field-md',\n  lg: 'min-h-field-lg',\n}\n\nconst FIELD_HEIGHT_VAR: Record<FieldSize, string> = {\n  sm: 'var(--field-height-sm)',\n  md: 'var(--field-height-md)',\n  lg: 'var(--field-height-lg)',\n}\n\n// Label / Description / Error 的字體固定 text-body (14px)，不隨 field size 變。\n// 世界級共識：field size 只影響 input 高度，不影響表單佈局元素的 typography。\nconst FIELD_TEXT_CLASS = 'text-body'\n\ntype SlotKind = 'label' | 'description' | 'error' | 'control'\n\nfunction resolveSlotKind(node: React.ReactNode): SlotKind {\n  if (!React.isValidElement(node)) return 'control'\n  const displayName = (node.type as { displayName?: string } | null | undefined)?.displayName\n  if (displayName === 'FieldLabel') return 'label'\n  if (displayName === 'FieldDescription') return 'description'\n  if (displayName === 'FieldError') return 'error'\n  return 'control'\n}\n\n/**\n * 偵測 control children 的 fieldLayout——任一 control 宣告為 'block' 即整個 area 切 block 模式。\n *\n * Convention：block primitive 在自己的元件檔案掛 static `fieldLayout = 'block'` 屬性,\n * Field 在 render 時讀 `child.type.fieldLayout`。預設 'inline'。\n *\n * 為什麼是「任一」而非「全部」：實務上 Field 一個 control area 通常只有一個 control,\n * 但若 consumer 同時放多個 child(例如 RadioGroup + 一段補充文字節點),只要其中有 block\n * primitive,整個 area 就應該以 block 模式佈局,確保第一行對齊正確。\n */\nfunction detectControlLayout(controlNodes: React.ReactNode[]): FieldControlLayout {\n  for (const node of controlNodes) {\n    if (!React.isValidElement(node)) continue\n    const layout = (node.type as { fieldLayout?: FieldControlLayout } | null | undefined)?.fieldLayout\n    if (layout === 'block') return 'block'\n  }\n  return 'inline'\n}\n\n// ── Field ───────────────────────────────────────────────────────────────────\n\nexport interface FieldProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'id'> {\n  id?: string\n  mode?: FieldMode\n  /**\n   * 視覺外殼(2026-05-05)。\n   * - `default`(預設)— 含 border + bg(一般 form input)\n   * - `bare` — 透明 variant,hover/focus reveal(cell-as-input substrate;VS Code/Figma toolbar idiom)\n   *\n   * 透傳機制:Field 一次宣告,所有 child Field control 自動繼承(per-control prop override 可覆寫)。\n   */\n  variant?: FieldVariant\n  orientation?: FieldOrientation\n  size?: FieldSize\n  required?: boolean\n  disabled?: boolean\n  invalid?: boolean\n  /**\n   * Horizontal mode 的 label 欄寬度。支援任何 CSS length 值（\"120px\"、\"10rem\"、\"30%\"...）。\n   * 預設 'auto' 由 label 內容撐開。\n   */\n  labelWidth?: string\n  /**\n   * Control area 佈局模型(逃生艙)。\n   *\n   * 預設由 Field 自動偵測——讀第一個 control child 的 `type.fieldLayout` static 屬性,\n   * primitive 沒宣告時視為 `'inline'`。\n   *\n   * 只有兩種情況需要手動指定:\n   * 1. consumer 把自己手寫的 JSX(`<div>` / 函式元件)當 control,系統無法偵測——強制 `'block'`\n   * 2. 想覆寫 primitive 的預設(如把 RadioGroup 強制 inline 呈現,罕見)\n   */\n  controlLayout?: FieldControlLayout\n}\n\n// ── FieldGroup Context(cascade horizontal labelWidth)──\n// 同一畫面多個 horizontal Field,label 寬度應統一對齊 → FieldGroup 提供 SSOT。\n// 下面 Field 組件自動 consume,consumer 可用 Field 的 labelWidth prop 覆寫單行。\ninterface FieldGroupContextValue {\n  horizontalLabelWidth?: string\n}\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FieldGroupContext = React.createContext<FieldGroupContextValue>({})\n\nconst Field = React.forwardRef<HTMLDivElement, FieldProps>(\n  (\n    {\n      id: idProp,\n      mode = 'edit',\n      variant = 'default',\n      orientation = 'vertical',\n      size = 'md',\n      required = false,\n      disabled: disabledProp = false,\n      invalid = false,\n      labelWidth,\n      controlLayout: controlLayoutProp,\n      className,\n      style,\n      children,\n      ...props\n    },\n    ref\n  ) => {\n    const generatedId = React.useId()\n    const id = idProp ?? generatedId\n    const labelId = `${id}-label`\n    const descriptionId = `${id}-description`\n    const errorId = `${id}-error`\n\n    // FieldGroup cascade:group 的 horizontalLabelWidth 是 fallback,單行 labelWidth 覆寫\n    const groupCtx = React.useContext(FieldGroupContext)\n    const effectiveLabelWidth = labelWidth ?? groupCtx.horizontalLabelWidth\n\n    // mode=disabled 與 disabled prop 任一為 true 即視為 disabled\n    const disabled = disabledProp || mode === 'disabled'\n\n    // 把 children 依 slot 類型分組\n    const labelNodes: React.ReactNode[] = []\n    const controlNodes: React.ReactNode[] = []\n    const descriptionNodes: React.ReactNode[] = []\n    const errorNodes: React.ReactNode[] = []\n\n    React.Children.forEach(children, (child) => {\n      const slot = resolveSlotKind(child)\n      if (slot === 'label') labelNodes.push(child)\n      else if (slot === 'description') descriptionNodes.push(child)\n      else if (slot === 'error') errorNodes.push(child)\n      else controlNodes.push(child)\n    })\n\n    // 解析 control layout：consumer 顯式指定 > primitive 自我宣告 > 預設 inline\n    const controlLayout: FieldControlLayout =\n      controlLayoutProp ?? detectControlLayout(controlNodes)\n\n    const contextValue = React.useMemo<FieldContextValue>(\n      () => ({\n        id,\n        labelId,\n        descriptionId,\n        errorId,\n        mode,\n        variant,\n        disabled,\n        required,\n        invalid,\n        size,\n        orientation,\n        controlLayout,\n        hasFieldWrapper: true,\n      }),\n      [id, labelId, descriptionId, errorId, mode, variant, disabled, required, invalid, size, orientation, controlLayout]\n    )\n\n    // Control area：兩種佈局模型,「第一行內容中線」都錨在 field-height/2,\n    // 跟 FieldLabel 在 horizontal 模式下的 padding-top 公式自然對齊。\n    //\n    // - inline: min-h-field-{size} + items-center\n    //   單行 control(Input、Button 等)中線置中於 min-h box。\n    //\n    // - block:  flex-col + items-start + padding-top: calc((field-height - 1lh) / 2)\n    //   多行 control(RadioGroup 等),第一行往下推到 field-height 中線,\n    //   後續 item 自然往下流。不設 min-h(內容自己決定高度)。\n    // Block control area 不加額外 paddingTop——block primitive(RadioGroup 等)\n    // 的子元件(SelectionItem)已自帶 py = calc((field-height - 1lh) / 2),\n    // 第一個 item 的文字自然落在 field-height/2。額外加 paddingTop 會 double padding。\n    const controlArea =\n      controlLayout === 'block' ? (\n        <div\n          className=\"flex flex-col items-start min-w-0\"\n          data-field-slot=\"control\"\n          data-field-control-layout=\"block\"\n        >\n          {controlNodes}\n        </div>\n      ) : (\n        <div\n          className={cn('flex items-center min-w-0', MIN_H_CLASS[size])}\n          data-field-slot=\"control\"\n          data-field-control-layout=\"inline\"\n        >\n          {controlNodes}\n        </div>\n      )\n\n    // Horizontal：grid 兩欄，label 在左、content 欄堆疊（control → description → error）\n    if (orientation === 'horizontal') {\n      return (\n        <FieldContext.Provider value={contextValue}>\n          <div\n            ref={ref}\n            className={cn('grid gap-x-3 items-start', className)}\n            style={{\n              gridTemplateColumns: 'var(--field-label-width, auto) minmax(0, 1fr)',\n              ...(effectiveLabelWidth !== undefined\n                ? ({ ['--field-label-width' as string]: effectiveLabelWidth } as React.CSSProperties)\n                : undefined),\n              ...style,\n            }}\n            data-field-orientation=\"horizontal\"\n            data-field-mode={mode}\n            data-field-size={size}\n            data-field-disabled={disabled ? '' : undefined}\n            data-field-invalid={invalid ? '' : undefined}\n            {...props}\n          >\n            {labelNodes}\n            <div className=\"flex flex-col gap-1 min-w-0\">\n              {controlArea}\n              {descriptionNodes}\n              {errorNodes}\n            </div>\n          </div>\n        </FieldContext.Provider>\n      )\n    }\n\n    // Vertical（預設）：單欄 flex-col\n    return (\n      <FieldContext.Provider value={contextValue}>\n        <div\n          ref={ref}\n          className={cn('flex flex-col gap-1 min-w-0', className)}\n          style={style}\n          data-field-orientation=\"vertical\"\n          data-field-mode={mode}\n          data-field-size={size}\n          data-field-disabled={disabled ? '' : undefined}\n          data-field-invalid={invalid ? '' : undefined}\n          {...props}\n        >\n          {labelNodes}\n          {controlArea}\n          {descriptionNodes}\n          {errorNodes}\n        </div>\n      </FieldContext.Provider>\n    )\n  }\n)\nField.displayName = 'Field'\n\n// ── FieldLabel ──────────────────────────────────────────────────────────────\n\nexport interface FieldLabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {\n  /**\n   * 強制渲染 required 星號（覆寫 Field context 的 required）。\n   * 若未設定，預設讀 context。\n   */\n  required?: boolean\n  /**\n   * 在 label 文字後方顯示 info icon (ℹ)，hover 出現 tooltip 說明。\n   * 傳 string → tooltip 內容。\n   *\n   * Info icon 用 inline action pattern（補充工具，視覺退後），\n   * 因為 label 的 primary interaction 是 input，info 是補充說明。\n   */\n  info?: string\n}\n\n// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding\nconst FieldLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(\n  ({ className, required: requiredProp, info, htmlFor: htmlForProp, style, children, ...props }, ref) => {\n    const ctx = useFieldContext()\n    const required = requiredProp ?? ctx?.required ?? false\n    const disabled = ctx?.disabled ?? false\n    const htmlFor = htmlForProp ?? ctx?.id\n    const isHorizontal = ctx?.orientation === 'horizontal'\n    const controlLayout = ctx?.controlLayout ?? 'inline'\n    const size: FieldSize = ctx?.size ?? 'md'\n\n    // Horizontal 模式對齊策略 — 依 controlLayout 分兩套 (CSS-only, 不需 JS 測量)\n    //\n    // ── Inline control (Input / Button / Switch / SegmentedControl) ──\n    //   Control 有固定單行高度 = field-height,可以對齊中線。\n    //   策略: min-h-field-{size} + flex flex-col + justify-content: center\n    //\n    //   1) 短 label (總高 ≤ field-height):\n    //      min-h 生效 → 容器 = field-height → justify-center 把 label 垂直置中\n    //      第一行 top = (field-height - 1lh)/2 → 第一行中線對齊 control 中線 ✓\n    //   2) 長 label (總高 > field-height):\n    //      min-h 被內容撐大 → 容器 = label 總高 → justify-center 無作用(內容已填滿)\n    //      第一行 top = 0 → label top 對齊 control top ✓\n    //\n    // ── Block control (RadioGroup / CheckboxGroup) ──\n    //   Control 是多行群組,沒有「整體中線」可以對齊;錨點是「第一個 item 的第一行\n    //   中線永遠在 field-height/2」,由 SelectionItem 的 py 維持。\n    //   策略: padding-top = (field-height - 1lh)/2 — 把 label 第一行推到同樣位置。\n    //\n    //   這個策略對任何 label 長度都正確:label 第一行永遠與第一個 item 第一行對齊,\n    //   label 超出 control 時往下流(因為 block control 通常本來就很高,不會有\n    //   inline 模式那種「label 比 control 高」的視覺問題)。\n    //\n    // 內層 <span>: 只有 inline 策略需要(flex-col 會把 * 星號和 label 文字縱向堆疊,\n    // 必須包一層讓兩者 inline 同行)。block 策略可以不包,但為了 DOM 一致性一律包。\n    const horizontalInlineClass =\n      isHorizontal && controlLayout === 'inline'\n        ? cn('flex flex-col justify-center', MIN_H_CLASS[size])\n        : undefined\n\n    const horizontalBlockStyle: React.CSSProperties | undefined =\n      isHorizontal && controlLayout === 'block'\n        ? { paddingTop: `calc((${FIELD_HEIGHT_VAR[size]} - 1lh) / 2)` }\n        : undefined\n\n    return (\n      <label\n        ref={ref}\n        id={ctx?.labelId}\n        htmlFor={htmlFor}\n        className={cn(\n          FIELD_TEXT_CLASS,\n          'font-normal select-none',\n          disabled ? 'text-fg-disabled' : 'text-foreground',\n          horizontalInlineClass,\n          className\n        )}\n        style={{ ...horizontalBlockStyle, ...style }}\n        data-field-slot=\"label\"\n        data-field-disabled={disabled ? '' : undefined}\n        {...props}\n      >\n        <span className=\"inline-flex items-center gap-1\">\n          <span>\n            {required && (\n              <span\n                aria-hidden=\"true\"\n                className={disabled ? 'text-fg-disabled' : 'text-fg-muted'}\n              >\n                *\n              </span>\n            )}\n            {children}\n          </span>\n          {info && !disabled && (\n            <Tooltip>\n              <TooltipTrigger asChild>\n                <button\n                  type=\"button\"\n                  aria-label={info}\n                  className=\"inline-flex items-center text-fg-muted hover:text-fg-secondary bg-transparent border-0 p-0 cursor-pointer\"\n                >\n                  <InfoIcon size={16} aria-hidden />\n                </button>\n              </TooltipTrigger>\n              <TooltipContent>{info}</TooltipContent>\n            </Tooltip>\n          )}\n        </span>\n      </label>\n    )\n  }\n)\nFieldLabel.displayName = 'FieldLabel'\n\n// ── FieldDescription ────────────────────────────────────────────────────────\n\nconst FieldDescription = React.forwardRef<\n  HTMLParagraphElement,\n  React.HTMLAttributes<HTMLParagraphElement>\n>(({ className, children, id: idProp, ...props }, ref) => {\n  const ctx = useFieldContext()\n  const disabled = ctx?.disabled ?? false\n\n  return (\n    <p\n      ref={ref}\n      id={idProp ?? ctx?.descriptionId}\n      className={cn(\n        FIELD_TEXT_CLASS,\n        disabled ? 'text-fg-disabled' : 'text-fg-secondary',\n        className\n      )}\n      data-field-slot=\"description\"\n      {...props}\n    >\n      {children}\n    </p>\n  )\n})\nFieldDescription.displayName = 'FieldDescription'\n\n// ── FieldError ──────────────────────────────────────────────────────────────\n\nconst FieldError = React.forwardRef<\n  HTMLParagraphElement,\n  React.HTMLAttributes<HTMLParagraphElement>\n>(({ className, children, id: idProp, ...props }, ref) => {\n  const ctx = useFieldContext()\n\n  // 無內容不渲染，避免空殼佔位\n  if (children == null || children === false || children === '') return null\n\n  return (\n    <p\n      ref={ref}\n      id={idProp ?? ctx?.errorId}\n      className={cn(FIELD_TEXT_CLASS, 'text-error-text', className)}\n      data-field-slot=\"error\"\n      role=\"alert\"\n      {...props}\n    >\n      {children}\n    </p>\n  )\n})\nFieldError.displayName = 'FieldError'\n\n// ── FieldGroup ──────────────────────────────────────────────────────────────\n// 垂直堆疊多個 Field，共用 gap 節奏。\n// 用於表單中多個欄位排列。\n\nexport interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {\n  /** Field 之間的垂直間距，預設 'normal'（gap-4） */\n  gap?: 'compact' | 'normal' | 'loose'\n  /**\n   * 同一 group 內所有 horizontal Field 共用的 label 欄寬度。\n   *\n   * 支援任何 CSS length(`\"140px\"` / `\"10rem\"` / `\"30%\"` 等)。預設不指定——\n   * 每個 Field 自動以 label 內容撐開(容易歪七扭八)。\n   *\n   * 世界級 idiom:macOS System Settings / iOS Settings / GitHub Settings 的\n   * setting list 一律 label 固定寬、control 右對齊,列與列整齊對齊。\n   *\n   * 單一 Field 可以用自己的 `labelWidth` prop 覆寫 cascade 值。\n   */\n  horizontalLabelWidth?: string\n}\n\nconst FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(\n  ({ className, gap = 'normal', horizontalLabelWidth, ...props }, ref) => {\n    const gapClass = gap === 'compact' ? 'gap-3' : gap === 'loose' ? 'gap-6' : 'gap-4'\n    const groupCtxValue = React.useMemo(\n      () => ({ horizontalLabelWidth }),\n      [horizontalLabelWidth],\n    )\n    return (\n      <FieldGroupContext.Provider value={groupCtxValue}>\n        <div\n          ref={ref}\n          className={cn('flex flex-col min-w-0', gapClass, className)}\n          data-field-group=\"\"\n          {...props}\n        />\n      </FieldGroupContext.Provider>\n    )\n  }\n)\nFieldGroup.displayName = 'FieldGroup'\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 fieldMeta = {\n  component: 'Field',\n  family: null, // non-family composite / overlay / layout\n  variants: {\n\n  },\n  sizes: {\n\n  },\n  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],\n  tokens: {\n    bg: [],\n    fg: ['text-error-text', 'text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],\n    ring: [],\n  },\n} as const\n\nexport { Field, FieldLabel, FieldDescription, FieldError, FieldGroup }\n"],"names":["InfoIcon"],"mappings":"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"}

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

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

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

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

package/dist/components/Field/index.js

@@ -0,0 +1,10 @@
+import { Field, FieldDescription, FieldError, FieldGroup, FieldLabel, fieldMeta } from "./field.js";
+export {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  fieldMeta
+};
+//# sourceMappingURL=index.js.map

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

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

package/dist/components/FieldControlGroup/field-control-group.d.ts

@@ -0,0 +1,74 @@
+import * as React from 'react';
+import type { FieldSize } from '../../components/Field/field-context';
+/**
+ * FieldControlGroup — 多個 Field controls 視覺接合成一個 input frame
+ *
+ * **Naming rationale**(2026-05-04):
+ * - Taxonomic 一致:FieldGroup(多 Field 堆疊)/ FieldControlGroup(多 control 接合)— scope 區分
+ * - Idiom 一致:ButtonGroup(多 Button 接合)同 pattern,只是 X = field control
+ * - 不撞 RadioGroup/CheckboxGroup(那是 1-question 多 options semantic group)
+ *
+ * **Behavior canonical**(verified Ant compact-item.ts L21-58):
+ * - 子 controls 保留自身 border + radius;不 strip
+ * - 鄰接子用負 margin 重疊 border(Bootstrap 也用此手法 但用 z-index 確保 focus 在最上層)
+ * - first child 只留左 radii / last child 只留右 radii / middle 全 0 radii
+ * - z-index:default 2 / hover|focus|focus-within 3 / disabled 0
+ * - Container `display: inline-flex`(Ant default)/ `block` prop → `display: flex; width: 100%`
+ *
+ * **Size cascade**(對齊 Field family):
+ * - `size` prop default = md;cascade 到 children via implicit context inheritance(children 自管 size 或繼承 useFieldContext)
+ * - Mode A:整個 FieldControlGroup 包進 Field 當 control slot,size 自動從 Field context 來
+ * - Mode B:standalone 用,size 由 prop 控制
+ *
+ * **Width 配置**(Ant Space.Compact W-A canonical):
+ * - 子 controls 自管 width(`className="w-[140px]"` / `style={{width:120}}` / `flex-1` etc.)
+ * - FieldControlGroup 不另開 Cell wrapper(避免 indirection,符合 Ant idiom)
+ *
+ * **使用範例**:
+ * ```tsx
+ * // Filter row: 2 fixed select + 1 flex value
+ * <FieldControlGroup>
+ *   <Select className="w-[140px]" options={fields} />
+ *   <Select className="w-[120px]" options={ops} />
+ *   <Input className="flex-1" placeholder="輸入值..." />
+ * </FieldControlGroup>
+ *
+ * // Phone: country code + number
+ * <Field>
+ *   <FieldLabel>電話</FieldLabel>
+ *   <FieldControlGroup>
+ *     <Select className="w-[80px]" options={codes} />
+ *     <Input className="flex-1" />
+ *   </FieldControlGroup>
+ * </Field>
+ *
+ * // Search + button
+ * <FieldControlGroup>
+ *   <Input className="flex-1" />
+ *   <Button variant="primary">搜尋</Button>
+ * </FieldControlGroup>
+ * ```
+ */
+export interface FieldControlGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Children size cascade(Mode B);Mode A 從 Field context 來 */
+    size?: FieldSize;
+    /** Block 模式:width 100% 撐滿 parent(對齊 Ant Space.Compact `block` prop) */
+    block?: boolean;
+}
+declare const FieldControlGroup: React.ForwardRefExoticComponent<FieldControlGroupProps & React.RefAttributes<HTMLDivElement>>;
+export declare const fieldControlGroupMeta: {
+    readonly component: "FieldControlGroup";
+    readonly family: "self-contained";
+    readonly variants: {};
+    readonly sizes: {};
+    readonly states: readonly ["default", "children-hover", "children-focus", "children-disabled"];
+    readonly tokens: {
+        readonly bg: readonly [];
+        readonly fg: readonly [];
+        readonly border: readonly ["var(--border-opaque)"];
+    };
+    readonly defaultVariant: undefined;
+    readonly defaultSize: undefined;
+};
+export { FieldControlGroup };
+//# sourceMappingURL=field-control-group.d.ts.map

package/dist/components/FieldControlGroup/field-control-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-control-group.d.ts","sourceRoot":"","sources":["../../../src/components/FieldControlGroup/field-control-group.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gDAAgD,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,WAAW,sBAAuB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAClF,6DAA6D;IAC7D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,QAAA,MAAM,iBAAiB,+FA0CtB,CAAA;AAQD,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;CAaxB,CAAA;AAEV,OAAO,EAAE,iBAAiB,EAAE,CAAA"}

package/dist/components/FieldControlGroup/field-control-group.js

@@ -0,0 +1,62 @@
+import { jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+const FieldControlGroup = React.forwardRef(
+  ({ size: _size = "md", block = false, className, children, ...props }, ref) => {
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref,
+        className: cn(
+          block ? "flex w-full" : "inline-flex",
+          "items-stretch",
+          // z-index baseline + active layer
+          "[&>*]:relative [&>*]:z-[2]",
+          "[&>*:hover]:z-[3] [&>*:focus]:z-[3] [&>*:focus-within]:z-[3]",
+          "[&>*[disabled]]:z-0 [&>*:has([disabled])]:z-0",
+          // border overlap
+          "[&>*+*]:-ml-px",
+          // border radius — 中間 0,首/尾保留外側 radii
+          "[&>*:not(:first-child):not(:last-child)]:rounded-none",
+          "[&>*:first-child:not(:last-child)]:rounded-r-none",
+          "[&>*:last-child:not(:first-child)]:rounded-l-none",
+          // K12 fix(2026-05-04 v7 — semantic token):FCG 內 disabled cell border 用 `--border-opaque`:
+          //   ✓ 保留 global `bg-disabled`(neutral-2 灰底)— disabled state 視覺主要承載
+          //   ✓ 用 SEMANTIC `--border-opaque`(視覺等同 --border 但不跟 bg compositing)
+          //   v6 直接消費 primitive `--color-neutral-5-opaque` 違反 token 4 規則「禁 primitive 色名作 utility」,
+          //   v7 升 semantic alias `--border-opaque` 在 semantic.css(其 primitive 後盾仍是 neutral-5-opaque)
+          //   → 對齊 Ant Design colorBorderSecondary solid idiom(table 外框 / row divider 用 solid,跟 input alpha border 視覺層級分)
+          //   → 解決 alpha border 在 grey bg 上 composite 略深 perception(physical 對比問題)
+          '[&>*[data-field-mode="disabled"]]:border-[var(--border-opaque)]',
+          className
+        ),
+        "data-field-control-group": "",
+        ...props,
+        children
+      }
+    );
+  }
+);
+FieldControlGroup.displayName = "FieldControlGroup";
+const fieldControlGroupMeta = {
+  component: "FieldControlGroup",
+  family: "self-contained",
+  variants: {},
+  sizes: {},
+  // self-contained wrapper, sizes cascade to children only
+  states: ["default", "children-hover", "children-focus", "children-disabled"],
+  tokens: {
+    bg: [],
+    // structural wrapper has no own bg
+    fg: [],
+    border: ["var(--border-opaque)"]
+    // K12 disabled cell border
+  },
+  defaultVariant: void 0,
+  defaultSize: void 0
+};
+export {
+  FieldControlGroup,
+  fieldControlGroupMeta
+};
+//# sourceMappingURL=field-control-group.js.map