@manohub/ui 0.7.0 → 0.8.0

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

@@ -4,6 +4,33 @@ import { type Padding } from '../part-padding';
 export type FormPadding = Padding;
 /** label 列的水平对齐：`right`（默认，与 farris / 主流水平表单一致）或 `left` */
 export type FormLabelAlign = 'left' | 'right';
+/**
+ * 字段行的排布档：
+ *
+ * - `1`（默认）：逐行；
+ * - `2 ~ 6`：**列数上限** —— 容器放得下 N 列就并排，放不下**少排一列**（不会把控件压成窄条）。
+ *   高列数（5 / 6）在默认最小宽 320 下要容器 1632 / 1960px 才排得出来，普通表单页用不到 ——
+ *   留着它是给「宽屏展示页 / 大屏看板」这类场景，配 `columnMinWidth` 才好落地；
+ * - `'auto'`：**列数随容器宽度动态变化** —— 能排几列排几列，每列宽由 `columnMinWidth` 决定。
+ *
+ * 两类的差别是**可预期性**（不是能力高低）：
+ *
+ * - 数字档承诺「最多 N 列」，所以「哪几个字段同排」在够宽的容器里是确定的；
+ * - 动态档会一路排下去（默认参数下 1320px 就够 4 列），窄了就减 ——
+ *   同一个表单在不同容器里列数不同 ⇒ **字段的相对位置会变**。要「两个字段必须并肩」就别用它。
+ */
+export type FormColumns = 1 | 2 | 3 | 4 | 5 | 6 | 'auto';
+/**
+ * 行内**垂直**对齐（label 与控件在控件行内怎么对齐）：
+ *
+ * - `center`（默认）：label 文字与控件**中线**对齐 —— 单行控件（输入框 / 选择器 / 开关）用它；
+ * - `start`：label 与控件**首行文字**对齐 —— 多行控件（文本域）与整块内容用它，
+ *   否则 label 会落到整块高度的中间。
+ *
+ * 不传即**自动判定**（样式按控件类型切档：文本域行零配置就是顶对齐）；
+ * 显式传入优先于自动判定，用于自绘内容（卡片组 / 表格 / 富文本这类样式认不出来的块）。
+ */
+export type FormItemAlign = 'center' | 'start';
 /** 表单值：**字段名 → 值**（键就是 `Form.Item` 的 `name`） */
 export type FormValues = Record<string, unknown>;
 /**
@@ -31,16 +58,27 @@ export interface FormProps {
      *
      * 宽表单（>600px）里让输入框一路拉到右边缘很难看，两种收法二选一：
      * ① 收宽度 —— 传 `controlWidth={360}`，控件列封顶、右侧留白；
-     * ② 分两列 —— 传 `columns={2}`，把行并排起来（更充分地用宽度，见下）。
+     * ② 分列 —— 传 `columns`（`2 | 3 | 4` 上限档，或 `'auto'` 动态），把行并排起来（见下）。
      */
     controlWidth?: number;
     /**
-     * 列数：`1`（默认，逐行）或 `2`（**容器够宽才并排**，窄了按列最小宽度自动回落一列）。
+     * 列数：`1`（默认，逐行）/ `2 ~ 6`（**容器够宽才并排**，窄了按列最小宽度自动回落一列）/
+     * `'auto'`（列数随容器宽度动态变化，取舍见 `FormColumns`）。
+     *
+     * 多列下每一行都要能独立成格，所以「整行内容」（说明行、卡片组、表格、文本域）记得
+     * 在对应 `Form.Item` 上给 `fullWidth`，否则会被压成一格。
+     */
+    columns?: FormColumns;
+    /**
+     * 一列的**最小宽度**（px）；缺省取令牌 `--ui-form-column-min`（320 = 「label 120 + 一个还能用的
+     * 输入框」的下限）。
      *
-     * 两列下每一行都要能独立成格，所以「整行内容」（说明行、卡片组、表格、文本域）记得
-     * 在对应 `Form.Item` 上给 `fullWidth`，否则会被压成半宽。
+     * 它同时是**回落阈值**与**动态列数的除数**：数字档下容器窄于
+     * `N × 最小宽 + (N − 1) × 行距` 就少排一列；动态档下列数 =
+     * `floor((容器宽 + 行距) / (最小宽 + 行距))`。抽屉 / 弹窗里嫌字段太窄就调小（如 280），
+     * 宽页面里嫌列太多就调大（如 380）。
      */
