@manohub/ui 1.0.5 → 1.0.6

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

@@ -28,6 +28,8 @@ export interface TabsProps {
      * 2. **缺省皮肤的尺寸档**：原样透传给 `TabBar`（高度 `24 / 32 / 40` + 同级字号）。
      *    换了皮肤则这一条不生效：控件的尺寸归你放进来的那个控件自己管
      *    （`Capsule` / 分段按钮各有自己的 `size`），本件不代它加类。
+   *
+   * 用法见 `docs/demos/tabs/`（每个维度一份可运行样例；文档页 `docs/components/tabs.md`）。
      */
     size?: ControlSize;
 }
@@ -45,18 +47,11 @@ export interface TabPanelProps {
 /**
  * 面板：`Tabs` 的**信息入口**。
  *
- * 使用方只写面板自己的信息（`name` 等），`Tabs` 在渲染期把它提取成轨道项 ——
- * 缺省就是页签条，要换皮就写 `Tabs` 的 `selector` 插槽（胶囊 / 分段按钮 / 单选卡片）。
+ * 使用方只写面板自己的信息（`name` 等），`Tabs` 在渲染期把它提取成轨道项 —— 缺省就是页签条，要换皮就写
+ * `Tabs` 的 `selector` 插槽（胶囊 / 分段按钮 / 单选卡片）。
  *
- * 本件**不画任何东西**：渲染即默认插槽直通。面板壳（`.mh-tabs-panel`）与显隐由 `Tabs` 出，
- * 故挂在本件上的 `class` / `style` 会被搬到那块壳上（面板级样式改的是**壳** —— 内距、限高、
- * 自己滚，挂到内容上就没有这层可改）。
- *
- * @example
- * <Tabs v-model:value="current">
- *   <TabPanel name="概览">…</TabPanel>
- *   <TabPanel name="工具" disabled>…</TabPanel>
- * </Tabs>
+ * 本件**不画任何东西**（渲染即默认插槽直通）：面板壳（`.mh-tabs-panel`）与显隐由 `Tabs` 出，故挂在本件上的
+ * `class` / `style` 会被搬到那块壳上（面板级样式改的是**壳** —— 内距、限高、自己滚，挂到内容上就没有这层可改）。
  */
 export declare const TabPanel: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     name: {
@@ -105,50 +100,33 @@ export declare const TabPanel: import("vue").DefineComponent<import("vue").Extra
  * 面板切换（**操作层骨架 + 组件路径显隐**）。
  *
  * ## 它是什么
- * 把「一组互斥选项」与「按顺序排列的面板」接起来：第 n 个选项 ↔ 第 n 块面板。
- * 骨架（根、面板组、收起态）在操作层 `styles/operations/tabs.css`，本件负责：
- * 受控值、从面板提取项、面板包装与显隐、把 `select` 交给选择控件。
+ * 把「一组互斥选项」与「按顺序排列的面板」接起来（第 n 个选项 ↔ 第 n 块面板）。骨架（根 / 面板组 / 收起态）
+ * 在操作层 `styles/operations/tabs.css`，本件负责：受控值、从面板提取项、面板包装与显隐、把 `select` 交给
+ * 选择控件。
  *
  * ## 信息从哪来（两条路，**写了 `TabPanel` 就以它为准**）
- * - **`TabPanel`（推荐）**：面板自带 `name`（页签文字 + 缺省项值）、`value`、`disabled`、`lazy`，
- *   本件在渲染期提取成轨道项 —— 使用方不必再维护一份与之平行的 `options`；
- * - **`options`（老写法）**：默认插槽给裸节点，按顺序与 `options` 一一配对；
- *   裸节点没有同序项时那块面板**永远不可见**（不越档）。
+ * - **`TabPanel`（推荐）**：面板自带 `name`（页签文字 + 缺省项值）/ `value` / `disabled` / `lazy`，本件在渲染
+ *   期提取成轨道项 —— 使用方不必再维护一份平行的 `options`；
+ * - **`options`（老写法）**：默认插槽给裸节点，按顺序与 `options` 一一配对；裸节点没有同序项时那块面板**永远
+ *   不可见**（不越档）。
  * 两条路不叠加：写了 `TabPanel` 的那次渲染里 `options` 不参与（两套并行声明必打架）。
  *
  * ## 选择控件从哪来（`selector` 插槽）
  * - **不传插槽 = 用缺省皮肤 `TabBar`**（页签条形态）—— 绝大多数用法只要这一句；
- * - 传插槽则整块替换：放 `Capsule`（胶囊）、按钮族的分段形态、单选卡片都行，
- *   作用域参数 `{ value, options, select }` 把值、项（已含从 `TabPanel` 提取的那些）与选中回调
- *   递出来。本件不认识任何选择控件的类名 —— **控制器与骨架零互指**，换皮肤不必动本件。
+ * - 传插槽则整块替换：`Capsule`（胶囊）、按钮族的分段形态、单选卡片都行，作用域参数
+ *   `{ value, options, select }` 把值、项（已含从 `TabPanel` 提取的那些）与选中回调递出来。本件不认识任何
+ *   选择控件的类名 —— **控制器与骨架零互指**，换皮肤不必动本件。
  * - 尺寸档 `size` 管两件事：① 骨架的呼吸位（`.mh-tabs` 的 `gap`，4 / 8 / 12px，**与皮肤无关**）；
- *   ② 缺省皮肤 `TabBar` 的高与字号（24 / 32 / 40）。换了皮肤则第 ② 条不生效 ——
- *   控件尺寸归你的控件自己管，本件不代它加类。
+ *   ② 缺省皮肤 `TabBar` 的高与字号（24 / 32 / 40）；换了皮肤则第 ② 条不生效（控件尺寸归你的控件自己管）。
  *
  * ## 显隐只有一条路径
- * 本件按受控值给非选中面板下发 `hidden`，**与控件形态无关**（是不是原生 radio 都一样）。
- * 曾经的「零 JS 路径」（原生 radio + 操作层档位表 `:has(input:nth-of-type(n):checked)`）**已退役**：
- * 写不出通式、上限 8 档、还要求开关与面板同父级同序 —— 局限远大于收益。
- * 故拿 `Capsule` 当控件时**不必**再给它 `name`（那曾经只是给操作层认组用的）。
+ * 本件按受控值给非选中面板下发 `hidden`，**与控件形态无关**（是不是原生 radio 都一样）。曾经的「零 JS 路径」
+ * （原生 radio + 操作层档位表 `:has(input:nth-of-type(n):checked)`）**已退役**：写不出通式、上限 8 档、还要
+ * 求开关与面板同父级同序 —— 局限远大于收益。故拿 `Capsule` 当控件时**不必**再给它 `name`。
  *
  * ## 惰性档
- * `lazy` 在 `Tabs` 与 `TabPanel` 上都可给（取或）：非激活面板**不渲染**（切走即卸载）。
- * 缺省档全部挂载、只用 `hidden` 藏 —— 保留面板内部状态（滚动位置、局部输入）。
- *
- * @example 最小用法：只写面板信息（缺省页签条）
- * <Tabs v-model:value="current">
- *   <TabPanel name="概览">…</TabPanel>
- *   <TabPanel name="工具">…</TabPanel>
- * </Tabs>
- *
- * @example 换皮：胶囊作选择控件
- * <Tabs v-model:value="current">
- *   {{
- *     selector: ({ value, options, select }) =>
- *       <Capsule :options="options" modelValue={value} onChange={select} />,
- *     default: () => [<TabPanel name="概览">…</TabPanel>, <TabPanel name="工具">…</TabPanel>],
- *   }}
- * </Tabs>
+ * `lazy` 在 `Tabs` 与 `TabPanel` 上都可给（取或）：非激活面板**不渲染**（切走即卸载）；缺省档全部挂载、只用
+ * `hidden` 藏 —— 保留面板内部状态（滚动位置、局部输入）。
  */
 export declare const Tabs: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     options: {

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

@@ -6,6 +6,8 @@ export type TextSize = 'caption' | 'body' | 'heading' | 'title';
  *
  * ⚠️ 自绘样式时要字色，一律落 `--ui-<tone>` / `--ui-<tone>-strong`（浅底深字）。
  * `--ui-*-content` 那一族是**实心填充之上的白字**，配浅底（`-weak`）就是白字白底。
+ *
+ * 用法见 `docs/demos/text/`（每个维度一份可运行样例；文档页 `docs/components/text.md`）。
  */
 export type TextTone = 'default' | 'muted' | 'subtle' | 'primary' | 'success' | 'warning' | 'error';
 /** 字重档（缺省**不设**，即继承上下文 —— 这样「在已加粗的区域里放一段普通文字」不必显式写 regular） */
@@ -31,36 +33,23 @@ export interface TextProps {
  *
  * ## 为什么需要它
  *
- * `theme` 一直有 `--ui-font-{caption,body,heading,title}` 与 `--ui-font-mono` 这套档位令牌，
- * 但**没有件消费它们**：卡片描述、表单说明、只读值、列表次级信息这些「容器里的文字层级」
- * 于是无处可归 —— `Card` 只管卡片外壳，`Panel` 只管区域，两者都不管内容里的排版；
- * 而契约 L1-5 又禁应用侧写 `font-*` / `color`。**令牌有了、路径没有**，
- * 结果就是每个应用都要为「卡片里的文字」保留一条定版例外登记（首批迁移的登记项里，
- * 绝大多数属于这一类）。本件把这条路径补上。
+ * `theme` 一直有 `--ui-font-{caption,body,heading,title}` 与 `--ui-font-mono` 这套档位令牌，但**没有件消费
+ * 它们** —— 卡片描述、表单说明、只读值、列表次级信息这些「容器里的文字层级」于是无处可归（`Card` 只管卡片
+ * 外壳、`Panel` 只管区域，两者都不管内容里的排版），而契约 L1-5 又禁应用侧写 `font-*` / `color`。**令牌有了、
+ * 路径没有**，结果就是每个应用都要为「卡片里的文字」保留一条定版例外登记。本件把这条路径补上。
  *
  * ## 与 `Title` / 平台默认的关系
  *
- * `as="h2"` 只贡献**语义**，视觉完全由 `size` / `weight` 决定：字号由 `size` 档（缺省 `body`）显式给，
- * 浏览器给 `h1`-`h6` 的那套字阶（`1.5em` + 粗体）由**本件自己的面**归零（`.mh-text:where(h1…h6)`，
- * 只点名标题标签 —— `strong` 的加粗是它唯一的表达，不归零）。元素级基线**不再**代管这条：
- * 它在 Tailwind 的层外，会压住消费方的 `text-*` 工具类（理由见 `styles/reset.css` 文件头）。
+ * `as="h2"` 只贡献**语义**，视觉完全由 `size` / `weight` 决定：字号由 `size` 档（缺省 `body`）显式给，浏览器
+ * 给 `h1`-`h6` 的那套字阶（`1.5em` + 粗体）由**本件自己的面**归零（`.mh-text:where(h1…h6)`，只点名标题标签
+ * —— `strong` 的加粗是它唯一的表达，不归零）。元素级基线**不再**代管这条：它在 Tailwind 的层外，会压住消费
+ * 方的 `text-*` 工具类（理由见 `styles/reset.css` 文件头）。
  *
  * ## 不做什么
  *
  * - **不做富文本**：不解析 markdown、不认 `**加粗**`（富文本排版的归属见 `@manohub/kit/CONTRACT.md` §10）；
  * - **不做省略的展开**：截断只表示「显示不下就省略」，需要「展开全文」交互的走业务自己实现；
  * - **不承载色底 / 描边 / 内距**：那是 `Tag` / `Badge` / `Card` 的事。
- *
- * @example 卡片里的三行信息（标题 / 描述 / 元信息）
- * <Text as="h3" size="heading" weight="semibold">{repo.name}</Text>
- * <Text tone="muted" truncate>{repo.url}</Text>
- * <Text as="small" size="caption" tone="subtle">{repo.updatedAt}</Text>
- *
- * @example 只读值 + 等宽
- * <Text mono>{task.id}</Text>
- *
- * @example 最多两行，超出省略
- * <Text :truncate="2">{longDescription}</Text>
  */
 export declare const Text: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     size: {

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

@@ -6,23 +6,14 @@ export type ToastTone = 'info' | 'success' | 'warning' | 'error' | 'loading';
  *
  * ## 与 `Notification` / `Notice` 的判据
  *
- * 三者都是「告诉用户一件事」，按**出现方式**分：**浮出后自己消失** → 本件（消息提示）；
- * 嵌在页面里、用户自己关 → `Notification`（通知卡，有标题/头像/标签）；一行话 + 可选操作 → `Notice`。
+ * 三者都是「告诉用户一件事」，按**出现方式**分：**浮出后自己消失** → 本件（消息提示）；嵌在页面里、用户自己
+ * 关 → `Notification`（通知卡，有标题 / 头像 / 标签）；一行话 + 可选操作 → `Notice`。
  *
  * ## 只管一条
  *
- * 本件是**一条**提示的渲染与计时：`duration > 0` 时到点发出 `close` 事件（**不自己移除 DOM** —— 存在性归
- * 调用方，避免"组件消失了、队列里还留着"两套口径）；多条堆叠用 `Toast.Stack` 包一层。
- *
+ * 本件是**一条**提示的渲染与计时：`duration > 0` 时到点发出 `close` 事件（**不自己移除 DOM** —— 存在性归调用
+ * 方，避免"组件消失了、队列里还留着"两套口径）；多条堆叠用 `Toast.Stack` 包一层。
  * `loading` 档通常是「先给一条加载中，完成后再换成结果态」：换态由调用方替换 `tone`，本件不做轮询。
- *
- * @example 基本（3 秒自动消失）
- * <Toast tone="success" text="保存成功" :duration="3000" @close="remove(it)" />
- *
- * @example 堆叠容器 + 带动作
- * <Toast.Stack>
- *   <Toast tone="error" text="导出失败" action="重试" @action="retry" />
- * </Toast.Stack>
  */
 export declare const Toast: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     tone: {

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

@@ -17,18 +17,7 @@ export type TooltipTrigger = 'hover' | 'click';
  *
  * 定位两者同一套：`data-side` 给方位、`data-align` 给两侧对齐（缺省中线），溢出自动翻面。
  *
- * @example 悬停
- * <Tooltip content="导出为 CSV" side="bottom" align="end">
- *   <Button variant="secondary">导出</Button>
- * </Tooltip>
- *
- * @example 点击（内容可交互 / 怕被裁切时）
- * <Tooltip trigger="click" content="最近 24 小时无异常">
- *   <Icon name="info" />
- * </Tooltip>
- *
- * @example 带标题与动作（引导档外观）
- * <Tooltip guide title="新功能" content="支持批量导入" action="去看看" @action="go" />
+ * 用法见 `docs/demos/tooltip/`（每个维度一份可运行样例；文档页 `docs/components/tooltip.md`）。
  */
 export declare const Tooltip: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 正文（复杂内容走 `content` 插槽） */

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

@@ -43,17 +43,7 @@ export interface TreeNode {
  *
  * 不在其中之列的（标题里的图标 + 文字）走 `renderLabel`：那属于标签**本体**。
  *
- * @example 受控展开 + 计数徽标 + 行尾操作
- * <Tree nodes={treeNodes.value} rowKey="id" labelKey="name"
- *   selected={selectedId.value} onSelect={(n) => select(n.id)}
- *   expandedKeys={expandedKeys.value} onExpandChange={(k) => (expandedKeys.value = k)}
- *   renderNode={(n) => <Badge>{countOfDomain(n.id)}</Badge>}
- *   renderActions={(n) => <Button title="删除" onClick={() => removeDomain(n.id)} />} />
- *
- * @example 文件夹 / 文件图标 + 方向字形自表达（不靠旋转）
- * <Tree nodes={tree.value} rowKey="id"
- *   renderIcon={(n) => <Icon name={hasChild(n) ? 'folder' : 'file-text'} />}
- *   renderCaret={(_n, expanded) => <Icon name={expanded ? 'chevron-down' : 'chevron-right'} />} />
+ * 用法见 `docs/demos/tree/`（每个维度一份可运行样例；文档页 `docs/components/tree.md`）。
  */
 export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     nodes: {
@@ -85,38 +75,29 @@ export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPr
         default: undefined;
     };
     /**
-     * 标签体的自定义渲染（**替掉** `labelKey` 的纯文本）。
-     *
-     * 与 `renderNode` 的分工：本 prop 渲染的是**标签本体**（占位、省略号、行内对齐都由 `.mh-tree__label`
-     * 承担，因此必须留在那个槽里）；`renderNode` 渲染的是标签**之后**的常驻附加内容（计数徽标一类）。
-     * 典型用途是搜索命中的文本高亮（把标签切成多个片段）。
-     *
-     * 缺省不传时仍渲染 `labelKey` 的纯文本 —— 这是绝大多数消费方的路径，行为零变化。
+     * 标签体的自定义渲染（**替掉** `labelKey` 的纯文本）。与 `renderNode` 的分工：本 prop 渲染的是**标签本体**
+     * （占位 / 省略号 / 行内对齐都由 `.mh-tree__label` 承担，故必须留在那个槽里）；`renderNode` 渲染标签**之后**的
+     * 常驻附加内容（计数徽标一类）。典型用途是搜索命中的文本高亮（把标签切成多个片段）。缺省不传时仍渲染
+     * `labelKey` 的纯文本 —— 绝大多数消费方走这条，行为零变化。
      */
     renderLabel: {
         type: PropType<(node: TreeNode) => unknown>;
         default: undefined;
     };
     /**
-     * 展开 / 收起箭头的自定义渲染（拿到节点与**当前展开态**）。
-     *
-     * 缺省仍是 `chevron-down` 字形 + 面层收起态转 −90°（默认路径零变化）。
-     * 自定义时**朝向由消费方按 `expanded` 自选字形**（`chevron-right` / `chevron-down`）——
-     * 与包内「方位一律用字形、不靠旋转别的图标」的口径同源；**不要再给内容加
-     * `mh-tree__caret-icon` 类**（那是缺省字形的转向钩子，加上会被转成 −90°）。
-     * 尺寸不必自管：槽位与槽内字形都取全局图标档 `--ui-font-icon`。
+     * 展开 / 收起箭头的自定义渲染（拿到节点与**当前展开态**）。缺省仍是 `chevron-down` 字形 + 面层收起态转 −90°
+     * （默认路径零变化）；自定义时**朝向由消费方按 `expanded` 自选字形**（`chevron-right` / `chevron-down`）——
+     * 与包内「方位一律用字形、不靠旋转别的图标」同源。**不要再给内容加 `mh-tree__caret-icon` 类**（那是缺省字形
+     * 的转向钩子，加上会被转成 −90°）；尺寸不必自管：槽位与槽内字形都取全局图标档 `--ui-font-icon`。
      */
     renderCaret: {
         type: PropType<(node: TreeNode, expanded: boolean) => unknown>;
         default: undefined;
     };
     /**
-     * 标签**前**的节点图标槽（文件夹 / 文件一类）。
-     *
-     * 父节点与叶子节点**都由消费方按 `node` 判定**（组件不替它猜「是不是叶子」：同一个图标槽
-     * 在两种节点上都成立，判定依据是数据而不是渲染期形态）。缺省不渲染该槽，几何零变化。
-     * 叶子行的箭头占位仍保留，故图标列跨层级对齐。颜色不写死：跟随行色，
-     * 选中行的主色字与滑过态自动同步。
+     * 标签**前**的节点图标槽（文件夹 / 文件一类）。父节点与叶子节点**都由消费方按 `node` 判定**（组件不替它猜
+     * 「是不是叶子」：判定依据是数据而不是渲染期形态）。缺省不渲染该槽，几何零变化；叶子行的箭头占位仍保留，故
+     * 图标列跨层级对齐。颜色不写死：跟随行色，选中行的主色字与滑过态自动同步。
      */
     renderIcon: {
         type: PropType<(node: TreeNode) => unknown>;
@@ -128,12 +109,9 @@ export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPr
         default: undefined;
     };
     /**
-     * 行尾操作区（新增 / 重命名 / 删除等）。
-     *
-     * **默认隐藏、行悬浮或行内获得焦点时显形**（触屏无 hover 能力时恒显形），点击**不冒泡**到 `onSelect`
-     * —— 与 `ListView.CardItem` 的 `actions` 同一口径（几何与显隐归组件，应用侧只给节点）。
-     *
-     * 与 `renderNode` 的分工：**常驻**的附加内容（计数徽标）走 `renderNode`；**可点**的行尾操作走这里。
+     * 行尾操作区（新增 / 重命名 / 删除等）。**默认隐藏、行悬浮或行内获得焦点时显形**（触屏无 hover 能力时恒显形），
+     * 点击**不冒泡**到 `onSelect` —— 与 `ListView.CardItem` 的 `actions` 同一口径（几何与显隐归组件，应用侧只给
+     * 节点）。与 `renderNode` 的分工：**常驻**的附加内容（计数徽标）走 `renderNode`，**可点**的行尾操作走这里。
      */
     renderActions: {
         type: PropType<(node: TreeNode) => unknown>;
@@ -182,13 +160,9 @@ export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPr
         default: undefined;
     };
     /**
-     * 错误态（truthy 即触发）。
-     *
-     * **构造器顺序同 `表格.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
-     * 空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。
-     *
-     * 有它之前，消费方只能把错误文案塞进 `empty`：错误被渲染成空态语义（无错误插画、无重试入口），
-     * 用户看不出「是没数据还是加载挂了」。
+     * 错误态（truthy 即触发）。**构造器顺序同 `表格.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功
+     * 态传的空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。有它之前消费方只能把错误文案塞进 `empty`：
+     * 错误被渲染成空态语义（无错误插画、无重试入口），用户看不出「是没数据还是加载挂了」。
      */
     error: {
         type: PropType<any>;
@@ -243,38 +217,29 @@ export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPr
         default: undefined;
     };
     /**
-     * 标签体的自定义渲染（**替掉** `labelKey` 的纯文本）。
-     *
-     * 与 `renderNode` 的分工：本 prop 渲染的是**标签本体**（占位、省略号、行内对齐都由 `.mh-tree__label`
-     * 承担，因此必须留在那个槽里）；`renderNode` 渲染的是标签**之后**的常驻附加内容（计数徽标一类）。
-     * 典型用途是搜索命中的文本高亮（把标签切成多个片段）。
-     *
-     * 缺省不传时仍渲染 `labelKey` 的纯文本 —— 这是绝大多数消费方的路径，行为零变化。
+     * 标签体的自定义渲染（**替掉** `labelKey` 的纯文本）。与 `renderNode` 的分工：本 prop 渲染的是**标签本体**
+     * （占位 / 省略号 / 行内对齐都由 `.mh-tree__label` 承担，故必须留在那个槽里）；`renderNode` 渲染标签**之后**的
+     * 常驻附加内容（计数徽标一类）。典型用途是搜索命中的文本高亮（把标签切成多个片段）。缺省不传时仍渲染
+     * `labelKey` 的纯文本 —— 绝大多数消费方走这条，行为零变化。
      */
     renderLabel: {
         type: PropType<(node: TreeNode) => unknown>;
         default: undefined;
     };
     /**
-     * 展开 / 收起箭头的自定义渲染（拿到节点与**当前展开态**）。
-     *
-     * 缺省仍是 `chevron-down` 字形 + 面层收起态转 −90°（默认路径零变化）。
-     * 自定义时**朝向由消费方按 `expanded` 自选字形**（`chevron-right` / `chevron-down`）——
-     * 与包内「方位一律用字形、不靠旋转别的图标」的口径同源；**不要再给内容加
-     * `mh-tree__caret-icon` 类**（那是缺省字形的转向钩子，加上会被转成 −90°）。
-     * 尺寸不必自管：槽位与槽内字形都取全局图标档 `--ui-font-icon`。
+     * 展开 / 收起箭头的自定义渲染（拿到节点与**当前展开态**）。缺省仍是 `chevron-down` 字形 + 面层收起态转 −90°
+     * （默认路径零变化）；自定义时**朝向由消费方按 `expanded` 自选字形**（`chevron-right` / `chevron-down`）——
+     * 与包内「方位一律用字形、不靠旋转别的图标」同源。**不要再给内容加 `mh-tree__caret-icon` 类**（那是缺省字形
+     * 的转向钩子，加上会被转成 −90°）；尺寸不必自管：槽位与槽内字形都取全局图标档 `--ui-font-icon`。
      */
     renderCaret: {
         type: PropType<(node: TreeNode, expanded: boolean) => unknown>;
         default: undefined;
     };
     /**
-     * 标签**前**的节点图标槽（文件夹 / 文件一类）。
-     *
-     * 父节点与叶子节点**都由消费方按 `node` 判定**（组件不替它猜「是不是叶子」：同一个图标槽
-     * 在两种节点上都成立，判定依据是数据而不是渲染期形态）。缺省不渲染该槽，几何零变化。
-     * 叶子行的箭头占位仍保留，故图标列跨层级对齐。颜色不写死：跟随行色，
-     * 选中行的主色字与滑过态自动同步。
+     * 标签**前**的节点图标槽（文件夹 / 文件一类）。父节点与叶子节点**都由消费方按 `node` 判定**（组件不替它猜
+     * 「是不是叶子」：判定依据是数据而不是渲染期形态）。缺省不渲染该槽，几何零变化；叶子行的箭头占位仍保留，故
+     * 图标列跨层级对齐。颜色不写死：跟随行色，选中行的主色字与滑过态自动同步。
      */
     renderIcon: {
         type: PropType<(node: TreeNode) => unknown>;
@@ -286,12 +251,9 @@ export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPr
         default: undefined;
     };
     /**
-     * 行尾操作区（新增 / 重命名 / 删除等）。
-     *
-     * **默认隐藏、行悬浮或行内获得焦点时显形**（触屏无 hover 能力时恒显形），点击**不冒泡**到 `onSelect`
-     * —— 与 `ListView.CardItem` 的 `actions` 同一口径（几何与显隐归组件，应用侧只给节点）。
-     *
-     * 与 `renderNode` 的分工：**常驻**的附加内容（计数徽标）走 `renderNode`；**可点**的行尾操作走这里。
+     * 行尾操作区（新增 / 重命名 / 删除等）。**默认隐藏、行悬浮或行内获得焦点时显形**（触屏无 hover 能力时恒显形），
+     * 点击**不冒泡**到 `onSelect` —— 与 `ListView.CardItem` 的 `actions` 同一口径（几何与显隐归组件，应用侧只给
+     * 节点）。与 `renderNode` 的分工：**常驻**的附加内容（计数徽标）走 `renderNode`，**可点**的行尾操作走这里。
      */
     renderActions: {
         type: PropType<(node: TreeNode) => unknown>;
@@ -340,13 +302,9 @@ export declare const Tree: import("vue").DefineComponent<import("vue").ExtractPr
         default: undefined;
     };
     /**
-     * 错误态（truthy 即触发）。
-     *
-     * **构造器顺序同 `表格.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
-     * 空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。
-     *
-     * 有它之前，消费方只能把错误文案塞进 `empty`：错误被渲染成空态语义（无错误插画、无重试入口），
-     * 用户看不出「是没数据还是加载挂了」。
+     * 错误态（truthy 即触发）。**构造器顺序同 `表格.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功
+     * 态传的空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。有它之前消费方只能把错误文案塞进 `empty`：
+     * 错误被渲染成空态语义（无错误插画、无重试入口），用户看不出「是没数据还是加载挂了」。
      */
     error: {
         type: PropType<any>;

package/dist/components/tree/index.js

@@ -34,38 +34,29 @@ const Tree = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 标签体的自定义渲染（**替掉** `labelKey` 的纯文本）。
-     *
-     * 与 `renderNode` 的分工：本 prop 渲染的是**标签本体**（占位、省略号、行内对齐都由 `.mh-tree__label`
-     * 承担，因此必须留在那个槽里）；`renderNode` 渲染的是标签**之后**的常驻附加内容（计数徽标一类）。
-     * 典型用途是搜索命中的文本高亮（把标签切成多个片段）。
-     *
-     * 缺省不传时仍渲染 `labelKey` 的纯文本 —— 这是绝大多数消费方的路径，行为零变化。
+     * 标签体的自定义渲染（**替掉** `labelKey` 的纯文本）。与 `renderNode` 的分工：本 prop 渲染的是**标签本体**
+     * （占位 / 省略号 / 行内对齐都由 `.mh-tree__label` 承担，故必须留在那个槽里）；`renderNode` 渲染标签**之后**的
+     * 常驻附加内容（计数徽标一类）。典型用途是搜索命中的文本高亮（把标签切成多个片段）。缺省不传时仍渲染
+     * `labelKey` 的纯文本 —— 绝大多数消费方走这条，行为零变化。
      */
     renderLabel: {
       type: Function,
       default: void 0
     },
     /**
-     * 展开 / 收起箭头的自定义渲染（拿到节点与**当前展开态**）。
-     *
-     * 缺省仍是 `chevron-down` 字形 + 面层收起态转 −90°（默认路径零变化）。
-     * 自定义时**朝向由消费方按 `expanded` 自选字形**（`chevron-right` / `chevron-down`）——
-     * 与包内「方位一律用字形、不靠旋转别的图标」的口径同源；**不要再给内容加
-     * `mh-tree__caret-icon` 类**（那是缺省字形的转向钩子，加上会被转成 −90°）。
-     * 尺寸不必自管：槽位与槽内字形都取全局图标档 `--ui-font-icon`。
+     * 展开 / 收起箭头的自定义渲染（拿到节点与**当前展开态**）。缺省仍是 `chevron-down` 字形 + 面层收起态转 −90°
+     * （默认路径零变化）；自定义时**朝向由消费方按 `expanded` 自选字形**（`chevron-right` / `chevron-down`）——
+     * 与包内「方位一律用字形、不靠旋转别的图标」同源。**不要再给内容加 `mh-tree__caret-icon` 类**（那是缺省字形
+     * 的转向钩子，加上会被转成 −90°）；尺寸不必自管：槽位与槽内字形都取全局图标档 `--ui-font-icon`。
      */
     renderCaret: {
       type: Function,
       default: void 0
     },
     /**
-     * 标签**前**的节点图标槽（文件夹 / 文件一类）。
-     *
-     * 父节点与叶子节点**都由消费方按 `node` 判定**（组件不替它猜「是不是叶子」：同一个图标槽
-     * 在两种节点上都成立，判定依据是数据而不是渲染期形态）。缺省不渲染该槽，几何零变化。
-     * 叶子行的箭头占位仍保留，故图标列跨层级对齐。颜色不写死：跟随行色，
-     * 选中行的主色字与滑过态自动同步。
+     * 标签**前**的节点图标槽（文件夹 / 文件一类）。父节点与叶子节点**都由消费方按 `node` 判定**（组件不替它猜
+     * 「是不是叶子」：判定依据是数据而不是渲染期形态）。缺省不渲染该槽，几何零变化；叶子行的箭头占位仍保留，故
+     * 图标列跨层级对齐。颜色不写死：跟随行色，选中行的主色字与滑过态自动同步。
      */
     renderIcon: {
       type: Function,
@@ -77,12 +68,9 @@ const Tree = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 行尾操作区（新增 / 重命名 / 删除等）。
-     *
-     * **默认隐藏、行悬浮或行内获得焦点时显形**（触屏无 hover 能力时恒显形），点击**不冒泡**到 `onSelect`
-     * —— 与 `ListView.CardItem` 的 `actions` 同一口径（几何与显隐归组件，应用侧只给节点）。
-     *
-     * 与 `renderNode` 的分工：**常驻**的附加内容（计数徽标）走 `renderNode`；**可点**的行尾操作走这里。
+     * 行尾操作区（新增 / 重命名 / 删除等）。**默认隐藏、行悬浮或行内获得焦点时显形**（触屏无 hover 能力时恒显形），
+     * 点击**不冒泡**到 `onSelect` —— 与 `ListView.CardItem` 的 `actions` 同一口径（几何与显隐归组件，应用侧只给
+     * 节点）。与 `renderNode` 的分工：**常驻**的附加内容（计数徽标）走 `renderNode`，**可点**的行尾操作走这里。
      */
     renderActions: {
       type: Function,
@@ -131,13 +119,9 @@ const Tree = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 错误态（truthy 即触发）。
-     *
-     * **构造器顺序同 `表格.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功态传的
-     * 空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。
-     *
-     * 有它之前，消费方只能把错误文案塞进 `empty`：错误被渲染成空态语义（无错误插画、无重试入口），
-     * 用户看不出「是没数据还是加载挂了」。
+     * 错误态（truthy 即触发）。**构造器顺序同 `表格.error`：`String` 必须排在 `Boolean` 前** —— 顺序写反时，成功
+     * 态传的空字符串会被 Vue 的布尔转换判成 `true`，树永远停在错误态。有它之前消费方只能把错误文案塞进 `empty`：
+     * 错误被渲染成空态语义（无错误插画、无重试入口），用户看不出「是没数据还是加载挂了」。
      */
     error: {
       type: [String, Boolean, Object, Number, Array],

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

@@ -24,10 +24,7 @@ export declare function formatFileSize(bytes?: number): string;
  * 文件列表是**受控**的（`files` 由消费方持有）：选择 / 拖入回调 `onSelect`、删除回调 `onRemove`，
  * 本件不做上传、不自己增删数组（也就不会出现「组件以为删了、业务还留着」的错位）。
  *
- * @example 基本
- * <Upload :files="list" hint="支持 PDF / XLS，单个不超过 20MB"
- *   @select="(fs) => (list = [...list, ...fs.map(toItem)])"
- *   @remove="(_, i) => list.splice(i, 1)" />
+ * 用法见 `docs/demos/upload/`（每个维度一份可运行样例；文档页 `docs/components/upload.md`）。
  */
 export declare const Upload: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 已选文件（受控；本件只渲染与回调） */

package/dist/index.d.ts

@@ -57,7 +57,7 @@ export { Loading, type LoadingOverlay, type LoadingProps } from './components/lo
 export type { ControlSize } from './components/control-size';
 export type { Padding } from './components/part-padding';
 export { partPaddingStyle, mergePartStyle } from './components/part-padding';
-export { configureHost, getHostSelector, resolveHost } from './services';
+export { configureHost, getHostSelector, resolveHost, type ServiceHandle } from './services';
 export { toast, clearToasts, type ToastHandle, type ToastServiceOptions } from './services';
 export { alert, closeAllDialogs, confirm, type ConfirmOptions } from './services';
-export { hideLoading, showLoading } from './services';
+export { hideLoading, showLoading, type LoadingHandle } from './services';

package/dist/services/base.d.ts

@@ -1,3 +1,31 @@
+/**
+ * 服务层 · 宿主解析（`toast` / `dialog` / `loading` 三个命令式服务共用）。
+ *
+ * ## 为什么服务层要自己造宿主
+ * 本包的反馈件都是**受控组件**（到点只回调、可见性归调用方），命令式服务没有调用方的组件树可挂，只能自己建一个 Vue
+ * 实例 —— 于是第一件事就是「挂在哪个元素上」。
+ *
+ * ## 解析顺序（四档，前两档是确定性来源）
+ * 1. **显式配置**（`configureHost(el)`）—— 子应用入口拿到自己的容器后调它最稳；
+ * 2. **带 `data-manohub-ui` 锚点的容器** —— 骨架层在包裹节点上补一个属性即可，服务层因此**不必反向依赖上层包**；
+ * 3. **文档里第一个 `[data-manohub-ui]`** —— 未接骨架层的裸挂载场景；4. `document.body` —— 兜底。
+ *
+ * ## 为什么不能落到 `body` 就完事
+ * 本包全部令牌锚在容器的 `[data-manohub-ui]` 上（`--ui-*`），**微前端下应用侧 CSS 还会被 scopecss 限制在容器内**。
+ * 命令式浮层若落在容器外，会出现两种「样式全丢」：变量解析为空（组件退回无样式的裸结构），或被前缀化的应用侧样式匹配
+ * 不到。所以宿主必须精确到**本应用自己的容器**（门户里可能同时挂着多个子应用，`querySelector` 会命中别人的 —— 这也是
+ * 第 1 档存在的原因）。
+ */
+/**
+ * 命令式服务的**通用句柄**（`toast()` 与 `showLoading()` 返回同一形状）。
+ *
+ * 只承诺一件事：**关掉自己那一次**，且**幂等**（重复 `close()` 不再生效）。与模块级的 `hideLoading()`
+ * （计数减一）`clearToasts()`（全清）分工不同 —— 那两枚是「整体动作」，句柄是「我这次调用」的收尾凭据，
+ * 配平语义只认它。
+ */
+export interface ServiceHandle {
+    close: () => void;
+}
 /** 注册宿主变更时的清理动作（服务层内部用；后注册的也按注册顺序执行） */
 export declare function onHostReset(hook: () => void): void;
 /** 显式指定服务层宿主；传 `null` 恢复自动解析 */
@@ -5,17 +33,13 @@ export declare function configureHost(el: Element | null): void;
 /** 解析当前宿主（顺序见文件头；浏览器环境外直接抛错 —— 命令式服务没有可渲染的宿主） */
 export declare function resolveHost(): Element;
 /**
- * 同 `resolveHost()`，但返回**选择器字符串** —— 给「只吃字符串宿主」的上游件用。
- *
- * 为什么不能直接给 Element：有的上游件把宿主当选择器解析（`document.querySelector(host)`），
- * 传 Element 会拿到 `"[object HTMLDivElement]"` 这个非法选择器而当场抛错。给字符串又要避免
- * 「门户里多应用并存时串到第一个 `[data-manohub-ui]`」，故给容器补一个**进程内唯一 id** 再返回它。
+ * 同 `resolveHost()`，但返回**选择器字符串** —— 给「只吃字符串宿主」的上游件用。不能直接给 Element：有的上游件把宿主当
+ * 选择器解析（`document.querySelector(host)`），传 Element 会拿到 `"[object HTMLDivElement]"` 这个非法选择器而当场抛错；
+ * 给字符串又要避免「门户里多应用并存时串到第一个 `[data-manohub-ui]`」，故给容器补一个**进程内唯一 id** 再返回它。
  */
 export declare function getHostSelector(): string;
 /**
- * 建一个挂载容器并挂到宿主下。
- *
- * 挂在宿主**内部**而不是拿宿主本身当挂载点：宿主是应用自己的根节点，直接挂上去会让
+ * 建一个挂载容器并挂到宿主下。挂在宿主**内部**而不是拿宿主本身当挂载点：宿主是应用自己的根节点，直接挂上去会让
  * `app.unmount()` 把应用自己的渲染结果一起抹掉。
  */
 export declare function createHostContainer(): HTMLElement;

package/dist/services/dialog.d.ts

@@ -9,6 +9,8 @@ export interface ConfirmOptions {
      *
      * 不传则无图标。**危险操作用 `error`** —— 它同时把确定按钮染成危险色
      * （除非显式给了 `okDanger`），这样「删除确认」与「保存成功」不再长得一样。
+   *
+   * 用法见 `docs/demos/dialog/`（每个维度一份可运行样例；文档页 `docs/components/dialog.md`）。
      */
     tone?: DialogTone;
     /** 面板宽度档：**缺省 `'sm'`（400）**，比 `Dialog` 的 `md` 档窄一档 */
@@ -25,33 +27,19 @@ export interface ConfirmOptions {
 /**
  * 确认框（命令式）：确定 → `true`，取消 / 关闭位 / Esc / 点遮罩 → `false`。
  *
- * 与 `Dialog` 组件的分工：组件是「受控弹窗」，本函数补齐命令式调用缺的那一层（宿主 + 收场 Promise）。
- * 语义与主流库一致：**任何非确定路径都折成 `false`**，调用方 `if (await confirm(...))` 一处判断即可。
- *
- * **遮罩与 Esc 都归 `false`**：`Dialog` 组件形态的 `closeOnBackdrop` 默认已改为 `true`（跟主流），
- * 但命令式确认框必须**显式关掉它** —— 这里一条误点就丢一次决策，与 Ant Design
- * （`<Modal maskClosable>` 默认 `true`、`Modal.confirm` 默认 `false`）的分工一致。
- *
- * 需要「确定按钮进加载态」的异步确认请直接用 `Dialog` 组件（`onOk` 返回 Promise 时自动进加载态）——
- * 命令式形态刻意不引入跨 tick 的加载态，免得调用方以为弹窗已经关了。
- *
- * @example 删除确认（`tone: 'error'` 给标题加提示图标并把确定按钮染危险色）
- * if (await confirm({ title: '删除确认', detail: '删除后不可恢复，确认继续？', okText: '删除', tone: 'error' })) {
- *   await remove()
- * }
+ * 与 `Dialog` 组件的分工：组件是「受控弹窗」，本函数补齐命令式调用缺的那一层（宿主 + 收场 Promise）。语义与
+ * 主流库一致：**任何非确定路径都折成 `false`**，调用方 `if (await confirm(...))` 一处判断即可。
+ * **遮罩与 Esc 都归 `false`**：`Dialog` 组件形态的 `closeOnBackdrop` 默认已改为 `true`（跟主流），但命令式确认框
+ * 必须**显式关掉它** —— 这里一条误点就丢一次决策（与 Ant Design 的 `Modal` 与 `Modal.confirm` 分工一致）。
+ * 需要「确定按钮进加载态」的异步确认请直接用 `Dialog` 组件（`onOk` 返回 Promise 时自动进加载态）—— 命令式形态
+ * 刻意不引入跨 tick 的加载态，免得调用方以为弹窗已经关了。
  */
 export declare function confirm(options?: ConfirmOptions): Promise<boolean>;
 /**
  * 告知框（命令式）：只有一个「知道了」，任意收场路径都 resolve。
  *
- * 底栏**自绘**而不是用内建底栏：内建底栏固定是「取消 + 确定」两枚，而告知框没有「取消」可言
- * （给两枚按钮会让用户以为还有一条分支）。
- *
- * 与 `confirm()` 同一口径：**遮罩与 Esc 都显式关掉**（告知框同样不该被一次误点打发掉）。
- *
- * @example 危险操作的回执：这一条与「保存成功」在图标与配色上区分开
- * await alert({ tone: 'error', title: '移除失败', detail: '该来源系统仍被 3 个应用引用。' })
- * await alert({ tone: 'success', title: '导入完成', detail: '共 128 条，其中 3 条被跳过。' })
+ * 底栏**自绘**而不是用内建底栏：内建底栏固定是「取消 + 确定」两枚，而告知框没有「取消」可言（给两枚按钮会让
+ * 用户以为还有一条分支）。与 `confirm()` 同一口径：**遮罩与 Esc 都显式关掉**（告知框同样不该被一次误点打发掉）。
  */
 export declare function alert(options?: ConfirmOptions): Promise<void>;
 /** 收掉全部在档弹窗（逐个折成 `false`）；幂等。换应用 / 卸载时调 */

package/dist/services/index.d.ts

@@ -6,7 +6,7 @@
  *
  * 宿主解析见 `./base`：微前端下必须落回**本应用自己的容器**，否则令牌与应用侧样式同时失效。
  */
-export { configureHost, getHostSelector, resolveHost } from './base';
+export { configureHost, getHostSelector, resolveHost, type ServiceHandle } from './base';
 export { toast, clearToasts, type ToastHandle, type ToastServiceOptions } from './toast';
 export { alert, closeAllDialogs, confirm, type ConfirmOptions } from './dialog';
-export { hideLoading, showLoading } from './loading';
+export { hideLoading, showLoading, type LoadingHandle } from './loading';