@manohub/ui 0.10.2 → 0.10.4

package/README.md

@@ -62,7 +62,7 @@ import { Card, Form, Tree, Checkbox } from '@manohub/ui'
 | 分组 | 组件 |
 |---|---|
 | 容器与分区 | `Page`（页面级骨架：`.Header` / `.Body` / `.Footer` / `.Filter` / `.Toolbar` / `.Split`）、`Panel`（+ `.Header` / `.Body` / `.Footer`）、`Card`（+ 三件）、`Nav`、`Layout`（`Layout.Row` 排「行」/ `Layout.Column` 排「列」：轴向 × 间距档 × 对齐） |
-| 数据展示 | `Tree`、`ListView`（+ `.CardItem`）、`Badge`、`Tag`（常规 / 状态 / 可选 / 新增 / 筛选片） |
+| 数据展示 | `Tree`、`ListView`（+ `.CardItem`）、`Badge`、`Tag`（`Badge` 的可关闭 / 可新增封装） |
 | 展示 | `Avatar`（+ `.Group`）、`Skeleton`（行 / 列表 / 块状） |
 | 表单基础（**自绘**） | `Button`（+ `.Group` / `.Divider`；五型 / 小号 / 加载 / 菜单按钮 / 连体切换）、`Input`（+ `.Group` / `.Chip` / `.Display` / `.Textarea`；清除 / 可见性切换 / 校验）、`Search`（搜索框：值 / 搜索 / 清空三条回调）、`Select`（单选 / 多选 / 搜索 / 加载；面板用原生 popover）、`SelectTree`（树形态：仅叶子可选 + 本地过滤 + 命中高亮；与 `Select` 平级导出、共用触发器与面板）、`Switch`（表格档 / 表单档） |
 | 表单与选择 | `Form`（+ `.Header` / `.Item`；标签体系、成员归位、`v-model` 值收集与命令式 `clear()`）、`Filter`（+ `.Item`；`Form` 的壳：条件字段写成子件、控件自放、查询/重置与快照归一）、`Checkbox`、`Radio`（+ `.Group` / `.Card`；卡片式单选）、`Capsule`（胶囊选择器；胶囊 / 方形两档外形，与 `Tabs` 组合即页签） |

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

@@ -19,6 +19,13 @@ export type BadgeStatus = 'success' | 'processing' | 'default' | 'warning' | 'er
  * - `outline`：浅底 + 同色描边；`tone="default"` 时退化为白底 + 中性描边 + 正文色（状态胶囊）
  * - `plain`：无底无框，靠圆点表达状态
  *
+ * **本件是「只读标记」的唯一样式源**：`Tag`（可关闭 / 可新增）只是在本件之上加交互位，
+ * 几何与色彩一行都不重写 —— 改本件的档位，两件一起走（见 `components/tag/index.tsx`）。
+ *
+ * **属性落点**：`class` / `style` 有专口（并入档位类、随档位内联），**其余 attrs 一律透传到根元素**
+ * （`id` / `aria-*` / `data-*` / `title` / 原生事件）—— 停在组件上等于丢掉（`Tag` 的「新增」
+ * 就靠这条把 `onClick` 落到那颗按钮上），见 `forwardAttrs`。
+ *
  * @example 内容徽标
  * <Badge tone="success" shape="outline" size="md" dot="filled">运行中</Badge>
  *
@@ -28,6 +35,9 @@ export type BadgeStatus = 'success' | 'processing' | 'default' | 'warning' | 'er
  *
  * @example 状态点
  * <Badge status="processing" text="运行中" />
+ *
+ * @example 可点形态（复合件用；`Tag` 的「新增」即此形 + 本件自己的遮罩）
+ * <Badge as="button" tone="warning" onClick={() => add()}>新增</Badge>
  */
 export declare const Badge: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     tone: {
@@ -73,6 +83,23 @@ export declare const Badge: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         default: undefined;
     };
