@manohub/ui 1.0.4 → 1.0.6

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

@@ -5,31 +5,15 @@ export type NoticeTone = 'info' | 'success' | 'warning' | 'error';
  * 说明条 / 警告提示（**自建**，不封装 farris）。
  *
  * ## 为什么自建
- *
- * 它要的是**嵌在页面里的一行说明**（通栏、语义三件套「底 / 边 / 字」、操作为文字按钮）——
- * 与 `Notification`（有标题与头像的卡片）、`Toast`（浮出后自己消失）都不是一回事，
- * 三者的判据是**出现方式**（见 `Toast` 的「与 Notice / Notification 的判据」）。
- * 上游没有可复用的形态，故自建并定为本包的一族。
+ * 它要的是**嵌在页面里的一行说明**（通栏、语义三件套「底 / 边 / 字」、操作为文字按钮）—— 与 `Notification`（有标题与
+ * 头像的卡片）、`Toast`（浮出后自己消失）都不是一回事，三者的判据是**出现方式**（见 `Toast` 的「与 Notice /
+ * Notification 的判据」）；上游没有可复用的形态，故自建并定为本包的一族。
  *
  * ## 口径（取自主题包 Alert 规范）
- *
- * - **警示 / 错误须常驻**（不渲染关闭按钮），只有通知类信息才可关闭 —— 故 `closable` 默认 `false`，
- *   由消费方显式开启；
- * - 位置：页面顶部通栏（页面主体顶部），静态展示、不随滚动消失。
- *
- * ## 两种排版（按内容量选）
- *
- * | 内容 | 写法 | 排布 |
- * | --- | --- | --- |
- * | 一行话 | 默认插槽 / `description` | 单行，图标与文字同行 |
- * | 有标题 | `message` + `description`（或插槽） | **标题行 + 描述行**两行 |
- *
- * @example 可关闭的说明条（列表页顶部）
- * <Notice closable onClose={() => (visible = false)} icon>值映射用于将来源向量转换为目标值。</Notice>
- *
- * @example 带标题与操作
- * <Notice tone="warning" icon message="尚未完成实名认证" description="使用该服务前须完成认证"
- *   action="立即认证" :on-action="goAuth" />
+ * **警示 / 错误须常驻**（不渲染关闭按钮），只有通知类信息才可关闭 —— 故 `closable` 默认 `false`，由消费方显式开启；
+ * 位置：页面顶部通栏（页面主体顶部），静态展示、不随滚动消失。
+ * **两种排版**（按内容量选）：一行话（默认插槽 / `description`）→ 单行，图标与文字同行；有标题（`message` +
+ * `description` 或插槽）→ **标题行 + 描述行**两行。
  */
 export declare const Notice: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 语义类型；决定底/边/字三件套与图标 */