-    columns?: 1 | 2;
+    columnMinWidth?: number;
     /**
      * 表单内距（**px 数字**，与 `Panel` 同一口径）：`number` = 四边同值；`{ y, x }` = 上下 / 左右分别给。
      *
@@ -95,23 +133,22 @@ export interface FormItemProps {
     /** 在两列表单里跨满整行（说明行 / 卡片组 / 表格 / 文本域等整块内容） */
     fullWidth?: boolean;
     /**
-     * **只读文本形态**：传了它（含空串）即不走控件插槽，改为在控件位渲染纯文本 ——
-     * 用于「摘要 / 详情」这类静态表单行（同一个表单里 label 列、行距、错误、说明全部复用）。
+     * **只读展示行**：把 label 降一档**次要色**（与值拉开层级），内容仍走默认插槽。
      *
-     * 空值（`''` / 全空白）由组件统一显示 `—`，消费方不必每处写 `value || '—'`；
-     * 换行符原样保留（SQL where 这类多行文本回显不会被压成一行）。
+     * 用于「摘要 / 详情」这类只读行 —— 控件位可以是文本值，也可以是徽标 / 链接这类非文本内容：
      *
-     * 传了它这一行的 label 会降一档**次要色**（与正文色的值拉开层级），控件行不受影响。
+     * - **文本值**：控件位放 `<Input model-value={…} readonly bordered={false} />` ——
+     *   几何复用输入面（与可编辑输入框**同高、同内距**，值文字落在同一条竖线与中线上），
+     *   并且「无框 + 只读」会自动退掉输入框的交互线索（不显悬停底与聚焦框环，仍可选中复制）；
+     *   空值占位由业务侧自己拼（如 `model-value="v || '—'"`）；
+     * - **非文本内容**：内容直接从默认插槽进，`readonly` 只负责弱化 label。
      */
-    text?: string;
+    readonly?: boolean;
     /**
-     * **只读展示行**：只把 label 弱化（次要色），内容仍走默认插槽 ——
-     * 用于控件位不是纯文本的只读内容（徽标 / 链接这类）。
-     *
-     * 纯文本一律用 `text`（它自带只读语义，不必再传本开关）；本开关与 `text` 互斥不会冲突 ——
-     * 两个都给时 `text` 优先（`readonly` 只是把 label 的弱化带过去）。
+     * 行内**垂直**对齐：`center`（默认，label 与控件中线对齐）/ `start`（label 与控件首行文字对齐，
+     * 用于多行与整块内容）。不传即按控件类型自动判定（文本域自动顶对齐），显式传入优先。
      */
