@manohub/ui 0.9.0 → 0.10.1

package/README.md

@@ -7,7 +7,7 @@ AIHub **自绘组件层**：不依赖 farris 的手写 Vue TSX 组件 + 自带
 | 层 | 入口 | 内容 |
 |---|---|---|
 | ① 主题 | `@manohub/theme/default.css`（兜底）/ `@manohub/theme/farris.css`（Farris 规范） | **全局**令牌（值）—— 随主题包独立发布，换主题只换这一行 |
-| ② 组件面 | `@manohub/ui/styles.css` | **元素级 reset**（盒模型 / 按钮外观 / 列表序号 / 链接下划线 / 标题字阶归零）+ 类与状态协议 + 组件令牌基础值，**无需 JS** 即可使用 |
+| ② 组件面 | `@manohub/ui/styles.css` | **元素级 reset**（只有盒模型 + 容器基座两面，见下）+ 类与状态协议 + 组件令牌基础值，**无需 JS** 即可使用 |
 | ③ Vue 层 | `@manohub/ui` | Vue 组件：渲染 ② 的类 + 行为增强 |
 | ④ 服务层 | `@manohub/ui` | 命令式反馈：`toast()` / `confirm()` / `alert()` / `showLoading()`（宿主 + 队列 + 生命周期，共用 ③ 的组件） |
 
@@ -37,13 +37,19 @@ pnpm add @manohub/ui @manohub/theme
 
 只写静态页（不装 Vue）时引这两行即可 —— 类名与 `data-*` 状态协议直接可用。
 
-**② 的第一条 import 就是元素级 reset**（随包内置，不需要第三行）：盒模型、按钮外观、
-`ul` / `ol` 的序号与缩进、`a` 的下划线、标题的默认字阶一并归零。作用域锚 `[data-manohub-ui]`
-且特异性为 0 —— 应用侧写任何元素选择器都能盖过它，所以**不必再自己写一份全局 reset**。
+**② 的第一条 import 就是元素级 reset**（随包内置，不需要第三行），它只有两面：
 
-唯一需要留意的是**富文本**：reset 之后 `ul` / `li` 没有圆点、`a` 没有下划线也没有链接色，
-需要富文本排版的页面请给自己的富文本容器类补回 `list-style` 与链接样式
-（富文本排版暂无合规归属，见 `@manohub/kit/CONTRACT.md` §10）。
+1. **盒模型**：`box-sizing: border-box` 覆盖容器、全部后代与伪元素（本包所有面的几何前提）；
+2. **容器基座**：`[data-manohub-ui]` 上的字族 / 字号 / 行高 / 字色 / 底色 / 整链高度（令牌的落点）。
+
+作用域锚 `[data-manohub-ui]` 且特异性为 0 —— 应用侧写任何元素选择器都能盖过它。
+**它有意不再归零标题字阶、列表序号、链接下划线、控件外观**：那些规则在 Tailwind 的层外
+（未分层 > 分层），会把消费方的工具类整片压住（`border*`、`img` 上的 `h-*`、`hidden` …）；
+需要归零的元素各自归到渲染它的组件面上（`img` 在 Avatar / Upload、`a` 在 Button、
+`textarea` 的 `resize` 在 `.mh-input--textarea`、`h1`-`h6` 在 `.mh-text`）。
+Tailwind 消费方另有 preflight 兜底，两者不冲突。
+
+所以**不必再自己写一份全局 reset**；也**不要**用元素级选择器去补（那正是被压住的成因）。
 
 本包**可独立发布**：组件与类型一律从 `@manohub/ui` 直接引；下游（如 `@manohub/kit`）若转出口，是下游自己的选择。
 

package/dist/components/checkbox/index.js

