@manohub/ui 1.0.5 → 1.0.8

package/README.md

@@ -106,8 +106,8 @@ pending.close()
 if (await confirm({ title: '删除确认', detail: '删除后不可恢复', okDanger: true })) await remove()
 await alert({ title: '导入完成', detail: '共 128 条' })
 
-const done = showLoading('保存中…')   // 引用计数：并发调用要各关各的
-try { await save() } finally { done() }
+const loading = showLoading('保存中…')            // 引用计数：并发调用要各关各的
+try { await save() } finally { loading.close() }  // 句柄与 toast() 同形状：{ close() }
 ```
 
 **四件必须知道的事**：
@@ -124,6 +124,8 @@ try { await save() } finally { done() }
    `toast` 队列空了、`loading` 计数归零即收掉宿主 —— 反复重挂不留悬挂实例。
 4. **`loading` 是引用计数语义**：并发的两次「显示」只关一次时遮罩仍在（先结束的那个不会把
    别人的遮罩一起收掉）。推荐用返回的句柄在 `finally` 里关掉自己那一次。
+   两枚命令式句柄**形状统一**：`toast()` 与 `showLoading()` 都返回 **`{ close(): void }`**
+   （`ServiceHandle`）—— 只关自己那一次且**幂等**；「整体动作」另走 `clearToasts()` / `hideLoading()`。
 
 ## 主题层
 
@@ -141,6 +143,10 @@ try { await save() } finally { done() }
 
 后一半必须在面里：它们靠「同一元素上两个选择器改写同一个令牌」生效，搬走就断链。
 
+改组件外观一律**重设令牌**，不写高特异性选择器（令牌是唯一的覆盖点，作用域就是那棵子树）。
+单件令牌的粒度到「整块区域的呼吸位」为止：`--ui-dialog-padding-x` / `--ui-table-padding-x` 这类
+「改一枚即整块观感变化」的值才有令牌，**分件里的细小内距没有令牌**（如标签片、树行、行内代码）。
+
 随包两套：
 
 | 主题 | 入口 | 锚点 | 取值来源 |

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

@@ -8,36 +8,22 @@ export type BadgeStatus = 'success' | 'processing' | 'default' | 'warning' | 'er
 /**
  * 徽标 / 标签 —— 三种用法，按「传了什么」自动选形态：
  *
- * 1. **内容徽标**（默认插槽 = 徽标文字）：`tone × shape × size × dot` 的正交组合。
- *    吃掉的分身：前 4 个应用各自手搓徽标（状态胶囊、准入状态、类型标签、结论徽标）。
- * 2. **数字角标**（传了 `count`）：独立显示，或包裹子元素后钉在其右上角
- *    （此时默认插槽的含义从「徽标文字」变成「被包裹的内容」，与主流库一致）。
+ * 1. **内容徽标**（默认插槽 = 徽标文字）：`tone × shape × size × dot` 的正交组合；
+ * 2. **数字角标**（传了 `count`）：独立显示，或包裹子元素后钉在其右上角（此时默认插槽的含义从「徽标文字」变成
+ *    「被包裹的内容」，与主流库一致）；
  * 3. **状态点 + 文字**（传了 `status`）：`● 已完成` 这种最轻的状态表达。
  *
- * 形态（`shape`）：
- * - `soft`：浅底 + 同色文字（标签）
- * - `outline`：浅底 + 同色描边；`tone="default"` 时退化为白底 + 中性描边 + 正文色（状态胶囊）
- * - `plain`：无底无框，靠圆点表达状态
+ * 形态（`shape`）：`soft`（浅底 + 同色文字）、`outline`（浅底 + 同色描边；`tone="default"` 时退化为白底 +
+ * 中性描边 + 正文色）、`plain`（无底无框，靠圆点表达状态）。
  *
- * **本件是「只读标记」的唯一样式源**：`Tag`（可关闭 / 可新增）只是在本件之上加交互位，
- * 几何与色彩一行都不重写 —— 改本件的档位，两件一起走（见 `components/tag/index.tsx`）。
+ * **本件是「只读标记」的唯一样式源**：`Tag`（可关闭 / 可新增）只是在本件之上加交互位，几何与色彩一行都不重写
+ * —— 改本件的档位，两件一起走（见 `components/tag/index.tsx`）。
  *
  * **属性落点**：`class` / `style` 有专口（并入档位类、随档位内联），**其余 attrs 一律透传到根元素**
- * （`id` / `aria-*` / `data-*` / `title` / 原生事件）—— 停在组件上等于丢掉（`Tag` 的「新增」
- * 就靠这条把 `onClick` 落到那颗按钮上），见 `forwardAttrs`。
+ * （`id` / `aria-*` / `data-*` / `title` / 原生事件）—— 停在组件上等于丢掉（`Tag` 的「新增」就靠这条把
+ * `onClick` 落到那颗按钮上），见 `forwardAttrs`。
  *
- * @example 内容徽标
- * <Badge tone="success" shape="outline" size="md" dot="filled">运行中</Badge>
- *
- * @example 数字角标（包裹子元素时钉右上角）
- * <Badge count={12}><Avatar letter="张" /></Badge>
- * <Badge count={120} :overflow-count="99" />   // 渲染 99+
- *
- * @example 状态点
- * <Badge status="processing" text="运行中" />
- *
- * @example 可点形态（复合件用；`Tag` 的「新增」即此形 + 本件自己的遮罩）
- * <Badge as="button" tone="warning" onClick={() => add()}>新增</Badge>
+ * 用法见 `docs/demos/badge/`（每个维度一份可运行样例；文档页 `docs/components/badge.md`）。
  */
 export declare const Badge: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     tone: {
@@ -84,17 +70,13 @@ export declare const Badge: import("vue").DefineComponent<import("vue").ExtractP
         default: undefined;
     };
     /**
-     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。
-     *
-     * `Tag` 就是靠它拿到「可点」的：徽标是**只读标记**的唯一样式源，`Tag` 只往上加
-     * 关闭位与新增位，不再自己画一遍框（见 `components/tag/index.tsx`）。
-     * `as="button"` 会渲染真实 `<button type="button">`（`type` 不能省：缺省是 `submit`，
-     * 放进表单会提交），并保留本件全部档位类与几何 —— 按钮的外观缺三项由本件面自带
-     * （`border` / `background` / `padding`，见 `contract-reset.spec.ts` 的第三组），
-     * `font-family: inherit` 在 `badge.css` 的基块补（UA 会把按钮字形换成 Arial）。
-     *
-     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），
-     * 传了它们就忽略本 prop（那时走各自的分支，根仍是 `<span>`）。
+     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。`Tag` 就是靠它拿到「可点」
+     * 的（徽标是只读标记的唯一样式源，`Tag` 只往上加交互位、不自己画框）。`as="button"` 渲染真实
+     * `<button type="button">`（`type` 不能省：缺省是 `submit`，放进表单会提交），并保留本件全部档位类与几何
+     * —— 按钮的外观缺三项由本件面自带（`border` / `background` / `padding`，见 `contract-reset.spec.ts`
+     * 第三组），`font-family: inherit` 在 `badge.css` 基块补（UA 会把按钮字形换成 Arial）。
+     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），传了它们就忽略
+     * 本 prop（那时走各自的分支，根仍是 `<span>`）。
      */
     as: {
         type: PropType<"span" | "button">;
@@ -145,17 +127,13 @@ export declare const Badge: import("vue").DefineComponent<import("vue").ExtractP
         default: undefined;
     };
     /**
-     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。
-     *
-     * `Tag` 就是靠它拿到「可点」的：徽标是**只读标记**的唯一样式源，`Tag` 只往上加
-     * 关闭位与新增位，不再自己画一遍框（见 `components/tag/index.tsx`）。
-     * `as="button"` 会渲染真实 `<button type="button">`（`type` 不能省：缺省是 `submit`，
-     * 放进表单会提交），并保留本件全部档位类与几何 —— 按钮的外观缺三项由本件面自带
-     * （`border` / `background` / `padding`，见 `contract-reset.spec.ts` 的第三组），
-     * `font-family: inherit` 在 `badge.css` 的基块补（UA 会把按钮字形换成 Arial）。
-     *
-     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），
-     * 传了它们就忽略本 prop（那时走各自的分支，根仍是 `<span>`）。
+     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。`Tag` 就是靠它拿到「可点」
+     * 的（徽标是只读标记的唯一样式源，`Tag` 只往上加交互位、不自己画框）。`as="button"` 渲染真实
+     * `<button type="button">`（`type` 不能省：缺省是 `submit`，放进表单会提交），并保留本件全部档位类与几何
+     * —— 按钮的外观缺三项由本件面自带（`border` / `background` / `padding`，见 `contract-reset.spec.ts`
+     * 第三组），`font-family: inherit` 在 `badge.css` 基块补（UA 会把按钮字形换成 Arial）。
+     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），传了它们就忽略
+     * 本 prop（那时走各自的分支，根仍是 `<span>`）。
      */
     as: {
         type: PropType<"span" | "button">;

package/dist/components/badge/index.js

@@ -54,17 +54,13 @@ const Badge = /* @__PURE__ */ defineComponent({
       default: void 0
     },
     /**
-     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。
-     *
-     * `Tag` 就是靠它拿到「可点」的：徽标是**只读标记**的唯一样式源，`Tag` 只往上加
-     * 关闭位与新增位，不再自己画一遍框（见 `components/tag/index.tsx`）。
-     * `as="button"` 会渲染真实 `<button type="button">`（`type` 不能省：缺省是 `submit`，
-     * 放进表单会提交），并保留本件全部档位类与几何 —— 按钮的外观缺三项由本件面自带
-     * （`border` / `background` / `padding`，见 `contract-reset.spec.ts` 的第三组），
-     * `font-family: inherit` 在 `badge.css` 的基块补（UA 会把按钮字形换成 Arial）。
-     *
-     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），
-     * 传了它们就忽略本 prop（那时走各自的分支，根仍是 `<span>`）。
+     * 根元素形态：`span`（缺省，纯展示）/ `button`（可点形态，给**复合件**用）。`Tag` 就是靠它拿到「可点」
+     * 的（徽标是只读标记的唯一样式源，`Tag` 只往上加交互位、不自己画框）。`as="button"` 渲染真实
+     * `<button type="button">`（`type` 不能省：缺省是 `submit`，放进表单会提交），并保留本件全部档位类与几何
+     * —— 按钮的外观缺三项由本件面自带（`border` / `background` / `padding`，见 `contract-reset.spec.ts`
+     * 第三组），`font-family: inherit` 在 `badge.css` 基块补（UA 会把按钮字形换成 Arial）。
+     * **只对「内容徽标」形态生效**：`count` / `status` 两种形态是装饰（角标、状态点 + 文字），传了它们就忽略
+     * 本 prop（那时走各自的分支，根仍是 `<span>`）。
      */
     as: {
       type: String,

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

@@ -4,48 +4,28 @@ import type { ControlSize } from '../control-size';
 /**
  * 按钮型（六型 + 未选半区）。
  *
- * `danger` 保留在枚举里是**向后兼容**：它等价于 `variant="primary"` 叠加 `danger` 布尔，
- * 语义上「危险」是色彩角色（与主色正交），不是第六种结构形态 ——
- * 故新代码请用 `danger` 布尔修饰任意型，`variant="danger"` 只在旧调用点继续有效。
+ * `danger` 保留在枚举里是**向后兼容**：它等价于 `variant="primary"` 叠加 `danger` 布尔 —— 语义上「危险」是色彩
+ * 角色（与主色正交），不是第六种结构形态，故新代码请用 `danger` 布尔修饰任意型（`variant="danger"` 只在旧调用点
+ * 继续有效）。
+ * `text` 与 `link` 都是无底色档，但**语义不同，别混**：`text` =「行内文本操作」（编辑 / 删除 / 更多 / 展开，无
+ * 下划线）；`link` =「跳转语义」（带下划线，像超链接）。「行内可点文字」一律用它 → `text`。
  *
- * `text` 与 `link` 都是无底色档，但**语义不同，别混**：
- * `text` = 「行内文本操作」（编辑 / 删除 / 更多 / 展开，无下划线）；
- * `link` = 「跳转语义」（带下划线，像超链接）。
- *「行内可点文字」一律用它 → `text`。
+ * 用法见 `docs/demos/button/`（每个维度一份可运行样例；文档页 `docs/components/button.md`）。
  */
 export type ButtonVariant = 'primary' | 'secondary' | 'dashed' | 'danger' | 'text' | 'link' | 'icon' | 'off';
 /** 外形档：`round` = 胶囊；`circle` = 正圆（配 `variant="icon"` 用） */
 export type ButtonShape = 'default' | 'round' | 'circle';
 /** 按钮（**自绘**；按钮族：六型 × 三档尺寸 × 外形 × 危险色 + 加载 / 图标 / 菜单形态 + 组容器）。
  *
- * 词表：`variant` = `primary` / `secondary` / `dashed` / `danger` / `text` / `link` / `icon`；
- * `size`：`sm` 24 / `md` 32（标准）/ `lg` 40 —— 三档**真实不同高**（与 `--ui-control-height-*` 同值）；
- * `shape` / `danger` / `block` 是正交修饰（可叠加任意型）；
- * `loading` 会置 `disabled` —— 真正吞掉点击的是原生 `disabled`，不只是光标；
+ * 词表：`variant` = `primary` / `secondary` / `dashed` / `danger` / `text` / `link` / `icon`；`size`：`sm` 24 /
+ * `md` 32（标准）/ `lg` 40 —— 三档**真实不同高**（与 `--ui-control-height-*` 同值）；`shape` / `danger` /
+ * `block` 是正交修饰（可叠加任意型）；`loading` 会置 `disabled`（真正吞掉点击的是原生 `disabled`，不只是光标）；
  * `menu` + `caret` 组合出菜单按钮（文本区 ‖ 分割线 ‖ 箭头区），面板交给操作层组合。
  *
  * 图标走 `@manohub/icon`（`icon` prop 传图标名，写错编译期即报错）；菜单箭头由
  * `styles/operations/popup.css` 负责转向，故箭头图标的类名是 `mh-button__caret mh-popup-caret` 两个。
- *
- * `href` 存在时渲染成 `<a>`（链接语义 + 原生右键菜单）；此时 `disabled` 只能靠 `aria-disabled`
- * 与拦截点击表达（`<a>` 没有原生禁用），这是有意的取舍。
- *
- * @example 六型
- * <Button variant="primary" onClick={save}>保存</Button>
- * <Button variant="secondary">取消</Button>
- * <Button variant="text">编辑</Button>
- * <Button variant="link">查看详情</Button>
- *
- * @example 修饰叠加
- * <Button variant="primary" danger>删除</Button>
- * <Button variant="secondary" danger>删除</Button>
- * <Button variant="primary" block shape="round">提交</Button>
- *
- * @example 菜单按钮（面板用 popup 操作层组合）
- * <Button variant="primary" menu caret popoverTarget="menu-1">更多</Button>
- * <div id="menu-1" popover class="mh-popup mh-button__menu" data-side="bottom" data-align="start">
- *   <div class="mh-button__menu-item">导出</div>
- * </div>
+ * `href` 存在时渲染成 `<a>`（链接语义 + 原生右键菜单）；此时 `disabled` 只能靠 `aria-disabled` 与拦截点击表达
+ * （`<a>` 没有原生禁用），这是有意的取舍。
  */
 export declare const Button: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 按钮型（缺省 `secondary`，与规范「次要为默认」一致） */

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

@@ -12,44 +12,30 @@ export type CapsuleShape = 'pill' | 'square';
  *
  * ## 结构与键盘全靠原生
  *
- * 渲染的是「**平级相邻、开关在前**」的 `<input type="radio">` + `<label for>`：
- * 样式层靠 `input:checked + .mh-capsule__item` 选态，故**顺序不能调**（input 必须紧邻项之前）；
- * 项上带 `for`/`id` 是为了整项可点（开关自身是 1px 隐身盒、`pointer-events: none`）。
- * Tab 进组、← → 换项、空格选中、跳过禁用项 —— 都是原生 radio 组的行为，本件不写键盘代码。
+ * 渲染的是「**平级相邻、开关在前**」的 `<input type="radio">` + `<label for>`：样式层靠
+ * `input:checked + .mh-capsule__item` 选态，故**顺序不能调**（input 必须紧邻项之前）；项上带 `for` / `id`
+ * 是为了整项可点（开关自身是 1px 隐身盒、`pointer-events: none`）。Tab 进组、← → 换项、空格选中、跳过禁用项
+ * —— 都是原生 radio 组的行为，本件不写键盘代码。
  *
  * ## 外形档（`shape`）
  *
  * - `pill`（缺省）：整条轨道与选中项都是胶囊形（圆角取圆角满档令牌）；
- * - `square`：整组变圆角矩形，**轨道与选中项同取复选框档圆角**（比控件档更方），
- *   与方角控件并排排版时用；只覆盖圆角令牌，几何与颜色一律不变。
+ * - `square`：整组变圆角矩形，**轨道与选中项同取复选框档圆角**（比控件档更方），与方角控件并排排版时用；只
+ *   覆盖圆角令牌，几何与颜色一律不变。
  *
  * ## 与面板组合（页签用法）
  *
- * 塞进 `Tabs` 的 `selector` 插槽即可：本件的 `onChange` 把选中值递给 `Tabs` 的 `select`，
- * 面板显隐由 `Tabs` 按受控值下发 `hidden`。本件不认识 tabs，tabs 也不认识本件（两层零互指）。
- * 故**不必**为了组合而给它 `name`（组名不传即按实例自动生成）。
- *
- * 状态三源等价：原生 `input:checked` / 组件下发 `[data-state='active'|'inactive']` / 静态档 `.is-selected`。
+ * 塞进 `Tabs` 的 `selector` 插槽即可：本件的 `onChange` 把选中值递给 `Tabs` 的 `select`，面板显隐由 `Tabs`
+ * 按受控值下发 `hidden`。本件不认识 tabs、tabs 也不认识本件（两层零互指），故**不必**为了组合而给它 `name`
+ * （组名不传即按实例自动生成）。
+ * 状态三源等价：原生 `input:checked` / `[data-state='active'|'inactive']` / 静态档 `.is-selected`。
  *
  * ## 必须有值
  *
- * 单选语义就是必选其一：受控传 `modelValue`，非受控由 `defaultValue` 起，**两者都没给时缺省选中第一个
- * 可选项**（跳过禁用项；没有可选项才是空值）—— 与 `Radio.Group` / `Radio.Card` / `Tabs` 同一条口径。
- *
- * @example 选项表
- * <Capsule :options="[{label:'全部',value:'all'}]" v-model="v" />
- *
- * @example 方形档（与方角控件并排时用）
- * <Capsule shape="square" :options="[{label:'全部',value:'all'}]" v-model="v" />
+ * 单选语义就是必选其一：受控传 `modelValue`、非受控由 `defaultValue` 起，**两者都没给时缺省选中第一个可选项**
+ * （跳过禁用项；没有可选项才是空值）—— 与 `Radio.Group` / `Radio.Card` / `Tabs` 同一条口径。
  *
- * @example 与面板组合（页签）
- * <Tabs v-model:value="v">
- *   {{
- *     selector: ({ value, options, select }) =>
- *       <Capsule :options="options" modelValue={value} onChange={select} />,
- *     default: () => [<TabPanel name="全部">…</TabPanel>, <TabPanel name="进行中">…</TabPanel>],
- *   }}
- * </Tabs>
+ * 用法见 `docs/demos/capsule/`（每个维度一份可运行样例；文档页 `docs/components/capsule.md`）。
  */
 export declare const Capsule: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 选项表（也可用默认插槽自排） */

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

@@ -23,68 +23,40 @@ export type CardHeaderIcon = string | (() => VNodeChild);
  *
  * ## Header 区域（四件；`Card.Header` 是完整入口，`Card` 上的同名 props 是它的简写）
  *
- * ```
- * ┌───────────────────────────────────────────────┐
- * │ [图标] 标题                      extra（右端） │
- * │        副标题                                   │
- * └───────────────────────────────────────────────┘
- * ```
- *
- * - **左侧区域**（`__header-main`）= 图标（`icon`）+ 文字块（`title` / `subtitle` 上下两行）
- *   + `Card.Header` 默认插槽的自排内容；
- * - **右侧** = `extra` 插槽（状态胶囊 / 行内按钮 / 统计）；
- * - 四个位**一个都没给**时退化为**纯自排容器**：默认插槽内容原样进头容器（DOM 与没有这些位时一致）。
- *
- * 四个位两处入口完全等价：
- * `<Card title="…" subtitle="…" icon="…">` ≡ `<Card.Header title="…" subtitle="…" icon="…" />`。
- *
- * 几何：图标 36×36（与 `ListView.CardItem` 同一档）、圆角取控件档 6；标题 16/600 单行省略；
- * 副标题 12 + 弱字色，同样单行省略。
+ * **左侧区域**（`__header-main`）= 图标（`icon`，36×36、圆角取控件档 6）+ 文字块（`title` 16/600 单行省略 /
+ * `subtitle` 12 + 弱字色，同样单行省略）+ `Card.Header` 默认插槽的自排内容；**右侧** = `extra` 插槽（状态胶囊 /
+ * 行内按钮 / 统计）；四个位**一个都没给**时退化为**纯自排容器**（默认插槽内容原样进头容器）。
+ * 两处入口完全等价：`<Card title=… subtitle=… icon=…>` ≡ `<Card.Header title=… subtitle=… icon=… />`。
  *
  * ## 内距：**全部由段承载，根件不出内距**
  *
- * 根件只出面（底 / 描边 / 圆角），既不出内距也不出段间距；内距一律吃在**段**上：
- * `Card.Header` / `Body` / `Footer`（分件）与 `Card` 内建头 / 操作行默认各吃 `--mh-card-padding`（20px）。
- *
- * **不给 `padding`**（面上的缺省口径）：纵向是「**每段只吃上边**」—— 一段只负责**与自己上方之间的距离**
- * （下一段的上内距就是段间距），卡片的**下沿由最后一段补**（面上 `:last-child` 那条规则）——
- * 所以 header + body、body + footer 相邻时都不会叠成两份（20 + 20），卡片首末两端又各有一份完整内距。
- *
+ * 根件只出面（底 / 描边 / 圆角），既不出内距也不出段间距；内距一律吃在**段**上（分件与内建头 / 操作行默认各吃
+ * `--mh-card-padding`）。
+ * **不给 `padding`**（面上的缺省口径）：纵向是「**每段只吃上边**」，卡片的**下沿由最后一段补**（面上
+ * `:last-child` 那条）—— 所以 header + body、body + footer 相邻时都不会叠成两份（20 + 20），首末两端又各有一份
+ * 完整内距。
  * **给了 `padding`**：这一段**整段由消费方定价**（`y` = 上下、`x` = 左右，两维都给时下 `padding: y x` 简写，
- * 只给一维就只落那一维、另一维照旧吃令牌）。行内样式盖过面上那条 `:last-child`，
- * 故**下边也按 `y` 走**（`{ y: 0, x: 16 }` ≡ `padding: 0 16px`，内容贴该段下边）—— 要保留兜底就别传。
- * 要整卡统一就改令牌 `--mh-card-padding`。
- *
- * 直接写内容（`<Card>正文</Card>`）时，**裸子节点会被自动包进一层 `Card.Body`**（与 `Panel` 的简写路径同款），
- * 所以它与显式写 `<Card><Card.Body>正文</Card.Body></Card>` 得到同一份内距。
+ * 只给一维就只落那一维）；行内样式盖过 `:last-child`，故**下边也按 `y` 走**（要保留兜底就别传）。要整卡统一就
+ * 改令牌 `--mh-card-padding`。
+ * 直接写内容（`<Card>正文</Card>`）时**裸子节点会被自动包进一层 `Card.Body`**（与 `Panel` 的简写路径同款），故
+ * 与显式写 `<Card.Body>` 得到同一份内距。
  *
  * ## 三件（`Card.Header` / `Body` / `Footer`）
  *
- * 分件只有内距这一个维度：**不给就走 CSS 默认值**（不额外产生行内 `style`，DOM 与没有该维度时一致）。
- * 分件的 `padding` 语义同上（给了就整段由消费方定价，含下边；不给才吃「只吃上边 + 末段补下沿」的缺省口径）。
- *
- * ## 底部操作行（`actions` 插槽）
- *
- * `margin-top: auto` 贴卡片底部，卡片被拉伸（网格等高）时才有差别；内距与段同口径。
+ * 分件只有内距这一个维度：**不给就走 CSS 默认值**（不额外产生行内 `style`）；`padding` 语义同上。
+ * **底部操作行**（`actions` 插槽）：`margin-top: auto` 贴卡片底部（卡片被拉伸时才有差别），内距与段同口径。
  *
  * ## 为什么不是 `<button>`
  *
  * 卡片里常驻操作按钮（编辑 / 删除等），整卡换成按钮会产生嵌套可交互元素；键盘可达性由卡内控件承担。
  * 「整卡可点」由 `interactive`（光标 + 悬浮反馈）+ `onClick` 表达，与原型一致。
  *
- * @example 技能卡（图标 + 标题/副标题 + 右端状态 + 正文 + 操作行）
- * <Card>
- *   <Card.Header icon={skill.icon} title={skill.name} subtitle={`V${skill.version}`}>
- *     <template #extra><Badge shape="soft" tone="success">已发布</Badge></template>
- *   </Card.Header>
- *   <Card.Body>{skill.description}</Card.Body>
- *   <template #actions><Button size="sm">编辑</Button></template>
- * </Card>
+ * 用法见 `docs/demos/card/`（每个维度一份可运行样例；文档页 `docs/components/card.md`）。
  */
 export interface CardProps {
     /**
-     * 描边档：`outline`（默认）弱描边 `--ui-base-300`；`plain` 无描边。
-     * 底 / 圆角 / 阴影不随档位变化 —— 卡片外观在本件只有一处定义。
+     * 描边档：`outline`（默认）弱描边 `--ui-base-300`；`plain` 无描边。底 / 圆角 / 阴影不随档位变化 —— 卡片外观在
+     * 本件只有一处定义。
      */
     variant?: CardVariant;
     /** 悬浮反馈：hover 描边转主色 + 主色 12% 阴影，并显示 `cursor: pointer` */
@@ -103,10 +75,8 @@ export interface CardProps {
     onClick?: (e: MouseEvent) => void;
 }
 /**
- * 卡片头部：**四件**（图标 / 标题 / 副标题 + 右端 `extra`）。
- *
- * 四个位都可由属性给；`icon` / `title` / `subtitle` / `extra` 也都可走同名插槽（**插槽优先**）。
- * 一个位都不给时退化为自排容器：默认插槽内容原样进头容器（`Card.Header` 也仍然是「自己排头」的逃生口）。
+ * 卡片头部：**四件**（图标 / 标题 / 副标题 + 右端 `extra`）—— 四个位都可由属性给，也都可走同名插槽（**插槽
+ * 优先**）；一个位都不给时退化为自排容器（`Card.Header` 也仍然是「自己排头」的逃生口）。
  */
 export declare const CardHeader: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 这一段的内距（`number` = 四边同值；`{ y, x }` = 上下 / 左右）：不给时吃组件令牌 `--mh-card-padding`（20px）、下边由末段补；**给了就整段由消费方定价（含下边）** */
@@ -198,10 +168,7 @@ export declare const CardFooter: import("vue").DefineComponent<import("vue").Ext
 }, SlotsType<{
     default?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-/**
- * 复合件入口：`Card` + `Card.Header` / `Card.Body` / `Card.Footer`
- * （与 `Panel` 同款 `Object.assign` 复合写法；成员不平级导出）
- */
+/** 复合件入口：`Card` + `Card.Header` / `Card.Body` / `Card.Footer`（与 `Panel` 同款 `Object.assign` 复合写法；成员不平级导出） */
 export declare const Card: {
     new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
         variant: {

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

@@ -23,15 +23,7 @@ export interface CheckboxOption {
  *   要再引入中性面填充请做成 `tone` 的第二档，**不要**把默认改回深色；
  * - 半选（`indeterminate`）是**旁路态**：点击后由消费方自行决定落到 `checked` 还是 `unchecked`。
  *
- * @example
- * <Checkbox modelValue={row.enabled} onChange={(v) => (row.enabled = v)}>是否生效</Checkbox>
- *
- * @example 全选 / 半选
- * <Checkbox indeterminate={someChecked && !allChecked}
- *   modelValue={allChecked} onChange={(v) => toggleAll(v)}>全选</Checkbox>
- *
- * @example 多选组（值就是选中项的数组）
- * <Checkbox.Group v-model={picked} options={[{ label: '读', value: 'r' }]} />
+ * 用法见 `docs/demos/checkbox/`（每个维度一份可运行样例；文档页 `docs/components/checkbox.md`）。
  */
 export declare const Checkbox: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     /** 受控勾选值 */

package/dist/components/code-block/index.d.ts

@@ -21,36 +21,23 @@ export interface CodeViewProps {
 /**
  * 代码视图（**只读展示件**）：行内 chip / 代码块 / 语言角标 / 复制位。
  *
- * 三种形态：`inline`（行内 chip，如版本号、规则 ID）、`inline + plain`（中性档）、
- * 缺省（代码块 + 右上角 hover / 聚焦显形的方形图标复制按钮 + 可选语言角标）。
- * 代码块**缺省不折行**（横向滚动，缩进与列对齐不被破坏），`wrap` 才软换行。
- *
- * 通常不直接用本件：`CodeBlock.View` 是这个件在族里的位置，单独用也完全合法
- * （要「只读看 + 就地改」用组合件 `CodeBlock`，要更强的编辑控制用 `CodeBlock.Editor`）。
+ * 三种形态：`inline`（行内 chip，如版本号、规则 ID）、`inline + plain`（中性档）、缺省（代码块 + 右上角 hover /
+ * 聚焦显形的方形图标复制按钮 + 可选语言角标）。代码块**缺省不折行**（横向滚动，缩进与列对齐不被破坏），`wrap` 才软换行。
+ * 通常不直接用本件，但单独用也完全合法（要「只读看 + 就地改」用组合件 `CodeBlock`）。
  *
  * ## 高亮由消费方声明（本件不做语法高亮）
- *
- * 本件不认识任何语言：`language` 只画右上角的**角标**，**不做**分词着色。
- * 需要高亮时走**默认插槽**传入已高亮过的节点（VNode / 已转义好的 HTML 片段皆可），
- * 此时 `code` 仍应给**纯文本** —— 它是复制进剪贴板的内容（插槽内容是渲染结果，不能拿去复制）。
+ * 本件不认识任何语言：`language` 只画右上角的**角标**、**不做**分词着色。需要高亮时走**默认插槽**传入已高亮过的
+ * 节点（VNode / 已转义好的 HTML 片段皆可），此时 `code` 仍应给**纯文本** —— 它是复制进剪贴板的内容。
  *
  * ## 复制按钮的面归按钮族（`.mh-button--icon`）
- *
- * 本件只补定位与显隐（见 `styles/components/code-block.css`）；按钮挂在**族根**上
- * 而**不是代码面里** —— 代码面是 `overflow-x: auto` 的滚动容器，放进去会被裁掉。
+ * 本件只补定位与显隐；按钮挂在**族根**上而**不是代码面里** —— 代码面是 `overflow-x: auto` 的滚动容器，放进去会被裁掉。
  *
  * ## 复制动作与降级
+ * 走 `navigator.clipboard.writeText`（**唯一需要 JS 的部分**，按 copied 状态二选一图标）。环境没有该 API（旧浏览器 /
+ * 非安全上下文）或写入被拒时：不谎报成功，`onCopy(false)` 交回结果并 `console.warn` 一次 —— 消费方据此提示「请手动
+ * 复制」（本件不自己弹提示，避免与页面的提示口径两套）。
  *
- * 走 `navigator.clipboard.writeText`（**唯一需要 JS 的部分**，按 copied 状态二选一图标）。
- * 环境没有该 API（旧浏览器、非安全上下文）或写入被拒时：不谎报成功，`onCopy(false)` 交回结果
- * 并 `console.warn` 一次 —— 消费方据此提示「请手动复制」（本件不自己弹提示，避免与页面的提示口径两套）。
- *
- * @example 行内
- * <CodeBlock.View inline>v1.2.0</CodeBlock.View>
- * <CodeBlock.View inline plain>RULE-1024</CodeBlock.View>
- *
- * @example 代码块 + 语言角标 + 复制
- * <CodeBlock.View :code="sql" language="sql" copyable @copy="(ok) => ok || showManualTip()" />
+ * 用法见 `docs/demos/code-block/`（每个维度一份可运行样例；文档页 `docs/components/code-block.md`）。
  */
 export declare const CodeView: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     code: {
@@ -124,9 +111,9 @@ export declare const CodeView: import("vue").DefineComponent<import("vue").Extra
     plain: boolean;
     code: string;
     onCopy: (ok: boolean) => void;
+    maxHeight: string | number;
     language: string;
     copyable: boolean;
-    maxHeight: string | number;
 }, SlotsType<{
     default?: () => VNodeChild;
 }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
@@ -145,10 +132,7 @@ export interface CodeEditorProps {
     placeholder?: string;
     /** 固定可见行数（`autoSize: false` 时生效；缺省 4） */
     rows?: number;
-    /**
-     * 按内容行数自适应高度（**本件缺省开启**，与 `Textarea` 的缺省相反：
-     * 代码区按内容长高是常态，固定行数才是特例）。
-     */
+    /** 按内容行数自适应高度（**本件缺省开启**，与 `Textarea` 的缺省相反：代码区按内容长高是常态，固定行数才是特例）。 */
     autoSize?: boolean | CodeEditorAutoSize;
     /** 最大高度（数字按 px）：超出后**框内滚动** */
     maxHeight?: string | number;
@@ -164,31 +148,22 @@ export interface CodeEditorProps {
 /**
  * 可编辑代码区：等宽多行 + 按行自适应 + 可限高内滚 + 只读 / 禁用态。
  *
- * 与 `CodeBlock.View` 是同一族的两半：**看**用 `View`（可按只读块观感渲染已高亮节点），
- * **改**用本件。两件共用族根与面（同底 / 同圆角 / 同等宽字），互切时块体不跳。
+ * 与 `CodeBlock.View` 是同一族的两半：**看**用 `View`（可按只读块观感渲染已高亮节点），**改**用本件；两件共用族根
+ * 与面（同底 / 同圆角 / 同等宽字），互切时块体不跳。
  *
  * ## 与 `Textarea` 的分工（不要重复造）
- *
- * 表单里的普通多行文本用 `Input.Textarea`；本件服务**代码**：等宽字、去掉拼写检查与自动大写、
- * 折行行为按代码区的口径来。两者共用同一套受控词表（`modelValue` / `onChange` / `readonly` / `disabled`）。
+ * 表单里的普通多行文本用 `Input.Textarea`；本件服务**代码**：等宽字、去掉拼写检查与自动大写、折行按代码区口径来。
+ * 两者共用同一套受控词表（`modelValue` / `onChange` / `readonly` / `disabled`）。
  *
  * ## 不做的事（有意）
- *
- * - **不做语法高亮**：编辑态就是原生 `textarea`，着色一律交给消费方（只读态用 `View` 的插槽接高亮）；
- * - **不内建动作按钮**（编辑 / 保存 / 取消 / 复制）：动作条由消费方在外部摆放，本件只负责"能改"；
- * - 不做行号、不做 Tab 缩进接管（会与浏览器的焦点导航与粘贴行为打架）。
+ * **不做语法高亮**（编辑态就是原生 `textarea`，着色一律交给消费方；只读态用 `View` 的插槽接高亮）；**不内建动作
+ * 按钮**（编辑 / 保存 / 取消 / 复制由消费方在外部摆放）；不做行号、不做 Tab 缩进接管（会与浏览器的焦点导航与粘贴
+ * 行为打架）。
  *
  * ## 自适应高度怎么算
- *
- * 按 `\n` **计数行数**在 `minRows` / `maxRows` 间截断（同 `Input.Textarea`）：不测 `scrollHeight`
- * ——那要在每次输入后读布局（强制同步回流），且软换行 / 隐藏容器 / SSR 下都拿不到可靠值。
- * 代价是**超长单行不会自己长高**（此时由 `maxHeight` + 框内滚动兜底，或由外层容器限宽）。
- *
- * @example 受控
- * <CodeBlock.Editor v-model="sql" language="sql" placeholder="写一条 SQL" />
- *
- * @example 固定高度 + 限高内滚
- * <CodeBlock.Editor v-model="config" :auto-size="false" :rows="6" :max-height="240" language="json" />
+ * 按 `\n` **计数行数**在 `minRows` / `maxRows` 间截断（同 `Input.Textarea`）：不测 `scrollHeight` —— 那要在每次
+ * 输入后读布局（强制同步回流），且软换行 / 隐藏容器 / SSR 下都拿不到可靠值。代价是**超长单行不会自己长高**（由
+ * `maxHeight` + 框内滚动兜底，或由外层容器限宽）。
  */
 export declare const CodeEditor: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
     modelValue: {
@@ -285,25 +260,23 @@ export declare const CodeEditor: import("vue").DefineComponent<import("vue").Ext
     modelValue: string;
     readonly: boolean;
     autoSize: boolean | CodeEditorAutoSize;
-    language: string;
     maxHeight: string | number;
+    language: string;
 }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 /** `CodeBlock` 的 props：**两形态的并集** + 切换开关（按 `editable` 分两组，见各条说明） */
 export interface CodeBlockProps extends CodeViewProps, CodeEditorProps {
     /**
-     * 编辑档：`true` 渲染 `Editor`（可改），缺省 `false` 渲染 `View`（只读展示）。
-     *
-     * 两形态的 props 都挂在本件上，但**按档生效**：只读档读 `code` / `inline` / `plain` / `copyable` /
-     * `wrap` / `onCopy`，编辑档读 `modelValue` / `defaultValue` / `placeholder` / `rows` / `autoSize` /
-     * `readonly` / `disabled` / `onChange`；`language` / `maxHeight` 两档共用。
+     * 编辑档：`true` 渲染 `Editor`（可改），缺省 `false` 渲染 `View`（只读展示）。两形态的 props 都挂在本件上，
+     * 但**按档生效**：只读档读 `code` / `inline` / `plain` / `copyable` / `wrap` / `onCopy`，编辑档读
+     * `modelValue` / `defaultValue` / `placeholder` / `rows` / `autoSize` / `readonly` / `disabled` / `onChange`；
+     * `language` / `maxHeight` 两档共用。
      */
     editable?: boolean;
 }
 /**
- * 族入口：`CodeBlock` 本体 + 两个成员件（`View` 只读 / `Editor` 可编辑）。
- *
- * `Object.assign` 是**原地**挂载（与 `Input.Textarea` 同一手法）：运行时的 `CodeBlock` 就是它，
- * 类型上也带成员（`typeof CodeBlock` 是交叉类型），故 TSX 与模板里 `CodeBlock.View` 都有提示。
+ * 族入口：`CodeBlock` 本体 + 两个成员件（`View` 只读 / `Editor` 可编辑）。`Object.assign` 是**原地**挂载
+ * （与 `Input.Textarea` 同一手法）：运行时的 `CodeBlock` 就是它，类型上也带成员，故 TSX 与模板里
+ * `CodeBlock.View` 都有提示。
  */
 export declare const CodeBlock: {
     new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
@@ -393,9 +366,9 @@ export declare const CodeBlock: {
         modelValue: string;
         readonly: boolean;
         autoSize: boolean | CodeEditorAutoSize;
+        maxHeight: string | number;
         language: string;
         copyable: boolean;
-        maxHeight: string | number;
         editable: boolean;
     }, true, {}, SlotsType<{
         default?: () => VNodeChild;
@@ -491,9 +464,9 @@ export declare const CodeBlock: {
         modelValue: string;
         readonly: boolean;
         autoSize: boolean | CodeEditorAutoSize;
+        maxHeight: string | number;
         language: string;
         copyable: boolean;
-        maxHeight: string | number;
         editable: boolean;
     }>;
     __isFragment?: never;
@@ -586,9 +559,9 @@ export declare const CodeBlock: {
     modelValue: string;
     readonly: boolean;
     autoSize: boolean | CodeEditorAutoSize;
+    maxHeight: string | number;
     language: string;
     copyable: boolean;
-    maxHeight: string | number;
     editable: boolean;
 }, {}, string, SlotsType<{
     default?: () => VNodeChild;
@@ -665,9 +638,9 @@ export declare const CodeBlock: {
         plain: boolean;
         code: string;
         onCopy: (ok: boolean) => void;
+        maxHeight: string | number;
         language: string;
         copyable: boolean;
-        maxHeight: string | number;
     }, SlotsType<{
         default?: () => VNodeChild;
     }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
@@ -766,8 +739,8 @@ export declare const CodeBlock: {
         modelValue: string;
         readonly: boolean;
         autoSize: boolean | CodeEditorAutoSize;
-        language: string;
         maxHeight: string | number;
+        language: string;
     }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 };
 /** 含成员的 `CodeBlock` 类型（与 `CodeBlockCompoundType` 同义，两个名字都为对齐本仓既有的 `XxxCompound` 口径） */

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

@@ -5,6 +5,8 @@ export interface CollapseProps {
     /**
      * 受控展开态。不传即**非受控**（由 `defaultOpen` 起，之后自己管）。
      * 受控时父级不同步回写，本件会把 DOM 拨回 `open` 的值（见下方「受控」注释）。
+   *
+   * 用法见 `docs/demos/collapse/`（每个维度一份可运行样例；文档页 `docs/components/collapse.md`）。
      */
     open?: boolean;
     /** 非受控初始展开态，缺省收起（与原生 `<details>` 一致：不写 open 即收起） */