-    readonly?: boolean;
+    align?: FormItemAlign;
 }
 /**
  * 表单行（**自建**）：`label + 控件 + 错误 + 说明` 四件。
@@ -128,27 +165,52 @@ export interface FormItemProps {
  * ## 宽表单怎么处理（两条杠杆，可叠加）
  *
  * - **限宽**：`controlWidth` 封顶控件列（表单级给默认、逐行可覆盖）—— 单列表单不至于把输入框拉成长条；
- * - **分两列**：`columns={2}` 让行并排，宽度用得更充分；列最小宽度取令牌
- *   `--ui-form-column-min`（默认 320），所以窄容器会**自动回落成一列**，不需要消费方写媒体查询。
- *   两列下「整块内容」记得 `fullWidth`。
+ * - **分列**：`columns` 让行并排，宽度用得更充分。档位见 `FormColumns`：
+ *   `2 ~ 6` 是**列数上限**（宽够就并排、窄了自动少排一列）；`'auto'` 是**列数随宽度动态变化**。
+ *   回落阈值与动态列数都由 `columnMinWidth`（缺省令牌 `--ui-form-column-min` = 320）决定，
+ *   **不需要消费方写媒体查询**；多列下「整块内容」记得 `fullWidth`。
  *
  * `Form.Item` 是唯一入口（`Form` 只承载表单级设置、行间距/列数与容器内距），
  * 控件从默认插槽进，因此输入框 / 下拉 / 文本域 / 自绘分组卡片共用同一个容器。
  *
+ * ## 行内垂直对齐（label 与控件怎么对齐）
+ *
+ * 对齐参照是**控件那一行**，不是整行：控件列与 label 同处第 1 行，错误 / 说明自然落第 2 行起 ——
+ * 所以提示文案的有无与长短都不会带动 label 的位置。规则按控件形态自动切档，消费方零配置：
+ *
+ * - **单行控件**（输入框 / 选择器 / 开关 / 自绘单行内容）：label 与控件**中线**对齐，**与控件高度无关**
+ *   —— 档位切 sm/md/lg、换主题、放自绘控件都自动成立；
+ * - **多行与整块内容**（文本域这类样式认得出形态的）：label 与控件**首行文字**对齐，不会落到整块中间；
+ * - 样式认不出形态的自绘块（卡片组 / 表格 / 富文本）用 `align="start"` 显式声明；要强制居中用 `align="center"`。
+ *
+ * **本件不再依赖任何「控件高度」常量**：从前用一个外部注入的高度变量把 label 撑到控件高，
+ * 而那个变量在骨架层没有任何出处（回退成 `auto`），于是 label 盒退化成一行文字并贴行顶 ——
+ * 输入框中线偏高 6px、大号档偏高 10px、文本域偏高 9px，档位越高错得越多。
+ *
  * ## 容器内距（`padding`）
  *
  * 与 `Panel` **同一口径同一实现**（`src/components/part-padding.ts`）：`number` 四边同值、
  * `{ y, x }` 上下 / 左右分别给，缺省 0（贴容器边）。页面里的表单在 `Panel.Body` 里、内距由那块给；
  * **弹窗 / 抽屉里没有别的容器**给内距，就用表单自带的 `padding={{ y: 16, x: 20 }}`。
  *
- * ## 静态表单（摘要 / 详情）
+ * ## 只读值（摘要 / 详情）
  *
- * `Form.Item` 传 `text` 即切成**只读文本行**，三类行可以在同一个表单里混排 ——
- * label 列宽、行距、错误与说明全部共用，所以「向导最后一步的确认摘要」「详情弹窗」不需要
- * 另起一套描述列表件（自绘表格的 label/value 几何与表单行迟早会漂开）。
- * 空值占位 `—`、长文案折行、换行符保留都由组件给；只读行的 label 自动降一档次要色，
- * 字段名与取值一眼分得开（应用侧写不了 `color`，这层区分只能由组件给）。
- * 控件位要放徽标 / 链接这类**非文本**只读内容时传 `readonly`：内容走默认插槽，label 的弱化照旧。
+ * 「向导最后一步的确认摘要」「详情弹窗」不需要另起一套描述列表件 —— 只用表单行本身，
+ * label 列宽、行距、错误与说明全部复用。控件位放**只读 + 无框**的输入框即可（本件不给
+ * 「静态文本」形态：那套几何与输入框迟早会漂开 —— 从前它没有高度与内距，值文字既不在
+ * 输入框那条竖线上、也不在同一条中线上）：
+ *
+ * ```tsx
+ * <Form.Item label="创建人" readonly>
+ *   <Input model-value={row.creator || '—'} readonly bordered={false} />
+ * </Form.Item>
+ * ```
+ *
+ * - **几何与可编辑行完全一致**：值文字与输入框内的值同高、同左缘、同中线，混排时节奏整齐；
+ * - **没有「可编辑」的线索**：不显悬停底色、不给聚焦边框与主色环，但仍可点进去选中 / 复制；
+ * - **空值占位归业务**：组件不再替你把 `''` 显示成 `—`，按上面的写法自己拼；
+ * - **label 弱化**：传 `readonly` 把 label 降一档次要色，字段名与取值一眼分得开；
+ * - 控件位是徽标 / 链接这类**非文本**只读内容时同样传 `readonly`：内容直接走默认插槽。
  *
  * @example
  * <Form labelWidth={120} columns={2}>
@@ -201,16 +263,16 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         type: BooleanConstructor;
         default: boolean;
     };
-    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-    text: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
     };
+    /** 行内垂直对齐；不传即自动（单行居中、多行顶对齐） */
+    align: {
+        type: PropType<FormItemAlign>;
+        default: undefined;
+    };
 }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
     name: {
@@ -249,22 +311,22 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         type: BooleanConstructor;
         default: boolean;
     };