@@ -1,4 +1,4 @@
-import { defineComponent, ref, computed, watchEffect, createVNode, mergeProps } from "vue";
+import { defineComponent, ref, computed, watchEffect, createVNode, mergeProps, nextTick } from "vue";
 import { Icon } from "@manohub/icon";
 const Checkbox = /* @__PURE__ */ defineComponent({
   name: "Checkbox",
@@ -58,6 +58,10 @@ const Checkbox = /* @__PURE__ */ defineComponent({
       const next = event.target.checked;
       emit("update:modelValue", next);
       props.onChange?.(next);
+      void nextTick(() => {
+        const el = inputRef.value;
+        if (el && el.checked !== !!props.modelValue) el.checked = !!props.modelValue;
+      });
     };
     return () => {
       const state = props.indeterminate ? "indeterminate" : props.modelValue ? "checked" : "unchecked";

package/dist/components/code-block/index.js

@@ -1,5 +1,8 @@
-import { defineComponent, createVNode, mergeProps, ref, computed, onBeforeUnmount } from "vue";
+import { defineComponent, createVNode, mergeProps, ref, computed, onBeforeUnmount, isVNode } from "vue";
 import { Icon } from "@manohub/icon";
+function _isSlot(s) {
+  return typeof s === "function" || Object.prototype.toString.call(s) === "[object Object]" && !isVNode(s);
+}
 const CodeView = /* @__PURE__ */ defineComponent({
   name: "CodeView",
   inheritAttrs: false,
@@ -285,6 +288,7 @@ const CodeBlockBase = /* @__PURE__ */ defineComponent({
     attrs
   }) {
     return () => {
+      let _slot;
       const shared = {
         language: props.language,
         maxHeight: props.maxHeight,
@@ -304,16 +308,19 @@ const CodeBlockBase = /* @__PURE__ */ defineComponent({
           "onUpdate:modelValue": (v) => emit("update:modelValue", v)
         }), null);
       }
-      return createVNode(CodeView, mergeProps(shared, {
-        "code": props.code,
-        "inline": props.inline,
-        "plain": props.plain,
-        "copyable": props.copyable,
-        "wrap": props.wrap,
-        "onCopy": props.onCopy
-      }), {
-        default: () => [slots.default?.()]
-      });
+      const view = {
+        ...shared,
+        code: props.code,
+        inline: props.inline,
+        plain: props.plain,
+        copyable: props.copyable,
+        wrap: props.wrap,
+        onCopy: props.onCopy
+      };
+      const body = slots.default;
+      return body ? createVNode(CodeView, view, _isSlot(_slot = body()) ? _slot : {
+        default: () => [_slot]
+      }) : createVNode(CodeView, view, null);
     };
   }
 });

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

@@ -41,7 +41,12 @@ export interface FilterProps {
     title?: string;
     /** 标题下的说明小字（透传给 `Form.Header`） */
     description?: string;
-    /** label 列宽（px）；缺省 `56`（见 `FILTER_LABEL_WIDTH`），透传给 `Form` */
+    /**
+     * label 列宽（px），透传给 `Form`。
+     *
+     * **缺省不设**：不传即与 `Form` 一致（取令牌 `--ui-form-label-width`，120）。
+     * 想收窄（筛选条的标签多为四字）就显式传，例如 `labelWidth={68}`。
+     */
     labelWidth?: number;
     /** 受控条件快照（`条件名 → 值`）；不传即非受控（由 `defaultValue` 起） */
     modelValue?: FilterValues;
@@ -79,7 +84,8 @@ export interface FilterItemProps {
  * 增量只有一处 —— **读写的值都是归一后的**（`'all'` / 空数组 / 空值 → 空串），
  * 于是消费方直接把 `value` 绑给控件，不必自己处理哨兵。
  *
- * 字段宽**自适应**：容器够宽一行排下，窄了整体换行（列距 24 / 行距 16）。
+ * 字段宽**自适应**：字段区是 `Form` 的多列动态档（`Filter` 传 `columns="auto"`），
+ * 故本件只输出 `Form.Item` 自己的类 —— 列宽由那条网格轨道算，换行下来的字段与上一行逐列对齐。
  *
  * @example
  * <Filter.Item code="status" label="授权状态">

package/dist/components/filter/index.js

@@ -2,8 +2,6 @@ import { defineComponent, createVNode, ref, h, Fragment } from "vue";
 import { Button } from "../button/index.js";
 import { FormItem, Form } from "../form/index.js";
 const FILTER_ALL = "all";
-const FILTER_LABEL_WIDTH = 68;
-const FILTER_GAP = 16;
 function normalizeFilterValue(value) {
   if (Array.isArray(value)) {
     const kept = value.map((item) => normalizeFilterValue(item)).filter((item) => item !== "");
@@ -96,7 +94,7 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       emit("update:modelValue", next);
       props.onReset?.(next);
     };
-    const onFieldsKeydown = (event) => {
+    const onFormKeydown = (event) => {
       if (event.key !== "Enter" || event.isComposing) return;
       const target = event.target;
       if (target?.tagName !== "INPUT" || target.closest("[popover]")) return;
@@ -118,30 +116,23 @@ const FilterRoot = /* @__PURE__ */ defineComponent({
       "ref": formRef,
       "class": ["mh-filter__form", attrs.class].filter(Boolean).join(" "),
       "style": attrs.style,
-      "labelWidth": props.labelWidth ?? FILTER_LABEL_WIDTH,
-      "gap": FILTER_GAP,
+      "labelWidth": props.labelWidth,
+      "columns": "auto",
+      "onKeydown": onFormKeydown,
       "modelValue": props.modelValue,
       "defaultValue": props.defaultValue,
       "onChange": onFormChange
     }, {
-      default: () => [
-        /* 插槽一律走对象形态：TSX 的 `v-slots={{…}}` 会被当**普通属性**丢掉
-           （见 `list-view/index.tsx` 同款记录），而多子节点直传会触发
-           「Non-function value encountered for default slot」告警（同 `page/index.tsx`）。 */
-        h(Form.Header, {
+      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
-        }),
-        // 字段区也用插槽对象形态传子节点：`h()` 的第三参不收 `null`（`slots.default?.()` 的返回可能是 null）
-        h("div", {
-          class: "mh-filter__fields",
-          onKeydown: onFieldsKeydown
-        }, {
-          default: () => slots.default?.()
-        })
-      ]
+        }), ...fields];
+      }
     });
   }
 });
@@ -181,7 +172,7 @@ const FilterItem = /* @__PURE__ */ defineComponent({
       "required": props.required,
       "error": props.error,
       "hint": props.hint,
-      "class": ["mh-filter__item", attrs.class].filter(Boolean).join(" "),
+      "class": attrs.class,
       "style": attrs.style
     }, {
       default: (scope) => slots.default?.({

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

@@ -99,6 +99,18 @@ export interface FormProps {
     defaultValue?: FormValues;
     /** 值变更（快照含**全部已登记字段**，未设值的字段为 `undefined`） */
     onChange?: (values: FormValues) => void;
+    /**
+     * 根节点的键盘事件（**转发到表单根**）。
+     *
+     * 本件是 `inheritAttrs: false`，根节点只显式绑 `class` / `style` —— 不声明的监听器会被**静默丢掉**
+     * （与该文件里已修过的「消费方 style 被静默丢弃」同款前科）。而根节点就是「全部字段行的容器」，
+     * 故它是「字段区层面的委托」的落点：本包 `Filter` 的「字段区回车 = 查询」就搭在这条通道上
+     * （构造 `Filter` 时因此不必再套一层只为挂事件的壳 —— 那会改变 `class` / `style` 的落点）。
+     *
+     * **有意只开这一条**：其它监听器（如 `onClick`）不转发；要把某一条也接进来，先当一次公开行为变更裁决。
+     * 要不要拦、拦哪些按键（本包 `Filter` 收窄到「`<input>` 上的回车」）由调用方自己判断，本件只转发。
+     */
+    onKeydown?: (event: KeyboardEvent) => void;
 }
 export interface FormItemProps {
     /**
@@ -193,6 +205,15 @@ export interface FormItemProps {
  * `{ y, x }` 上下 / 左右分别给，缺省 0（贴容器边）。页面里的表单在 `Panel.Body` 里、内距由那块给；
  * **弹窗 / 抽屉里没有别的容器**给内距，就用表单自带的 `padding={{ y: 16, x: 20 }}`。
  *
+ * ## 键盘事件（`onKeydown` 转发到根节点）
+ *
+ * `onKeydown` 是本件的**声明式入口**（缺省不绑）：传进来的处理器绑在根节点上 ——
+ * 本件是 `inheritAttrs: false`，根节点只显式绑 `class` / `style`，不声明的监听器会被静默丢掉。
+ * 根节点即「全部字段行的容器」，因此它是「字段区层面的委托」的落点：本包 `Filter` 的
+ * 「字段区回车 = 查询」就搭在这里，构造 `Filter` 时**不必**再套一层只为挂事件的壳
+ * （那会改变 `class` / `style` 的落点）。要不要拦、拦哪些按键由调用方自己判断，本件只转发。
+ * **有意只开这一条**：其它监听器不转发，扩张要先当一次公开行为变更裁决。
+ *
  * ## 只读值（摘要 / 详情）
  *
  * 「向导最后一步的确认摘要」「详情弹窗」不需要另起一套描述列表件 —— 只用表单行本身，
@@ -455,6 +476,11 @@ export declare const Form: {
             type: PropType<(values: FormValues) => void>;
             default: undefined;
         };
+        /** 根节点的键盘事件（转发到表单根；缺省不绑）—— 用途与边界见 `FormProps` 的同名注释 */
+        onKeydown: {
+            type: PropType<(event: KeyboardEvent) => void>;
+            default: undefined;
+        };
     }>> & Readonly<{
         "onUpdate:modelValue"?: ((values: FormValues) => any) | undefined;
     }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
@@ -463,6 +489,7 @@ export declare const Form: {
         padding: Padding;
         layout: "horizontal" | "vertical";
         onChange: (values: FormValues) => void;
+        onKeydown: (event: KeyboardEvent) => void;
         defaultValue: FormValues;
         gap: number;
         columns: FormColumns;
@@ -544,12 +571,18 @@ export declare const Form: {
             type: PropType<(values: FormValues) => void>;
             default: undefined;
         };
+        /** 根节点的键盘事件（转发到表单根；缺省不绑）—— 用途与边界见 `FormProps` 的同名注释 */
+        onKeydown: {
+            type: PropType<(event: KeyboardEvent) => void>;
+            default: undefined;
+        };
     }>> & Readonly<{
         "onUpdate:modelValue"?: ((values: FormValues) => any) | undefined;
     }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, {
         padding: Padding;
         layout: "horizontal" | "vertical";
         onChange: (values: FormValues) => void;
+        onKeydown: (event: KeyboardEvent) => void;
         defaultValue: FormValues;
         gap: number;
         columns: FormColumns;
@@ -626,6 +659,11 @@ export declare const Form: {
         type: PropType<(values: FormValues) => void>;
         default: undefined;
     };
+    /** 根节点的键盘事件（转发到表单根；缺省不绑）—— 用途与边界见 `FormProps` 的同名注释 */
+    onKeydown: {
+        type: PropType<(event: KeyboardEvent) => void>;
+        default: undefined;
+    };
 }>> & Readonly<{
     "onUpdate:modelValue"?: ((values: FormValues) => any) | undefined;
 }>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
@@ -634,6 +672,7 @@ export declare const Form: {
     padding: Padding;
     layout: "horizontal" | "vertical";
     onChange: (values: FormValues) => void;
+    onKeydown: (event: KeyboardEvent) => void;
     defaultValue: FormValues;
     gap: number;
     columns: FormColumns;

package/dist/components/form/index.js

@@ -236,6 +236,11 @@ const FormRoot = /* @__PURE__ */ defineComponent({
     onChange: {
       type: Function,
       default: void 0
+    },
+    /** 根节点的键盘事件（转发到表单根；缺省不绑）—— 用途与边界见 `FormProps` 的同名注释 */
+    onKeydown: {
+      type: Function,
+      default: void 0
     }
   },
   emits: {
@@ -313,6 +318,7 @@ const FormRoot = /* @__PURE__ */ defineComponent({
       } = splitFormHeader(list);
       return createVNode("div", {
         "class": ["mh-form", columnsClass(), props.layout === "vertical" ? "mh-form--vertical" : "", attrs.class].filter(Boolean).join(" "),
+        "onKeydown": props.onKeydown,
         "style": [
           mergePartStyle(attrs.style, props.padding),
           /* 行距同时下发实体 `gap` 与变量：多列的轨道下限公式要用**同一个**行距值算 ——

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

@@ -22,6 +22,11 @@ export interface TextareaAutoSize {
  * 附加位：`prefix` / `suffix` **插槽**里放什么由你决定（图标 / 单位 / 域名 / 你自己的可点元素），
  * 本件不内置标签件 —— 纯装饰形态无底色、不参与 Tab 序列，可点形态的热区与底色归消费方。
  *
+ * **属性落点**（用错位置就会「样式在壳上、属性在组件上被丢掉」）：
+ * `class` / `style` → 表壳 `.mh-input__wrap`（整件的宽度与显式锚）；**其余 attrs 一律透传到控件**
+ * （`id` / `name` / `aria-*` / `data-*` / `title` / 原生事件）—— 壳只是排版容器，属性落它上面等于丢掉
+ * —— 见 `forwardAttrs`；触发器形态另有 `controlClass` / `controlAttrs` 两个**专口子**（同名键以它为准）。
+ *
  * @example 受控 + 可清除
  * <Input modelValue={kw} placeholder="搜索" clearable prefix={<Icon name="search" />} onChange={setKw} />
  *
@@ -35,8 +40,9 @@ export interface TextareaAutoSize {
  * <Textarea modelValue={note} autoSize={{ minRows: 2, maxRows: 6 }} maxlength={500} showCount onChange={setNote} />
  *
  * @example 触发器形态（复合件用：控件换成 `<button>`，表壳 / 清除位 / 右侧图标位全部复用）
- * <Input as="button" clearable hasValue={!!value} controlClass="my-picker" controlAttrs={{ popovertarget: id }}>
- *   {{ default: () => value ?? '请选择', suffix: () => <Icon name="chevron-down" /> }}
+ * <Input as="button" clearable hasValue={!!value} placeholder="请选择" controlClass="my-picker"
+ *   controlAttrs={{ popovertarget: id }}>
+ *   {{ default: () => value, suffix: () => <Icon name="chevron-down" /> }}
  * </Input>
  */
 export declare const Input: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
@@ -50,6 +56,13 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         default: string;
     };
+    /**
+     * 占位文案。两种形态都消费它：
+     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
+     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
+     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
+     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     */
     placeholder: {
         type: StringConstructor;
         default: undefined;
@@ -107,7 +120,7 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: NumberConstructor;
         default: undefined;
     };
-    /** 右侧字数统计（单行须给 `maxlength` 才有意义） */
+    /** 右侧字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
     showCount: {
         type: BooleanConstructor;
         default: boolean;
@@ -137,12 +150,14 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         default: undefined;
     };
-    /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上） */
+    /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上）;
+     *  与透传的 attrs 撞名时以本 prop 为准 */
     controlAttrs: {
         type: PropType<Record<string, unknown>>;
         default: undefined;
     };
-    /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判） */
+    /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判）。
+     *  同时是触发器形态「显示值还是显示占位」的判据（仅当它为 `false` 且传了 `placeholder` 时接管） */
     hasValue: {
         type: BooleanConstructor;
         default: undefined;
@@ -160,6 +175,13 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         default: string;
     };
+    /**
+     * 占位文案。两种形态都消费它：
+     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
+     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
+     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
+     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     */
     placeholder: {
         type: StringConstructor;
         default: undefined;
@@ -217,7 +239,7 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: NumberConstructor;
         default: undefined;
     };
-    /** 右侧字数统计（单行须给 `maxlength` 才有意义） */
+    /** 右侧字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
     showCount: {
         type: BooleanConstructor;
         default: boolean;
@@ -247,12 +269,14 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         type: StringConstructor;
         default: undefined;
     };
-    /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上） */
+    /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上）;
+     *  与透传的 attrs 撞名时以本 prop 为准 */
     controlAttrs: {
         type: PropType<Record<string, unknown>>;
         default: undefined;
     };
-    /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判） */
+    /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判）。
+     *  同时是触发器形态「显示值还是显示占位」的判据（仅当它为 `false` 且传了 `placeholder` 时接管） */
     hasValue: {
         type: BooleanConstructor;
         default: undefined;
@@ -307,7 +331,7 @@ export interface TextareaProps {
     /** 是否带边框 */
     bordered?: boolean;
     maxlength?: number;
-    /** 右下角字数统计（须给 `maxlength` 才有意义） */
+    /** 右下角字数统计（须给 `maxlength` 才渲染） */
     showCount?: boolean;
     autofocus?: boolean;
     onChange?: (v: string) => void;
@@ -315,8 +339,9 @@ export interface TextareaProps {
 /**
  * 多行输入（同一份面；结构与单行不同，故单列一个件）。
  *
- * ⚠️ 本件**没有** `mono` 档（`Input` 有）。要等宽的输入框别拿 `Text mono` 去包 —— 那会丢掉输入能力；
- * 该写法目前只能保留一条带 `font-family: var(--ui-font-mono)` 的应用侧样式登记（缺口见包内 `docs/kit-gaps.md`）。
+ * ⚠️ **输入族没有 `mono` 档**（`Input` 与 `Textarea` 都没有）。要等宽的输入框别拿 `Text mono` 去包
+ * —— 那会丢掉输入能力；目前只能由应用侧保留一条带 `font-family: var(--ui-font-mono)` 的样式登记
+ * （缺件登记见下游仓 `aihub-frontend/docs/kit-gaps.md`，本仓不复制那份台账）。
  *
  * @example 备注框：自适应 2~6 行 + 限长计数
  * <Textarea modelValue={note} autoSize={{ minRows: 2, maxRows: 6 }} maxlength={500} showCount onChange={setNote} />
@@ -371,6 +396,7 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
         type: NumberConstructor;
         default: undefined;
     };
+    /** 右下角字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
     showCount: {
         type: BooleanConstructor;
         default: boolean;
@@ -435,6 +461,7 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
         type: NumberConstructor;
         default: undefined;
     };
+    /** 右下角字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
     showCount: {
         type: BooleanConstructor;
         default: boolean;
@@ -478,6 +505,13 @@ export declare const InputCompound: {
             type: StringConstructor;
             default: string;
         };
+        /**
+         * 占位文案。两种形态都消费它：
+         * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
+         * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
+         *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
+         *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+         */
         placeholder: {
             type: StringConstructor;
             default: undefined;
@@ -535,7 +569,7 @@ export declare const InputCompound: {
             type: NumberConstructor;
             default: undefined;
         };
-        /** 右侧字数统计（单行须给 `maxlength` 才有意义） */
+        /** 右侧字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
         showCount: {
             type: BooleanConstructor;
             default: boolean;
@@ -565,12 +599,14 @@ export declare const InputCompound: {
             type: StringConstructor;
             default: undefined;
         };
-        /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上） */
+        /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上）;
+         *  与透传的 attrs 撞名时以本 prop 为准 */
         controlAttrs: {
             type: PropType<Record<string, unknown>>;
             default: undefined;
         };
-        /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判） */
+        /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判）。
+         *  同时是触发器形态「显示值还是显示占位」的判据（仅当它为 `false` 且传了 `placeholder` 时接管） */
         hasValue: {
             type: BooleanConstructor;
             default: undefined;
@@ -622,6 +658,13 @@ export declare const InputCompound: {
             type: StringConstructor;
             default: string;
         };
+        /**
+         * 占位文案。两种形态都消费它：
+         * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
+         * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
+         *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
+         *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+         */
         placeholder: {
             type: StringConstructor;
             default: undefined;
@@ -679,7 +722,7 @@ export declare const InputCompound: {
             type: NumberConstructor;
             default: undefined;
         };
-        /** 右侧字数统计（单行须给 `maxlength` 才有意义） */
+        /** 右侧字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
         showCount: {
             type: BooleanConstructor;
             default: boolean;
@@ -709,12 +752,14 @@ export declare const InputCompound: {
             type: StringConstructor;
             default: undefined;
         };
-        /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上） */
+        /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上）;
+         *  与透传的 attrs 撞名时以本 prop 为准 */
         controlAttrs: {
             type: PropType<Record<string, unknown>>;
             default: undefined;
         };
-        /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判） */
+        /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判）。
+         *  同时是触发器形态「显示值还是显示占位」的判据（仅当它为 `false` 且传了 `placeholder` 时接管） */
         hasValue: {
             type: BooleanConstructor;
             default: undefined;
@@ -757,6 +802,13 @@ export declare const InputCompound: {
         type: StringConstructor;
         default: string;
     };
+    /**
+     * 占位文案。两种形态都消费它：
+     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
+     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
+     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
+     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     */
     placeholder: {
         type: StringConstructor;
         default: undefined;
@@ -814,7 +866,7 @@ export declare const InputCompound: {
         type: NumberConstructor;
         default: undefined;
     };
-    /** 右侧字数统计（单行须给 `maxlength` 才有意义） */
+    /** 右侧字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
     showCount: {
         type: BooleanConstructor;
         default: boolean;
@@ -844,12 +896,14 @@ export declare const InputCompound: {
         type: StringConstructor;
         default: undefined;
     };
-    /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上） */
+    /** 展开到**控件元素**上的属性（触发器形态要 `popovertarget` / `aria-*` / `onKeydown` 落到控件上）;
+     *  与透传的 attrs 撞名时以本 prop 为准 */
     controlAttrs: {
         type: PropType<Record<string, unknown>>;
         default: undefined;
     };
-    /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判） */
+    /** 显式覆盖清除位显隐；不给时仍按「有内容」判定（多选类复合件没有单值可判）。
+     *  同时是触发器形态「显示值还是显示占位」的判据（仅当它为 `false` 且传了 `placeholder` 时接管） */
     hasValue: {
         type: BooleanConstructor;
         default: undefined;
@@ -934,6 +988,7 @@ export declare const InputCompound: {
             type: NumberConstructor;
             default: undefined;
         };
+        /** 右下角字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
         showCount: {
             type: BooleanConstructor;
             default: boolean;
@@ -998,6 +1053,7 @@ export declare const InputCompound: {
             type: NumberConstructor;
             default: undefined;
         };
+        /** 右下角字数统计（**须给 `maxlength` 才渲染**：没有分母的 `n/0` 是坏值） */
         showCount: {
             type: BooleanConstructor;
             default: boolean;