@manohub/ui 1.0.4 → 1.0.6

package/dist/services/dialog.d.ts

@@ -1,4 +1,4 @@
-import { type DialogTone } from '../components/dialog';
+import { type DialogTone, type DialogWidth } from '../components/dialog';
 export interface ConfirmOptions {
     /** 标题（缺省不渲染页头，只剩内容与底栏） */
     title?: string;
@@ -9,8 +9,12 @@ export interface ConfirmOptions {
      *
      * 不传则无图标。**危险操作用 `error`** —— 它同时把确定按钮染成危险色
      * （除非显式给了 `okDanger`），这样「删除确认」与「保存成功」不再长得一样。
+   *
+   * 用法见 `docs/demos/dialog/`（每个维度一份可运行样例；文档页 `docs/components/dialog.md`）。
      */
     tone?: DialogTone;
+    /** 面板宽度档：**缺省 `'sm'`（400）**，比 `Dialog` 的 `md` 档窄一档 */
+    width?: DialogWidth | number;
     /** 确定按钮文案 */
     okText?: string;
     /** 取消按钮文案（`alert` 不使用） */
@@ -23,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/dialog.js

@@ -40,6 +40,7 @@ function confirm(options = {}) {
         open: ctx.isOpen(),
         title: options.title,
         tone: options.tone,
+        width: options.width || "sm",
         closable: options.closable ?? true,
         // 组件形态默认已开（跟主流）；命令式这一层显式关掉，防误点丢决策
         closeOnBackdrop: false,
@@ -63,6 +64,7 @@ function alert(options = {}) {
         open: ctx.isOpen(),
         title: options.title,
         tone: options.tone,
+        width: options.width || "sm",
         closable: options.closable ?? true,
         closeOnBackdrop: false,
         maskClosable: 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';

package/dist/services/loading.d.ts

@@ -1,21 +1,18 @@
+import { type ServiceHandle } from './base';
+/** 加载遮罩的句柄（与 `toast()` 同一形状，见 `ServiceHandle`）：关掉自己那一次 */
+export type LoadingHandle = ServiceHandle;
 /**
- * 显示全屏加载遮罩（命令式），返回**幂等的关闭句柄**。
+ * 显示全屏加载遮罩（命令式），返回**幂等的关闭句柄**（`{ close() }`，与 `toast()` 同形状）。
  *
  * 遮罩落在服务宿主（应用自己的 `[data-manohub-ui]` 容器）内 —— 令牌与应用侧样式都跟着它走。
  * 层级压在同包的 `Toast` 堆叠之上、模态层（`<dialog>` 的 top layer）之下。
  *
- * @example 配平用法（推荐：句柄只关自己那一次）
- * const done = showLoading('保存中…')
- * try {
- *   await save()
- * } finally {
- *   done()
- * }
+ * 句柄只关**自己那一次**（计数减一）；重复 `close()` 不再生效（幂等）。不接句柄时也可用模块级的
+ * `hideLoading()` 手动减一（已是 0 时 no-op）。
  *
- * @example 文案可后置（同一批并发里最后一次给的文案生效）
- * showLoading()
- * showLoading('正在导入，请勿关闭页面')
+ * 用法见 `docs/demos/loading/service.vue`（配平与并发样例）与 `docs/components/loading.md` 的
+ * 「命令式调用」一节。
  */
-export declare function showLoading(value?: string): () => void;
+export declare function showLoading(value?: string): LoadingHandle;
 /** 关闭一次（引用计数递减）；计数归零时收掉宿主与实例。已是 0 时是 no-op */
 export declare function hideLoading(): void;

package/dist/services/loading.js

@@ -27,7 +27,14 @@ function showLoading(value) {
   ensureApp();
   count += 1;
   text.value = value;
-  return () => hideLoading();
+  let closed = false;
+  return {
+    close: () => {
+      if (closed) return;
+      closed = true;
+      hideLoading();
+    }
+  };
 }
 function hideLoading() {
   if (count === 0) return;

package/dist/services/toast.d.ts

@@ -1,4 +1,5 @@
 import { type ToastTone } from '../components/toast';
+import { type ServiceHandle } from './base';
 export interface ToastServiceOptions {
     /** 自动消失毫秒数（缺省 3000；`0` = 常驻，必须由调用方或用户自行关掉） */
     duration?: number;
@@ -10,10 +11,8 @@ export interface ToastServiceOptions {
     /** 手动关闭位（缺省：常驻提示自动开、会自己消失的不开） */
     closable?: boolean;
 }
-/** 单条提示的句柄：提前关掉它（如「保存中」完成后立刻收掉） */
-export interface ToastHandle {
-    close: () => void;
-}
+/** 单条提示的句柄（与 `showLoading()` 同一形状，见 `ServiceHandle`）：提前关掉它那一条 */
+export type ToastHandle = ServiceHandle;
 /**
  * 弹一条消息提示（命令式）。
  *
@@ -24,16 +23,7 @@ export interface ToastHandle {
  * ③ 同屏最多 5 条，超出挤掉最早的；
  * ④ 返回句柄可提前关掉它自己（其余各条互不影响）。
  *
- * @example 成功提示（3 秒自动消失）
- * toast('success', '保存成功')
- *
- * @example 失败 + 重试动作
- * toast('error', '导出失败', { action: { text: '重试', onClick: retry } })
- *
- * @example 常驻的「进行中」，完成后自己收掉
- * const pending = toast('loading', '正在导入…', { duration: 0 })
- * // …导入完成
- * pending.close()
+ * 用法见 `docs/demos/toast/service.vue` 与 `docs/components/toast.md` 的「命令式调用」一节。
  */
 export declare function toast(tone: ToastTone, text: string, options?: ToastServiceOptions): ToastHandle;
 /** 清空全部提示并收掉宿主（换应用 / 卸载时调；幂等） */

package/dist/styles/components/avatar.css

@@ -1,14 +1,12 @@
 /**
  * Avatar —— 头像（四档尺寸 / 文字 / 图标 / 占位 / 方角 / 带框 / 计数 / 头像组 / 角标）。
  *
- * 出处：`@aihub/theme` 的 `playground/components/avatar.css` 与 `src/components/avatar.css`
- * （实测四档 24 / 36 / 60 / 80；字母底色取主色；角标高 20 白描边）。
+ * 出处：规范（实测四档 24 / 36 / 60 / 80；字母底色取主色；角标高 20 白描边）。
  *
- * 两条来自规范的硬结论，改前先读：
- * 1. **圆形裁切归图片自身，容器不裁**：角上的角标（`__badge`）与徽章（`__chip`）是绝对定位件，
- *    容器若带 `overflow: hidden`，会沿圆弧把它们各切掉一半（实测反馈）。故容器 `overflow: visible`，
- *    图片用 `border-radius: inherit` 跟着形态自裁。
- * 2. **头像组靠负边距堆叠**（`.mh-avatar-group`），每个头像带 2px 的底描边把相邻项隔开。
+ * 两条硬结论（改前先读）：① **圆形裁切归图片自身，容器不裁** —— 角上的角标（`__badge`）与徽章
+ * （`__chip`）是绝对定位件，容器若带 `overflow: hidden` 会沿圆弧把它们各切掉一半（实测反馈），故容器
+ * `overflow: visible`、图片用 `border-radius: inherit` 跟着形态自裁；② **头像组靠负边距堆叠**
+ * （`.mh-avatar-group`），每项带 2px 底描边把相邻项隔开。
  */
 .mh-avatar {
   display: inline-flex;

package/dist/styles/components/avatar.tokens.css

@@ -3,16 +3,11 @@
  *
  * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
  *
- * ## 抽出说明
- * 本文件从面文件里抽出（原先混写在 `avatar.css` 顶部）：这些是**基础值**，锚在
- * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
- * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
- * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
  *
- * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
- * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
- * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
- */
+ * 令牌锚 `[data-manohub-ui]`（容器是每个分件的祖先 ⇒ 落在容器里的分件都取得到值）。
+ * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里（搬走会让档位失效）；
+ * 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
+*/
 [data-manohub-ui] {
   /* 单件令牌（只服务本件；跨件令牌才进 theme/） */
   --ui-avatar-size-sm: 24px;

package/dist/styles/components/badge.css

@@ -1,13 +1,10 @@
 /**
- * Badge（徽标 / 标签）。
+ * Badge（徽标 / 标签）。出处：规范 `badge.css`（徽标高 20 / 胶囊）与 `tag.css`（标签片几何）。
  *
- * 依据：@aihub/theme 的 components/badge.css（徽标高 20 / 胶囊）与 components/tag.css（标签片几何）。
+ * 按设计稿收敛为 tone × shape × size × dot 的正交组合：每个 tone 先铺一组局部变量（前景 / 底色 /
+ * 描边 / 圆点），形态类只决定「用哪几个变量」。
  */
 
-/* ===== Badge（徽标 / 标签）=====
-   批次 5 前 4 个应用各自手搓徽标，这里按设计稿收敛为 tone × shape × size × dot 的正交组合。
-   每个 tone 先铺一组局部变量（前景 / 底色 / 描边 / 圆点），形态类只决定「用哪几个变量」。 */
-
 .mh-badge {
   --mh-badge-fg: var(--ui-base-content);
   --mh-badge-bg: transparent;

package/dist/styles/components/badge.tokens.css

@@ -1,22 +1,10 @@
 /**
- * badge —— 单件令牌（**基础值**）。
+ * badge —— 单件令牌（**基础值**；只服务本件，故不随主题进 `@manohub/theme`）。
  *
- * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
- *
- * ## 抽出说明
- * 本文件从面文件里抽出（原先混写在 `badge.css` 顶部）：这些是**基础值**，锚在
- * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
- * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
- * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值、组内间距变 0）。
- *
- * 本件为什么需要本文件：`Badge` 有**两个互不嵌套的根类** —— `.mh-badge`（内容徽标 / 数字角标）
- * 与 `.mh-badge--status`（状态点 + 文字，它不带 `.mh-badge`）。前置点与状态点共用同一枚
- * 光学对齐位移，声明在任何**根类**上都到不了另一个根（自定义属性只向下继承），故按本仓口径
- * 落到容器锚上。
- *
- * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
- * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
- * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
+ * 本件有两个**互不嵌套的根类**：`.mh-badge`（内容徽标 / 数字角标）与 `.mh-badge--status`（状态点 + 文字，
+ * 不带 `.mh-badge`）—— 前置点与状态点共用同一枚光学对齐位移，声明在任何根类上都到不了另一个根，故按本仓
+ * 口径落到容器锚 `[data-manohub-ui]` 上（容器是每个分件的祖先，分件都取得到值）。
+ * ⚠️ 档位改写留在面文件的修饰符块里（搬来会失效）；新增组件登记两处：本文件 + `src/styles/index.css`。
  */
 [data-manohub-ui] {
   /* 前置点 / 状态点的**光学对齐**位移（数字见面文件 `__dot` 一节：盒居中读起来偏高）。 */

package/dist/styles/components/button.css

@@ -1,30 +1,21 @@
 /**
  * Button —— 自绘按钮族（六型 + 三档真实尺寸 + 外形 / 危险色 / 整宽修饰 + 加载 + 图标/文本/菜单形态 + 组容器 + 菜单皮肤）。
  *
- * 出处（几何以设计稿《MH后台-0911》品牌页为准，规范同值处不再复述）：
- * - 控件高 **32** / 内距 **12** / 图文距 **4** / 圆角 **6** / 字号 **14/18 w400** / 组间距 8；
- * - 主要 = 主色实底 **无投影**（`0:3897`）；次要 = 白底 + `#e6e6e6` 描边 + **中性字色**
- *   （`0:3892`，文本 `#1a1a1a`）；禁用 = `#f2f2f2` 底 + `#888888` 字（`次要按钮备份`）；
- * - 小号 24、大号 40（设计未覆盖，沿用）；图标槽 = 全局图标档（见 `--ui-button-icon-size`）；加载环 14 · 0.8s linear；
- *   虚线 = 区域内添加，文本 = 行内操作，图标 = 方形热区；菜单按钮 = 文本区 ‖ 分割线 ‖ 箭头区。
+ * 出处（几何以设计稿《MH后台-0911》品牌页为准）：控件高 **32** / 内距 **12** / 图文距 **4** /
+ * 圆角 **6** / 字号 **14/18 w400** / 组间距 8；主要 = 主色实底**无投影**（`0:3897`）；
+ * 次要 = 白底 + `#e6e6e6` 描边 + **中性字色**（`0:3892`）；禁用 = `#f2f2f2` 底 + `#888888` 字；
+ * 小号 24 / 大号 40（设计未覆盖，沿用）；图标槽 = 全局图标档；加载环 14 · 0.8s linear；
+ * 虚线 = 区域内添加，文本 = 行内操作，图标 = 方形热区；菜单按钮 = 文本区 ‖ 分割线 ‖ 箭头区。
  *
- * **色彩槽位走局部变量**（`--ui-button-accent*`）：六型只描述「底 / 边 / 字的取用位置」，
- * 具体颜色由槽位变量给。危险色只是把槽位换成错误色，故 `danger` 与任意型**天然正交**，
- * hover / active / 加载态一并跟随，无需为每个型再写一遍危险态（这是本文件的核心结构）。
+ * **色彩槽位走局部变量**（`--ui-button-accent*`）：六型只描述「底 / 边 / 字的取用位置」，具体颜色由
+ * 槽位变量给 ⇒ 危险色只是把槽位换成错误色，`danger` 与任意型**天然正交**，hover / active / 加载态
+ * 一并跟随（本文件的核心结构）。
  *
- * **高度三档全部吃主题令牌**（`--ui-control-height-sm` / `-md` / `-lg`，default 24 / 32 / 40）——
- * 换主题即换控件尺寸，这正是 theme 层的职责。md 与 lg **不同高**：同高会让 `size`
- * 沦为无视觉差别的语义标签，调用方无从选择。
- *
- * **类名一律 `mh-` 前缀**：本包独立发布，不迁就任何下游的既有类名；同一词根在本包内只有一套类（见 AGENTS）。
- * 自绘件服务「不装 farris」的场景：静态页 / 其他框架 / 微前端里不带 farris 的子应用。
- *
- * **投影**：主要与次要两型**不再带投影**（设计稿的按钮是平的，节点上无 effects）。
- * 图标型的 hover 光晕仍引用 `--ui-shadow-card-hover` —— 那是 hover 反馈，不是静止装饰，
- * 且投影一律走令牌、不新造字面量（与 shadows.css「拟物重投影一律收敛到令牌」的口径一致）。
- *
- * 边界（有意不做）：规范的 `.btn-seg`（分段按钮，原生同名 radio 驱动）**不在这里实现** ——
- * 它的用途（一组互斥选项的轻量选择器）由 `capsule` 族承担，重复实现会出现两套分段控件。
+ * **高度三档全部吃主题令牌**（`--ui-control-height-sm|-md|-lg`，default 24 / 32 / 40）：换主题即换尺寸。
+ * md 与 lg **不同高**：同高会让 `size` 沦为无视觉差别的语义标签。
+ * **投影**：主要与次要两型**不带投影**（设计稿的按钮是平的）；图标型 hover 的光晕仍引用
+ * `--ui-shadow-card-hover` —— 那是 hover 反馈，不是静止装饰（投影一律走令牌）。
+ * 边界（有意不做）：规范的 `.btn-seg`（分段按钮）**不在这里实现** —— 其用途由 `capsule` 族承担。
  */
 
 /* 几何只挂在按钮本体上：令牌在同名 `.tokens.css`（锚 `[data-manohub-ui]`），几何若跟着挂会把容器也画成按钮 */
@@ -48,10 +39,11 @@
   transition-property: background-color, border-color, color, box-shadow;
   transition-duration: 0.15s;
   transition-timing-function: ease;
+  /* 定位上下文：隐身 file input 的包含块必须落在按钮内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
-/* 危险色修饰：换槽位即可，六型与各自 hover / active 一并跟随
-   （`--ui-button-accent-soft` 随无消费者的孤令牌一并撤除，2026-09-30） */
+/* 危险色修饰：换槽位即可，六型与各自 hover / active 一并跟随 */
 .mh-button--danger {
   --ui-button-accent: var(--ui-error);
   --ui-button-accent-hover: color-mix(in srgb, var(--ui-error) 88%, black);
@@ -130,8 +122,7 @@
 }
 
 /* ===== 主要：主色实底（**无投影**） =====
-   设计实证：`0:3897` 是纯 `#2660ff` 实底 + r6，节点上没有任何 effects。
-   改前挂的 `--ui-shadow-card-hover` 会让按钮在设计里「浮起来」，属多余装饰。 */
+   设计实证：`0:3897` 是纯 `#2660ff` 实底 + r6，节点上没有任何 effects。 */
 .mh-button--primary {
   background: var(--ui-button-accent);
   color: var(--ui-button-accent-content);
@@ -147,8 +138,7 @@
 
 /* ===== 次要：白底描边 + **中性字色**（无投影） =====
    设计实证：`0:3892` = 白底 + `#e6e6e6` 描边 + r6 + 文本 `#1a1a1a`（**中性**，不是主色蓝）。
-   改前用 `--ui-button-accent`（主色蓝）+ `--ui-shadow-card`，页头上会出现「蓝字带投影」的次要按钮，
-   与设计的「黑字平贴」观感不同。白底按钮在浅色页面上本就靠描边成形，**不需要投影**。 */
+   白底按钮在浅色页面上本就靠描边成形，**不需要投影**。 */
 .mh-button--secondary {
   background: var(--ui-base-100);
   border: 1px solid var(--ui-base-300);
@@ -167,9 +157,7 @@
 
 /* ===== 虚线：区域内添加内容 =====
  * 虚线取 `--ui-line-dashed`（= `base-400`，比实线深一档）：同样粗细下虚线的墨迹只有实线的一半，
- * 取实线色（`base-300`）会明显偏浅、整条框看着发虚。
- * 这条口径 2026-09-30 一天内翻过一次：早些时候按「线框色只留一套」把虚线也收敛到 `base-300`，
- * 当日晚按实机观感反转 —— 定稿见 `@manohub/theme` 的 `default/colors.css` 头「三条口径」第 2 条。 */
+ * 取实线色（`base-300`）会明显偏浅、整条框看着发虚（口径见 theme 的 `default/colors.css` 第 2 条）。 */
 .mh-button--dashed {
   background: var(--ui-base-100);
   border: 1px dashed var(--ui-line-dashed);
@@ -256,15 +244,12 @@
   color: color-mix(in srgb, var(--ui-error) 88%, black);
 }
 
-/* ===== 禁用（各类通用；用专用令牌而非 opacity，避免禁用态被底色影响）
- *
- * 描边走 **inset 阴影而不是 `border`**：`border: 1px` 会把「无边框」的常态按钮撑宽 2px，
- * 按钮一进禁用就在底栏里抖一下 —— inset 阴影画的还是同一圈 1px、位置也一致，但元素尺寸不变。
- *
- * **加载态排除在外**（`:not()`）：`loading` 虽然也置原生 disabled（吞点击），但它**外观保持本型**
- * —— 点击前后只有「文字 → 环」这一处变化，不换底 / 不换边 / 不换字。不排除的话，禁用档
- * （2 个类）会压过 `.mh-button--loading`（1 个类），全屏最显眼的主操作会在点下去的一瞬间
- * 整块变成禁用灰，观感突兀（浏览器实测过：底 `rgb(241,242,245)` + 灰字 + 灰边）。 */
+/* ===== 禁用（各类通用；用专用令牌而非 opacity，避免禁用态被底色影响） =====
+ * 描边走 **inset 阴影而不是 `border`**：`border: 1px` 会把「无边框」的常态按钮撑宽 2px，按钮一进禁用就在
+ * 底栏里抖一下 —— inset 阴影画的还是同一圈 1px、位置也一致，但元素尺寸不变。
+ * **加载态排除在外**（`:not()`）：`loading` 虽也置原生 disabled（吞点击），但**外观保持本型** —— 点击前后
+ * 只有「文字 → 环」这一处变化。不排除的话禁用档（2 个类）会压过 `.mh-button--loading`（1 个类），最显眼的
+ * 主操作会在点下去的一瞬间整块变成禁用灰（实测灰底 + 灰字 + 灰边）。 */
 .mh-button:disabled:not(.mh-button--loading),
 .mh-button.is-disabled:not(.mh-button--loading),
 .mh-button[aria-disabled='true']:not(.mh-button--loading) {
@@ -292,18 +277,13 @@
 
 /* ===== 加载（**本型外观 + 主色降透明 + 环**） =====
  *
- * 加载态不改色彩角色：`primary` 还是主色、`danger` 还是错误色、`secondary` 还是白底黑字 ——
- * 只是实底型的**主色底**按 `--ui-button-loading-mix` 与面板色显式合成一档更淡的同色。
- * 忙碌时的按钮该是「同一个按钮淡了一点点、在转圈」，而不是换一副面孔（整块变灰或换档色都太突兀）。
- *
- * **为什么是显式合成而不是 `opacity`**：`opacity` 压的是整块，连文案与加载环一起淡 ——
- * 忙碌时的文案恰恰要读得清；写成 `color-mix(主色 × mix, 面板色)` 只让**底**淡一档。
- * （也别用覆盖层：主色实底上再盖一层同色半透明层等于什么都没做 —— 那是条死路。）
- *
- * 其余五型（`secondary` / `dashed` / `text` / `link` / `icon`）的「主色」在描边或字上，
- * 底本来就是白的或透明的 —— 再降一档只会把边与字读淡，故它们加载时**外观完全不变**，只多一个环。
- * 环取 **`currentColor`**：一条规则自动跟上六型与 `danger`（实底型白环、浅底与图标型本型字色环、
- * 透明底型主色环），既不必逐型特判，也不额外引令牌。 */
+ * 加载态不改色彩角色（`primary` 还是主色、`danger` 还是错误色、`secondary` 还是白底黑字）—— 只是实底型的
+ * **主色底**按 `--ui-button-loading-mix` 与面板色显式合成一档更淡的同色：忙碌时的按钮该是「同一个按钮淡了
+ * 一点点、在转圈」，而不是换一副面孔。
+ * **为什么显式合成而不是 `opacity`**：`opacity` 压的是整块，连文案与加载环一起淡，而忙碌时的文案恰恰要读得
+ * 清；写成 `color-mix(主色 × mix, 面板色)` 只让**底**淡一档（也别用覆盖层：主色实底上再盖一层同色半透明
+ * 等于什么都没做）。其余五型的「主色」在描边或字上、底本就是白或透明 ⇒ 加载时**外观完全不变**，只多一个环。
+ * 环取 **`currentColor`**：一条规则自动跟上六型与 `danger`，不必逐型特判、也不额外引令牌。 */
 .mh-button--loading {
   cursor: not-allowed; /* 禁用档被排除了，`:disabled` 那条已不匹配它 */
 }
@@ -332,9 +312,8 @@
 }
 
 /* ===== 下拉箭头槽 =====
- * **只给槽位尺寸，不给字形**：字形由 `@manohub/icon` 的 `<Icon name="chevron-down">` 画，
- * 展开时的转向由操作层 `popup.css` 的 `.mh-popup-caret` 承担（本件不定义第二份 mask / 第二处转向）。
- * 故组件把两个类同时挂在图标上：`class="mh-button__caret mh-popup-caret"`。 */
+ * **只给槽位尺寸，不给字形**：字形由 `@manohub/icon` 的 `<Icon name="chevron-down">` 画，展开时的转向
+ * 由操作层 `popup.css` 的 `.mh-popup-caret` 承担（本件不定义第二份 mask / 第二处转向）。 */
 .mh-button__caret {
   flex: none;
   width: var(--ui-button-icon-size);
@@ -439,8 +418,7 @@
 .mh-button__menu {
   width: 130px;
   padding: var(--ui-space-1) 6px;
-  /* 圆角取容器档（原为硬编码 10px —— 与令牌里的容器档同义却写死，改版时不会跟随）；
-     投影取锚定浮层档（`--ui-shadow-popover`），不是居中浮层档。 */
+  /* 圆角取容器档（不写硬编码 px，改版时才会跟随）；投影取锚定浮层档，不是居中浮层档 */
   border-radius: var(--ui-radius-md);
   background: var(--ui-base-100);
   box-shadow: var(--ui-shadow-popover);

package/dist/styles/components/button.tokens.css

@@ -1,19 +1,10 @@
 /**
- * 单件令牌（只服务本件，故只随本包走，不进 `@manohub/theme`）。
+ * 单件令牌（只服务本件，故不进 `@manohub/theme`）。
  *
- * **本件有一批令牌是「跨分件消费」的**：`--ui-button-group-gap` 归组容器 `.mh-button__group`、
- * 组内分割线高度与菜单项圆角归 `.mh-button__menu`（popover 面板，与按钮**兄弟**、
- * 不在它的子树里）—— 自定义属性只向下继承，声明在 `.mh-button` 上这类分件取不到值
- * （声明在计算值阶段作废，且不报任何错）。
- *
- * 改前靠「把令牌同时声明在 4 个外层类上」的 workaround 兜（历史症状：组内间距变 0、
- * 组内分割线高度 0、连体切换与菜单项圆角 0）；锚到容器后，**容器是每个分件的祖先**，
- * 这类 workaround 整块撤掉 —— 这正是本文件从面文件里抽出来的直接原因。
- *
- * ## 抽出说明
- * 本文件从面文件里抽出：这些是**基础值**，锚在 `[data-manohub-ui]`（跨包唯一作用域锚，
- * 由入口层无条件写在应用容器上）—— 任何落在容器里的分件都取得到值，不再依赖
- * 「声明在某个组件根类上」这条脆弱假设。
+ * **本件有一批令牌是「跨分件消费」的**：`--ui-button-group-gap` 归组容器 `.mh-button__group`、组内分割线
+ * 高度与菜单项圆角归 `.mh-button__menu`（popover 面板，与按钮**兄弟**、不在它的子树里）—— 自定义属性只
+ * 向下继承，声明在 `.mh-button` 上这类分件取不到值（声明作废且不报错）。锚到容器后**容器是每个分件的
+ * 祖先**，「把令牌同时声明在 4 个外层类上」那类 workaround 整块撤掉 —— 这正是本文件抽出来的原因。
  * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里（拆开会让档位失效）。
  */
 [data-manohub-ui] {

package/dist/styles/components/capsule.css

@@ -1,30 +1,21 @@
 /**
  * Capsule —— 胶囊选择器（一组互斥选项，选中项白底胶囊浮在轨道上）。
  *
- * 出处：`@aihub/theme` 的 `playground/components/capsule.css` 与 `src/components/capsule.css`
- * （轨道 32 高 / 内距 2 / 项 28 高 / 项内距 14 / 字号 14 / 圆角全；选中 = 白底 + 主色字 + medium +
- *  1px 4px 主色投影；未选字 Te05、滑过转主色、禁用 Te07；轨道底 Au04）。
+ * 出处：规范（轨道 32 高 / 内距 2 / 项 28 高 / 项内距 14 / 字号 14 / 圆角全；选中 = 白底 + 主色字 +
+ * medium + `1px 4px` 主色投影；未选字 Te05、滑过转主色、禁用 Te07；轨道底 Au04）。
  *
- * **外形档**（`shape`）：规范只有「圆角全」的胶囊形态；`.mh-capsule--square` 是**本仓新增**的圆角矩形档
- * （与方角控件并排排版时用），圆角取**复选框档**令牌 `--ui-radius-sm`（比控件档更方，具体值随主题变）。
- * 两档只差圆角令牌一处，其余几何与颜色一律不变。
+ * **外形档**：规范只有「圆角全」；`.mh-capsule--square` 是本仓新增的圆角矩形档（与方角控件并排排版时用），
+ * 圆角取**复选框档**令牌 `--ui-radius-sm`（比控件档更方，值随主题变）。两档只差圆角令牌一处。
  *
  * **操作是原生的**：一组同名 radio —— 开关与项**平级相邻、开关在前**，开关由本族隐身但保持可聚焦
- * （Tab 进组、方向键换项、空格选中）。焦点环画在可见项上。
+ * （Tab 进组、方向键换项、空格选中），焦点环画在可见项上。
+ * 状态三源等价：原生 `input:checked` / `[data-state='active']` / 静态档 `.is-selected`。
+ * **与面板组合**：要「选中即切面板」就把它塞进 `Tabs` 的 `selector` 插槽 —— 面板显隐由 `Tabs` 按受控值
+ * 下发 `hidden`，两层零互指。（`Tabs` 是操作层骨架、不带面；本件是带自己轨道与选中胶囊的选择控件。）
  *
- * 状态三源等价：原生 `input:checked` / 组件下发 `[data-state='active']` / 静态档 `.is-selected`。
- *
- * **与面板组合**：要「选中即切面板」，把本件塞进 `Tabs` 的 `selector` 插槽即可 ——
- * 面板显隐由 `Tabs` 按受控值下发 `hidden`，本族不认识它、它也不认识本族（两层零互指）。
- *
- * **与 `Tabs` 的判据**：`Tabs` 是操作层的**骨架**（只给根、面板组与收起态，不带面），
- * 面可由本件或按钮族的分段形态担任；本件是**带自己轨道与选中胶囊的轻量选择控件**。
- *
- * **轨道按内容宽收缩，不被父级拉宽**（缺省档口径的第二半）—— `align-self: flex-start` 就是为这条而写：
- * 父级若是**列向弹性**（典型是 `Tabs` 的根 `.mh-tabs`），交叉轴缺省 `stretch` 会把唯一的子项拉成通栏，
- * 轨道底随之变成一条长胶囊（实测：内容 112px 的轨道被拉到 638px）；`TabBar` 同样被拉满，但它规范里
- * 第 1 条就是「不画轨线」，没有底色，肉眼看不出来。要**主动**撑满仍然走 `block` 档 —— 那条
- * `width: 100%` 是显式宽度，`align-self` 管不着它（撑满与否只由 `block` 决定）。
+ * **轨道按内容宽收缩，不被父级拉宽** —— `align-self: flex-start` 就是为这条而写：父级若是列向弹性
+ * （典型是 `.mh-tabs` 根），交叉轴缺省 `stretch` 会把唯一的子项拉成通栏，轨道底随之变成一条长胶囊
+ * （实测：内容 112px 被拉到 638px）。要**主动**撑满仍走 `block` 档（`width: 100%` 是显式宽度）。
  */
 .mh-capsule {
   display: inline-flex;
@@ -36,6 +27,8 @@
   padding: var(--ui-capsule-inset);
   border-radius: var(--ui-capsule-radius);
   background: var(--ui-capsule-track-bg);
+  /* 定位上下文：隐身 input 的包含块必须落在控件内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
 /* 隐身开关：视觉隐藏但保持可聚焦（1px 盒 + clip-path，同 checkbox / radio 配方） */

package/dist/styles/components/capsule.tokens.css

@@ -3,16 +3,11 @@
  *
  * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
  *
- * ## 抽出说明
- * 本文件从面文件里抽出（原先混写在 `capsule.css` 顶部）：这些是**基础值**，锚在
- * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
- * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
- * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
  *
- * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
- * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
- * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
- */
+ * 令牌锚 `[data-manohub-ui]`（容器是每个分件的祖先 ⇒ 落在容器里的分件都取得到值）。
+ * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里（搬走会让档位失效）；
+ * 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
+*/
 [data-manohub-ui] {
   /* 单件令牌（项高 28 + 内距 2×2 = 轨道 32，与规范实测一致） */
   --ui-capsule-height: 32px;

package/dist/styles/components/card.css

@@ -1,16 +1,11 @@
 /**
  * Card（卡片容器：底 / 弱描边 / 圆角 / 内距 / 悬浮与选中反馈）—— **卡片外观的唯一实现**。
  *
- * 依据：@aihub/theme 的 components/card.css（圆角 8 · 内距 20 · 弱描边）+ portal 技能市场卡片实测，见下方原注释。
+ * 出处：规范 `components/card.css`（圆角 8 · 内距 20 · 弱描边）+ portal 技能市场卡片实测，逐项落令牌：
+ * 圆角 8 / 内距 20（原型 p-5）/ 底 `base-100` / 弱描边 `base-300` / 悬浮主色描边 + 主色 12% 阴影。
+ * 卡片外观在本仓**只有这一处定义**：消费方（含 `ListView.CardItem`）不得自绘这四类属性。
  */
 
-/* ===== Card（卡片容器：底 / 弱描边 / 圆角 / 内距 / 悬浮与选中反馈）=====
-   几何来源：portal 技能市场卡片实测（apps/portal/src/views/skills/index.tsx 的 SkillCard），
-   逐项落令牌：圆角 8（原型 rounded-lg）、内距 20（原型 p-5）、
-   底 Ne12/base-100、弱描边 base-300（原型 border-border）、
-   悬浮主色描边 + 主色 12% 阴影（原型 hover:border-primary + hover:shadow-[0_4px_10px_…]）。
-   卡片外观在本仓**只有这一处定义**：消费方（含 ListView.CardItem）不得自绘这四类属性。 */
-
 .mh-card {
   /* 组件变量先铺一层，形态类只决定用哪几个（同 .mh-badge 手法） */
   --mh-card-bg: var(--ui-base-100);
@@ -29,23 +24,17 @@
 }
 
 /* ===== 内距归属（改这几条规则前务必先读）=====
- *
- * 1. **根件不出内距**：根件只出面（底 / 描边 / 圆角），也不出段间距 ——
- *    根件若也吃内距，就会与段的内距叠成两层留白（故面无「根件让出内距」的修饰类）。
- * 2. **段的纵向只吃上边**（`padding-block-start`）：一段只负责**与自己上方之间的距离**，
- *    下一段的上内距就是「段间距」。于是头部 + body、body + footer 相邻时**不会**叠成两份
- *    （各吃四边就会变成 20 + 20 = 40，这正是要避免的）。
- * 3. **卡片下沿由最后一段补**（下方那条 `:last-child` 规则）：段不吃下边，底边得有人兜。
- *    段的位置由组件保证（裸内容自动成段、封面不吃内距也不是段），故 `:last-child` 必定落在段上。
+ * 1. **根件不出内距**：根件只出面（底 / 描边 / 圆角），也不出段间距 —— 否则与段的内距叠成两层留白
+ *    （故面无「根件让出内距」的修饰类）。
+ * 2. **段的纵向只吃上边**（`padding-block-start`）：一段只负责**与自己上方之间的距离**，下一段的上内距就是
+ *    「段间距」。于是头部 + body、body + footer 相邻时**不会**叠成两份（各吃四边就成了 20 + 20 = 40）。
+ * 3. **卡片下沿由最后一段补**（下方那条 `:last-child` 规则）：段不吃下边，底边得有人兜；段的位置由组件保证
+ *    （裸内容自动成段、封面不吃内距也不是段），故 `:last-child` 必定落在段上。
  * 4. 横向每段恒吃 `--mh-card-padding`（`padding-inline`）。
- *
- * ⚠️ 以上 2 / 3 / 4 是**不给 `padding` 时的缺省口径**。分件一旦显式传了 `padding`，
- * 组件就落行内样式（`{ y, x }` 两维都给时是 `padding: y x` 简写），**整段四边由消费方定价** ——
- * 行内样式盖过这里的类规则，`:last-child` 那条下沿兜底也随之失效（这是有意的：消费方显式给了就说得清）。
- * 要保留兜底就不要给那一段传 `padding`。
- *
- * 直接写的内容（没包 `Card.Body` 的裸子节点）由组件自动补一层 Body，所以
- * 「不给分件」（`<Card>正文</Card>`）与显式分段得到的是同一套几何。 */
+ * ⚠️ 2 / 3 / 4 是**不给 `padding` 时的缺省口径**：分件一旦显式传了 `padding`，组件就落行内样式
+ * （`{ y, x }` 两维都给时是 `padding: y x` 简写），**整段四边由消费方定价** —— 行内样式盖过这里的类规则，
+ * `:last-child` 的下沿兜底也随之失效（有意：显式给了就说得清）。要保留兜底就不要给那一段传 `padding`。
+ * 直接写的内容（没包 `Card.Body` 的裸子节点）由组件自动补一层 Body，故「不给分件」与显式分段得到同一套几何。 */
 
 /* 头部：**分件 `Card.Header` 与 `Card` 上的内建头共用这一类**（四件：图标 / 标题 / 副标题 + 右端 extra）。
    行 + 两端对齐：左「左侧区域」、右「extra」；四个位一个都不给时退化为纯自排容器。 */