-    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-    text: {
-        type: StringConstructor;
-        default: undefined;
-    };
-    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
     readonly: {
         type: BooleanConstructor;
         default: boolean;
     };
+    /** 行内垂直对齐；不传即自动（单行居中、多行顶对齐） */
+    align: {
+        type: PropType<FormItemAlign>;
+        default: undefined;
+    };
 }>> & Readonly<{}>, {
-    text: string;
     name: string;
     label: string;
     error: string;
     required: boolean;
+    align: FormItemAlign;
     readonly: boolean;
     hint: string;
     labelWidth: number;
@@ -345,11 +407,16 @@ export declare const Form: {
             type: NumberConstructor;
             default: undefined;
         };
-        /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+        /** 列数：1（逐行，默认）/ 2~6（够宽才并排，窄了回落一列）/ 'auto'（列数随容器宽度动态变化） */
         columns: {
-            type: PropType<1 | 2>;
+            type: PropType<FormColumns>;
             default: number;
         };
+        /** 一列的最小宽度（px）；缺省取令牌 --ui-form-column-min（320）；它同时是回落阈值 */
+        columnMinWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
         /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
         padding: {
             type: PropType<FormPadding>;
@@ -398,11 +465,12 @@ export declare const Form: {
         onChange: (values: FormValues) => void;
         defaultValue: FormValues;
         gap: number;
-        columns: 1 | 2;
+        columns: FormColumns;
         modelValue: FormValues;
         labelWidth: number;
         labelAlign: FormLabelAlign;
         controlWidth: number;
+        columnMinWidth: number;
     }, true, {}, SlotsType<{
         default?: () => VNodeChild;
     }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
@@ -428,11 +496,16 @@ export declare const Form: {
             type: NumberConstructor;
             default: undefined;
         };
-        /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+        /** 列数：1（逐行，默认）/ 2~6（够宽才并排，窄了回落一列）/ 'auto'（列数随容器宽度动态变化） */
         columns: {
-            type: PropType<1 | 2>;
+            type: PropType<FormColumns>;
             default: number;
         };
+        /** 一列的最小宽度（px）；缺省取令牌 --ui-form-column-min（320）；它同时是回落阈值 */
+        columnMinWidth: {
+            type: NumberConstructor;
+            default: undefined;
+        };
         /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
         padding: {
             type: PropType<FormPadding>;
@@ -479,11 +552,12 @@ export declare const Form: {
         onChange: (values: FormValues) => void;
         defaultValue: FormValues;
         gap: number;
-        columns: 1 | 2;
+        columns: FormColumns;
         modelValue: FormValues;
         labelWidth: number;
         labelAlign: FormLabelAlign;
         controlWidth: number;
+        columnMinWidth: number;
     }>;
     __isFragment?: never;
     __isTeleport?: never;
@@ -504,11 +578,16 @@ export declare const Form: {
         type: NumberConstructor;
         default: undefined;
     };
-    /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+    /** 列数：1（逐行，默认）/ 2~6（够宽才并排，窄了回落一列）/ 'auto'（列数随容器宽度动态变化） */
     columns: {
-        type: PropType<1 | 2>;
+        type: PropType<FormColumns>;
         default: number;
     };
+    /** 一列的最小宽度（px）；缺省取令牌 --ui-form-column-min（320）；它同时是回落阈值 */
+    columnMinWidth: {
+        type: NumberConstructor;
+        default: undefined;
+    };
     /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
     padding: {
         type: PropType<FormPadding>;
@@ -557,11 +636,12 @@ export declare const Form: {
     onChange: (values: FormValues) => void;
     defaultValue: FormValues;
     gap: number;
-    columns: 1 | 2;
+    columns: FormColumns;
     modelValue: FormValues;
     labelWidth: number;
     labelAlign: FormLabelAlign;
     controlWidth: number;
+    columnMinWidth: number;
 }, {}, string, SlotsType<{
     default?: () => VNodeChild;
 }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
@@ -627,16 +707,16 @@ export declare const Form: {
             type: BooleanConstructor;
             default: boolean;
         };
-        /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-        text: {
-            type: StringConstructor;
-            default: undefined;
-        };
-        /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+        /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
         };
+        /** 行内垂直对齐；不传即自动（单行居中、多行顶对齐） */
+        align: {
+            type: PropType<FormItemAlign>;
+            default: undefined;
+        };
     }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
         /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
         name: {
@@ -675,22 +755,22 @@ export declare const Form: {
             type: BooleanConstructor;
             default: boolean;
         };
-        /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-        text: {
-            type: StringConstructor;
-            default: undefined;
-        };
-        /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+        /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
         readonly: {
             type: BooleanConstructor;
             default: boolean;
         };
+        /** 行内垂直对齐；不传即自动（单行居中、多行顶对齐） */
+        align: {
+            type: PropType<FormItemAlign>;
+            default: undefined;
+        };
     }>> & Readonly<{}>, {
-        text: string;
         name: string;
         label: string;
         error: string;
         required: boolean;
+        align: FormItemAlign;
         readonly: boolean;
         hint: string;
         labelWidth: number;

package/dist/components/form/index.js

@@ -3,7 +3,6 @@ import { mergePartStyle } from "../part-padding.js";
 const FORM_LABEL_WIDTH = /* @__PURE__ */ Symbol("mh-form-label-width");
 const FORM_CONTROL_WIDTH = /* @__PURE__ */ Symbol("mh-form-control-width");
 const FORM_LABEL_ALIGN = /* @__PURE__ */ Symbol("mh-form-label-align");
-const FORM_TEXT_EMPTY = "—";
 const FORM_STORE = /* @__PURE__ */ Symbol("mh-form-store");
 const FormItem = /* @__PURE__ */ defineComponent({
   name: "FormItem",
@@ -46,15 +45,15 @@ const FormItem = /* @__PURE__ */ defineComponent({
       type: Boolean,
       default: false
     },
-    /** `undefined` 与「传了空串」必须区分：前者走插槽（控件形态），后者是「值为空的只读行」 */
-    text: {
-      type: String,
-      default: void 0
-    },
-    /** 只读展示行（label 弱化，内容走插槽）：用于控件位是徽标 / 链接这类非文本的只读内容 */
+    /** 只读展示行（label 弱化）：文本值放 Input 的只读 + 无框形态，非文本内容走默认插槽 */
     readonly: {
       type: Boolean,
       default: false
+    },
+    /** 行内垂直对齐；不传即自动（单行居中、多行顶对齐） */
+    align: {
+      type: String,
+      default: void 0
     }
   },
   slots: Object,
@@ -87,18 +86,19 @@ const FormItem = /* @__PURE__ */ defineComponent({
         "--mh-form-label-width": `${labelWidth}px`
       } : null].filter(Boolean);
       const showLabel = !!props.label || props.required;
-      const hasText = props.text !== void 0;
-      const textIsEmpty = hasText && !props.text.trim();
-      const isReadonlyRow = hasText || props.readonly;
       return createVNode("div", {
         "class": [
           "mh-form-item",
           props.error ? "is-invalid" : "",
           props.fullWidth ? "mh-form-item--full" : "",
+          // 无 label 列：控件位与提示横跨整行（两列 grid 下第一列不能留空位）
+          showLabel ? "" : "mh-form-item--no-label",
+          // 行内垂直对齐：**只在显式传入时**挂类；不传即由样式按控件类型自动判定（见 form.css 的顶对齐档）
+          props.align ? `mh-form-item--align-${props.align}` : "",
           // 右对齐是基类默认值，只有左对齐需要额外的修饰类（两处都挂会让「谁胜出」依赖源码顺序）
           labelAlign === "left" ? "mh-form-item--label-left" : "",
           // 只读展示行：label 降一档为次要色，与值拉开层级（样式见 `.mh-form-item--readonly .mh-form-item__label`）
-          isReadonlyRow ? "mh-form-item--readonly" : "",
+          props.readonly ? "mh-form-item--readonly" : "",
           attrs.class
         ].filter(Boolean).join(" "),
         "data-invalid": props.error ? "true" : "false",
@@ -114,20 +114,11 @@ const FormItem = /* @__PURE__ */ defineComponent({
         "style": controlWidth ? {
           maxWidth: `${controlWidth}px`
         } : void 0
-      }, [hasText ? (
-        /*
-         * 只读文本形态（摘要 / 详情行）：控件位直接渲染业务值，占位与换行规则都在组件里
-         * —— 应用侧不再自绘 label/value 表格（那套几何与表单行迟早会漂开）。
-         */
-        createVNode("div", {
-          "class": "mh-form-item__text",
-          "data-empty": textIsEmpty ? "true" : "false"
-        }, [textIsEmpty ? FORM_TEXT_EMPTY : props.text])
-      ) : slots.default?.(scope()), props.error ? createVNode("div", {
+      }, [slots.default?.(scope())]), props.error ? createVNode("div", {
         "class": "mh-form-item__error"
       }, [props.error]) : null, props.hint ? createVNode("div", {
         "class": "mh-form-item__hint"
-      }, [props.hint]) : null])]);
+      }, [props.hint]) : null]);
     };
   }
 });
