@manohub/ui 1.0.4 → 1.0.6

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

@@ -5,37 +5,25 @@ 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 列），窄了就减 ——
- *   同一个表单在不同容器里列数不同 ⇒ **字段的相对位置会变**。要「两个字段必须并肩」就别用它。
+ * 字段行的排布档：`1`（默认，逐行）；`2 ~ 6`（**列数上限** —— 放得下 N 列就并排、放不下少排一列，不会把控件压成
+ * 窄条；5 / 6 给宽屏展示页，默认最小宽 320 下要容器 1632 / 1960px）；`'auto'`（**列数随容器宽度动态变化**，每列宽
+ * 由 `columnMinWidth` 决定）。
+ * 两类的差别是**可预期性**（不是能力高低）：数字档承诺「最多 N 列」，够宽时「哪几个字段同排」是确定的；动态档窄了
+ * 就减，同一表单在不同容器里列数不同 ⇒ **字段的相对位置会变** —— 要「两个字段必须并肩」就别用它。
+ * 用法见 `docs/demos/form/`（每个维度一份可运行样例；文档页 `docs/components/form.md`）。
  */
 export type FormColumns = 1 | 2 | 3 | 4 | 5 | 6 | 'auto';
 /**
- * 行内**垂直**对齐（label 与控件在控件行内怎么对齐）：
- *
- * - `center`（默认）：label 文字与控件**中线**对齐 —— 单行控件（输入框 / 选择器 / 开关）用它；
- * - `start`：label 与控件**首行文字**对齐 —— 多行控件（文本域）与整块内容用它，
- *   否则 label 会落到整块高度的中间。
- *
- * 不传即**自动判定**（样式按控件类型切档：文本域行零配置就是顶对齐）；
- * 显式传入优先于自动判定，用于自绘内容（卡片组 / 表格 / 富文本这类样式认不出来的块）。
+ * 行内**垂直**对齐（label 与控件在控件行内怎么对齐）：`center`（默认，与控件**中线**对齐，单行控件用）；`start`
+ * （与控件**首行文字**对齐，多行控件与整块内容用，否则 label 会落到整块高度中间）。不传即**自动判定**（样式按控件
+ * 类型切档），显式传入优先，用于自绘内容（卡片组 / 表格 / 富文本）。
  */
 export type FormItemAlign = 'center' | 'start';
 /** 表单值：**字段名 → 值**（键就是 `Form.Item` 的 `name`） */
 export type FormValues = Record<string, unknown>;
 /**
- * 带 `name` 的 `Form.Item` 的默认插槽作用域：控件由消费方渲染，本件只把绑定值交出去。
- * 不带 `name` 的项（纯布局 / 只读行）不需要这些，作用域里的值恒为 `undefined`。
+ * 带 `name` 的 `Form.Item` 的默认插槽作用域：控件由消费方渲染，本件只把绑定值交出去；不带 `name` 的项
+ * （纯布局 / 只读行）不需要这些，作用域里的值恒为 `undefined`。
  */
 export interface FormItemSlotScope {
     /** 当前字段值（Form 里的原值，不做任何归一） */
@@ -48,51 +36,34 @@ export interface FormItemSlotScope {
 export interface FormProps {
     /** 表单级 label 列宽（px）；缺省取令牌 `--ui-form-label-width`（120）。px 不跟随根字号，见 CONTRACT「已知偏差」 */
     labelWidth?: number;
-    /**
-     * 表单级 label 对齐：`right`（默认，文本贴着控件列）或 `left`（所有 label 起点一致）。
-     * `Form.Item` 上再写则只改那一行。
-     */
+    /** 表单级 label 对齐：`right`（默认，文本贴着控件列）或 `left`（所有 label 起点一致）；`Form.Item` 上再写则只改那一行。 */
     labelAlign?: FormLabelAlign;
     /**
-     * 表单级控件列宽上限（px）；缺省**撑满**剩余宽度。
-     *
-     * 宽表单（>600px）里让输入框一路拉到右边缘很难看，两种收法二选一：
-     * ① 收宽度 —— 传 `controlWidth={360}`，控件列封顶、右侧留白；
-     * ② 分列 —— 传 `columns`（`2 | 3 | 4` 上限档，或 `'auto'` 动态），把行并排起来（见下）。
+     * 表单级控件列宽上限（px）；缺省**撑满**剩余宽度。宽表单（>600px）里让输入框一路拉到右边缘很难看，两种收法
+     * 二选一：① 收宽度（`controlWidth={360}`，控件列封顶、右侧留白）；② 分列（`columns`，见下）。
      */
     controlWidth?: number;
     /**
-     * 列数：`1`（默认，逐行）/ `2 ~ 6`（**容器够宽才并排**，窄了按列最小宽度自动回落一列）/
-     * `'auto'`（列数随容器宽度动态变化，取舍见 `FormColumns`）。
-     *
-     * 多列下每一行都要能独立成格，所以「整行内容」（说明行、卡片组、表格、文本域）记得
-     * 在对应 `Form.Item` 上给 `fullWidth`，否则会被压成一格。
+     * 列数：`1`（默认，逐行）/ `2 ~ 6`（**容器够宽才并排**，窄了自动回落一列）/ `'auto'`（列数随容器宽度动态变化）。
+     * 多列下「整行内容」（说明行 / 卡片组 / 表格 / 文本域）记得在对应 `Form.Item` 上给 `fullWidth`，否则会被压成一格。
      */
     columns?: FormColumns;
     /**
-     * 一列的**最小宽度**（px）；缺省取令牌 `--ui-form-column-min`（320 = 「label 120 + 一个还能用的
-     * 输入框」的下限）。
-     *
-     * 它同时是**回落阈值**与**动态列数的除数**：数字档下容器窄于
-     * `N × 最小宽 + (N − 1) × 行距` 就少排一列；动态档下列数 =
-     * `floor((容器宽 + 行距) / (最小宽 + 行距))`。抽屉 / 弹窗里嫌字段太窄就调小（如 280），
-     * 宽页面里嫌列太多就调大（如 380）。
+     * 一列的**最小宽度**（px）；缺省取令牌 `--ui-form-column-min`（320 =「label 120 + 一个还能用的输入框」的下限）。
+     * 它同时是**回落阈值**与**动态列数的除数**：数字档下容器窄于 `N × 最小宽 + (N − 1) × 行距` 就少排一列；动态档下
+     * 列数 = `floor((容器宽 + 行距) / (最小宽 + 行距))`。抽屉 / 弹窗里嫌字段太窄就调小（如 280），宽页面里嫌列太多就调大。
      */
     columnMinWidth?: number;
     /**
-     * 表单内距（**px 数字**，与 `Panel` 同一口径）：`number` = 四边同值；`{ y, x }` = 上下 / 左右分别给。
-     *
-     * **缺省 0**：表单贴容器边，内距由所在容器给（页面里的表单在 `Panel.Body` 里，那块自带内距）。
-     * 弹窗 / 抽屉里没有别的容器给内距时用它自带 —— 如 `padding={{ y: 16, x: 20 }}`，
-     * 这样就不必再给表单挂一个「只写 padding」的应用侧类。
+     * 表单内距（**px 数字**，与 `Panel` 同一口径）：`number` = 四边同值；`{ y, x }` = 上下 / 左右分别给。**缺省 0**
+     * （表单贴容器边，内距由所在容器给）；弹窗 / 抽屉里没别的容器给内距时用它自带（如 `{ y: 16, x: 20 }`）。
      */
     padding?: FormPadding;
     /** 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档 */
     gap?: number;
     /**
-     * 受控表单值（**字段名 → 值**，键就是 `Form.Item` 的 `name`）；不传即非受控（由 `defaultValue` 起）。
-     *
-     * 值变更时 `emit('update:modelValue')` 与 `onChange` **双走**（`v-model` 落地 + 回调）。
+     * 受控表单值（**字段名 → 值**，键就是 `Form.Item` 的 `name`）；不传即非受控（由 `defaultValue` 起）。值变更时
+     * `emit('update:modelValue')` 与 `onChange` **双走**（`v-model` 落地 + 回调）。
      */
     modelValue?: FormValues;
     /** 非受控初值；其中的键会一并成为快照的键（不必等字段挂载） */
@@ -100,178 +71,104 @@ export interface FormProps {
     /** 值变更（快照含**全部已登记字段**，未设值的字段为 `undefined`） */
     onChange?: (values: FormValues) => void;
     /**
-     * 根节点的键盘事件（**转发到表单根**）。
-     *
-     * 本件是 `inheritAttrs: false`，根节点只显式绑 `class` / `style` —— 不声明的监听器会被**静默丢掉**
-     * （与该文件里已修过的「消费方 style 被静默丢弃」同款前科）。而根节点就是「全部字段行的容器」，
-     * 故它是「字段区层面的委托」的落点：本包 `Filter` 的「字段区回车 = 查询」就搭在这条通道上
-     * （构造 `Filter` 时因此不必再套一层只为挂事件的壳 —— 那会改变 `class` / `style` 的落点）。
-     *
-     * **有意只开这一条**：其它监听器（如 `onClick`）不转发；要把某一条也接进来，先当一次公开行为变更裁决。
-     * 要不要拦、拦哪些按键（本包 `Filter` 收窄到「`<input>` 上的回车」）由调用方自己判断，本件只转发。
+     * 根节点的键盘事件（**转发到表单根**）。本件是 `inheritAttrs: false`，根节点只显式绑 `class` / `style` ——
+     * 不声明的监听器会被**静默丢掉**；而根节点就是「全部字段行的容器」，故它是「字段区层面的委托」的落点（`Filter`
+     * 的「字段区回车 = 查询」就搭在这条通道上，构造 `Filter` 时因此不必再套一层只为挂事件的壳）。
+     * **有意只开这一条**：其它监听器（如 `onClick`）不转发；判据（`Filter` 收窄到「`<input>` 上的回车」）由调用方
+     * 自己定，本件只转发。
      */
     onKeydown?: (event: KeyboardEvent) => void;
 }
 export interface FormItemProps {
     /**
-     * **字段名**（绑定的键）：带了它，本行就从 `Form` 取值并把写值交出去
-     * （默认插槽作用域 `{ value, setValue, clear }`）；不带则与从前一样 ——
-     * 纯布局行，值由消费方自己在控件上绑定（静态摘要 / 只读行都属这一类）。
+     * **字段名**（绑定的键）：带了它，本行就从 `Form` 取值并把写值交出去（默认插槽作用域 `{ value, setValue, clear }`）；
+     * 不带则与从前一样 —— 纯布局行，值由消费方自己在控件上绑定（静态摘要 / 只读行都属这一类）。
      */
     name?: string;
-    /**
-     * 字段名（label 文本）。缺省且非必填时**不渲染 label 列**：控件列占满整行
-     * —— 用于无字段名的整块内容（如列编辑区）与纯说明行。
-     */
+    /** 字段名（label 文本）。缺省且非必填时**不渲染 label 列**（控件列占满整行）—— 用于无字段名的整块内容与纯说明行。 */
     label?: string;
-    /**
-     * 必填标记：星号渲染在 label 文本**之后**（`服务名称*`）—— 星号是字段名的一部分，
-     * 跟着字段名走；与 farris 动态表单「星号在左」的写法**有意不同**（本仓口径）。
-     */
+    /** 必填标记：星号渲染在 label 文本**之后**（`服务名称*`）—— 星号是字段名的一部分，跟着字段名走（与 farris「星号在左」有意不同）。 */
     required?: boolean;
     /** 校验错误文案：非空即进入 invalid 态，文案排布在控件**下方**（不遮挡后续行） */
     error?: string;
     /** 字段说明文案（常驻，排在错误之后） */
     hint?: string;
     /**
-     * **label 旁的提示**（问号图标 + 悬停气泡，仅文本）。
-     *
-     * 与 `hint` 分工不同：`hint` 是**常驻**在控件下方的说明文案，`tip` 是**按需展开**的补充解释 ——
-     * 不占版面，只在悬停（或键盘聚焦）问号图标时出现，两者可以同时给。
-     *
-     * 图标排在 label 文本与必填星号**之后**（`服务名称*ⓘ`）；只给 `tip` 而不给 `label` 时同样保留
-     * label 列（与「只给 required」同一判据）—— 否则图标没有列可落、静默消失。
-     *
-     * 用的是 `Tooltip` 的 **hover 档**（零 JS）：显隐与定位全在 CSS，移入 / 聚焦即显、移开即隐，
-     * 因此**不吃点击、不抢焦点**。代价一条：hover 档不进浏览器顶层浮层，会被祖先 `overflow` 裁切
-     * —— 弹窗 / 抽屉里贴着裁剪边的字段可能看不全（要顶层浮层就得换 `Tooltip trigger="click"`，
-     * 本件有意不暴露该维度，见文件头「label 提示」）。
+     * **label 旁的提示**（问号图标 + 悬停气泡，仅文本）。`hint` 是**常驻**在控件下方的说明，`tip` 是**按需展开**的
+     * 补充解释（不占版面，悬停 / 键盘聚焦时出现），两者可同时给。图标排在 label 文本与必填星号**之后**
+     * （`服务名称*ⓘ`）；只给 `tip` 而不给 `label` 时同样保留 label 列（否则图标没有列可落、静默消失）。气泡用
+     * `Tooltip` 的 **hover 档**（零 JS、不吃点击、不抢焦点），代价一条：hover 档不进顶层浮层、会被祖先 `overflow` 裁切。
      */
     tip?: string;
     /** 本行 label 列宽（px）；覆盖 `Form` 的表单级设置 */
     labelWidth?: number;
     /** 本行 label 对齐；覆盖 `Form` 的表单级设置 */
     labelAlign?: FormLabelAlign;
-    /**
-     * 本行控件列宽上限（px）；覆盖 `Form` 的表单级设置。
-     * 缺省撑满剩余宽度（宽表单里的选型字段用它收敛，避免长条下拉）。
-     */
+    /** 本行控件列宽上限（px）；覆盖 `Form` 的表单级设置，缺省撑满剩余宽度（宽表单里的选型字段用它收敛，避免长条下拉）。 */
     controlWidth?: number;
     /** 在两列表单里跨满整行（说明行 / 卡片组 / 表格 / 文本域等整块内容） */
     fullWidth?: boolean;
     /**
-     * **只读展示行**：把 label 降一档**次要色**（与值拉开层级），内容仍走默认插槽。
-     *
-     * 用于「摘要 / 详情」这类只读行 —— 控件位可以是文本值，也可以是徽标 / 链接这类非文本内容：
-     *
-     * - **文本值**：控件位放 `<Input model-value={…} readonly bordered={false} />` ——
-     *   几何复用输入面（与可编辑输入框**同高、同内距**，值文字落在同一条竖线与中线上），
-     *   并且「无框 + 只读」会自动退掉输入框的交互线索（不显悬停底与聚焦框环，仍可选中复制）；
-     *   空值占位由业务侧自己拼（如 `model-value="v || '—'"`）；
-     * - **非文本内容**：内容直接从默认插槽进，`readonly` 只负责弱化 label。
+     * **只读展示行**（摘要 / 详情）：把 label 降一档**次要色**（与值拉开层级），内容仍走默认插槽。文本值放
+     * `<Input model-value={…} readonly bordered={false} />` —— 几何复用输入面（与可编辑输入框同高、同内距，值文字落在
+     * 同一条竖线与中线上），且「无框 + 只读」自动退掉交互线索（不显悬停底与聚焦框环，仍可选中复制）；空值占位由业务
+     * 侧自己拼。非文本内容（徽标 / 链接）直接从默认插槽进，`readonly` 只负责弱化 label。
      */
     readonly?: boolean;
-    /**
-     * 行内**垂直**对齐：`center`（默认，label 与控件中线对齐）/ `start`（label 与控件首行文字对齐，
-     * 用于多行与整块内容）。不传即按控件类型自动判定（文本域自动顶对齐），显式传入优先。
-     */
+    /** 行内**垂直**对齐：`center`（默认，与控件中线对齐）/ `start`（与首行文字对齐，用于多行与整块内容）。不传即按控件类型自动判定（文本域自动顶对齐），显式传入优先。 */
     align?: FormItemAlign;
 }
 /**
  * 表单行（**自建**）：`label + 控件 + 错误 + 说明` 四件。
  *
- * 为什么不封装 farris 的 `FDynamicFormGroup`：那是动态表单（元数据驱动）体系里的分组件 ——
- * 控件要经 `editor` 描述对象交给它渲染，label 宽度 / 控件限宽由 farris 表单类写死
- * （inline 6rem 右对齐、字段 max-width 26.625rem），校验信息走**绝对定位的浮层提示条**。
- * 与本仓三条口径冲突：① 控件由消费方直接写（不构造底层配置对象）；② 数据入参只收朴素业务值；
- * ③ 错误与说明按文档流排布（浮层在弹窗里会压住下一行的控件）。故按「缺件处置流程」自建，
- * 必填星号固定在 label 文本**之后**（`服务名称*`，有意偏离 farris 的「星号在左」）；
- * **label 对齐是维度**（`labelAlign`，
- * 默认 `right`（与 farris / 主流水平表单一致），`left` 时所有 label 起点一致）。
+ * 为什么不封装 farris 的 `FDynamicFormGroup`：那是元数据驱动的动态表单分组件（控件经 `editor` 描述对象
+ * 渲染、label 宽度由 farris 表单类写死、校验信息走绝对定位的浮层提示条），与本仓三条口径冲突：控件由
+ * 消费方直接写、数据入参只收朴素业务值、错误与说明按文档流排布（浮层在弹窗里会压住下一行的控件）。故按
+ * 「缺件处置流程」自建；必填星号固定在 label 文本**之后**（`服务名称*`，有意偏离 farris 的「星号在左」）；
+ * label 对齐是维度（`labelAlign`，默认 `right` 与主流水平表单一致，`left` 时所有 label 起点一致）。
  *
  * ## 宽表单怎么处理（两条杠杆，可叠加）
- *
  * - **限宽**：`controlWidth` 封顶控件列（表单级给默认、逐行可覆盖）—— 单列表单不至于把输入框拉成长条；
- * - **分列**：`columns` 让行并排，宽度用得更充分。档位见 `FormColumns`：
- *   `2 ~ 6` 是**列数上限**（宽够就并排、窄了自动少排一列）；`'auto'` 是**列数随宽度动态变化**。
- *   回落阈值与动态列数都由 `columnMinWidth`（缺省令牌 `--ui-form-column-min` = 320）决定，
- *   **不需要消费方写媒体查询**；多列下「整块内容」记得 `fullWidth`。
+ * - **分列**：`columns` 让行并排（`2 ~ 6` 是**列数上限**，宽够才并排；`'auto'` 是列数随宽度动态变化）。
+ *   回落阈值与动态列数都由 `columnMinWidth`（缺省令牌 `--ui-form-column-min` = 320）决定，**不需要消费方
+ *   写媒体查询**；多列下「整块内容」记得 `fullWidth`。
  *
- * `Form.Item` 是唯一入口（`Form` 只承载表单级设置、行间距/列数与容器内距），
- * 控件从默认插槽进，因此输入框 / 下拉 / 文本域 / 自绘分组卡片共用同一个容器。
+ * `Form.Item` 是唯一入口（`Form` 只承载表单级设置、行间距 / 列数与容器内距），控件从默认插槽进。
  *
  * ## 行内垂直对齐（label 与控件怎么对齐）
- *
- * 对齐参照是**控件那一行**，不是整行：控件列与 label 同处第 1 行，错误 / 说明自然落第 2 行起 ——
- * 所以提示文案的有无与长短都不会带动 label 的位置。规则按控件形态自动切档，消费方零配置：
- *
- * - **单行控件**（输入框 / 选择器 / 开关 / 自绘单行内容）：label 与控件**中线**对齐，**与控件高度无关**
- *   —— 档位切 sm/md/lg、换主题、放自绘控件都自动成立；
- * - **多行与整块内容**（文本域这类样式认得出形态的）：label 与控件**首行文字**对齐，不会落到整块中间；
- * - 样式认不出形态的自绘块（卡片组 / 表格 / 富文本）用 `align="start"` 显式声明；要强制居中用 `align="center"`。
- *
- * **本件不再依赖任何「控件高度」常量**：从前用一个外部注入的高度变量把 label 撑到控件高，
- * 而那个变量在骨架层没有任何出处（回退成 `auto`），于是 label 盒退化成一行文字并贴行顶 ——
- * 输入框中线偏高 6px、大号档偏高 10px、文本域偏高 9px，档位越高错得越多。
+ * 对齐参照是**控件那一行**，不是整行：控件列与 label 同处第 1 行、错误 / 说明自然落第 2 行起 —— 提示文案
+ * 的有无与长短都不会带动 label 的位置。规则按控件形态自动切档、消费方零配置：单行控件 → label 与控件
+ * **中线**对齐（**与控件高度无关**，切档 / 换主题 / 放自绘控件都成立）；多行与整块内容（文本域这类样式
+ * 认得出形态的）→ **首行文字**对齐；样式认不出形态的自绘块（卡片组 / 表格 / 富文本）用 `align="start"`，
+ * 要强制居中用 `align="center"`。
+ * **本件不再依赖任何「控件高度」常量**：从前那个外部注入的高度变量在骨架层没有出处（回退成 `auto`），
+ * label 盒因此退化成一行文字并贴行顶 —— 档位越高错得越多。
  *
  * ## 容器内距（`padding`）
- *
- * 与 `Panel` **同一口径同一实现**（`src/components/part-padding.ts`）：`number` 四边同值、
- * `{ y, x }` 上下 / 左右分别给，缺省 0（贴容器边）。页面里的表单在 `Panel.Body` 里、内距由那块给；
- * **弹窗 / 抽屉里没有别的容器**给内距，就用表单自带的 `padding={{ y: 16, x: 20 }}`。
+ * 与 `Panel` **同一口径同一实现**（`src/components/part-padding.ts`）：`number` 四边同值、`{ y, x }` 分别
+ * 给，缺省 0（贴容器边）。页面里的表单在 `Panel.Body` 里、内距由那块给；**弹窗 / 抽屉里没有别的容器**
+ * 给内距，就用表单自带的 `padding={{ y: 16, x: 20 }}`。
  *
  * ## label 提示（`tip`）
- *
- * 字段名（与必填星号）之后挂一枚问号图标，悬停 / 键盘聚焦弹出说明气泡。它是**按需展开**的补充
- * 解释，不占版面；常驻说明仍归 `hint`（排在控件下方）。两者分工不同，也**不互相替代**。
- *
- * - 图标取 `@manohub/icon` 的 `help`（带圈问号），尺寸随主题图标档（`--ui-font-icon`）；
- * - 图标**排在星号之后**（`服务名称*ⓘ`）—— 与「星号跟着字段名走」同一口径；
- * - 只给 `tip`（无 `label`、非必填）时**同样保留 label 列**（与「只给 required」同一判据），
- *   否则图标没有列可落、静默消失；
- * - 气泡用 `Tooltip` 的 **hover 档**（零 JS）：不吃点击、不抢焦点；代价是 hover 档不进浏览器
- *   顶层浮层，会被祖先 `overflow` 裁切（弹窗 / 抽屉里贴着裁剪边的字段可能看不全）。
+ * 字段名（与必填星号）之后挂一枚问号图标，悬停 / 键盘聚焦弹出说明气泡 —— 按需展开的补充解释、不占版面；
+ * 常驻说明仍归 `hint`（排在控件下方），两者不互相替代。图标取 `help`（带圈问号）字形、尺寸随主题图标档、
+ * **排在星号之后**（`服务名称*ⓘ`）；只给 `tip`（无 `label`、非必填）时**同样保留 label 列**，否则图标
+ * 没有列可落、静默消失。气泡用 `Tooltip` 的 **hover 档**（零 JS、不吃点击、不抢焦点），代价是 hover 档
+ * 不进浏览器顶层浮层，会被祖先 `overflow` 裁切（弹窗 / 抽屉里贴着裁剪边的字段可能看不全）。
  *
  * ## 键盘事件（`onKeydown` 转发到根节点）
- *
- * `onKeydown` 是本件的**声明式入口**（缺省不绑）：传进来的处理器绑在根节点上 ——
- * 本件是 `inheritAttrs: false`，根节点只显式绑 `class` / `style`，不声明的监听器会被静默丢掉。
- * 根节点即「全部字段行的容器」，因此它是「字段区层面的委托」的落点：本包 `Filter` 的
- * 「字段区回车 = 查询」就搭在这里，构造 `Filter` 时**不必**再套一层只为挂事件的壳
- * （那会改变 `class` / `style` 的落点）。要不要拦、拦哪些按键由调用方自己判断，本件只转发。
- * **有意只开这一条**：其它监听器不转发，扩张要先当一次公开行为变更裁决。
+ * `onKeydown` 是本件的**声明式入口**（缺省不绑）：本件是 `inheritAttrs: false`，根节点只显式绑
+ * `class` / `style`，不声明的监听器会被静默丢掉。根节点即「全部字段行的容器」，故它是「字段区层面的委托」
+ * 的落点 —— `Filter` 的「字段区回车 = 查询」就搭在这里，构造 `Filter` 时**不必**再套一层只为挂事件的壳
+ * （那会改变 `class` / `style` 的落点）。要不要拦、拦哪些按键由调用方判断，本件只转发；**有意只开这一条**，
+ * 其它监听器不转发，扩张要先当一次公开行为变更裁决。
  *
  * ## 只读值（摘要 / 详情）
- *
- * 「向导最后一步的确认摘要」「详情弹窗」不需要另起一套描述列表件 —— 只用表单行本身，
- * 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}>
- *   <Form.Item label="编码" required error={errors.code} hint="保存后不可修改">
- *     <Input modelValue={form.code} onChange={(v) => (form.code = v)} />
- *   </Form.Item>
- *   <Form.Item label="缓存策略" controlWidth={360} tip="命中即不请求后端">
- *     <Select options={cacheOptions} modelValue={form.cache} onChange={…} />
- *   </Form.Item>
- *   <Form.Item label="过滤条件" fullWidth>
- *     <Textarea modelValue={form.filter} onChange={…} />
- *   </Form.Item>
- * </Form>
+ * 「向导最后一步的确认摘要」「详情弹窗」不需要另起一套描述列表件 —— 只用表单行本身（label 列宽 / 行距 /
+ * 错误与说明全部复用），控件位放**只读 + 无框**的输入框即可（本件不给「静态文本」形态：那套几何与输入框
+ * 迟早会漂开）。几何与可编辑行完全一致；没有「可编辑」的线索（不显悬停底色、不给聚焦框与主色环，仍可点
+ * 进去选中 / 复制）；**空值占位归业务**（组件不替你把 `''` 显示成 `—`）；传 `readonly` 把 label 降一档
+ * 次要色；控件位是徽标 / 链接这类**非文本**只读内容时同样传 `readonly`，内容直接走默认插槽。
  */
 export declare const FormItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
@@ -396,10 +293,7 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
     default?: (scope: FormItemSlotScope) => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 export interface FormHeaderProps {
-    /**
-     * 表单头标题。不传则该行不渲染标题文本 —— 但给了 `extra` 时这一行**照渲染**
-     * （右端操作位不能凭空消失，与 `Panel`「只给 toolbar / actions、不给 title」同一条口径）。
-     */
+    /** 表单头标题。不传则该行不渲染标题文本 —— 但给了 `extra` 时这一行**照渲染**（右端操作位不能凭空消失，与 `Panel`「只给 toolbar / actions、不给 title」同口径）。 */
     title?: string;
     /** 标题下的说明小字（一行话，讲清这块表单是做什么的） */
     description?: string;
@@ -412,17 +306,6 @@ export interface FormHeaderProps {
  *
  * 它只做**标题排版**与操作位，不承担区块分组（那是 `Panel` 的职责）；三样（`title` /
  * `extra` / `description`）都没有时整组不渲染 —— 空盒子同样占一档 `Form` 的 gap，会凭空多出间距。
- *
- * @example 筛选条的头（标题 + 右侧查询/重置）—— 插槽走 `h()` 的对象形态：
- * TSX 的 `v-slots={{…}}` 在 vitest 的 JSX 管线里会被当**普通属性**丢掉（见 `list-view/index.tsx` 同款记录）
- * {h(Form, {}, {
- *   default: () => [
- *     h(Form.Header, { title: '高级筛选' }, { extra: () => h(Button, { variant: 'primary' }, '筛选') }),
- *     h(Form.Item, { name: 'keyword', label: '技能名称' }, { default: () => h(Input) }),
- *   ],
- * })}
- *
- * @example 只要操作位（不要标题）：`h(Form.Header, {}, { extra: () => … })`
  */
 export declare const FormHeader: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     title: {
@@ -482,19 +365,14 @@ export declare const Form: {
             default: undefined;
         };
         /**
-         * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
-         *
-         * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+         * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。窄容器（抽屉 / 移动端）与「字段名很
+         * 长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
          */
         layout: {
             type: PropType<"horizontal" | "vertical">;
             default: string;
         };
-        /**
-         * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
-         *
-         * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
-         */
+        /** 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径），长表单也可以调松。 */
         gap: {
             type: NumberConstructor;
             default: undefined;
@@ -577,19 +455,14 @@ export declare const Form: {
             default: undefined;
         };
         /**
-         * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
-         *
-         * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+         * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。窄容器（抽屉 / 移动端）与「字段名很
+         * 长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
          */
         layout: {
             type: PropType<"horizontal" | "vertical">;
             default: string;
         };
-        /**
-         * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
-         *
-         * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
-         */
+        /** 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径），长表单也可以调松。 */
         gap: {
             type: NumberConstructor;
             default: undefined;
@@ -665,19 +538,14 @@ export declare const Form: {
         default: undefined;
     };
     /**
-     * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
-     *
-     * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+     * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。窄容器（抽屉 / 移动端）与「字段名很
+     * 长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
      */
     layout: {
         type: PropType<"horizontal" | "vertical">;
         default: string;
     };
-    /**
-     * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
-     *
-     * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
-     */
+    /** 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径），长表单也可以调松。 */
     gap: {
         type: NumberConstructor;
         default: undefined;

package/dist/components/form/index.js

@@ -230,19 +230,14 @@ const FormRoot = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。
-     *
-     * 窄容器（抽屉 / 移动端）与「字段名很长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
+     * 排布：`horizontal`（label 在左，缺省）/ `vertical`（label 在控件上方）。窄容器（抽屉 / 移动端）与「字段名很
+     * 长」的场景请用纵向 —— 横向时 label 列宽会把控件压得很窄。
      */
     layout: {
       type: String,
       default: "horizontal"
     },
-    /**
-     * 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。
-     *
-     * 筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径）；长表单也可以调松。
-     */
+    /** 行距（px，字段行之间 / 与 `Form.Header` 之间）；缺省沿用样式里的 8px 档。筛选条这类「上行 + 一行字段」的紧凑排布要 16（设计稿口径），长表单也可以调松。 */
     gap: {
       type: Number,
       default: void 0
@@ -316,10 +311,8 @@ const FormRoot = /* @__PURE__ */ defineComponent({
       /** 当前快照（含全部已登记字段） */
       getValues: () => values.value,
       /**
-       * 清空全部字段（置 `undefined`；受控模式下同样会发 `update:modelValue`）。
-       *
-       * **返回清空后的快照**：受控时外部还没回写 `modelValue`，调用方此刻再 `getValues()`
-       * 会读到清空前的旧值 —— 直接吃返回值才不依赖回写时序。
+       * 清空全部字段（置 `undefined`；受控模式下同样会发 `update:modelValue`）。**返回清空后的快照**：受控时外部
+       * 还没回写 `modelValue`，调用方此刻再 `getValues()` 会读到清空前的旧值 —— 直接吃返回值才不依赖回写时序。
        */
       clear: () => {
         const cleared = {};

package/dist/components/input/bordered.d.ts

@@ -1,10 +1,8 @@
 /**
- * `bordered` 三档 → 控件类名（**唯一来源**）。
- *
- * 输入族三个件（`Input` / `Textarea` / `NumberInput`）共用同一份面与同一个 prop，判定表抄三份必然漂，
- * 故收在这里。类名口径：prop 是**肯定式**（`bordered`）、类名是**否定式**（`--borderless`）——
- * 那一对的反差是库内既定口径（见 `docs/guide/naming-and-defaults.md` §2.1）；
- * `'focus'` 档的类名 `--border-on-focus` 是这套口径下的新成员：它说的就是「聚焦时才有框」。
+ * `bordered` 三档 → 控件类名（**唯一来源**）：输入族三个件（`Input` / `Textarea` / `NumberInput`）共用同一份面与同一个
+ * prop，判定表抄三份必然漂，故收在这里。类名口径：prop 是**肯定式**（`bordered`）、类名是**否定式**（`--borderless`）
+ * —— 那对反差是库内既定口径（见 `docs/guide/naming-and-defaults.md` §2.1）；`'focus'` 档的
+ * `.mh-input--border-on-focus` 是这套口径下的新成员（它说的就是「聚焦时才有框」）。
  *
  * | `bordered` | 类名 | 常态 | 悬停 | 聚焦 |
  * | --- | --- | --- | --- | --- |