@manohub/ui 1.0.5 → 1.0.6

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

@@ -6,18 +6,16 @@ export type DrawerSide = 'left' | 'right';
  *
  * ## 与 `Dialog` 的关系：同一套行为，只换落位
  *
- * 模态语义、Esc、焦点陷阱、`::backdrop` 遮罩、top layer 渲染都是**原生 `<dialog>`** 给的，
- * 本件因此与 `Dialog` 共用同一条「JS 只做原生做不到的那两件」的取舍：
- * ① 把受控的 `open` 同步到原生 API（`open` 变真 → `showModal()`，变假 → `close()`）；
- * ② 内建底栏的「确定」在 `onOk` 返回 Promise 时自动进加载态并吞重复点击。
+ * 模态语义、Esc、焦点陷阱、`::backdrop` 遮罩、top layer 渲染都是**原生 `<dialog>`** 给的，本件因此与
+ * `Dialog` 共用同一条「JS 只做原生做不到的那两件」的取舍：① 把受控的 `open` 同步到原生 API（真 →
+ * `showModal()`，假 → `close()`）；② 内建底栏的「确定」在 `onOk` 返回 Promise 时自动进加载态并吞重复点击。
  * 差异只有一条：本件贴屏幕某一侧、**整屏高**，而不是视口居中。
- *
- * **不另开一套浮层机制**：抽屉不是「新的定位体系」，是同一张面板换个落位 ——
- * 所以类名同样并列 `.mh-popup`（操作层状态根）+ 本族皮肤，开合、遮罩、UA 装饰归零全部免费继承。
+ * **不另开一套浮层机制**：抽屉不是「新的定位体系」，是同一张面板换个落位 —— 故类名同样并列 `.mh-popup`
+ * （操作层状态根）+ 本族皮肤，开合 / 遮罩 / UA 装饰归零全部免费继承。
  *
  * ## 关闭是受控的
  *
- * 关闭位、Esc（原生 `cancel` 事件）与点遮罩都只回调：`update:open(false)` + `onClose()` / `onCancel()`。
+ * 关闭位、Esc（原生 `cancel` 事件）与点遮罩都只回调（`update:open(false)` + `onClose()` / `onCancel()`）；
  * 可见性归消费方 —— 避免「组件自己消失、业务状态还以为开着」两套口径。
  *
  * ## 底栏三态（**由消费方按需选一**，不要混着用）
@@ -28,13 +26,7 @@ export type DrawerSide = 'left' | 'right';
  * | 给 `okText` / `onOk` | 内建底栏：`[取消] [确定]`，按钮就是本包 `Button` |
  * | `:show-footer="false"` | 不渲染底栏（纯展示抽屉） |
  *
- * @example 内建底栏
- * <Drawer v-model:open="visible" title="MCP 配置" width={640} :on-ok="save" :on-cancel="() => (visible = false)">
- *   …抽屉内容…
- * </Drawer>
- *
- * @example 右侧属性面板（窄、无底栏、自绘关闭位）
- * <Drawer v-model:open="visible" title="属性" :width="320" :show-footer="false">…</Drawer>
+ * 用法见 `docs/demos/drawer/`（每个维度一份可运行样例；文档页 `docs/components/drawer.md`）。
  */
 export declare const Drawer: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 受控开合 */

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