@@ -198,14 +189,19 @@ const FormRoot = /* @__PURE__ */ defineComponent({
       type: Number,
       default: void 0
     },
-    /** 列数：1（逐行，默认）/ 2（容器够宽才并排，窄了自动回落一列） */
+    /** 列数：1（逐行，默认）/ 2~6（够宽才并排，窄了回落一列）/ 'auto'（列数随容器宽度动态变化） */
     columns: {
-      type: Number,
+      type: [Number, String],
       default: 1
     },
+    /** 一列的最小宽度（px）；缺省取令牌 --ui-form-column-min（320）；它同时是回落阈值 */
+    columnMinWidth: {
+      type: Number,
+      default: void 0
+    },
     /** 表单内距（px 数字，或 `{ y, x }`）；缺省 0 = 贴容器边（弹窗 / 抽屉里常用它自带内距） */
     padding: {
-      type: [Number, Object],
+      type: [Number, Object, String],
       default: void 0
     },
     /**
@@ -302,6 +298,12 @@ const FormRoot = /* @__PURE__ */ defineComponent({
         return cleared;
       }
     });
+    const columnsClass = () => {
+      const value = props.columns;
+      if (value === "auto") return "mh-form--columns-auto";
+      if (typeof value !== "number" || value <= 1) return "";
+      return value === 2 ? "mh-form--two-column" : `mh-form--columns-${value}`;
+    };
     return () => {
       const raw = slots.default?.();
       const list = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
@@ -310,10 +312,20 @@ const FormRoot = /* @__PURE__ */ defineComponent({
         rest
       } = splitFormHeader(list);
       return createVNode("div", {
-        "class": ["mh-form", props.columns === 2 ? "mh-form--two-column" : "", props.layout === "vertical" ? "mh-form--vertical" : "", attrs.class].filter(Boolean).join(" "),
-        "style": [mergePartStyle(attrs.style, props.padding), props.gap !== void 0 ? {
-          gap: `${props.gap}px`
-        } : null]
+        "class": ["mh-form", columnsClass(), props.layout === "vertical" ? "mh-form--vertical" : "", attrs.class].filter(Boolean).join(" "),
+        "style": [
+          mergePartStyle(attrs.style, props.padding),
+          /* 行距同时下发实体 `gap` 与变量：多列的轨道下限公式要用**同一个**行距值算 ——
+             从前公式里硬编码 8px，`gap={16}` 时列宽会算偏（临界宽度上还会误判回落）。 */
+          props.gap !== void 0 ? {
+            gap: `${props.gap}px`,
+            "--mh-form-gap": `${props.gap}px`
+          } : null,
+          /* 一列最小宽度：动态档列数的除数、数字档的回落阈值 */
+          props.columnMinWidth !== void 0 ? {
+            "--mh-form-column-min": `${props.columnMinWidth}px`
+          } : null
+        ]
       }, [header, rest]);
     };
   }