@manohub/ui 1.0.4 → 1.0.6

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

@@ -27,23 +27,7 @@ export interface TextareaAutoSize {
  * （`id` / `name` / `aria-*` / `data-*` / `title` / 原生事件）—— 壳只是排版容器，属性落它上面等于丢掉
  * —— 见 `forwardAttrs`；触发器形态另有 `controlClass` / `controlAttrs` 两个**专口子**（同名键以它为准）。
  *
- * @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<{
     /** 受控值 */
@@ -57,11 +41,9 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         default: string;
     };
     /**
-     * 占位文案。两种形态都消费它：
-     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
-     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
-     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
-     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
         type: StringConstructor;
@@ -82,12 +64,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;
@@ -184,11 +163,9 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         default: string;
     };
     /**
-     * 占位文案。两种形态都消费它：
-     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
-     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
-     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
-     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
         type: StringConstructor;
@@ -209,12 +186,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;
@@ -354,13 +328,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: {
@@ -524,11 +493,9 @@ export declare const InputCompound: {
             default: string;
         };
         /**
-         * 占位文案。两种形态都消费它：
-         * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
-         * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
-         *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
-         *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+         * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
+         * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+         * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
          */
         placeholder: {
             type: StringConstructor;
@@ -549,12 +516,9 @@ export declare const InputCompound: {
             default: boolean;
         };
         /**
-         * **只读**：值可选中 / 复制，但不能改。
-         *
-         * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
-         * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
-         * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-         * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+         * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+         * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+         * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
          */
         readonly: {
             type: BooleanConstructor;
@@ -685,11 +649,9 @@ export declare const InputCompound: {
             default: string;
         };
         /**
-         * 占位文案。两种形态都消费它：
-         * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
-         * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
-         *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
-         *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+         * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
+         * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+         * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
          */
         placeholder: {
             type: StringConstructor;
@@ -710,12 +672,9 @@ export declare const InputCompound: {
             default: boolean;
         };
         /**
-         * **只读**：值可选中 / 复制，但不能改。
-         *
-         * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
-         * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
-         * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-         * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+         * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+         * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+         * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
          */
         readonly: {
             type: BooleanConstructor;
@@ -837,11 +796,9 @@ export declare const InputCompound: {
         default: string;
     };
     /**
-     * 占位文案。两种形态都消费它：
-     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
-     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
-     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
-     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
         type: StringConstructor;
@@ -862,12 +819,9 @@ export declare const InputCompound: {
         default: boolean;
     };
     /**
-     * **只读**：值可选中 / 复制，但不能改。
-     *
-     * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
-     * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
-     * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+     * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+     * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
      */
     readonly: {
         type: BooleanConstructor;
@@ -1147,9 +1101,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

@@ -16,11 +16,9 @@ const Input = /* @__PURE__ */ defineComponent({
       default: ""
     },
     /**
-     * 占位文案。两种形态都消费它：
-     * - 缺省（`as="input"`）走原生 `::placeholder` 伪元素；
-     * - 触发器形态（`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载
-     *   （`.mh-input__placeholder`）—— 当且仅当 `hasValue === false` 且本 prop 有值时渲染它，
-     *   并**取代** `default` 插槽（见上面触发器一节）。没传 `hasValue` 的调用方行为不变。
+     * 占位文案（两种形态都消费它）：缺省（`as="input"`）走原生 `::placeholder` 伪元素；触发器形态
+     * （`as="button"`）**没有 `::placeholder` 可用**，改由一个 span 承载（`.mh-input__placeholder`）—— 当且仅当
+     * `hasValue === false` 且本 prop 有值时渲染它，并**取代** `default` 插槽。
      */
     placeholder: {
       type: String,
@@ -41,12 +39,9 @@ const Input = /* @__PURE__ */ defineComponent({
       default: false
     },
     /**
-     * **只读**：值可选中 / 复制，但不能改。
-     *
-     * 与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是 `Form.Item`
-     * 的 `readonly` 行推荐的写法）：几何与可编辑输入框**完全一致**（同高、同内距、值文字同左缘），
-     * 但滑过不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」。
-     * 只读 ≠ 禁用：它照旧可聚焦、可选中复制，也不变灰。
+     * **只读**：值可选中 / 复制，但不能改。与 `bordered={false}` 组合即**只读值档**（摘要 / 详情里回显业务值，也是
+     * `Form.Item` 的 `readonly` 行推荐写法）：几何与可编辑输入框**完全一致**（同高 / 同内距 / 值文字同左缘），但滑过
+     * 不亮浅底、聚焦不给边框与主色环 —— 一眼看去是「值」而不是「输入位」；只读 ≠ 禁用（照旧可聚焦、可复制、不变灰）。
      */
     readonly: {
       type: Boolean,

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: {

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

@@ -6,38 +6,21 @@ export type NavVariant = 'tree' | 'list';
  * 侧栏导航（单列、固定宽、内滚）：**`tree` / `list` 两态，行渲染完全复用 `Tree`**。
  *
  * ## 为什么不是 `Tree` 的一个 prop
+ * `Tree` 是**展示件**（层级数据怎么显示）；导航是另一种语义：选中驱动右侧内容、单列固定宽、外壳自己滚动。两者对**行**
+ * 的几何要求完全一致，故本件不重写行渲染 —— 数据、展开态、选中态、缩进、三态全部交给 `Tree`（不存在第二棵树）；两态
+ * 的差异只有一处：`variant="list"` 隐藏箭头占位（扁平导航没有层级）。
  *
- * `Tree` 是**展示件**（层级数据怎么显示）；导航是另一种语义：选中驱动右侧内容、单列固定宽、
- * 外壳自己滚动。两者对**行**的几何要求完全一致，所以本件不重写行渲染 —— 数据、展开态、选中态、
- * 缩进、三态全部交给 `Tree`，改一处两处同时生效（不存在第二棵树）。
- * 两态的差异只有一处：`variant="list"` 隐藏箭头占位（扁平导航没有层级，不需要那一段缩进）。
+ * ## 滚动归属 / 宽度
+ * 根件 `overflow: hidden`，**只有 `mh-nav__body` 滚**（与 `Panel.Body` 同一口径）。缺省**填满所在栏**
+ * （`width: var(--mh-nav-width, 100%)`）—— 列宽由 `Page.Split` 的侧栏列或外层布局决定，不重复锁一个可能与栏宽不符的
+ * 数；独立使用需要固定宽时传 `width`（px 数字）。
  *
- * ## 滚动归属
+ * ## 行尾操作 / 图标
+ * `renderActions` 直接透传给 `Tree`（默认隐藏、行悬浮或行内获得焦点时显形、点击不冒泡）—— 应用侧只给节点，不要自己写
+ * 显隐 CSS，也不要塞进 `renderNode`（那是常驻附加内容）。导航项图标走 `renderIcon`，**不要**用 `renderLabel` 拼
+ * 「图标 + 文字」：标签槽承担省略号与行内对齐，图标进去会被裁掉、也不成列。
  *
- * 根件 `overflow: hidden`，**只有 `mh-nav__body` 滚**（与 `Panel.Body` 同一口径）：
- * 侧栏滚动不再由应用侧写 `overflow-y: auto` 的应用侧类来顶。
- *
- * ## 宽度
- *
- * 缺省**填满所在栏**（`width: var(--mh-nav-width, 100%)`）：列宽由 `Page.Split` 的侧栏列
- * 或外层布局决定，导航件不重复锁一个可能与栏宽不符的数；独立使用需要固定宽时传 `width`（px 数字）。
- *
- * ## 行尾操作
- *
- * `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)}
- *   expandedKeys={expandedKeys.value} onExpandChange={(keys) => (expandedKeys.value = keys)}
- *   loading={query.isPending.value} error={query.isError.value} empty="暂无分类"
- *   renderActions={(node) => <Button title="删除" onClick={() => removeCategory(node.id)} />} />
+ * 用法见 `docs/demos/nav/`（每个维度一份可运行样例；文档页 `docs/components/nav.md`）。
  */
 export declare const Nav: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 导航形态：`tree`（默认，层级 + 箭头）/ `list`（扁平，无箭头占位） */
@@ -138,9 +121,7 @@ export declare const Nav: import("vue").DefineComponent<import("vue").ExtractPro
         default: undefined;
     };
     /**
-     * 错误态（truthy 即触发）。
-     *
-     * **构造器顺序同 `Tree.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
+     * 错误态（truthy 即触发）。**构造器顺序同 `Tree.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
      * 空字符串会被 Vue 的布尔转换判成 `true`，侧栏永远停在错误态。
      */
     error: {
@@ -265,9 +246,7 @@ export declare const Nav: import("vue").DefineComponent<import("vue").ExtractPro
         default: undefined;
     };
     /**
-     * 错误态（truthy 即触发）。
-     *
-     * **构造器顺序同 `Tree.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
+     * 错误态（truthy 即触发）。**构造器顺序同 `Tree.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
      * 空字符串会被 Vue 的布尔转换判成 `true`，侧栏永远停在错误态。
      */
     error: {

package/dist/components/nav/index.js

@@ -102,9 +102,7 @@ const Nav = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 错误态（truthy 即触发）。
-     *
-     * **构造器顺序同 `Tree.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
+     * 错误态（truthy 即触发）。**构造器顺序同 `Tree.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
      * 空字符串会被 Vue 的布尔转换判成 `true`，侧栏永远停在错误态。
      */
     error: {