@@ -1,36 +1,29 @@
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 /**
  * 条件值：单值（文本 / 单选）或数组（多选）。数字与字符串同等对待（取值原样透传）。
+ *
+ * 用法见 `docs/demos/filter/`（每个维度一份可运行样例；文档页 `docs/components/filter.md`）。
  */
 export type FilterValue = string | number | Array<string | number>;
 /** 条件快照：`条件名 → 值`（未选条件的值为空串，语义是「不过滤」） */
 export type FilterValues = Record<string, FilterValue>;
 /**
- * 「全部」哨兵：选项值等于它即「不过滤」。
- *
- * 与既有查询方案（骨架层的筛选适配件）同词，便于迁移时**选项表原样搬运**；
- * 自绘场景更推荐直接用 `placeholder="全部"` 表达未选（本包 `Select` 把空串视为未选中，
- * 会显示占位文案）—— 两条路子的最终视觉一致，见 `docs/components/filter.md`。
+ * 「全部」哨兵：选项值等于它即「不过滤」。与既有查询方案（骨架层的筛选适配件）同词，便于迁移时**选项表原样搬运**；
+ * 自绘场景更推荐直接用 `placeholder="全部"` 表达未选（本包 `Select` 把空串视为未选中 → 显示占位文案）—— 两条路子
+ * 的最终视觉一致，见 `docs/components/filter.md`。
  */
 export declare const FILTER_ALL = "all";
 /**
- * 筛选时机：
- *
- * - `manual`（缺省）：值变化只回写快照（`onChange`），查询由**回车 / 「筛选」按钮**显式触发
- *   （`onQuery`）—— 适合「几个字段填完再查」的条件区；
- * - `auto`：值变化即查询（发 `onQuery`）—— 适合「改即查」的轻量条件区。
- *   此时**同一次变化不再发 `onChange`**（一个变化只对应一个事件，消费方两处都接也不会查两遍），
- *   且操作区默认不渲染（见 `showReset`）。
- *
- * 两种时机下**值变化都会发 `update:modelValue`**（`v-model` 落地不受时机影响）。
+ * 筛选时机：`manual`（缺省）—— 值变化只回写快照（`onChange`），查询由**回车 / 「筛选」按钮**显式触发
+ * （`onQuery`），适合「几个字段填完再查」的条件区；`auto` —— 值变化即查询（发 `onQuery`），适合「改即查」的轻量
+ * 条件区，此时**同一次变化不再发 `onChange`**（一个变化只对应一个事件，消费方两处都接也不会查两遍），且操作区
+ * 默认不渲染（见 `showReset`）。两种时机下**值变化都会发 `update:modelValue`**（`v-model` 落地不受时机影响）。
  */
 export type FilterTrigger = 'manual' | 'auto';
 /**
- * 筛选字段的作用域插槽：控件由消费方渲染，本件交出**归一后**的当前值。
- *
- * 与 `Form.Item` 的作用域同形，差别只在归一：筛选语义里「未选」一律是空串
- * （`'all'` 哨兵 / `null` / 空数组都归到空串），于是消费方直接把 `value` 绑给控件即可，
- * 不必自己处理哨兵——这是 `Filter.Item` 相对 `Form.Item` 唯一的增量。
+ * 筛选字段的作用域插槽：控件由消费方渲染，本件交出**归一后**的当前值。与 `Form.Item` 的作用域同形，差别只在归一：
+ * 筛选语义里「未选」一律是空串（`'all'` 哨兵 / `null` / 空数组都归到空串），故消费方直接把 `value` 绑给控件即可
+ * —— 这是 `Filter.Item` 相对 `Form.Item` 唯一的增量。
  */
 export interface FilterItemSlotScope {
     /** 当前条件值（已归一：空串 = 未选） */
@@ -41,11 +34,9 @@ export interface FilterItemSlotScope {
     clear: () => void;
 }
 /**
- * 归一（读与写**同一份实现**，两处不各写一套）：
- * - `'all'`（哨兵）/ `''` / `null` / `undefined` → `''`（= 不过滤）；
- * - 数组逐项归一后去空，全空 → `''`；**只剩一项仍是数组**（多选值的类型不降级成标量）；
- * - 数字原样（`0` 是有效值，不是「空」）；
- * - 其余原样（不做 trim：归一不负责改写用户输入）。
+ * 归一（读与写**同一份实现**，两处不各写一套）：`'all'`（哨兵）/ `''` / `null` / `undefined` → `''`（= 不过滤）；
+ * 数组逐项归一后去空、全空 → `''`（**只剩一项仍是数组**，多选值的类型不降级成标量）；数字原样（`0` 是有效值，
+ * 不是「空」）；其余原样（不做 trim：归一不负责改写用户输入）。
  */
 export declare function normalizeFilterValue(value: FilterValue | null | undefined): FilterValue;
 export interface FilterProps {
@@ -53,12 +44,7 @@ export interface FilterProps {
     title?: string;
     /** 标题下的说明小字（透传给 `Form.Header`） */
     description?: string;
-    /**
-     * label 列宽（px），透传给 `Form`。
-     *
-     * **缺省不设**：不传即与 `Form` 一致（取令牌 `--ui-form-label-width`，120）。
-     * 想收窄（筛选条的标签多为四字）就显式传，例如 `labelWidth={68}`。
-     */
+    /** label 列宽（px），透传给 `Form`；**缺省不设**（不传即与 `Form` 一致，取令牌 `--ui-form-label-width` = 120）。想收窄（筛选条标签多为四字）就显式传，如 `labelWidth={68}`。 */
     labelWidth?: number;
     /** 受控条件快照（`条件名 → 值`）；不传即非受控（由 `defaultValue` 起） */
     modelValue?: FilterValues;
@@ -68,15 +54,9 @@ export interface FilterProps {
     queryText?: string;
     /** 「重置」按钮文案 */
     resetText?: string;
-    /**
-     * 是否渲染「重置」按钮 —— **两档的缺省口径不同**（故本项缺省是 `undefined` 而非 `true`）：
-     * `manual` 缺省渲染（`:show-reset="false"` 才隐藏）；`auto` 缺省**不**渲染（显式传 `true` 才留一颗）。
-     */
+    /** 是否渲染「重置」按钮 —— **两档缺省口径不同**（故缺省是 `undefined` 而非 `true`）：`manual` 缺省渲染，`auto` 缺省**不**渲染（显式 `true` 才留一颗）。 */
     showReset?: boolean;
-    /**
-     * 筛选时机：`manual`（缺省）值变化只回写、查询靠「筛选」按钮 / 字段区回车；
-     * `auto` 值变化**即**查询，且操作区默认不渲染（详见组件说明「筛选时机」一节）。
-     */
+    /** 筛选时机：`manual`（缺省）值变化只回写、查询靠「筛选」按钮 / 字段区回车；`auto` 值变化**即**查询，且操作区默认不渲染（详见组件说明「筛选时机」）。 */
     trigger?: FilterTrigger;
     /** 条件值变化（快照已归一）。**`auto` 下不发** —— 同一次变化改走 `onQuery` */
     onChange?: (values: FilterValues) => void;
@@ -106,13 +86,6 @@ export interface FilterItemProps {
  *
  * 字段宽**自适应**：字段区是 `Form` 的多列动态档（`Filter` 传 `columns="auto"`），
  * 故本件只输出 `Form.Item` 自己的类 —— 列宽由那条网格轨道算，换行下来的字段与上一行逐列对齐。
- *
- * @example
- * <Filter.Item code="status" label="授权状态">
- *   {{ default: ({ value, setValue }) => (
- *       <Select options={statusOptions} modelValue={String(value)} placeholder="全部" onChange={setValue} />
- *     ) }}
- * </Filter.Item>
  */
 export declare const FilterItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     code: {
@@ -196,14 +169,9 @@ export declare const Filter: {
             default: string;
         };
         /**
-         * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
-         *
-         * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
-         * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
-         *   要留一颗重置按钮就得**显式**写 `show-reset`。
-         *
-         * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
-         * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+         * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`、不是 `true`）：`manual` 缺省**渲染**
+         * （只有显式 `:show-reset="false"` 才隐藏）；`auto` 缺省**不渲染**（操作区整块让位给字段，要留一颗就得**显式**写
+         * `show-reset`）。自动模式下一键清空的另一条路是各字段自带的清除位，或页面级入口。
          */
         showReset: {
             type: BooleanConstructor;
@@ -282,14 +250,9 @@ export declare const Filter: {
             default: string;
         };
         /**
-         * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
-         *
-         * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
-         * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
-         *   要留一颗重置按钮就得**显式**写 `show-reset`。
-         *
-         * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
-         * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+         * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`、不是 `true`）：`manual` 缺省**渲染**
+         * （只有显式 `:show-reset="false"` 才隐藏）；`auto` 缺省**不渲染**（操作区整块让位给字段，要留一颗就得**显式**写
+         * `show-reset`）。自动模式下一键清空的另一条路是各字段自带的清除位，或页面级入口。
          */
         showReset: {
             type: BooleanConstructor;
@@ -361,14 +324,9 @@ export declare const Filter: {
         default: string;
     };
     /**
-     * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
-     *
-     * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
-     * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
-     *   要留一颗重置按钮就得**显式**写 `show-reset`。
-     *
-     * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
-     * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+     * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`、不是 `true`）：`manual` 缺省**渲染**
+     * （只有显式 `:show-reset="false"` 才隐藏）；`auto` 缺省**不渲染**（操作区整块让位给字段，要留一颗就得**显式**写
+     * `show-reset`）。自动模式下一键清空的另一条路是各字段自带的清除位，或页面级入口。
      */
     showReset: {
         type: BooleanConstructor;

package/dist/components/filter/index.js

@@ -51,14 +51,9 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       default: "重置"
     },
     /**
-     * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
-     *
-     * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
-     * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
-     *   要留一颗重置按钮就得**显式**写 `show-reset`。
-     *
-     * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
-     * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+     * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`、不是 `true`）：`manual` 缺省**渲染**
+     * （只有显式 `:show-reset="false"` 才隐藏）；`auto` 缺省**不渲染**（操作区整块让位给字段，要留一颗就得**显式**写
+     * `show-reset`）。自动模式下一键清空的另一条路是各字段自带的清除位，或页面级入口。
      */
     showReset: {
       type: Boolean,

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

@@ -5,26 +5,25 @@ export type FormPadding = Padding;
 /** label 列的水平对齐：`right`（默认，与 farris / 主流水平表单一致）或 `left` */
 export type FormLabelAlign = 'left' | 'right';
 /**
- * 字段行的排布档：`1`（默认，逐行）；`2 ~ 6`（**列数上限** —— 放得下 N 列就并排，放不下少排一列，不会
- * 把控件压成窄条；5 / 6 是给宽屏展示页的，默认最小宽 320 下要容器 1632 / 1960px）；`'auto'`（**列数随容器
- * 宽度动态变化**，每列宽由 `columnMinWidth` 决定）。
- *
- * 两类的差别是**可预期性**（不是能力高低）：数字档承诺「最多 N 列」，够宽的容器里「哪几个字段同排」是
- * 确定的；动态档会一路排下去、窄了就减，同一个表单在不同容器里列数不同 ⇒ **字段的相对位置会变**
- * —— 要「两个字段必须并肩」就别用它。
+ * 字段行的排布档：`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`（默认，与控件**中线**对齐，单行控件用）；
- * `start`（与控件**首行文字**对齐，多行控件与整块内容用，否则 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 里的原值，不做任何归一） */
@@ -37,41 +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`，见下）。
+     * 表单级控件列宽上限（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**（表单贴容器边，内距由所在容器给）；弹窗 / 抽屉里没有别的容器给内距时用它自带
-     * （如 `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;
     /** 非受控初值；其中的键会一并成为快照的键（不必等字段挂载） */
@@ -79,81 +71,51 @@ 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;
 }
 /**
@@ -207,19 +169,6 @@ export interface FormItemProps {
  * 迟早会漂开）。几何与可编辑行完全一致；没有「可编辑」的线索（不显悬停底色、不给聚焦框与主色环，仍可点
  * 进去选中 / 复制）；**空值占位归业务**（组件不替你把 `''` 显示成 `—`）；传 `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>
  */
 export declare const FormItem: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 字段名（绑定的键）；不传即纯布局行（值由消费方自己在控件上绑定） */
@@ -344,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;
@@ -360,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: {
@@ -430,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;
@@ -525,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;
@@ -613,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` | 类名 | 常态 | 悬停 | 聚焦 |
  * | --- | --- | --- | --- | --- |