+    /**
+     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。
+     *
+     * `Tag` 就是靠它拿到「可点」的：徽标是**只读标记**的唯一样式源，`Tag` 只往上加
+     * 关闭位与新增位，不再自己画一遍框（见 `components/tag/index.tsx`）。
+     * `as="button"` 会渲染真实 `<button type="button">`（`type` 不能省：缺省是 `submit`，
+     * 放进表单会提交），并保留本件全部档位类与几何 —— 按钮的外观缺三项由本件面自带
+     * （`border` / `background` / `padding`，见 `contract-reset.spec.ts` 的第三组），
+     * `font-family: inherit` 在 `badge.css` 的基块补（UA 会把按钮字形换成 Arial）。
+     *
+     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），
+     * 传了它们就忽略本 prop（那时走各自的分支，根仍是 `<span>`）。
+     */
+    as: {
+        type: PropType<"span" | "button">;
+        default: string;
+    };
 }>, () => import("vue/jsx-runtime").JSX.Element | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
     tone: {
         type: PropType<BadgeTone>;
@@ -117,16 +144,34 @@ export declare const Badge: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         default: undefined;
     };
+    /**
+     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。
+     *
+     * `Tag` 就是靠它拿到「可点」的：徽标是**只读标记**的唯一样式源，`Tag` 只往上加
+     * 关闭位与新增位，不再自己画一遍框（见 `components/tag/index.tsx`）。
+     * `as="button"` 会渲染真实 `<button type="button">`（`type` 不能省：缺省是 `submit`，
+     * 放进表单会提交），并保留本件全部档位类与几何 —— 按钮的外观缺三项由本件面自带
+     * （`border` / `background` / `padding`，见 `contract-reset.spec.ts` 的第三组），
+     * `font-family: inherit` 在 `badge.css` 的基块补（UA 会把按钮字形换成 Arial）。
+     *
+     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），
+     * 传了它们就忽略本 prop（那时走各自的分支，根仍是 `<span>`）。
+     */
+    as: {
+        type: PropType<"span" | "button">;
+        default: string;
+    };
 }>> & Readonly<{}>, {
     text: string;
     size: BadgeSize;
     dot: boolean | BadgeDot;
     shape: BadgeShape;
     count: number;
-    status: BadgeStatus;
     tone: BadgeTone;
     overflowCount: number;
     showZero: boolean;
+    status: BadgeStatus;
+    as: "button" | "span";
 }, SlotsType<{
     default?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/components/badge/index.js

@@ -1,4 +1,4 @@
-import { defineComponent, computed, createVNode } from "vue";
+import { defineComponent, computed, createVNode, mergeProps, Fragment } from "vue";
 const STATUS_TONE = {
   success: "success",
   processing: "primary",
@@ -52,6 +52,23 @@ const Badge = /* @__PURE__ */ defineComponent({
     text: {
       type: String,
       default: void 0
+    },
+    /**
+     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。
+     *
+     * `Tag` 就是靠它拿到「可点」的：徽标是**只读标记**的唯一样式源，`Tag` 只往上加
+     * 关闭位与新增位，不再自己画一遍框（见 `components/tag/index.tsx`）。
+     * `as="button"` 会渲染真实 `<button type="button">`（`type` 不能省：缺省是 `submit`，
+     * 放进表单会提交），并保留本件全部档位类与几何 —— 按钮的外观缺三项由本件面自带
+     * （`border` / `background` / `padding`，见 `contract-reset.spec.ts` 的第三组），
+     * `font-family: inherit` 在 `badge.css` 的基块补（UA 会把按钮字形换成 Arial）。
+     *
+     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），
+     * 传了它们就忽略本 prop（那时走各自的分支，根仍是 `<span>`）。
+     */
+    as: {
+      type: String,
+      default: "span"
     }
   },
   slots: Object,
@@ -59,6 +76,13 @@ const Badge = /* @__PURE__ */ defineComponent({
     slots,
     attrs
   }) {
+    const forwardAttrs = computed(() => {
+      const rest = {};
+      for (const [key, value] of Object.entries(attrs)) {
+        if (key !== "class" && key !== "style") rest[key] = value;
+      }
+      return rest;
+    });
     const countText = computed(() => {
       if (props.count === void 0) return null;
       if (props.count === 0 && !props.showZero) return null;
@@ -69,28 +93,37 @@ const Badge = /* @__PURE__ */ defineComponent({
       const style = attrs.style;
       const extra = attrs.class;
       if (props.status) {
-        return createVNode("span", {
+        return createVNode("span", mergeProps(forwardAttrs.value, {
           "class": ["mh-badge--status", `mh-badge--${STATUS_TONE[props.status]}`, extra].filter(Boolean).join(" "),
           "style": style
-        }, [createVNode("span", {
+        }), [createVNode("span", {
           "class": "mh-badge__status-dot"
         }, null), props.text ?? slots.default?.()]);
       }
       if (props.count !== void 0) {
         if (countText.value === null && !slots.default) return null;
-        return createVNode("span", {
+        return createVNode("span", mergeProps(forwardAttrs.value, {
           "class": ["mh-badge--count", extra].filter(Boolean).join(" "),
           "style": style
-        }, [slots.default?.(), countText.value !== null ? createVNode("sup", {
+        }), [slots.default?.(), countText.value !== null ? createVNode("sup", {
           "class": ["mh-badge__count", `mh-badge--${props.tone}`].join(" ")
         }, [countText.value]) : null]);
       }
-      return createVNode("span", {
-        "class": ["mh-badge", `mh-badge--${props.tone}`, `mh-badge--${props.shape}`, `mh-badge--${props.size}`, dotKind.value ? `mh-badge--dot-${dotKind.value}` : "", extra].filter(Boolean).join(" "),
-        "style": style
-      }, [dotKind.value ? createVNode("span", {
+      const classes = ["mh-badge", `mh-badge--${props.tone}`, `mh-badge--${props.shape}`, `mh-badge--${props.size}`, dotKind.value ? `mh-badge--dot-${dotKind.value}` : "", extra].filter(Boolean).join(" ");
+      const content = createVNode(Fragment, null, [dotKind.value ? createVNode("span", {
         "class": "mh-badge__dot"
       }, null) : null, slots.default?.()]);
+      if (props.as === "button") {
+        return createVNode("button", mergeProps(forwardAttrs.value, {
+          "type": "button",
+          "class": classes,
+          "style": style
+        }), [content]);
+      }
+      return createVNode("span", mergeProps(forwardAttrs.value, {
+        "class": classes,
+        "style": style
+      }), [content]);
     };
   }
 });

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

@@ -76,7 +76,7 @@ export type CardHeaderIcon = string | (() => VNodeChild);
  * @example 技能卡（图标 + 标题/副标题 + 右端状态 + 正文 + 操作行）
  * <Card>
  *   <Card.Header icon={skill.icon} title={skill.name} subtitle={`V${skill.version}`}>
- *     <template #extra><Tag shape="status" tone="success">已发布</Tag></template>
+ *     <template #extra><Badge shape="soft" tone="success">已发布</Badge></template>
  *   </Card.Header>
  *   <Card.Body>{skill.description}</Card.Body>
  *   <template #actions><Button size="sm">编辑</Button></template>

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

@@ -221,6 +221,7 @@ export declare const Drawer: import("vue").DefineComponent<import("vue").Extract
     onClose: () => void;
     width: string | number;
     closable: boolean;
+    side: DrawerSide;
     closeOnBackdrop: boolean;
     maskClosable: boolean;
     keyboard: boolean;
@@ -230,7 +231,6 @@ export declare const Drawer: import("vue").DefineComponent<import("vue").Extract
     confirmLoading: boolean;
     showFooter: boolean | undefined;
     onOk: () => unknown;
-    side: DrawerSide;
 }, SlotsType<{
     default?: () => VNodeChild;
     title?: () => VNodeChild;

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

@@ -13,6 +13,18 @@ export type FilterValues = Record<string, FilterValue>;
  * 会显示占位文案）—— 两条路子的最终视觉一致，见 `docs/components/filter.md`。
  */
 export declare const FILTER_ALL = "all";
+/**
+ * 筛选时机：
+ *
+ * - `manual`（缺省）：值变化只回写快照（`onChange`），查询由**回车 / 「筛选」按钮**显式触发
+ *   （`onQuery`）—— 适合「几个字段填完再查」的条件区；
+ * - `auto`：值变化即查询（发 `onQuery`）—— 适合「改即查」的轻量条件区。
+ *   此时**同一次变化不再发 `onChange`**（一个变化只对应一个事件，消费方两处都接也不会查两遍），
+ *   且操作区默认不渲染（见 `showReset`）。
+ *
+ * 两种时机下**值变化都会发 `update:modelValue`**（`v-model` 落地不受时机影响）。
+ */
+export type FilterTrigger = 'manual' | 'auto';
 /**
  * 筛选字段的作用域插槽：控件由消费方渲染，本件交出**归一后**的当前值。
  *
@@ -56,11 +68,19 @@ export interface FilterProps {
     queryText?: string;
     /** 「重置」按钮文案 */
     resetText?: string;
-    /** 是否渲染「重置」按钮（缺省渲染） */
+    /**
+     * 是否渲染「重置」按钮 —— **两档的缺省口径不同**（故本项缺省是 `undefined` 而非 `true`）：
+     * `manual` 缺省渲染（`:show-reset="false"` 才隐藏）；`auto` 缺省**不**渲染（显式传 `true` 才留一颗）。
+     */
     showReset?: boolean;
-    /** 条件值变化（快照已归一） */
+    /**
+     * 筛选时机：`manual`（缺省）值变化只回写、查询靠「筛选」按钮 / 字段区回车；
+     * `auto` 值变化**即**查询，且操作区默认不渲染（详见组件说明「筛选时机」一节）。
+     */
+    trigger?: FilterTrigger;
+    /** 条件值变化（快照已归一）。**`auto` 下不发** —— 同一次变化改走 `onQuery` */
     onChange?: (values: FilterValues) => void;
-    /** 「筛选」按钮 / 字段区回车（回车只作用于输入框，且不认浮层里的输入） */
+    /** 「筛选」按钮 / 字段区回车（回车只作用于输入框，且不认浮层里的输入）；**`auto` 下由值变化触发** */
     onQuery?: (values: FilterValues) => void;
     /** 「重置」按钮：全部条件清空（**不再触发 `onChange`**，避免与重置回调双触发） */
     onReset?: (values: FilterValues) => void;
@@ -175,9 +195,24 @@ export declare const Filter: {
             type: StringConstructor;
             default: string;
         };
+        /**
+         * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
+         *
+         * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
+         * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
+         *   要留一颗重置按钮就得**显式**写 `show-reset`。
+         *
+         * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
+         * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+         */
         showReset: {
             type: BooleanConstructor;
-            default: boolean;
+            default: undefined;
+        };
+        /** 筛选时机：`manual`（缺省，回车 / 「筛选」按钮查询）/ `auto`（值变化即查询，操作区默认不渲染） */
+        trigger: {
+            type: PropType<FilterTrigger>;
+            default: string;
         };
         onChange: {
             type: PropType<(values: FilterValues) => void>;
@@ -202,6 +237,7 @@ export declare const Filter: {
         defaultValue: FilterValues;
         modelValue: FilterValues;
         description: string;
+        trigger: FilterTrigger;
         labelWidth: number;
         queryText: string;
         resetText: string;
@@ -245,9 +281,24 @@ export declare const Filter: {
             type: StringConstructor;
             default: string;
         };
+        /**
+         * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
+         *
+         * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
+         * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
+         *   要留一颗重置按钮就得**显式**写 `show-reset`。
+         *
+         * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
+         * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+         */
         showReset: {
             type: BooleanConstructor;
-            default: boolean;
+            default: undefined;
+        };
+        /** 筛选时机：`manual`（缺省，回车 / 「筛选」按钮查询）/ `auto`（值变化即查询，操作区默认不渲染） */
+        trigger: {
+            type: PropType<FilterTrigger>;
+            default: string;
         };
         onChange: {
             type: PropType<(values: FilterValues) => void>;
@@ -270,6 +321,7 @@ export declare const Filter: {
         defaultValue: FilterValues;
         modelValue: FilterValues;
         description: string;
+        trigger: FilterTrigger;
         labelWidth: number;
         queryText: string;
         resetText: string;
@@ -308,9 +360,24 @@ export declare const Filter: {
         type: StringConstructor;
         default: string;
     };
+    /**
+     * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
+     *
+     * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
+     * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
+     *   要留一颗重置按钮就得**显式**写 `show-reset`。
+     *
+     * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
+     * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+     */
     showReset: {
         type: BooleanConstructor;
-        default: boolean;
+        default: undefined;
+    };
+    /** 筛选时机：`manual`（缺省，回车 / 「筛选」按钮查询）/ `auto`（值变化即查询，操作区默认不渲染） */
+    trigger: {
+        type: PropType<FilterTrigger>;
+        default: string;
     };
     onChange: {
         type: PropType<(values: FilterValues) => void>;
@@ -335,6 +402,7 @@ export declare const Filter: {
     defaultValue: FilterValues;
     modelValue: FilterValues;
     description: string;
+    trigger: FilterTrigger;
     labelWidth: number;
     queryText: string;
     resetText: string;

package/dist/components/filter/index.js

@@ -1,4 +1,4 @@
-import { defineComponent, createVNode, ref, h, Fragment } from "vue";
+import { defineComponent, createVNode, ref, computed, h, Fragment } from "vue";
 import { Button } from "../button/index.js";
 import { FormItem, Form } from "../form/index.js";
 const FILTER_ALL = "all";
@@ -50,9 +50,24 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       type: String,
       default: "重置"
     },
+    /**
+     * 是否渲染「重置」按钮。**缺省值随时机而变**（故本 prop 缺省是 `undefined`，不是 `true`）：
+     *
+     * - `trigger="manual"`（缺省）：缺省**渲染**（只有显式 `:show-reset="false"` 才隐藏）；
+     * - `trigger="auto"`：缺省**不渲染** —— 自动模式下操作区整块让位给字段，
+     *   要留一颗重置按钮就得**显式**写 `show-reset`。
+     *
+     * 自动模式下一键清空的另一条路是各字段自带的清除位（控件自己的 `clearable`），
+     * 或页面级入口（`Form.Header` 的 `extra` 一侧）。
+     */
     showReset: {
       type: Boolean,
-      default: true
+      default: void 0
+    },
+    /** 筛选时机：`manual`（缺省，回车 / 「筛选」按钮查询）/ `auto`（值变化即查询，操作区默认不渲染） */
+    trigger: {
+      type: String,
+      default: "manual"
     },
     onChange: {
       type: Function,
@@ -82,6 +97,10 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       if (clearing) return;
       const snapshot2 = normalizeValues(values);
       emit("update:modelValue", snapshot2);
+      if (props.trigger === "auto") {
+        props.onQuery?.(snapshot2);
+        return;
+      }
       props.onChange?.(snapshot2);
     };
     const snapshot = () => normalizeValues(formRef.value?.getValues());
@@ -101,12 +120,14 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       event.preventDefault();
       query();
     };
-    const renderActions = () => createVNode(Fragment, null, [createVNode(Button, {
+    const showResetButton = computed(() => props.trigger === "auto" ? props.showReset === true : props.showReset !== false);
+    const hasActions = computed(() => props.trigger === "manual" || showResetButton.value);
+    const renderActions = () => createVNode(Fragment, null, [props.trigger === "manual" ? createVNode(Button, {
       "variant": "primary",
       "onClick": query
     }, {
       default: () => props.queryText
-    }), props.showReset ? createVNode(Button, {
+    }) : null, showResetButton.value ? createVNode(Button, {
       "variant": "secondary",
       "onClick": reset
     }, {
@@ -126,12 +147,19 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       default: () => {
         const raw = slots.default?.();
         const fields = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
-        return [h(Form.Header, {
-          title: props.title,
-          description: props.description
-        }, {
-          extra: renderActions
-        }), ...fields];
+        return [h(
+          Form.Header,
+          {
+            title: props.title,
+            description: props.description
+          },
+          /* 没有任何按钮时**不传** `extra`：`Form.Header` 认的是「插槽有没有传」，
+             传一个渲染成空的 slot 仍会撑出一行（右端空容器 + 一档行距），
+             且三样都没有时整块还会照常占位。 */
+          hasActions.value ? {
+            extra: renderActions
+          } : {}
+        ), ...fields];
       }
     });
   }

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

@@ -133,6 +133,21 @@ export interface FormItemProps {
     error?: string;
     /** 字段说明文案（常驻，排在错误之后） */
     hint?: string;
+    /**
+     * **label 旁的提示**（问号图标 + 悬停气泡，仅文本）。
+     *
+     * 与 `hint` 分工不同：`hint` 是**常驻**在控件下方的说明文案，`tip` 是**按需展开**的补充解释 ——
+     * 不占版面，只在悬停（或键盘聚焦）问号图标时出现，两者可以同时给。
+     *
+     * 图标排在 label 文本与必填星号**之后**（`服务名称*ⓘ`）；只给 `tip` 而不给 `label` 时同样保留
+     * label 列（与「只给 required」同一判据）—— 否则图标没有列可落、静默消失。
+     *
+     * 用的是 `Tooltip` 的 **hover 档**（零 JS）：显隐与定位全在 CSS，移入 / 聚焦即显、移开即隐，
+     * 因此**不吃点击、不抢焦点**。代价一条：hover 档不进浏览器顶层浮层，会被祖先 `overflow` 裁切
+     * —— 弹窗 / 抽屉里贴着裁剪边的字段可能看不全（要顶层浮层就得换 `Tooltip trigger="click"`，
+     * 本件有意不暴露该维度，见文件头「label 提示」）。
+     */
+    tip?: string;
     /** 本行 label 列宽（px）；覆盖 `Form` 的表单级设置 */
     labelWidth?: number;
     /** 本行 label 对齐；覆盖 `Form` 的表单级设置 */
@@ -205,6 +220,18 @@ export interface FormItemProps {
  * `{ 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` 裁切（弹窗 / 抽屉里贴着裁剪边的字段可能看不全）。
+ *
  * ## 键盘事件（`onKeydown` 转发到根节点）
  *
  * `onKeydown` 是本件的**声明式入口**（缺省不绑）：传进来的处理器绑在根节点上 ——
@@ -238,7 +265,7 @@ export interface FormItemProps {
  *   <Form.Item label="编码" required error={errors.code} hint="保存后不可修改">
  *     <Input modelValue={form.code} onChange={(v) => (form.code = v)} />
  *   </Form.Item>
- *   <Form.Item label="缓存策略" controlWidth={360}>
+ *   <Form.Item label="缓存策略" controlWidth={360} tip="命中即不请求后端">
  *     <Select options={cacheOptions} modelValue={form.cache} onChange={…} />
  *   </Form.Item>
  *   <Form.Item label="过滤条件" fullWidth>
@@ -268,6 +295,11 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         type: StringConstructor;
         default: string;
     };
+    /** label 旁的提示文案（问号图标 + 悬停气泡）；口径见 `FormItemProps.tip` */
+    tip: {
+        type: StringConstructor;
+        default: string;
+    };
     labelWidth: {
         type: NumberConstructor;
         default: undefined;
@@ -316,6 +348,11 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
         type: StringConstructor;
         default: string;
     };
+    /** label 旁的提示文案（问号图标 + 悬停气泡）；口径见 `FormItemProps.tip` */
+    tip: {
+        type: StringConstructor;
+        default: string;
+    };
     labelWidth: {
         type: NumberConstructor;
         default: undefined;
@@ -350,6 +387,7 @@ export declare const FormItem: import("vue").DefineComponent<import("vue").Extra
     align: FormItemAlign;
     readonly: boolean;
     hint: string;
+    tip: string;
     labelWidth: number;
     labelAlign: FormLabelAlign;
     controlWidth: number;
@@ -730,6 +768,11 @@ export declare const Form: {
             type: StringConstructor;
             default: string;
         };
+        /** label 旁的提示文案（问号图标 + 悬停气泡）；口径见 `FormItemProps.tip` */
+        tip: {
+            type: StringConstructor;
+            default: string;
+        };
         labelWidth: {
             type: NumberConstructor;
             default: undefined;
@@ -778,6 +821,11 @@ export declare const Form: {
             type: StringConstructor;
             default: string;
         };
+        /** label 旁的提示文案（问号图标 + 悬停气泡）；口径见 `FormItemProps.tip` */
+        tip: {
+            type: StringConstructor;
+            default: string;
+        };
         labelWidth: {
             type: NumberConstructor;
             default: undefined;
@@ -812,6 +860,7 @@ export declare const Form: {
         align: FormItemAlign;
         readonly: boolean;
         hint: string;
+        tip: string;
         labelWidth: number;
         labelAlign: FormLabelAlign;
         controlWidth: number;

package/dist/components/form/index.js

@@ -1,5 +1,7 @@
 import { defineComponent, inject, watch, createVNode, createTextVNode, provide, toRef, ref, computed, isVNode } from "vue";
+import { Icon } from "@manohub/icon";
 import { mergePartStyle } from "../part-padding.js";
+import { Tooltip } from "../tooltip/index.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");
@@ -29,6 +31,11 @@ const FormItem = /* @__PURE__ */ defineComponent({
       type: String,
       default: ""
     },
+    /** label 旁的提示文案（问号图标 + 悬停气泡）；口径见 `FormItemProps.tip` */
+    tip: {
+      type: String,
+      default: ""
+    },
     labelWidth: {
       type: Number,
       default: void 0
@@ -85,7 +92,7 @@ const FormItem = /* @__PURE__ */ defineComponent({
       const styles = [attrs.style, labelWidth ? {
         "--mh-form-label-width": `${labelWidth}px`
       } : null].filter(Boolean);
-      const showLabel = !!props.label || props.required;
+      const showLabel = !!props.label || props.required || !!props.tip;
       return createVNode("div", {
         "class": [
           "mh-form-item",
@@ -109,7 +116,18 @@ const FormItem = /* @__PURE__ */ defineComponent({
         "class": "mh-form-item__label-text"
       }, [props.label]), props.required ? createVNode("span", {
         "class": "mh-form-item__required"
-      }, [createTextVNode("*")]) : null]) : null, createVNode("div", {
+      }, [createTextVNode("*")]) : null, props.tip ? createVNode(Tooltip, {
+        "class": "mh-form-item__tip",
+        "content": props.tip
+      }, {
+        default: () => [createVNode("button", {
+          "type": "button",
+          "class": "mh-form-item__tip-btn",
+          "aria-label": props.tip
+        }, [createVNode(Icon, {
+          "name": "help"
+        }, null)])]
+      }) : null]) : null, createVNode("div", {
         "class": "mh-form-item__control",
         "style": controlWidth ? {
           maxWidth: `${controlWidth}px`

package/dist/components/input/index.js

@@ -168,6 +168,7 @@ const Input = /* @__PURE__ */ defineComponent({
       if (props.modelValue !== void 0 && props.modelValue !== el.value) el.value = props.modelValue;
     };
     const onKeydown = (event) => {
+      if (event.isComposing) return;
       if (event.key === "Enter") props.onEnter?.(current.value ?? "");
       if (event.key === "Delete" && props.clearable) commit("");
     };

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

@@ -27,6 +27,11 @@ export type NavVariant = 'tree' | 'list';
  * `renderActions` 直接透传给 `Tree`：默认隐藏、行悬浮或行内获得焦点时显形、点击不冒泡（§4.16）。
  * 应用侧只给节点，不要自己写显隐 CSS，也不要把它塞进 `renderNode`（那是常驻附加内容）。
  *
+ * ## 图标
+ *
+ * 导航项图标走 `renderIcon`（标签前的一位图标，口径同 `Tree.renderIcon`）—— **不要**用
+ * `renderLabel` 拼「图标 + 文字」：标签槽承担省略号与行内对齐，图标进去会被裁掉，也不成列。
+ *
  * @example 分类导航树（选中驱动右侧 + 行尾管理操作）
  * <Nav variant="tree" nodes={categoryNodes.value} rowKey="id" labelKey="name" width={220}
  *   selected={categoryId.value} onSelect={(node) => (categoryId.value = node.id)}
@@ -89,6 +94,16 @@ export declare const Nav: import("vue").DefineComponent<import("vue").ExtractPro
         type: PropType<(node: TreeNode) => unknown>;
         default: undefined;
     };
+    /** 导航项图标（标签前的一位图标）：见 `Tree.renderIcon`（侧栏图标走这一位，不要塞进 `renderLabel`） */
+    renderIcon: {
+        type: PropType<(node: TreeNode) => unknown>;
+        default: undefined;
+    };
+    /** 展开 / 收起箭头字形：见 `Tree.renderCaret`（`list` 态箭头位被隐藏，传了也不显形） */
+    renderCaret: {
+        type: PropType<(node: TreeNode, expanded: boolean) => unknown>;
+        default: undefined;
+    };
     /** 侧栏标题（可选；不传则只有导航体） */
     title: {
         type: StringConstructor;
@@ -206,6 +221,16 @@ export declare const Nav: import("vue").DefineComponent<import("vue").ExtractPro
         type: PropType<(node: TreeNode) => unknown>;
         default: undefined;
     };
+    /** 导航项图标（标签前的一位图标）：见 `Tree.renderIcon`（侧栏图标走这一位，不要塞进 `renderLabel`） */
+    renderIcon: {
+        type: PropType<(node: TreeNode) => unknown>;
+        default: undefined;
+    };
+    /** 展开 / 收起箭头字形：见 `Tree.renderCaret`（`list` 态箭头位被隐藏，传了也不显形） */
+    renderCaret: {
+        type: PropType<(node: TreeNode, expanded: boolean) => unknown>;
+        default: undefined;
+    };
     /** 侧栏标题（可选；不传则只有导航体） */
     title: {
         type: StringConstructor;
@@ -285,6 +310,8 @@ export declare const Nav: import("vue").DefineComponent<import("vue").ExtractPro
     onErrorAction: () => void;
     labelKey: string;
     childrenKey: string;
+    renderCaret: (node: TreeNode, expanded: boolean) => unknown;
+    renderIcon: (node: TreeNode) => unknown;
     renderActions: (node: TreeNode) => unknown;
     expandedKeys: string[];
     defaultExpandedKeys: string[];