@manohub/ui 1.0.5 → 1.0.8

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` | 类名 | 常态 | 悬停 | 聚焦 |
  * | --- | --- | --- | --- | --- |

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

@@ -1,4 +1,4 @@
-import { type PropType, type SlotsType, type VNodeChild } from 'vue';
+import { type HTMLAttributes, type PropType, type SlotsType, type VNodeChild } from 'vue';
 import type { ControlSize } from '../control-size';
 /** 校验状态（`error` 红、`warning` 黄；缺省无校验态） */
 export type InputStatus = 'error' | 'warning';
@@ -26,26 +26,11 @@ export interface TextareaAutoSize {
  * `class` / `style` → 表壳 `.mh-input__wrap`（整件的宽度与显式锚）；**其余 attrs 一律透传到控件**
  * （`id` / `name` / `aria-*` / `data-*` / `title` / 原生事件）—— 壳只是排版容器，属性落它上面等于丢掉
  * —— 见 `forwardAttrs`；触发器形态另有 `controlClass` / `controlAttrs` 两个**专口子**（同名键以它为准）。
+ * 这组属性在**类型面**同步放开（两形态共认的键）：`onClick` / `title` / `data-*` / `aria-*` 直接写在组件上即可。
  *
- * @example 受控 + 可清除
- * <Input modelValue={kw} placeholder="搜索" clearable prefix={<Icon name="search" />} onChange={setKw} />
- *
- * @example 密码（右端图标切换明/密文）
- * <Input type="password" modelValue={pwd} onChange={setPwd} />
- *
- * @example 校验态与尺寸
- * <Input status="error" size="lg" placeholder="请输入任务名" />
- *
- * @example 多行 + 字数 + 自适应高度
- * <Textarea modelValue={note} autoSize={{ minRows: 2, maxRows: 6 }} maxlength={500} showCount onChange={setNote} />
- *
- * @example 触发器形态（复合件用：控件换成 `<button>`，表壳 / 清除位 / 右侧图标位全部复用）
- * <Input as="button" clearable hasValue={!!value} placeholder="请选择" controlClass="my-picker"
- *   controlAttrs={{ popovertarget: id }}>
- *   {{ default: () => value, suffix: () => <Icon name="chevron-down" /> }}
- * </Input>
+ * 用法见 `docs/demos/input/`（每个维度一份可运行样例；文档页 `docs/components/input.md`）。
  */
-export declare const Input: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+declare const InputBase: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 受控值 */
     modelValue: {
         type: StringConstructor;
@@ -58,9 +43,8 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
     };
     /**
      * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
-     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）
-     * —— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。没传 `hasValue`
-     * 的调用方行为不变。
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
         type: StringConstructor;
@@ -81,10 +65,9 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显
-     * 业务值，也是 `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 /
-     * 值文字同左缘），但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+     * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+     * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
      */
     readonly: {
         type: BooleanConstructor;
@@ -182,9 +165,8 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
     };
     /**
      * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
-     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）
-     * —— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。没传 `hasValue`
-     * 的调用方行为不变。
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
         type: StringConstructor;
@@ -205,10 +187,9 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显
-     * 业务值，也是 `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 /
-     * 值文字同左缘），但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+     * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+     * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
      */
     readonly: {
         type: BooleanConstructor;
@@ -319,6 +300,16 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
     prefix?: () => VNodeChild;
     suffix?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+/**
+ * 控件元素上的原生属性 / 事件（`HTMLAttributes` 即输入框与触发器共有的那张基表）：
+ * 本件不登记它们，运行时按 attrs 透传到控件，这里只把类型面同步放开。
+ */
+type InputControlAttrs = Omit<HTMLAttributes, keyof InstanceType<typeof InputBase>['$props']>;
+export declare const Input: typeof InputBase & {
+    new (): {
+        $props: InstanceType<typeof InputBase>["$props"] & InputControlAttrs;
+    };
+};
 export interface TextareaProps {
     /** 受控值 */
     modelValue?: string;
@@ -348,13 +339,8 @@ export interface TextareaProps {
 }
 /**
  * 多行输入（同一份面；结构与单行不同，故单列一个件）。
- *
- * ⚠️ **输入族没有 `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} />
+ * ⚠️ **输入族没有 `mono` 档**（`Input` 与 `Textarea` 都没有）：要等宽的输入框别拿 `Text mono` 去包（那会丢掉输入
+ * 能力），目前只能由应用侧保留一条带 `font-family: var(--ui-font-mono)` 的样式登记。
  */
 export declare const Textarea: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     modelValue: {
@@ -519,9 +505,8 @@ export declare const InputCompound: {
         };
         /**
          * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
-         * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）
-         * —— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。没传 `hasValue`
-         * 的调用方行为不变。
+         * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+         * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
          */
         placeholder: {
             type: StringConstructor;
@@ -542,10 +527,9 @@ export declare const InputCompound: {
             default: boolean;
         };
         /**
-         * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显
-         * 业务值，也是 `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 /
-         * 值文字同左缘），但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-         * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+         * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+         * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+         * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
          */
         readonly: {
             type: BooleanConstructor;
@@ -677,9 +661,8 @@ export declare const InputCompound: {
         };
         /**
          * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
-         * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）
-         * —— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。没传 `hasValue`
-         * 的调用方行为不变。
+         * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+         * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
          */
         placeholder: {
             type: StringConstructor;
@@ -700,10 +683,9 @@ export declare const InputCompound: {
             default: boolean;
         };
         /**
-         * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显
-         * 业务值，也是 `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 /
-         * 值文字同左缘），但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-         * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+         * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+         * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+         * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
          */
         readonly: {
             type: BooleanConstructor;
@@ -826,9 +808,8 @@ export declare const InputCompound: {
     };
     /**
      * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
-     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）
-     * —— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。没传 `hasValue`
-     * 的调用方行为不变。
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
         type: StringConstructor;
@@ -849,10 +830,9 @@ export declare const InputCompound: {
         default: boolean;
     };
     /**
-     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显
-     * 业务值，也是 `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 /
-     * 值文字同左缘），但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+     * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+     * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
      */
     readonly: {
         type: BooleanConstructor;
@@ -964,7 +944,9 @@ export declare const InputCompound: {
     default?: () => VNodeChild;
     prefix?: () => VNodeChild;
     suffix?: () => VNodeChild;
-}>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
+}>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & (new () => {
+    $props: InstanceType<typeof InputBase>["$props"] & InputControlAttrs;
+}) & {
     Textarea: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
         modelValue: {
             type: StringConstructor;
@@ -1132,9 +1114,8 @@ export declare const InputCompound: {
 };
 export type InputCompoundType = typeof InputCompound;
 /**
- * 数字输入与 `Input` **同族**（同一个表壳 / 内距 / 状态协议，同一份面 `input.css`），
- * 故与 `Textarea` 同款处置：**平级导出、共用本目录**（`AGENTS.md` 硬约束 1）。
- * 它**不是** `Input` 的点号成员 —— 成员位留给「同一件自己的形态」（`.Textarea` / `.Display`），
- * 而数字输入是另一件（值模型 `number | null` vs `string`）。
+ * 数字输入与 `Input` **同族**（同一个表壳 / 内距 / 状态协议，同一份面 `input.css`），故与 `Textarea` 同款处置：
+ * **平级导出、共用本目录**。它**不是** `Input` 的点号成员 —— 成员位留给「同一件自己的形态」（`.Textarea` /
+ * `.Display`），而数字输入是另一件（值模型 `number | null` vs `string`）。
  */
 export { NumberInput, type NumberInputProps } from './number-input';

package/dist/components/input/index.js

@@ -1,7 +1,7 @@
 import { defineComponent, ref, computed, createVNode, mergeProps, createTextVNode } from "vue";
 import { Icon } from "@manohub/icon";
 import { borderedClassOf } from "./bordered.js";
-const Input = /* @__PURE__ */ defineComponent({
+const InputBase = /* @__PURE__ */ defineComponent({
   name: "Input",
   inheritAttrs: false,
   props: {
@@ -17,9 +17,8 @@ const Input = /* @__PURE__ */ defineComponent({
     },
     /**
      * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
-     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）
-     * —— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。没传 `hasValue`
-     * 的调用方行为不变。
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
       type: String,
@@ -40,10 +39,9 @@ const Input = /* @__PURE__ */ defineComponent({
       default: false
     },
     /**
-     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显
-     * 业务值，也是 `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 /
-     * 值文字同左缘），但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+     * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+     * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
      */
     readonly: {
       type: Boolean,
@@ -244,6 +242,7 @@ const Input = /* @__PURE__ */ defineComponent({
     }, [current.value?.length ?? 0, createTextVNode("/"), props.maxlength]) : null]);
   }
 });
+const Input = InputBase;
 const Textarea = /* @__PURE__ */ defineComponent({
   name: "Textarea",
   inheritAttrs: false,

package/dist/components/input/number-input.d.ts

@@ -4,38 +4,26 @@ import type { InputStatus } from './index';
 /**
  * 数字输入（**自绘**）。
  *
- * 与 `Input` **同族同面**（同一个表壳 / 内距 / 状态协议，样式归 `styles/components/input.css`），
- * 按 `AGENTS.md` 硬约束 1 的「同族两件可并排平级导出、共用同一目录与同一份面」处置
- * —— 与 `Input` / `Textarea` 的关系同款，故不另开组件目录、不新增面文件。
+ * 与 `Input` **同族同面**（同一个表壳 / 内距 / 状态协议，样式归 `styles/components/input.css`），按「同族两件
+ * 可并排平级导出、共用同一目录与同一份面」处置 —— 故不另开组件目录、不新增面文件。
  *
- * 为什么单列一个件而不是加进 `Input`：`Input` 的 `modelValue` 是 **string**，且已串起
- * 「密码可见切换 / 清除位 / 字数统计 / 触发器形态」一条链；把数值语义（`min` / `max` / `step` /
- * `precision` / 钳制 / 舍入 / 步进按钮）塞进去会污染统一词表（`AGENTS.md` 硬约束 8）。
- * 本件也**不接** `Input` 的 `as="button"` 触发器形态 —— 那是复合件（`Select` 一族）的口子。
+ * 为什么单列一件而不是加进 `Input`：`Input` 的 `modelValue` 是 **string**，且已串起「密码可见切换 / 清除位 /
+ * 字数统计 / 触发器形态」一条链；把数值语义（`min` / `max` / `step` / `precision` / 钳制 / 舍入 / 步进按钮）
+ * 塞进去会污染统一词表。本件也**不接** `Input` 的 `as="button"` 触发器形态（那是复合件一族的口子）。
  *
  * 统一词表（与 `Checkbox` / `Switch` / `Input` 同款）：`modelValue` / `onChange` / `disabled` / `size`；
  * 值变更时 `emit('update:modelValue')` 与 `onChange` **双走**。
  *
- * ## 值域口径（三条，都是「原生数字框最被讨厌的点」的反面）
- *
+ * ## 值域口径（都是「原生数字框最被讨厌的点」的反面）
  * 1. **空值是 `null`，不是 `0`**：留空与「填了 0」是两件事，前者不提交、后者要提交。
- * 2. **输入中途不钳制**：`-` / `1.` / 空串这些中间态一律原样留着（打一半就被改掉会打断输入）；
- *    钳制与舍入发生在**归一时刻** —— `blur` / `Enter` / 步进按钮 / `min`·`max`·`precision` 变化。
+ * 2. **输入中途不钳制**：`-` / `1.` / 空串这些中间态一律原样留着（打一半就被改掉会打断输入）；钳制与舍入发生
+ *    在**归一时刻** —— `blur` / `Enter` / 步进按钮 / `min`·`max`·`precision` 变化。
  * 3. **非法输入回滚**：解析不出来（如 `1a`）就退回上一个合法值，**不静默变 0**。
  *
- * 属性落点与 `Input` 完全同款：`class` / `style` → 表壳 `.mh-input__wrap`；其余 attrs 一律透传到
- * 控件（`id` / `name` / `aria-*` / `data-*` / 原生事件），见 `forwardAttrs`。
- *
- * @example 受控 + 区间
- * <NumberInput modelValue={timeout} min={0} max={43200} onChange={setTimeout} />
- *
- * @example 表格内 / 行内编辑档（无框）
- * <NumberInput modelValue={row.value} bordered={false} precision={0} onChange={set} />
+ * 属性落点与 `Input` 完全同款：`class` / `style` → 表壳 `.mh-input__wrap`；其余 attrs 一律透传到控件
+ * （`id` / `name` / `aria-*` / `data-*` / 原生事件），见 `forwardAttrs`。
  *
- * @example 带单位后缀
- * <NumberInput modelValue={size} min={1}>
- *   {{ suffix: () => 'MB' }}
- * </NumberInput>
+ * 用法见 `docs/demos/number-input/`（每个维度一份可运行样例；文档页 `docs/components/number-input.md`）。
  */
 export interface NumberInputProps {
     /** 受控值（空值为 `null`，不是 `0`） */

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

@@ -1,10 +1,11 @@
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import { type Padding } from '../part-padding';
 /**
- * 布局间距档：**只开放令牌档位，不开放任意 px**（`none/sm/md/lg/xl` → `0 / --ui-space-1/2/3/4`）。
+ * 布局间距档：**只开放令牌档位，不开放任意 px**（`none/sm/md/lg/xl` → `0 / --ui-space-1/2/3/4`）。间距一旦可以随手
+ * 写，同一个页面里就会出现 6/7/9/10/14 这些「看着差不多」的值、并在不同缩放档与不同人手里继续分叉 —— 与「应用侧只写
+ * 布局」是同一条理由的另一面。
  *
- * 间距一旦可以随手写，同一个页面里就会出现 6/7/9/10/14 这些「看着差不多」的值，
- * 而它们在不同缩放档、不同人手里会继续分叉 —— 与「应用侧只写布局」是同一条理由的另一面。
+ * 用法见 `docs/demos/layout/`（每个维度一份可运行样例；文档页 `docs/components/layout.md`）。
  */
 export type LayoutGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
 /** 交叉轴对齐（`align-items`）；主轴排布用 `justify` */
@@ -25,18 +26,16 @@ export type LayoutSpan = 1 | 2 | 3 | 4;
  *
  * ## 命名与方向口径（别再改回去）
  *
- * - **方向按表格语义定**：行与行上下相邻 ⇒ `Row` 竖排；列与列左右相邻 ⇒ `Column` 横排。
- * - `columns` 说的是「**这一行分几列**」（每行摆几格），不是「这个容器有几种方向」。
- * - 嵌套：要分栏 / 栅格就 `Row columns={n}` + `Column`；一格里要上下堆，就在 `Column` 里再放 `Row`。
- * - **公开面只出 `Layout`**，不平级导出 `Row` / `Column` —— 通用词会与 `TableColumn`
- *   在一份 import 清单里混读，也破坏「成族子件用点号」的约定（`Page.Header` / `Form.Item`）。
+ * **方向按表格语义定**（行与行上下相邻 ⇒ `Row` 竖排；列与列左右相邻 ⇒ `Column` 横排）；`columns` 说的是
+ * 「**这一行分几列**」（每行摆几格），不是「这个容器有几种方向」；嵌套上要分栏 / 栅格就 `Row columns={n}` +
+ * `Column`，一格里要上下堆就在 `Column` 里再放 `Row`。**公开面只出 `Layout`**，不平级导出 `Row` / `Column`
+ * —— 通用词会与 `TableColumn` 在一份 import 清单里混读，也破坏「成族子件用点号」的约定。
  *
  * ## 与其它件的边界
  *
- * - 表单里并排字段用 `Form` 的 `columns`（它管 label 列、行距与**回落**），不要用本族拼表单
- *   —— 本族的列数是**恒定**的，窄了只等分收窄，表单会被压出不可用的窄控件；
- * - 页面级两栏（各自滚动）用 `Page.Split`；
- * - 只有「块与块怎么摆」这一件事归本族，滚动 / 工具位 / 卡片外观都不归它。
+ * 表单里并排字段用 `Form` 的 `columns`（它管 label 列、行距与**回落**），不要用本族拼表单 —— 本族的列数是
+ * **恒定**的、窄了只等分收窄，表单会被压出不可用的窄控件；页面级两栏（各自滚动）用 `Page.Split`；只有
+ * 「块与块怎么摆」这一件事归本族（滚动 / 工具位 / 卡片外观都不归它）。
  */
 export declare const Layout: {
     Row: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
@@ -66,14 +65,11 @@ export declare const Layout: {
             default: undefined;
         };
         /**
-         * 内距：**走骨架件共享口径**（`Padding`，同 `Card` / `Form` / `Page` / `Panel`）——
-         * `number` 四边同值、`{ y, x }` 分上下 / 左右、`string` 原样下发（CSS 简写，**逃生舱**）。
-         * 口径与理由见 `part-padding.ts`。
-         *
-         * ⚠️ 与 `gap` 不同口径：`gap` 只开放令牌档（防间距分叉），`padding` 接具体值 ——
-         * 内距在设计稿里常是**确定坐标**，令牌梯度（最大 24px）表达不了。
-         * ⚠️ 用它之前先想一次：这个数真是「内距」吗？若是「与某个内容列对齐」这类**布局坐标**，
-         * 优先改由结构表达（同轴容器 / `columns` / `minColumnWidth`）。
+         * 内距：**走骨架件共享口径**（`Padding`，同 `Card` / `Form` / `Page` / `Panel`）—— `number` 四边同值、
+         * `{ y, x }` 分上下 / 左右、`string` 原样下发（CSS 简写，**逃生舱**），口径与理由见 `part-padding.ts`。
+         * ⚠️ 与 `gap` 不同口径：`gap` 只开放令牌档（防间距分叉），`padding` 接具体值 —— 内距在设计稿里常是**确定坐标**，
+         * 令牌梯度（最大 24px）表达不了。⚠️ 用它之前先想一次：这个数真是「内距」吗？若是「与某个内容列对齐」这类**布局
+         * 坐标**，优先改由结构表达（同轴容器 / `columns` / `minColumnWidth`）。
          */
         padding: {
             type: PropType<Padding>;
@@ -106,14 +102,11 @@ export declare const Layout: {
             default: undefined;
         };
         /**
-         * 内距：**走骨架件共享口径**（`Padding`，同 `Card` / `Form` / `Page` / `Panel`）——
-         * `number` 四边同值、`{ y, x }` 分上下 / 左右、`string` 原样下发（CSS 简写，**逃生舱**）。
-         * 口径与理由见 `part-padding.ts`。
-         *
-         * ⚠️ 与 `gap` 不同口径：`gap` 只开放令牌档（防间距分叉），`padding` 接具体值 ——
-         * 内距在设计稿里常是**确定坐标**，令牌梯度（最大 24px）表达不了。
-         * ⚠️ 用它之前先想一次：这个数真是「内距」吗？若是「与某个内容列对齐」这类**布局坐标**，
-         * 优先改由结构表达（同轴容器 / `columns` / `minColumnWidth`）。
+         * 内距：**走骨架件共享口径**（`Padding`，同 `Card` / `Form` / `Page` / `Panel`）—— `number` 四边同值、
+         * `{ y, x }` 分上下 / 左右、`string` 原样下发（CSS 简写，**逃生舱**），口径与理由见 `part-padding.ts`。
+         * ⚠️ 与 `gap` 不同口径：`gap` 只开放令牌档（防间距分叉），`padding` 接具体值 —— 内距在设计稿里常是**确定坐标**，
+         * 令牌梯度（最大 24px）表达不了。⚠️ 用它之前先想一次：这个数真是「内距」吗？若是「与某个内容列对齐」这类**布局
+         * 坐标**，优先改由结构表达（同轴容器 / `columns` / `minColumnWidth`）。
          */
         padding: {
             type: PropType<Padding>;

package/dist/components/layout/index.js

@@ -79,14 +79,11 @@ const LayoutRow = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 内距：**走骨架件共享口径**（`Padding`，同 `Card` / `Form` / `Page` / `Panel`）——
-     * `number` 四边同值、`{ y, x }` 分上下 / 左右、`string` 原样下发（CSS 简写，**逃生舱**）。
-     * 口径与理由见 `part-padding.ts`。
-     *
-     * ⚠️ 与 `gap` 不同口径：`gap` 只开放令牌档（防间距分叉），`padding` 接具体值 ——
-     * 内距在设计稿里常是**确定坐标**，令牌梯度（最大 24px）表达不了。
-     * ⚠️ 用它之前先想一次：这个数真是「内距」吗？若是「与某个内容列对齐」这类**布局坐标**，
-     * 优先改由结构表达（同轴容器 / `columns` / `minColumnWidth`）。
+     * 内距：**走骨架件共享口径**（`Padding`，同 `Card` / `Form` / `Page` / `Panel`）—— `number` 四边同值、
+     * `{ y, x }` 分上下 / 左右、`string` 原样下发（CSS 简写，**逃生舱**），口径与理由见 `part-padding.ts`。
+     * ⚠️ 与 `gap` 不同口径：`gap` 只开放令牌档（防间距分叉），`padding` 接具体值 —— 内距在设计稿里常是**确定坐标**，
+     * 令牌梯度（最大 24px）表达不了。⚠️ 用它之前先想一次：这个数真是「内距」吗？若是「与某个内容列对齐」这类**布局
+     * 坐标**，优先改由结构表达（同轴容器 / `columns` / `minColumnWidth`）。
      */
     padding: {
       type: [Number, Object, String],

package/dist/components/list-view/index.d.ts

@@ -21,31 +21,13 @@ export interface ListViewStatus {
  * ## 三态
  *
  * - `loading` → **骨架卡网格**（与卡片同尺寸占位，避免加载完成时高度跳动）；
- * - `error` / `empty` → 委托 `QueryState`（口径同 CONTRACT §4.6：**错误不得塞进空态**，
- *   两条各自的恢复入口由 `errorActionText` / `emptyActionText` 给）。
+ * - `error` / `empty` → 委托 `QueryState`（口径同 CONTRACT §4.6：**错误不得塞进空态**，两条各自的恢复入口由
+ *   `errorActionText` / `emptyActionText` 给）。
  *
  * 无数据或失败时消费方**不要渲染分页**（分页归属见 CONTRACT §4.17）。
+ * **卡片外观**：列表项一律用 `ListView.CardItem`（内部以 `Card interactive` 为壳），消费方不得自绘卡片外观。
  *
- * ## 卡片外观
- *
- * 列表项一律用 `ListView.CardItem`（内部以 `Card interactive` 为壳），消费方不得自绘卡片外观。
- *
- * @example 服务卡片列表（三态；分页由承载它的容器给）
- * <ListView
- *   minItemWidth={320}
- *   loading={query.isPending.value}
- *   error={query.isError.value}
- *   errorActionText="重试"
- *   onErrorAction={() => void query.refetch()}
- *   // 空态：传字符串即空态标题（传 true 会用内置的「暂无数据」）
- *   empty={items.value.length === 0 ? '暂无服务' : false}>
- *   {items.value.map((item) => (
- *     <ListView.CardItem key={item.id} title={item.name} description={item.desc}
- *       status={{ label: '在线', tone: 'success', dot: true }}
- *       onClick={() => openDetail(item.id)}
- *       actions={() => <Button title="编辑" onClick={() => openEdit(item.id)} />} />
- *   ))}
- * </ListView>
+ * 用法见 `docs/demos/list-view/`（每个维度一份可运行样例；文档页 `docs/components/list-view.md`）。
  */
 export interface ListViewProps {
     /**
@@ -82,28 +64,13 @@ export interface ListViewProps {
 /**
  * 列表卡片项：卡片的**结构化形态**（图标 / 标题 / 副标题 / 描述 / 标签 / 状态胶囊 / 统计 / 操作位）。
  *
- * 以 `Card interactive` 为壳，卡片外观与悬浮反馈都来自它；本件只管卡片**内部**的排版与几何
- * （最小高 144、图标 36、标题 16/600、描述两行截断、尾部贴底、胶囊与标签片），
- * 几何来源同 `Card`（技能市场卡片实测）。
- *
- * 三处「有意为之」：
- * 1. **操作位默认隐藏**（`opacity: 0`），卡片悬浮或卡内获得焦点时显形；触屏（无 hover 能力）恒显形 ——
- *    因此按钮始终可聚焦、可点，只是平时不抢视觉；
- * 2. **操作位点击不冒泡**：卡内按钮（编辑 / 删除）不会顺带触发整卡的 `onClick`（打开详情）；
- * 3. **状态胶囊与标签片由本件自绘**，不复用 `Badge`：原型是**全圆角胶囊**与无最小宽的标签片，
- *    而 `Badge` 的几何是方角 + 最小宽（给徽标列宽用的），套进来会改变原型几何。
+ * 以 `Card interactive` 为壳，卡片外观与悬浮反馈都来自它；本件只管卡片**内部**的排版与几何（最小高 144、
+ * 图标 36、标题 16/600、描述两行截断、尾部贴底、胶囊与标签片），几何来源同 `Card`（技能市场卡片实测）。
  *
- * @example 带状态、标签与操作位的卡片项
- * <ListView.CardItem
- *   icon={resolveIcon(item.icon)}
- *   title={item.name}
- *   subtitle={`V${item.version}`}
- *   description={item.desc}
- *   tags={[item.topic, item.domain]}
- *   status={{ label: '在线', tone: 'success', dot: true }}
- *   extra={() => <><Icon name="download" size={14} />{item.downloadCount}</>}
- *   actions={() => <Button title="编辑" onClick={() => openEdit(item.id)} />}
- *   onClick={() => openDetail(item.id)} />
+ * 三处「有意为之」：① **操作位默认隐藏**（`opacity: 0`），卡片悬浮或卡内获得焦点时显形、触屏恒显形 —— 因此
+ * 按钮始终可聚焦、可点，只是平时不抢视觉；② **操作位点击不冒泡**（卡内按钮不会顺带触发整卡的 `onClick`）；
+ * ③ **状态胶囊与标签片由本件自绘**，不复用 `Badge` —— 原型是**全圆角胶囊**与无最小宽的标签片，而 `Badge` 的
+ * 几何是方角 + 最小宽（给徽标列宽用的），套进来会改变原型几何。
  */
 export interface ListViewCardItemProps {
     /** 图标：图片地址（`<img>`，`alt` 走空串——名称已由标题承担）或自定义节点 / 返回节点的函数 */

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

@@ -14,33 +14,22 @@ export interface LoadingProps {
  * 加载态（转圈 + 可选文案；三种形态）。
  *
  * ## 三态与三个不同的东西
- *
  * | 形态 | 用什么 | 为什么不是本件 |
  * | --- | --- | --- |
- * | 区域/页面的加载中 | `QueryState` 的 `loading` | 那件带骨架屏与三态切换，是「容器」 |
+ * | 区域 / 页面的加载中 | `QueryState` 的 `loading` | 那件带骨架屏与三态切换，是「容器」 |
  * | 内容占位 | `Skeleton` | 骨架屏表达「这里将出现什么」，不是「正在忙」 |
  * | **正在忙、请等待** | 本件 | 遮罩 + 转圈，**拦住交互**才是它的职责 |
  *
  * ## 覆盖档必须由消费方给出定位上下文
+ * `overlay="area"` 走 `position: absolute`：它铺的是**最近的定位祖先**，故宿主元素要有 `position: relative`
+ * （`Panel.Body` / `Card.Body` 这类件自带）。宿主没有定位上下文时它会跑到更外层去 —— 这是 CSS 的规则，不是本件的缺陷；
+ * 界面上看不出错位但覆盖范围不对时，先查这一条。`overlay="screen"` 走 `position: fixed`：铺整个视口，层级压在 `Toast`
+ * 堆叠（1080）之上、模态层（原生 `<dialog>` 的 top layer）之下。
  *
- * `overlay="area"` 走 `position: absolute`：它铺的是**最近的定位祖先**，所以宿主元素要有
- * `position: relative`（`Panel.Body` / `Card.Body` 这类件自带）。宿主没有定位上下文时它会跑到
- * 更外层去 —— 这是 CSS 的规则，不是本件的缺陷；界面上看不出错位但覆盖范围不对时，先查这一条。
- *
- * `overlay="screen"` 走 `position: fixed`：铺整个视口，层级压在 `Toast` 堆叠（1080）之上、
- * 模态层（原生 `<dialog>` 的 top layer）之下。
- *
- * 转圈走 `@manohub/icon` 的 `loading` 字形 + CSS 旋转（**不手绘 SVG**）；尺寸按全局图标档
- * `--ui-font-icon` 用 `calc()` 派生，换主题时与其它图标一起缩放。
- *
- * @example 行内：小转圈 + 文案
- * <Loading text="加载中" />
- *
- * @example 区域遮罩（宿主需自带 position: relative）
- * <Panel.Body><Loading overlay="area" text="保存中" /></Panel.Body>
+ * 转圈走 `@manohub/icon` 的 `loading` 字形 + CSS 旋转（**不手绘 SVG**）；尺寸按全局图标档 `--ui-font-icon` 用
+ * `calc()` 派生，换主题时与其它图标一起缩放。
  *
- * @example 全屏遮罩
- * <Loading overlay="screen" text="正在导入，请勿关闭页面" />
+ * 用法见 `docs/demos/loading/`（每个维度一份可运行样例；文档页 `docs/components/loading.md`）。
  */
 export declare const Loading: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     text: {