@@ -48,11 +32,9 @@ export declare const Notice: import("vue").DefineComponent<import("vue").Extract
         default: undefined;
     };
     /**
-     * 前置图标：缺省 `false` 不出图标；`true` 按 `tone` 映射；也可直接给字形名。
-     *
-     * 与 `Toast.icon` / `Notification.icon` **同名同型**（0.6.x 本件叫 `showIcon` 且只收布尔，
-     * 三件三个名字三种默认 —— 已统一）。默认值仍与 `Toast` 不同：`Toast` 是「浮出即走」的
-     * 消息条，图标是它的主要语义承载；本件是嵌在页面里的说明条，页面里别处往往已经有图标，故缺省不出。
+     * 前置图标：缺省 `false` 不出图标；`true` 按 `tone` 映射；也可直接给字形名。与 `Toast.icon` /
+     * `Notification.icon` **同名同型**（0.6.x 本件叫 `showIcon` 且只收布尔，三件三个名字三种默认 —— 已统一）。默认
+     * 值仍与 `Toast` 不同：`Toast` 是「浮出即走」的消息条、图标是它的主要语义承载；本件嵌在页面里、别处往往已有图标。
      */
     icon: {
         type: PropType<boolean | IconName>;
@@ -100,11 +82,9 @@ export declare const Notice: import("vue").DefineComponent<import("vue").Extract
         default: undefined;
     };
     /**
-     * 前置图标：缺省 `false` 不出图标；`true` 按 `tone` 映射；也可直接给字形名。
-     *
-     * 与 `Toast.icon` / `Notification.icon` **同名同型**（0.6.x 本件叫 `showIcon` 且只收布尔，
-     * 三件三个名字三种默认 —— 已统一）。默认值仍与 `Toast` 不同：`Toast` 是「浮出即走」的
-     * 消息条，图标是它的主要语义承载；本件是嵌在页面里的说明条，页面里别处往往已经有图标，故缺省不出。
+     * 前置图标：缺省 `false` 不出图标；`true` 按 `tone` 映射；也可直接给字形名。与 `Toast.icon` /
+     * `Notification.icon` **同名同型**（0.6.x 本件叫 `showIcon` 且只收布尔，三件三个名字三种默认 —— 已统一）。默认
+     * 值仍与 `Toast` 不同：`Toast` 是「浮出即走」的消息条、图标是它的主要语义承载；本件嵌在页面里、别处往往已有图标。
      */
     icon: {
         type: PropType<boolean | IconName>;

package/dist/components/notice/index.js

@@ -26,11 +26,9 @@ const Notice = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 前置图标：缺省 `false` 不出图标；`true` 按 `tone` 映射；也可直接给字形名。
-     *
-     * 与 `Toast.icon` / `Notification.icon` **同名同型**（0.6.x 本件叫 `showIcon` 且只收布尔，
-     * 三件三个名字三种默认 —— 已统一）。默认值仍与 `Toast` 不同：`Toast` 是「浮出即走」的
-     * 消息条，图标是它的主要语义承载；本件是嵌在页面里的说明条，页面里别处往往已经有图标，故缺省不出。
+     * 前置图标：缺省 `false` 不出图标；`true` 按 `tone` 映射；也可直接给字形名。与 `Toast.icon` /
+     * `Notification.icon` **同名同型**（0.6.x 本件叫 `showIcon` 且只收布尔，三件三个名字三种默认 —— 已统一）。默认
+     * 值仍与 `Toast` 不同：`Toast` 是「浮出即走」的消息条、图标是它的主要语义承载；本件嵌在页面里、别处往往已有图标。
      */
     icon: {
       type: [Boolean, String],

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

@@ -21,15 +21,6 @@ export type NotificationTone = 'info' | 'success' | 'warning' | 'error' | 'submi
  *
  * 关闭是**受控**的：本件只回调 `onClose`，不自己隐藏（可见性归消费方，避免「点了没反应」与
  * 「组件自己消失」两套口径）。`duration` 到点也只回调 —— 与 `Toast` 同一口径。
- *
- * @example 基础
- * <Notification tone="warning" title="待办超期" closable @close="dismiss">3 个任务已超期</Notification>
- *
- * @example 图标 + 自动消失 + 头像 + 标签
- * <Notification icon duration={4000} tone="info" title="审批通知" avatar="张" @close="dismiss">
- *   <Badge shape="soft" tone="error">逾期</Badge>
- *   {{ actions: () => <Button size="sm" variant="primary">去处理</Button> }}
- * </Notification>
  */
 export declare const Notification: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     tone: {

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

@@ -3,97 +3,56 @@ import { type Padding } from '../part-padding';
 /**
  * 页面骨架复合件 —— 页面结构与滚动归属的统一契约。
  *
- * 滚动契约写死在 `.mh-page*` 样式：Header / Filter / Footer 不滚；
- * Body 只管**页面级**滚动归属，只有两档：`mode="scroll"` 自身滚（长内容页）、
- * `mode="plain"`（默认）不滚 —— 滚动下沉到区域内容区或内容件自持的定高容器。
- * **表格不靠 Body 的 mode 表达**：外框由 `Table` 的 `framed` 档给，高度与滚动由
- * 承载它的内容件承担（`Panel.Body`，或表格件自带的定高容器）。
+ * 滚动契约写死在 `.mh-page*` 样式：Header / Filter / Footer 不滚；Body 只管**页面级**滚动归属，只有两档：
+ * `mode="scroll"` 自身滚（长内容页）、`mode="plain"`（默认）不滚（滚动下沉到区域内容区或内容件自持的定高
+ * 容器）。**表格不靠 Body 的 mode 表达**：外框由 `Table` 的 `framed` 档给，高度与滚动由承载它的内容件承担
+ * （`Panel.Body`，或表格件自带的定高容器）。
  *
- * **Split 不滚，栏内滚动由内容承担** —— 双栏内部用 `Panel`
- * （Header 固定 + Body `overflow:auto`）承载各自区域的滚动。
+ * **Split 不滚，栏内滚动由内容承担** —— 双栏内部用 `Panel`（Header 固定 + Body `overflow:auto`）承载各自
+ * 区域的滚动。
  *
- * 与 `Panel` 的分工：本件是**页面级**（唯一），管页头规格、页脚固定、页面级滚动归属；
- * `Panel` 是**区域级**（可多个），只管区域内的三件与区域内滚动。分页归属跟承载表格的容器走。
+ * 与 `Panel` 的分工：本件是**页面级**（唯一），管页头规格 / 页脚固定 / 页面级滚动归属；`Panel` 是**区域级**
+ * （可多个），只管区域内的三件与区域内滚动。分页归属跟承载表格的容器走。
  *
- * **侧栏能力（内建，缺省开启，无需消费方配置）**：
- * - 分隔线即拖拽手柄：按住左右拖即改宽，夹在 `minWidth`（缺省 160）与 `maxWidth`（缺省 480）之间；
- * - 手柄上悬停显形一个箭头按钮，点击收起侧栏；收起后页面边缘常驻 16px 展开把手，点击展开并恢复收起前的宽度
- *   —— 展开按钮**占满整条把手**（全高全宽 + 描边 + 底），收起态里它是整块侧栏唯一看得见的东西；
- * - `width` 只是**初始宽度**：拖拽结果不持久化（刷新 / 重进回到初始宽度），收起也不清拖出的宽度；
- * - **宽度过渡期间内容不重排**：内容按展开时的宽度定宽（组件下发 `--mh-page-split-frozen`），
- *   多出的部分由容器裁掉 —— 栏内滚动容器不会因宽度被压缩而闪出滚动条；
- * - 左侧栏用 `sidebar`、右侧栏用 `rightSidebar`（互为镜像：分隔线在侧栏左侧、拖拽方向相反），
- *   两者可同时存在构成三栏；某侧传 `resizable: false` 时该侧不渲染手柄与把手。
+ * **侧栏能力（内建，缺省开启）**：分隔线即拖拽手柄（按住左右拖即改宽，夹在 `minWidth` 缺省 160 与
+ * `maxWidth` 缺省 480 之间）；手柄悬停显形一个箭头按钮，点击收起侧栏，收起后页面边缘常驻 16px 展开把手
+ * （**占满整条把手**：全高全宽 + 描边 + 底），点击展开并恢复收起前的宽度；`width` 只是**初始宽度**（拖拽
+ * 结果不持久化，收起也不清拖出的宽度）；**宽度过渡期间内容不重排**（内容按展开时的宽度定宽，组件下发
+ * `--mh-page-split-frozen`，多出的部分由容器裁掉，栏内滚动容器不会闪出滚动条）；左侧栏 `sidebar`、右侧栏
+ * `rightSidebar`（互为镜像），两者可同时存在构成三栏，某侧传 `resizable: false` 则不渲染手柄与把手。
  *
- * 两级滚动归属（契约）：
- * - `Page.Body.mode` 管**页面级**（scroll/plain，全页唯一）；
- * - `Panel.Body` 管**区域内**（Header 固定 / 内容滚）。
+ * 两级滚动归属（契约）：`Page.Body.mode` 管**页面级**（scroll / plain，全页唯一）；`Panel.Body` 管**区域内**。
  *
- * **成员位置固定（归位）**：成员不按书写顺序渲染 —— 以本件为根，一律归到固定位置，
- * 于是「读代码的顺序」不必等于「视觉顺序」（页脚写最前面也仍在底部）：
- * - **页面级行**：`Filter → Header → Body → Footer`（与 `Panel` 同款归位法）；
- * - **主体区**：自由内容（含直接写在根下的 `Page.Split`）—— 没写显式 `Page.Body` 时
- *   自动包一层 `Page.Body`（缺省 `mode="plain"`），所以双栏可以只写 `Page.Split`。
+ * **成员位置固定（归位）**：成员不按书写顺序渲染 —— 以本件为根一律归到固定位置，故「读代码的顺序」不必
+ * 等于「视觉顺序」（页脚写最前面也仍在底部）：页面级行 = `Filter → Header → Body → Footer`（与 `Panel`
+ * 同款归位法）；主体区自由内容（含直接写在根下的 `Page.Split`）没写显式 `Page.Body` 时自动包一层
+ * （缺省 `mode="plain"`），所以双栏可以只写 `Page.Split`。
  *
- * 页头右侧的自由位（搜索框 / 按钮 / 等）是 `Page.Header` 的 `extra` 位（属性或插槽），
- * 没有独立的成员件：那个位置只有页头一个承载者，写成成员等于给它加一层没有意义的转发。
+ * 页头右侧的自由位（搜索框 / 按钮 / 等）是 `Page.Header` 的 `extra` 位（属性或插槽），**没有独立的成员件**：
+ * 那个位置只有页头一个承载者，写成成员等于给它加一层没有意义的转发。
  *
- * @example
- * // 模板 A：列表页（页头 + 表格 + 页脚分页）
- * <Page>
- *   <Page.Header title="技能分类" subTitle="共 128 个技能"
- *                extra={<搜索框 modelValue={kw} />} />
- *   <Page.Body mode="plain">
- *     <Table framed rows={rows} columns={columns} rowKey="id" />
- *   </Page.Body>
- *   <Page.Footer>
- *     <Pagination page={page} pageSize={size} total={total} onPageChange={…} />
- *   </Page.Footer>
- * </Page>
- *
- * // 模板 B：双栏（Split 提供中间分隔线，栏内滚动由 Panel 承担）
- * <Page.Body mode="plain">
- *   <Page.Split sidebar={{ width: 208, content: () => <Panel title="业务域" /> }}>
- *     <Panel title="值映射列表"><Table framed rows={rows} columns={cols} rowKey="id" /></Panel>
- *   </Page.Split>
- * </Page.Body>
+ * 用法见 `docs/demos/page/`（每个维度一份可运行样例；文档页 `docs/components/page.md`）。
  */
 /** 页面骨架（及其各部件）的内距：与 `Panel` / `Form` 共用一套口径（`number` = 四边同值；`{ y, x }` 分别给） */
 export type PagePadding = Padding;
 export interface PageHeaderProps {
     /** 传入 title 走内置布局；不传则纯 slot 直出（自定义页头出口） */
     title?: string;
-    /**
-     * 页头副标题：标题**下一行**的次要说明（对象名、统计口径等），随 `title` 一起进内置布局。
-     * 不传即不渲染（页头条高度不变）；`title` 不传时本项不生效（整块走自定义页头出口）。
-     */
+    /** 页头副标题：标题**下一行**的次要说明（对象名、统计口径等），随 `title` 一起进内置布局。不传即不渲染（页头条高度不变）；`title` 不传时本项不生效。 */
     subTitle?: string;
-    /**
-     * 标题左侧图标：**svg 节点或返回节点的函数**皆可。缺省渲染设计稿默认图标
-     * （MH后台-0911 node 0:3904：26×26 圆角方块，`currentColor` 随主题）。
-     */
+    /** 标题左侧图标：**svg 节点或返回节点的函数**皆可；缺省渲染设计稿默认图标（MH后台-0911 `0:3904`：26×26 圆角方块，`currentColor` 随主题）。 */
     icon?: VNodeChild | (() => VNodeChild);
-    /**
-     * 页头右侧的自由位（唯一可自定义位）：搜索框 / 按钮 / 下拉等，水平排列。
-     * 传节点或返回节点的函数。布局（垂直居中 / 间距）由标准样式锁死。
-     */
+    /** 页头右侧的自由位（唯一可自定义位）：搜索框 / 按钮 / 下拉等，水平排列；传节点或返回节点的函数。布局（垂直居中 / 间距）由标准样式锁死。 */
     extra?: unknown;
 }
 export interface PageBodyProps {
     /** scroll=自身滚（长内容页）；plain=不滚（默认，滚动归区域内容区 / 内容件自持的定高容器） */
     mode?: 'scroll' | 'plain';
-    /**
-     * 内容区内距（px 数字 = 四边同值；`{ y, x }` 分别给）。缺省不落行内样式，沿用 CSS 默认（`0 20px`）——
-     * 行内只覆盖**给到的轴**，所以传 `{ y: 16 }` 时左右仍是 CSS 的 20px（与页头左对齐不破）。
-     * 典型用法：「表格 / 卡片不贴页头下边线」→ `padding={{ y: 16 }}`。
-     */
+    /** 内容区内距（px 数字 = 四边同值；`{ y, x }` 分别给）。缺省不落行内样式，沿用 CSS 默认（`0 20px`）—— 行内只覆盖**给到的轴**，故传 `{ y: 16 }` 时左右仍是 20px（与页头左对齐不破）。典型用法：表格 / 卡片不贴页头下边线 → `padding={{ y: 16 }}`。 */
     padding?: PagePadding;
 }
 export interface PageSplitSidebarProps {
-    /**
-     * 该侧栏的**初始**内容宽（px 数字，`content-box` 语义）：
-     * 不传即自适应（不写死宽度）；拖拽后以拖出的宽度为准 —— 拖拽结果不持久化，刷新 / 重进回到本值。
-     */
+    /** 该侧栏的**初始**内容宽（px，`content-box` 语义）：不传即自适应（不写死宽度）；拖拽后以拖出的宽度为准 —— 结果不持久化，刷新 / 重进回到本值。 */
     width?: number;
     /** 是否内建拖拽手柄与收起按钮，缺省 `true`；`false` 时该侧不渲染手柄/把手、不挂监听 */
     resizable?: boolean;
@@ -113,9 +72,8 @@ export interface PageSplitProps {
     rightSidebar?: PageSplitSidebarProps;
 }
 /**
- * Object.assign 复合件。两个注意点：
- * 1. Object.assign 后不要再 defineComponent 二次包装，否则 props 类型丢失；
- * 2. 每个子件必须显式声明 slots（SlotsType），否则 JSX 下 slot 参数类型退化为 any。
+ * Object.assign 复合件。两个注意点：① Object.assign 后不要再 defineComponent 二次包装，否则 props 类型丢失；
+ * ② 每个子件必须显式声明 slots（`SlotsType`），否则 JSX 下 slot 参数类型退化为 any。
  */
 export declare const Page: {
     new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<{}> & Readonly<{}>, () => import("vue/jsx-runtime").JSX.Element, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, import("vue").PublicProps, {}, true, {}, SlotsType<{

package/dist/components/page/split-resize.d.ts

@@ -1,12 +1,9 @@
 /**
  * `Page.Split` 侧栏交互的内部纯函数与常量（**不进对外导出面**：`src/index.ts` 白名单不外扩）。
  *
- * 抽出来的理由：宽度夹取与基准实测是**带分支的纯逻辑**（区间归一化、非有限数容错、
- * content-box 语义下的内距扣除、无布局环境下的回退顺序），放一处便于直接单测；
- * 组件里只留状态与 DOM 绑定。
- *
- * 已知取舍：`measureSidebarWidth` 依赖 `clientWidth`，jsdom 没有布局引擎（恒为 0），
- * 走的是「回退到 prop 宽度 → 回退到兜底常量」这条路径；浏览器里才有真实实测值。
+ * 抽出来的理由：宽度夹取与基准实测是**带分支的纯逻辑**（区间归一化、非有限数容错、content-box 语义下的内距扣除、无布局
+ * 环境下的回退顺序），放一处便于直接单测；组件里只留状态与 DOM 绑定。已知取舍：`measureSidebarWidth` 依赖
+ * `clientWidth`，jsdom 没有布局引擎（恒为 0），走的是「回退到 prop 宽度 → 回退到兜底常量」这条路径。
  */
 /** 侧栏所在侧：`left` = `sidebar` 槽位；`right` = `rightSidebar` 槽位（镜像） */
 export type SplitSide = 'left' | 'right';
@@ -14,10 +11,7 @@ export type SplitSide = 'left' | 'right';
 export declare const SPLIT_MIN_WIDTH = 160;
 /** 拖拽上限缺省值（px） */
 export declare const SPLIT_MAX_WIDTH = 480;
-/**
- * 未传 `width` 且实测不到时的拖拽基准兜底。
- * **只用于拖拽基准**，不参与初始渲染 —— 所以不违背「不传 `width` 就不写死宽度」的口径。
- */
+/** 未传 `width` 且实测不到时的拖拽基准兜底。**只用于拖拽基准**、不参与初始渲染 —— 故不违背「不传 `width` 就不写死宽度」的口径。 */
 export declare const SPLIT_FALLBACK_WIDTH = 208;
 /** 区间归一化：`max < min` 时按数值大小归位（不抛错），缺省 160 / 480 */
 export declare function splitWidthBounds(min?: number, max?: number): {
@@ -25,18 +19,15 @@ export declare function splitWidthBounds(min?: number, max?: number): {
     max: number;
 };
 /**
- * 夹取到区间并取整（防亚像素抖动）。
- *
- * 非有限数的口径：`NaN` 无法比较大小 ⇒ 落回下限；`±Infinity` 有明确方向
- * （"拖到无穷远"就是顶到那侧的边界）⇒ 由 `Math.min/max` 自然夹到上限 / 下限。
+ * 夹取到区间并取整（防亚像素抖动）。非有限数的口径：`NaN` 无法比较大小 ⇒ 落回下限；`±Infinity` 有明确方向（「拖到无穷
+ * 远」就是顶到那侧的边界）⇒ 由 `Math.min/max` 自然夹到上限 / 下限。
  */
 export declare function clampSplitWidth(value: number, min?: number, max?: number): number;
 /** 拖拽位移投影为宽度：右侧栏镜像（向左拖变宽） */
 export declare function projectSplitWidth(base: number, deltaX: number, side: SplitSide): number;
 /**
- * 实测某侧栏的**内容宽**（与 `box-sizing: content-box` 的 `width` 同语义）。
- *
- * `clientWidth` 天然排除边框、包含内距，故减去该侧内距即内容宽 —— 不必手工补 1px 边框。
- * 取不到正值（jsdom 无布局 / 未渲染 / 已收起）时按 `prop 宽度 → 兜底常量` 回退。
+ * 实测某侧栏的**内容宽**（与 `box-sizing: content-box` 的 `width` 同语义）。`clientWidth` 天然排除边框、包含内距，
+ * 故减去该侧内距即内容宽 —— 不必手工补 1px 边框。取不到正值（jsdom 无布局 / 未渲染 / 已收起）时按「prop 宽度 →
+ * 兜底常量」回退。
  */
 export declare function measureSidebarWidth(el: HTMLElement | null | undefined, side: SplitSide, fallback?: number): number;

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

@@ -22,11 +22,7 @@ export type PaginationPageItem = number | 'ellipsis';
  * 本件只管"翻到第几页"；**列表为空/加载中/出错**由 `QueryState` 承载（本件只在 `total === 0` 时给出一行
  * 兜底文案，因为分页条自己也得说清"没数据"而不是显示 `共 0 条`）。
  *
- * @example 基本
- * <Pagination :total="243" v-model="page" v-model:page-size="size" />
- *
- * @example 跳页 + 单页隐藏
- * <Pagination :total="243" show-quick-jumper hide-on-single-page v-model="page" />
+ * 用法见 `docs/demos/pagination/`（每个维度一份可运行样例；文档页 `docs/components/pagination.md`）。
  */
 export declare const Pagination: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 总条数 */

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

@@ -1,71 +1,51 @@
 import { type PropType, type SlotsType, type VNodeChild } from 'vue';
 import { type Padding } from '../part-padding';
 /**
- * 区域容器（页面内分区）—— 与 `Page` 的分工：
- *
- * - `Page`：**页面级**（唯一）。管页头规格、Footer 固定、页面级滚动归属（`Body.mode`）。
- * - `Panel`：**区域级**（可多个）。只管区域内的三件（Header / Body / Footer）与区域内滚动
- *   （Header 与 Footer 固定、只有 Body 滚），**不参与页面高度分配**，也不决定页面级滚动归属。
+ * 区域容器（页面内分区）—— 与 `Page` 的分工：`Page` 是**页面级**（唯一），管页头规格 / Footer 固定 / 页面级
+ * 滚动归属（`Body.mode`）；`Panel` 是**区域级**（可多个），只管区域内的三件（Header / Body / Footer）与区域内滚动
+ * （Header 与 Footer 固定、只有 Body 滚），**不参与页面高度分配**，也不决定页面级滚动归属。
  *
  * ## 三件结构（与 `Page` 同款复合写法）
  *
- * ```
- * <Panel>
- *   <Panel.Header title="值映射列表" toolbar={…} actions={…} />
- *   <Panel.Body>…内容（表格 / 树 / 表单）…</Panel.Body>
- *   <Panel.Footer><分页器 … /></Panel.Footer>
- * </Panel>
- * ```
- *
- * 简写仍可用（等价于「内建 Header + 包一层的 Body」）：`<Panel title=… toolbar=… actions=…>内容</Panel>`；
- * 两种写法可混用 —— 显式的 `Panel.Header/ Body/ Footer` 会被提到对应位置，其余子节点自动进 Body。
+ * `<Panel>` → `<Panel.Header title=… toolbar=… actions=… />` + `<Panel.Body>…内容（表格 / 树 / 表单）…</Panel.Body>`
+ * + `<Panel.Footer><分页器 … /></Panel.Footer>`。
+ * 简写仍可用（等价于「内建 Header + 包一层的 Body」）：`<Panel title=… toolbar=… actions=…>内容</Panel>`；两种
+ * 写法可混用 —— 显式的 `Panel.Header/Body/Footer` 会被提到对应位置，其余子节点自动进 Body。
  *
  * ## 分页归属（**跟承载表格的容器走**）
  *
- * 分页条不按「页面」决定位置，而按**表格所在容器**：
- * - 表格在 `Panel` 里（区域级列表）→ 放 `Panel.Footer`（面板内表 + 分页是一个整体，面板体滚动、分页常驻）；
- * - 表格直接挂在 页面主体 下（页面级列表）→ 放 页面页脚。
- * 把区域列表的分页提到 页面页脚（或把页面级分页塞进面板）都属于错位。
+ * 分页条不按「页面」决定位置，而按**表格所在容器**：表格在 `Panel` 里（区域级列表）→ 放 `Panel.Footer`
+ * （面板内表 + 分页是一个整体，面板体滚动、分页常驻）；表格直接挂在页面主体下（页面级列表）→ 放页面页脚。
+ * 把区域列表的分页提到页面页脚（或把页面级分页塞进面板）都属于错位。
  *
  * ## 无框契约
  *
- * `Panel` 自身**不加描边、不加圆角、不加阴影、不设独立底色、不加单侧边框** ——
- * 分区感只由 Header 下方的 1px 分隔线提供（与 `.mh-page__header` 同一手法）；
- * 两栏之间的竖直分隔线由 `Page` 提供。
- * 需要卡片外观时由**内容件**承载（表格用 `表格.framed`），业务侧不得给面板补描边/圆角/阴影。
+ * `Panel` 自身**不加描边 / 圆角 / 阴影 / 独立底色 / 单侧边框** —— 分区感只由 Header 下方的 1px 分隔线提供
+ * （与 `.mh-page__header` 同一手法）；两栏之间的竖直分隔线由 `Page` 提供。需要卡片外观时由**内容件**承载
+ * （表格用 `framed`），业务侧不得给面板补描边 / 圆角 / 阴影。
  *
  * ## 内距（`padding`）
  *
  * 面板与它的三件吃**同一套** `padding`（px 数字 / `{ y, x }`），缺省都不吃（贴各自的边）：
  *
- * - 根件 = 整块面板的内距：页面里的区域通常不吃（内外距由 `Page` 的各部件给）；
- *   弹窗内的区域没有别的东西可给内距，用它自带（`padding={{ y: 12, x: 20 }}`）——
- *   这样就不必再给面板挂一个「只写 padding」的应用侧类（那类规则曾经每个弹窗各写一份）。
- * - `Panel.Body` = 内容区的内距，**弹窗里最常用的一条**：如向导内容区
- *   `padding={{ y: 24, x: 100 }}` —— `y` 是上下留白，`x` 开大即充当**限宽**
- *   （宽弹窗里不让表单行一路拉到右边缘）；这条以前是应用侧的「只写 padding」类。
+ * - 根件 = 整块面板的内距：页面里的区域通常不吃（内外距由 `Page` 的各部件给）；弹窗内的区域没有别的东西可给内距，
+ *   用它自带（`padding={{ y: 12, x: 20 }}`）—— 这样就不必再给面板挂一个「只写 padding」的应用侧类。
+ * - `Panel.Body` = 内容区的内距，**弹窗里最常用的一条**：如向导内容区 `padding={{ y: 24, x: 100 }}` —— `y` 是
+ *   上下留白，`x` 开大即充当**限宽**（宽弹窗里不让表单行一路拉到右边缘）。
  * - `Panel.Footer` = 常驻控件（分页条等）与内容的距离，如 `padding={{ y: 10 }}`。
- * - `Panel.Header` = 内建头那一行的内距；走 `header` 插槽时（整行替换）会把自定义头**包一层**
- *   只带内距的 div（自定义头内部的几何仍归消费方）。
+ * - `Panel.Header` = 内建头那一行的内距；走 `header` 插槽时（整行替换）会把自定义头**包一层**只带内距的 div
+ *   （自定义头内部的几何仍归消费方）。
  *
  * ## 两位分工（不可互换）
  *
- * - `toolbar`：**本区域的筛选/搜索位**（≤3 个字段，过滤本区域数据）
- * - `actions`：**本区域的操作位**（该区域的新建 / 刷新等）
- *
- * 筛选归属判据：**先问「过滤谁的数据」决定放哪个区域的 toolbar，再问「几个字段」** ——
- * 字段数 > 3 时上提为页面级 页面级筛选区。把筛选塞进 `actions`、或把操作塞进 `toolbar` 均属违规。
+ * `toolbar` = **本区域的筛选 / 搜索位**（≤3 个字段，过滤本区域数据）；`actions` = **本区域的操作位**（该区域的
+ * 新建 / 刷新等）。筛选归属判据：**先问「过滤谁的数据」决定放哪个区域的 toolbar，再问「几个字段」** —— 字段数
+ * > 3 时上提为页面级筛选区；把筛选塞进 `actions`、或把操作塞进 `toolbar` 均属违规。
+ * 完全自定义的面板头请走 `Panel.Header`（不传 `title`）或 `header` 插槽（需在接入方登记为白名单）。**只给
+ * `toolbar` / `actions`、不给 `title` 也是合法形态**：那一行照渲染（标题在容器外层时用，如弹窗内的区域 ——
+ * 弹窗标题栏已写了区域名，面板头只剩一行「搜索 + 操作」）；三样都不给才不渲染头。
  *
- * 完全自定义的面板头请走 `Panel.Header`（不传 `title`）或 `header` 插槽（需在接入方登记为白名单）。
- * **只给 `toolbar` / `actions`、不给 `title` 也是合法形态**：那一行照渲染（标题在容器外层时用，如弹窗内的区域
- * —— 弹窗标题栏已写了区域名，面板头只剩一行「搜索 + 操作」）；三样都不给才不渲染头。
- *
- * @example 区域级列表（表格 + 分页都在本区域内）
- * <Panel>
- *   <Panel.Header title="值映射列表" toolbar={<搜索框 … />} actions={<Button>新建</Button>} />
- *   <Panel.Body><表格 framed rows={rows} columns={columns} rowKey="id" /></Panel.Body>
- *   <Panel.Footer><分页器 page={page} pageSize={size} total={total} onPageChange={…} /></Panel.Footer>
- * </Panel>
+ * 用法见 `docs/demos/panel/`（每个维度一份可运行样例；文档页 `docs/components/panel.md`）。
  */
 export interface PanelProps {
     /** 面板标题；缺省时若提供了 `header` 插槽则走完全自定义面板头 */
@@ -90,10 +70,7 @@ export interface PanelProps {
 export type PanelPadding = Padding;
 /** 面板标题行（区域级）：标题 + 本区域筛选位(toolbar) + 本区域操作位(actions) */
 export declare const PanelHeader: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
-    /**
-     * 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行
-     * （无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。
-     */
+    /** 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行（无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。 */
     title: {
         type: StringConstructor;
         default: undefined;
@@ -114,10 +91,7 @@ export declare const PanelHeader: import("vue").DefineComponent<import("vue").Ex
         default: undefined;
     };
 }>, () => VNodeChild, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
-    /**
-     * 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行
-     * （无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。
-     */
+    /** 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行（无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。 */
     title: {
         type: StringConstructor;
         default: undefined;
@@ -176,10 +150,8 @@ export declare const PanelBody: import("vue").DefineComponent<import("vue").Extr
     default?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 /**
- * 面板页脚：区域内**常驻**控件（本区域表格的分页条等），不随内容滚动。
- *
- * `padding` 用来把常驻控件与上面的内容拉开（如 `padding={{ y: 10 }}`）——
- * 页脚自己没有内距，以前这条距离各弹窗各写一个 `padding-top` 的应用侧类。
+ * 面板页脚：区域内**常驻**控件（本区域表格的分页条等），不随内容滚动。`padding` 用来把常驻控件与上面的内容拉开
+ * （如 `padding={{ y: 10 }}`）—— 页脚自己没有内距，以前这条距离各弹窗各写一个 `padding-top` 的应用侧类。
  */
 export declare const PanelFooter: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 页脚内距（与根件同一口径）；缺省 0 = 贴面板边 */
@@ -198,10 +170,7 @@ export declare const PanelFooter: import("vue").DefineComponent<import("vue").Ex
 }, SlotsType<{
     default?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-/**
- * 复合件入口：`Panel` + `Panel.Header` / `Panel.Body` / `Panel.Footer`
- * （与 `Page` 同款 Object.assign 复合写法）
- */
+/** 复合件入口：`Panel` + `Panel.Header` / `Panel.Body` / `Panel.Footer`（与 `Page` 同款 Object.assign 复合写法） */
 export declare const Panel: {
     new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
         /** 简写标题：等价于内建 `Panel.Header` */
@@ -304,10 +273,7 @@ export declare const Panel: {
     actions?: () => VNodeChild;
 }>, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & {
     Header: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
-        /**
-         * 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行
-         * （无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。
-         */
+        /** 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行（无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。 */
         title: {
             type: StringConstructor;
             default: undefined;
@@ -328,10 +294,7 @@ export declare const Panel: {
             default: undefined;
         };
     }>, () => VNodeChild, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
-        /**
-         * 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行
-         * （无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。
-         */
+        /** 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行（无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。 */
         title: {
             type: StringConstructor;
             default: undefined;

package/dist/components/panel/index.js

@@ -4,10 +4,7 @@ const PanelHeader = /* @__PURE__ */ defineComponent({
   name: "PanelHeader",
   inheritAttrs: false,
   props: {
-    /**
-     * 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行
-     * （无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。
-     */
+    /** 面板标题；缺省时**不渲染标题节点**，但仍会渲染 `toolbar` / `actions` 那一行（无标题的区域头，见组件头注释）；要给完全自定义的头走 `header` 插槽。 */
     title: {
       type: String,
       default: void 0

package/dist/components/part-padding.d.ts

@@ -5,26 +5,18 @@ import type { StyleValue } from 'vue';
  * - `number` → 四边同值（`padding={16}`）；
  * - `{ y, x }` → 上下 / 左右分别给（`{ y: 12, x: 20 }`，弹窗里的容器常用 —— 与 `Page` 的页面左右内距同档），
  *   **缺哪边就不落哪边的声明**（只给 `y` 时不覆盖消费方在 `style` 里写的左右内距）；
- * - `string` → **原样下发**（CSS 简写，可非对称，如 `'40px 0 0 140px'`）—— **逃生舱**。
+ * - `string` → **原样下发**（CSS 简写，可非对称）—— **逃生舱**，优先级最低：写它等于自己写 CSS，能不用就不用。
  *
- * 常规用 `number` / `{ y, x }`：几何值在本仓是**设计基准**，不跟根字号
- * （与 `Form.labelWidth` / `表格.rowHeight` 同口径）。
- * `string` 只为「令牌梯度与 `{ y, x }` 都表达不了的设计要求」留口（典型：**只给一侧**的非对称坐标）——
- * 写它等于自己写 CSS，所以**优先级最低**，能不用就不用。
+ * 常规用 `number` / `{ y, x }`：几何值在本仓是**设计基准**，不跟根字号（与 `Form.labelWidth` / `表格.rowHeight` 同口径）。
  */
 export type Padding = number | {
     y?: number;
     x?: number;
 } | string;
-/**
- * 内距 → 行内样式。缺省（`undefined` / 空串）时返回 `undefined`：**不额外产生 style 属性**，
- * DOM 与「没有这个维度」时完全一致。
- */
+/** 内距 → 行内样式。缺省（`undefined` / 空串）时返回 `undefined`：**不额外产生 style 属性**，DOM 与「没有这个维度」时一致。 */
 export declare function partPaddingStyle(padding: Padding | undefined): StyleValue | undefined;
 /**
- * 合并「消费方给的 `style`」与「内距行内样式」：两者都可能有，内距排在后面
- * —— 同一属性以组件的 `padding` 为准（消费方要覆盖就用 `class` 里更具体的规则）。
- *
- * 不给 `padding` 时**原样返回消费方的 style**（含 `undefined`）。
+ * 合并「消费方给的 `style`」与「内距行内样式」：两者都可能有时内距排在后面 —— 同一属性以组件的 `padding` 为准（消费方
+ * 要覆盖就用 `class` 里更具体的规则）。不给 `padding` 时**原样返回消费方的 style**（含 `undefined`）。
  */
 export declare function mergePartStyle(attrsStyle: unknown, padding: Padding | undefined): StyleValue | undefined;

package/dist/components/query-state/index.d.ts

@@ -39,41 +39,17 @@ export interface QueryStateProps {
  *
  * ## 视觉构成（三态非加载态一致）
  *
- * **插画 → 主文案 → 副文案 → 操作区**，整块垂直居中、留白由令牌给（`.mh-state`）。
- * 插画默认取内建件（设计交付的「空状态」/「错误」两张图，原样内联在 `utils/state-illustration.ts`），
- * 可用 `illustration` 属性换成图片资源、或用 `illustration` 插槽整幅自定义；操作区同理有 `actions` 插槽。
- *
- * 文案 props 可覆盖（i18n 由消费方传 t() 结果；本包不内置文案）。
+ * **插画 → 主文案 → 副文案 → 操作区**，整块垂直居中、留白由令牌给（`.mh-state`）。插画默认取内建件
+ * （设计交付的「空状态」/「错误」两张图，内联在 `utils/state-illustration.ts`），可用 `illustration` 属性
+ * 换成图片资源、或用同名插槽整幅自定义；操作区同理有 `actions` 插槽。文案 props 可覆盖（i18n 由消费方传
+ * `t()` 结果；本包不内置文案）。
  *
  * ## 两个容易拿不准的点
  *
- * - `empty` 是**触发位**，不是「文案 prop」：`true` 触发并用默认文案；给字符串则**既触发、
- *   又当空态标题**（副文案仍走 `emptyDescription`）；
- * - **本件不自带数据源**：`loading` / `error` / `empty` 都由调用方按自己的请求结果给。
- *   `Table` 自带加载与空两态却**没有错误态** —— 要么只把 error 交给本件，要么整块三态由本件在外层表达：
- *
- * @example 列表页：三态在外层，表格只管数据（经典写法）
- * <QueryState
- *   loading={isLoading}
- *   error={loadError}
- *   :empty="rows.length === 0"
- *   :error-action-text="t('common.retry')"
- *   onErrorAction={() => refetch()}>
- *   <Table :columns="columns" :data="rows" row-key="id" />
- * </QueryState>
- *
- * @example 三态齐备（空态带 CTA、错误态带重试）
- * <QueryState
- *   loading={isLoading}
- *   error={loadError.value}
- *   errorActionText={t('common.retry')}
- *   onErrorAction={() => reload()}
- *   empty={t('topic.empty')}
- *   emptyDescription={t('topic.emptyDescription')}
- *   emptyActionText={t('topic.create')}
- *   onEmptyAction={() => openCreate()}>
- *   <TopicGrid topics={topics} />
- * </QueryState>
+ * - `empty` 是**触发位**，不是「文案 prop」：`true` 触发并用默认文案；给字符串则**既触发、又当空态标题**
+ *   （副文案仍走 `emptyDescription`）；
+ * - **本件不自带数据源**：三态都由调用方按自己的请求结果给。`Table` 自带加载与空两态却**没有错误态** ——
+ *   要么只把 error 交给本件，要么整块三态由本件在外层表达。
  */
 export declare const QueryState: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     loading: {