@manohub/ui 1.0.5 → 1.0.8

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

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

@@ -31,62 +31,28 @@ import { type Padding } from '../part-padding';
  * 页头右侧的自由位（搜索框 / 按钮 / 等）是 `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;
@@ -106,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,24 +1,16 @@
 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。
  *
  * ## 分页归属（**跟承载表格的容器走**）
  *
@@ -36,34 +28,24 @@ import { type Padding } from '../part-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` 插槽则走完全自定义面板头 */
@@ -88,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;
@@ -112,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;
@@ -174,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 = 贴面板边 */
@@ -196,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` */
@@ -302,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;
@@ -326,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: {

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

@@ -17,6 +17,8 @@ import type { ControlSize } from '../control-size';
  *
  * 状态表达不统一是**有意的**（各自贴着自己的面）：`Radio` 走原生 `input:checked + .mh-radio__box`
  * （故 **input 必须紧邻框体之前**），`Radio.Card` 走卡片上的 `data-state`（卡片就是 label，圆点在卡内）。
+ *
+ * 用法见 `docs/demos/radio/`（每个维度一份可运行样例；文档页 `docs/components/radio.md`）。
  */
 export interface RadioProps {
     /** 本项的值（组内唯一） */
@@ -40,9 +42,6 @@ export interface RadioProps {
  * 三源等价的选中态由样式层承担（原生 `:checked` / 组件 `[data-state]` / 静态档 `.is-*`），
  * 本件只负责把原生 input 与自绘框体的顺序摆对（**input 必须在框体之前** —— 样式层靠
  * `input:checked + .mh-radio__box` 选态）。
- *
- * @example 单用（自己管互斥）
- * <Radio name="scope" value="all" label="全部" checked={v === 'all'} onChange={setV} />
  */
 export declare const Radio: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     value: {