@manohub/ui 1.0.5 → 1.0.6

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/button.css

@@ -39,6 +39,8 @@
   transition-property: background-color, border-color, color, box-shadow;
   transition-duration: 0.15s;
   transition-timing-function: ease;
+  /* 定位上下文：隐身 file input 的包含块必须落在按钮内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
 /* 危险色修饰：换槽位即可，六型与各自 hover / active 一并跟随 */

package/dist/styles/components/capsule.css

@@ -27,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/checkbox.css

@@ -22,6 +22,8 @@
   color: var(--ui-base-content);
   cursor: pointer;
   user-select: none;
+  /* 定位上下文：隐身 input 的包含块必须落在开关内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
 .mh-checkbox__input {

package/dist/styles/components/form.css

@@ -19,10 +19,9 @@
   display: flex;
   flex-direction: column;
   gap: var(--ui-space-2);
-  /* 多列公式用的三个变量（**都在本件**，不进 theme 令牌文件）：
-     - `--mh-form-columns`：数字档的**列数上限**（档位类只覆盖它，不复制几何）；
-     - `--mh-form-column-min`：一列的**最小宽度**（`columnMinWidth` 行内覆盖，缺省取令牌 320）；
-     - `--mh-form-gap`：行距 —— 公式里必须用**与实体 gap 同一个值**算轨道下限。 */
+  /* 多列公式用的三个变量（**都在本件**，不进 theme 令牌文件）：`--mh-form-columns`（数字档的**列数上限**，档位类
+     只覆盖它、不复制几何）、`--mh-form-column-min`（一列**最小宽度**，`columnMinWidth` 行内可覆盖，缺省令牌 320）、
+     `--mh-form-gap`（行距 —— 公式里必须用**与实体 gap 同一个值**算轨道下限）。 */
   --mh-form-columns: 2;
   --mh-form-column-min: var(--ui-form-column-min);
   --mh-form-gap: var(--ui-space-2);
@@ -72,10 +71,9 @@
 }
 
 /* ===== 动态列数（`columns="auto"`）=====
- * `auto-fill` + `minmax(最小列宽, 1fr)`：列数随容器宽度变。实测（最小宽 320 / 行距 8）：
- * 640px → 1 列、660px → 2 列、1000px → 3 列、1320px → 4 列。
- * 为什么是 `auto-fill` 而不是 `auto-fit`：两者只差在「子项少于轨道数」时 —— `auto-fit` 会**折叠空轨道**，
- * 宽容器里 2 个字段被拉成两条长条（实测 1400px 下每项 696px）；`auto-fill` 保留轨道，列宽稳定在区间内
+ * `auto-fill` + `minmax(最小列宽, 1fr)`：列数随容器宽度变（实测 最小宽 320 / 行距 8：640 → 1 列、660 → 2 列、
+ * 1000 → 3 列、1320 → 4 列）。为什么不是 `auto-fit`：两者只差在「子项少于轨道数」时 —— `auto-fit` 会**折叠空
+ * 轨道**，宽容器里 2 个字段被拉成两条长条（实测 1400px 下每项 696px）；`auto-fill` 保留轨道、列宽稳定在区间内
  * （1400px 下每项 344px）。表单要的是**列宽稳定**，不是「把剩余宽度填满」。 */
 
 .mh-form--columns-auto {
@@ -130,19 +128,18 @@
 }
 
 /* ===== label 提示位（`Form.Item` 的 `tip`）=====
- * 图标取 `@manohub/icon` 的 `help`，气泡复用 `Tooltip` 的面（`.mh-tooltip`）与操作层 `popup.css` 的
- * hover 档；本件只声明**提示位在 label 行里怎么排**。宿主位两件事必做：① `flex: 0 0 auto`（label
- * 文本过长走省略号时不挤压图标）；② 行高归 1（图标比一行文字矮，留在 label 行盒里会按基线排、
- * 中线与文字错开）。气泡是固定定位（操作层 hover 档），不参与本行排布。 */
+ * 图标取 `help`，气泡复用 `Tooltip` 的面（`.mh-tooltip`）与操作层 `popup.css` 的 hover 档；本件只声明
+ * **提示位在 label 行里怎么排**。宿主位两件事必做：① `flex: 0 0 auto`（label 文本过长走省略号时不挤压图标）；
+ * ② 行高归 1（图标比一行文字矮，留在 label 行盒里会按基线排、中线与文字错开）。气泡是固定定位，不参与本行排布。 */
 
 .mh-form-item__tip {
   display: inline-flex;
   align-items: center;
   flex: 0 0 auto;
   /* 行盒归零（`font-size: 0` + `line-height: 0`）：`Tooltip` 宿主里还夹着一层 **inline 的锚点 span**
-     （`.mh-popup-anchor`），它会给内含的 `inline-flex` 触发器生成行盒 —— 宿主因此比图标高出一个
-     descender 间隙（实测 16px 图标 ⇒ 宿主 17px），在 label 行里居中后图标中线比文字高 0.5px。
-     归零后宿主高度 === 图标高度。图标 svg 自带尺寸，不读字号。 */
+     （`.mh-popup-anchor`），它会给内含的 `inline-flex` 触发器生成行盒 —— 宿主因此比图标高出一个 descender 间隙
+     （实测 16px 图标 ⇒ 宿主 17px），在 label 行里居中后图标中线比文字高 0.5px。归零后宿主高度 === 图标高度
+     （图标 svg 自带尺寸，不读字号）。 */
   font-size: 0;
   line-height: 0;
 }
@@ -267,12 +264,11 @@
 }
 
 /* ===== 行内垂直对齐档 =====
- * 默认（基类）`center`：label 与控件**中线**对齐。需要顶对齐的是**多行与整块内容**：label 该与首行
- * 文字齐，而不是落到整块高度的中间。
- * 自动判定（按控件形态，消费方零配置）：认**原生元素** `textarea`，不认别件的类名（面之间不互指，
- * 是本仓的既有裁决；认元素还顺带覆盖了代码编辑区这类自绘多行件）。文本域的壳带 8px 上内距 + 1px 边框
- * （控件自身内距被壳归零，见 input.css），label 补上同样偏移才与**首行文字**同线 —— 不补偏高 9px（实测）。
- * 整条包 `:where()`：把特异性压回 0-1-0，显式修饰类（0-2-0）才稳定压过它，不必靠「谁写在后面」。 */
+ * 默认（基类）`center`：label 与控件**中线**对齐；需要顶对齐的是**多行与整块内容**（label 该与首行文字齐，而不是
+ * 落到整块高度的中间）。自动判定按控件形态、消费方零配置：认**原生元素** `textarea`、不认别件的类名（面之间不互指
+ * 是本仓的既有裁决；认元素还顺带覆盖了代码编辑区这类自绘多行件）。文本域的壳带 8px 上内距 + 1px 边框（控件自身
+ * 内距被壳归零，见 input.css），label 补上同样偏移才与**首行文字**同线 —— 不补偏高 9px（实测）。整条包
+ * `:where()`：特异性压回 0-1-0，显式修饰类（0-2-0）才稳定压过它，不必靠「谁写在后面」。 */
 .mh-form-item:where(:has(.mh-form-item__control textarea)) {
   align-items: start;
 }
@@ -297,9 +293,9 @@
 }
 
 /* ===== 纵向排布（`layout="vertical"`：label 在控件上方） =====
- * 窄容器（抽屉 / 移动端）与「字段名很长」的场景用纵向 —— 横向时 label 列宽会把控件压得很窄。
- * 单列三行：label / 控件 / 提示依次往下。选择器带 `>` 且写成 0-3-0：纵向档必须压过上面的顶对齐档
- * 与显式档 —— 纵向时 label 本来就在上方，那 9px 上内距只会多出一截空隙。 */
+ * 窄容器（抽屉 / 移动端）与「字段名很长」的场景用纵向 —— 横向时 label 列宽会把控件压得很窄。单列三行：label /
+ * 控件 / 提示依次往下。选择器带 `>` 且写成 0-3-0：纵向档必须压过上面的顶对齐档与显式档 —— 纵向时 label 本来就在
+ * 上方，那 9px 上内距只会多出一截空隙。 */
 .mh-form--vertical .mh-form-item {
   grid-template-columns: minmax(0, 1fr);
 }
@@ -351,10 +347,9 @@
   color: var(--ui-base-content);
 }
 
-/* 标题左端的品牌色竖标（主色胶囊，几何见 `form.tokens.css` 的两枚令牌 —— 库内唯一来源）。
- * **只在有标题文本时出现**：这一行也会在「只给 `extra`」时渲染（筛选条那种），那时凭空多一条竖标
-   就成了坏的排版 —— 用 `:has()` 守住真正有标题的那一种。
- * `flex: none`：标题换行时竖标不许被挤扁；竖标与文本之间的间距由标题行既有的 `gap` 给。 */
+/* 标题左端的品牌色竖标（主色胶囊，几何见 `form.tokens.css` 的两枚令牌 —— 库内唯一来源）。**只在有标题文本时出现**：
+ * 这一行也会在「只给 `extra`」时渲染（筛选条那种），那时凭空多一条竖标就成了坏的排版 —— 用 `:has()` 守住真正有
+ * 标题的那一种。`flex: none`：标题换行时竖标不许被挤扁；竖标与文本之间的间距由标题行既有的 `gap` 给。 */
 .mh-form__title:has(> .mh-form__title-text)::before {
   content: '';
   flex: none;

package/dist/styles/components/input.css

@@ -1,18 +1,13 @@
 /**
  * Input / Textarea —— 输入框族（三档尺寸 / 单行 / 多行 / 展示态 / 前后缀 / 清除·眼睛 / 前置后置标签）。
  *
- * 表壳是 flex 行（`__wrap`）：前置 → 控件 → 清除 → 眼睛 → 后缀 → 计数依次排列，间隔统一吃
- * `--ui-input-affix-gap`；壳内控件 `flex: 1 1 auto + min-width: 0`，故附加位出现/消失时输入区自动
- * 伸缩，**不需要为每种附加组合各写一条让位规则**（绝对定位 + padding 让位的旧法必然要两两枚举）。
- *
+ * 表壳是 flex 行（`__wrap`）：前置 → 控件 → 清除 → 眼睛 → 后缀 → 计数依次排列，间隔统一吃 `--ui-input-affix-gap`；
+ * 壳内控件 `flex: 1 1 auto + min-width: 0`，故附加位出现 / 消失时输入区自动伸缩，**不需要为每种附加组合各写一条让位
+ * 规则**（绝对定位 + padding 让位的旧法必然要两两枚举）。
  * 高度三档全部吃主题令牌（`--ui-control-height-sm|-md|-lg`），档位只覆盖令牌、几何规则只有一份。
- *
- * 状态三源等价：原生 `:hover` / `:focus` / `:disabled` / `[aria-invalid]` ⟷ 组件下发 `data-state`
- * ⟷ 静态档 `.is-*`，同名面共用一份声明。
- *
- * 有意差异（对齐设计源时定下的）：控件宽度由表单列宽驱动（`width: 100%`，不设 300 上限）；
- * 常规图标取 14（`--ui-input-affix-size = var(--ui-font-icon)`），非设计注记的 16。
- * 禁写：本件不消费 farris 类；跨件令牌一律进 `theme/`。
+ * 状态三源等价：`:hover` / `:focus` / `:disabled` / `[aria-invalid]` ⟷ `data-state` ⟷ 静态档 `.is-*`，同一份声明。
+ * 有意差异（对齐设计源时定下的）：控件宽度由表单列宽驱动（`width: 100%`，不设 300 上限）；常规图标取 14
+ * （`--ui-input-affix-size = var(--ui-font-icon)`），非设计注记的 16。禁写：本件不消费 farris 类；跨件令牌一律进 `theme/`。
  */
 
 /* 控件本体：**裸用（不带壳）时由控件自己画框** —— Select 的搜索行、静态页写法都靠这一条。
@@ -82,17 +77,14 @@
 }
 
 /* ===== 触发器形态（`as="button"`：控件是 `<button>`，框与状态仍归表壳） =====
- * 复用面（框 / 内距 / 附加位 / 三态）不需要为按钮重写一行（那些规则挂在 `.mh-input` 或表壳上，
- * 与元素类型无关），这里只补 **UA 样式会漏进来的四项**（实测 Chrome 的 html.css 给 `<button>`
- * 铺了 `align-items: flex-start; text-align: center; appearance: auto; font: 400 13.3333px Arial`）：
- * `align-items: center`（消费方开 flex 行时拦住 UA 的 flex-start）、`text-align: inherit`
- * （UA 的 center 会继承给值文本）、`font-weight` / `line-height: inherit`（UA 的 `font` 简写会把这两项
- * 从继承链上摘下来）、`appearance: none`（防仍画原生按钮皮肤的引擎）。
- *
- * 外加一条**单行契约**（nowrap + overflow hidden + ellipsis）：触发器与输入框同为单行控件，少了它，
- * 消费方把值当**裸文本**子节点渲染时长值会在定高框里折成两行（第二行溢出到框外、右端图标被挤走）。
- * 截断口径与 `.mh-input__placeholder` / `.mh-select__value` 同源，这里补的是控件本身那一层。
- *
+ * 复用面（框 / 内距 / 附加位 / 三态）不需要为按钮重写一行（那些规则挂在 `.mh-input` 或表壳上，与元素类型无关），这里
+ * 只补 **UA 样式会漏进来的四项**（实测 Chrome 的 html.css 给 `<button>` 铺了 `align-items: flex-start; text-align:
+ * center; appearance: auto; font: 400 13.3333px Arial`）：`align-items: center`（拦住 UA 的 flex-start）、
+ * `text-align: inherit`（UA 的 center 会继承给值文本）、`font-weight` / `line-height: inherit`（UA 的 `font` 简写会
+ * 把这两项从继承链上摘下来）、`appearance: none`。
+ * 外加一条**单行契约**（nowrap + overflow hidden + ellipsis）：触发器与输入框同为单行控件，少了它，消费方把值当
+ * **裸文本**子节点渲染时长值会在定高框里折成两行（第二行溢出到框外、右端图标被挤走）；截断口径与
+ * `.mh-input__placeholder` / `.mh-select__value` 同源。
  * 禁写：本块不碰框 / 色 / 尺寸 / 内距 —— 那些归 `.mh-input` 与表壳，重复声明就是又开一份会漂的规格。 */
 .mh-input--trigger {
   appearance: none;
@@ -109,11 +101,10 @@
 }
 
 /* ===== 触发器形态 · 占位文案 =====
- * `<button>` **没有 `::placeholder` 伪元素**，故触发器形态的占位由组件渲染一个 span 承载
- * （判据见 `components/input/index.tsx` 的 `showPlaceholder`）。
- * `display: block` 是必要的：span 默认 inline 而 `overflow` 对行内盒不生效（长占位会撑破控件）；
- * `flex: 1` 是给**父级是 flex** 的复合件用的 —— 实测「占位 + 右侧箭头」在 flex 父级下不给 `flex: 1`
- * 时占位只有内容宽（48px），给了才撑满到箭头前（207 / 可用 220）。 */
+ * `<button>` **没有 `::placeholder` 伪元素**，故触发器形态的占位由组件渲染一个 span 承载（判据见组件里的
+ * `showPlaceholder`）。`display: block` 是必要的：span 默认 inline 而 `overflow` 对行内盒不生效（长占位会撑破
+ * 控件）；`flex: 1` 是给**父级是 flex** 的复合件用的 —— 实测「占位 + 右侧箭头」不给它时占位只有内容宽（48px），
+ * 给了才撑满到箭头前（207 / 可用 220）。 */
 .mh-input__placeholder {
   display: block;
   flex: 1;
@@ -125,14 +116,13 @@
 }
 
 /* ===== 触发器形态 · 整箱热区（命中测试重定向，纯 CSS） =====
- * 目的：整件（值 / 标签 + 右侧图标 + 左右内距）都等同于点那个原生触发按钮 —— 触发器形态的附加位是
- * 控件的**兄弟**而非子孙，点它们本来永远到不了按钮。
- * 做法：给控件挂一张透明绝对定位覆盖层；伪元素**不产生独立事件目标**（命中它即命中宿主），
- * `inset: 0` 的包含块是最近的定位祖先 = **表壳** ⇒ 整个箱子的像素点都归控件，且不需要 JS 代理
- * （代理会丢掉 `:active` 与按下聚焦的原生时序）。
- * 层叠：覆盖层是定位元素、盖住静态兄弟（正是所需）；**清除位必须自己升到它之上**
- * （`.mh-input__clear` 带 `position: relative`，spec 有断言锁住 —— 漏了点清除会变成开面板）。
- * 必须写成「表壳 > 控件」：裸写时无壳场景的包含块会落到页面级定位祖先上，那块透明层会铺满一大片。 */
+ * 目的：整件（值 / 标签 + 右侧图标 + 左右内距）都等同于点那个原生触发按钮 —— 触发器形态的附加位是控件的**兄弟**而非
+ * 子孙，点它们本来永远到不了按钮。
+ * 做法：给控件挂一张透明绝对定位覆盖层；伪元素**不产生独立事件目标**（命中它即命中宿主），`inset: 0` 的包含块是最近
+ * 的定位祖先 = **表壳** ⇒ 整个箱子的像素点都归控件，且不需要 JS 代理（代理会丢掉 `:active` 与按下聚焦的原生时序）。
+ * 层叠：覆盖层是定位元素、盖住静态兄弟（正是所需）；**清除位必须自己升到它之上**（`.mh-input__clear` 带
+ * `position: relative`，spec 有断言锁住 —— 漏了点清除会变成开面板）。必须写成「表壳 > 控件」：裸写时无壳场景的包含块
+ * 会落到页面级定位祖先上，那块透明层会铺满一大片。 */
 .mh-input__wrap > .mh-input--trigger::after {
   content: '';
   position: absolute;
@@ -140,11 +130,10 @@
 }
 
 /* ===== 无边框档（`bordered={false}`：框与底全退，**任何状态都不再出现**） =====
- * 本档的效果**只有一种**：无框（悬停不亮底、聚焦不显框也不留环）—— 「常态无框、聚焦才显框」是
- * **另一档** `bordered="focus"`，不要把两种效果叠在同一档上。
- * 配 `readonly` 即**只读值档**：几何与可编辑输入框完全一致、仍可聚焦可选中复制（只读 ≠ 禁用），
- * 但「可编辑」的线索一条都没有 —— 摘要 / 详情里值回显的推荐写法。
- * 中和句与通用状态规则同为 0-2-0，靠写在它们之后取胜。 */
+ * 本档的效果**只有一种**：无框（悬停不亮底、聚焦不显框也不留环）——「常态无框、聚焦才显框」是**另一档**
+ * `bordered="focus"`，别把两种效果叠在同一档。配 `readonly` 即**只读值档**：几何与可编辑输入框完全一致、仍可聚焦
+ * 可选中复制（只读 ≠ 禁用），但「可编辑」的线索一条都没有 —— 摘要 / 详情里值回显的推荐写法；中和句与通用状态
+ * 规则同为 0-2-0，靠写在它们之后取胜。 */
 .mh-input--borderless {
   border-color: transparent;
   background: transparent;
@@ -160,9 +149,8 @@
 }
 
 /* ===== 聚焦显框档（`bordered="focus"`：行内编辑那档）=====
- * 常态无框无底；**悬停与聚焦复用有框档那两条**（框转 hover 线色、聚焦再加主色弱底环）——
- * 本档不另写任何状态描写，「聚焦 = 有框档的样子」这句话在面上只有一份。
- * 那两条是 0-2-0、本档常态 0-1-0 ⇒ 悬停 / 聚焦必定压过常态，与顺序无关（裸控件这一层）。 */
+ * 常态无框无底；**悬停与聚焦复用有框档那两条**（框转 hover 线色、聚焦再加主色弱底环）—— 本档不另写任何状态描写，
+ * 「聚焦 = 有框档的样子」这句话在面上只有一份。那两条是 0-2-0、本档常态 0-1-0 ⇒ 悬停 / 聚焦必定压过常态，与顺序无关。 */
 .mh-input--border-on-focus {
   border-color: transparent;
   background: transparent;
@@ -211,12 +199,10 @@
 }
 
 /* ===== 壳（附加位的排布容器，**整件的框主**） =====
- * 框画在壳上、不画在控件上：壳是 flex 行，附加位都在控件之外，框挂在控件上时附加位会落到框外
- * （实测带眼睛的密码框：壳 220px，带框的控件只到 196px，眼睛飘在框外）。
- * **裸 `.mh-input`（不带壳）仍由控件自己画框**（Select 的搜索行就靠它）。
- * **宽度口径归壳**（`--ui-control-width` / `--ui-control-min-width` 都在主题层）：壳就是消费方看见的
- * 那个控件箱，定宽与收缩下限都设在这里；控件本体仍 `width: 100%`（把令牌也设到本体会让它在壳的
- * 内距之外多出 24px）。 */
+ * 框画在壳上、不画在控件上：壳是 flex 行、附加位都在控件之外，框挂在控件上时附加位会落到框外（实测带眼睛的
+ * 密码框：壳 220px，带框的控件只到 196px，眼睛飘在框外）。**裸 `.mh-input`（不带壳）仍由控件自己画框**
+ * （`Select` 的搜索行靠它）。**宽度口径归壳**（两枚 `--ui-control-*` 都在主题层）：壳就是消费方看见的那个控件箱
+ * （定宽与收缩下限都设在这里），控件本体仍 `width: 100%`（把令牌也设到本体会让它在壳的内距之外多出 24px）。 */
 .mh-input__wrap {
   /* 左右内距走**内部变量**再吃令牌：壳是框与内距的主，而档位类挂在控件上（壳是它的父），
      档位规则要能改到壳的内距 —— 见下面两条 `:has()`。写成 `--mh-*` 是刻意的（内部中转），
@@ -356,13 +342,12 @@
 }
 
 /* ===== 清除（有内容才由组件渲染；圆形 + close 字形）=====
- * **默认隐形，滑过表壳或聚焦时才显形**：常显会在每个有内容的输入框右端永远挂一颗深色圆点，
- * 密集场景（表格内编辑、筛选条、多选触发器）里那一列圆点比字段本身还抢眼，也与「清除是低频动作」
- * 的层级不符。
- * 为什么用 `opacity` 而不是 `display` / `visibility`：① 它仍在流中**占位**（显隐时输入区宽度不变，
- * 换 `display` 会让文字在鼠标移入的一瞬间横跳）；② 它仍是可命中的**定位元素** —— 触发器形态的整箱
- * 热区靠 `position: relative` + DOM 顺序压在覆盖层之上，换 `visibility: hidden` 会连命中一起关掉。
- * `:focus-within` 是触屏与键盘的兜底（键盘另有 `Delete` 路径，见组件）；禁用档不显形。 */
+ * **默认隐形，滑过表壳或聚焦时才显形**：常显会在每个有内容的输入框右端永远挂一颗深色圆点，密集场景（表格内编辑、
+ * 筛选条、多选触发器）里那一列圆点比字段本身还抢眼，也与「清除是低频动作」的层级不符。为什么用 `opacity` 而不是
+ * `display` / `visibility`：① 它仍在流中**占位**（显隐时输入区宽度不变，换 `display` 会让文字在鼠标移入的一瞬间
+ * 横跳）；② 它仍是可命中的**定位元素** —— 触发器形态的整箱热区靠 `position: relative` + DOM 顺序压在覆盖层之上，
+ * 换 `visibility: hidden` 会连命中一起关掉。`:focus-within` 是触屏与键盘的兜底（键盘另有 `Delete` 路径）；禁用档
+ * 不显形。 */
 .mh-input__clear {
   flex: none;
   display: inline-flex;
@@ -447,21 +432,19 @@
 }
 
 /* ===== 数字输入（NumberInput；与 Input 同族同面） =====
- * 表壳 / 内距 / 状态协议全部复用上面几节 —— 本件只多两样：控件上的 `.mh-input--number` 与右端的
- * 一对步进按钮，故**没有**独立的面文件、也不进 `styles/index.css` 的登记清单。
- * 类名**与面文件同根**（`mh-input*`），与 `Textarea` 的 `.mh-input--textarea` 一致 ——
- * 另开 `mh-number-*` 会被 `contract-class-surface.spec.ts` 的「与面文件名同根」判据拦下。
- * `.mh-input--number` 只声明 `font-variant-numeric`：数值等宽，编辑时数字不因字形宽度变化而左右跳
- * （比例数字下 `1111` 比 `0000` 窄一截）；它**不承载几何** —— 框与内距归壳与控件。 */
+ * 表壳 / 内距 / 状态协议全部复用上面几节 —— 本件只多两样：控件上的 `.mh-input--number` 与右端一对步进按钮，故
+ * **没有**独立的面文件、也不进 `styles/index.css` 的登记清单。类名**与面文件同根**（`mh-input*`，与 `Textarea` 的
+ * `.mh-input--textarea` 一致）—— 另开 `mh-number-*` 会被「与面文件名同根」的用例拦下。`.mh-input--number` 只声明
+ * `font-variant-numeric`（数值等宽，编辑时数字不因字形宽度变化而左右跳：比例数字下 `1111` 比 `0000` 窄一截）；
+ * 它**不承载几何** —— 框与内距归壳与控件。 */
 .mh-input--number {
   font-variant-numeric: tabular-nums;
 }
 
-/* 步进位：右端的一对上下箭头（列排、整条居中）。
- * 取值（两条约束一起解出来的）：md 16 / 压 4（32 − 4 = 28 ≤ 30）、lg 16 / 压 0（32 ≤ 38）、
- * sm 13 / 压 4（26 − 4 = 22 ≤ 22；13 是「放得下 且 压不过字形」的最大值 —— 14 的两条约束互相打架）。
- * 尺寸声明落在**步进位自己**上（基准），两档改写靠表壳的 `:has()` 选到它 —— 档位类挂在控件上，
- * 而箭头是控件的**兄弟**：自定义属性只向下继承，声明在控件上箭头取不到值（同 `input.tokens.css` 的坑）。 */
+/* 步进位：右端的一对上下箭头（列排、整条居中）。取值（两条约束一起解出来的）：md 16 / 压 4（32 − 4 = 28 ≤ 30）、
+ * lg 16 / 压 0（32 ≤ 38）、sm 13 / 压 4（26 − 4 = 22 ≤ 22；13 是「放得下且压不过字形」的最大值 —— 14 的两条约束
+ * 互相打架）。尺寸声明落在**步进位自己**上（基准），两档改写靠表壳的 `:has()` 选到它 —— 档位类挂在控件上、而箭头是
+ * 控件的**兄弟**：自定义属性只向下继承，声明在控件上箭头取不到值（同 `input.tokens.css` 的坑）。 */
 .mh-input__step {
   /* md 基准：箭头盒取**常规图标档 16**（一对 32 比内容高 30 多 2，故两枚之间压 4 → 一对 28 落进 30） */
   --mh-input-step-icon: 16px;
@@ -471,10 +454,9 @@
   flex-direction: column;
   align-self: stretch;
   justify-content: center;
-  /* **默认隐形且不可点**：步进位是「聚焦后调值」的辅助位，常显会让每个数字框右端都挂着一对箭头。
-     用 `opacity` 而非 `display`：① 仍在流中**占位**（否则聚焦的一瞬间数字横向跳一格）；
-     ② `pointer-events: none` 让隐形时的热区一并失效，避免「点了看不见的箭头、值莫名其妙变了」。
-     读屏仍能读到这两个按钮（不丢可达性）。 */
+  /* **默认隐形且不可点**：步进位是「聚焦后调值」的辅助位，常显会让每个数字框右端都挂着一对箭头。用 `opacity` 而非
+     `display`：① 仍在流中**占位**（否则聚焦的一瞬间数字横向跳一格）；② `pointer-events: none` 让隐形时的热区一并
+     失效，避免「点了看不见的箭头、值莫名其妙变了」。读屏仍能读到这两个按钮。 */
   opacity: 0;
   pointer-events: none;
   transition-property: opacity;

package/dist/styles/components/notice.css

@@ -25,6 +25,8 @@
   box-shadow: var(--ui-notice-shadow);
   font-size: var(--ui-notice-font);
   line-height: var(--ui-line-body);
+  /* 定位上下文：隐身说明文本的包含块必须落在控件内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
 .mh-notice__body {

package/dist/styles/components/page.css

@@ -54,11 +54,11 @@
   height: 26px;
 }
 
-/* 页头右侧自由位（Header 唯一可自定义位，对应 `extra` 属性 / 插槽）：搜索框 / 按钮 / 下拉等水平排列。
-   `align-self: stretch` 是关键的一条：父级 `__header-inner` 是 `align-items: flex-end`（右侧位与文本块
-   **底边对齐**的既有口径），而 flex-end **只定位、不拉伸** —— 少了这条，本盒高度就等于内容高度
-   （内容比标题行矮时会短一截），自己画背景 / 分隔线就会露白边。拉满后盒高 = 内容行高，内部仍垂直居中。
-   注意这里只到「内容行」的上下边：页头条上下的 14 / 13px 留白是 `.mh-page__header` 的 padding。 */
+/* 页头右侧自由位（Header 唯一可自定义位，对应 `extra`）：搜索框 / 按钮 / 下拉等水平排列。`align-self: stretch`
+   是关键的一条：父级 `__header-inner` 是 `align-items: flex-end`（右侧位与文本块**底边对齐**的既有口径），而
+   flex-end **只定位、不拉伸** —— 少了这条，本盒高度就等于内容高度（比标题行矮时短一截），自己画背景 / 分隔线会露
+   白边。拉满后盒高 = 内容行高、内部仍垂直居中；注意这里只到「内容行」的上下边：页头条上下的 14 / 13px 留白是
+   `.mh-page__header` 的 padding。 */
 .mh-page__header-extra {
   flex-shrink: 0;
   align-self: stretch;
@@ -75,13 +75,11 @@
   color: var(--ui-base-content);
 }
 
-/* 页头副标题（Header 的 subTitle）：标题下一行的次要说明，取 caption 档字号与次要色。
-   间距只用 margin-top 4：页头条的上下留白由 .mh-page__header 的 padding 提供，
-   这里只负责标题行与副标题行之间的距离 —— 有副标题时条目高度自然变高（56 → 80），
-   不再另调 padding（避免「有/无副标题」两套页头规格）。
-   文本块与右侧位的**底边对齐**仍是 .mh-page__header-inner 的既有口径（flex-end），
-   只不过右位自身被拉伸占满内容行（见 .mh-page__header-extra 的 align-self: stretch），
-   所以有副标题时它跟着变高、内容在盒内垂直居中，不在本项里改。 */
+/* 页头副标题（`subTitle`）：标题下一行的次要说明，取 caption 档字号与次要色。间距只用 `margin-top: 4` —— 页头条
+   的上下留白由 `.mh-page__header` 的 padding 提供，这里只负责标题行与副标题行的距离，有副标题时条目高度自然变高
+   （56 → 80），不再另调 padding（避免「有 / 无副标题」两套页头规格）。文本块与右侧位的**底边对齐**仍归
+   `__header-inner` 的 flex-end，右位自身被拉伸占满内容行（见 `__header-extra` 的 `align-self: stretch`），故有
+   副标题时它跟着变高、内容在盒内垂直居中，不在本项里改。 */
 .mh-page__header-subtitle {
   margin-top: var(--ui-space-1);
   font-size: var(--ui-font-caption);
@@ -195,10 +193,9 @@
   width: 16px;
 }
 
-/* 展开按钮：**占满整条把手**（全高全宽）—— 收起态里它是整块侧栏唯一看得见的东西，
-   所以它自己就是那条「带边框的竖条」，不是里面再嵌一个小按钮。
-   盒模型走 border-box：1px 描边要算在 16px 里，否则右侧那条边会被把手的 overflow:hidden 裁掉。
-   与收起按钮共用同一套描边 / 底 / 圆角（尺寸不同是有意的：收起按钮钉在分隔线上，只能是小药丸）。 */
+/* 展开按钮：**占满整条把手**（全高全宽）—— 收起态里它是整块侧栏唯一看得见的东西，所以它自己就是那条「带边框的竖条」，
+   不是里面再嵌一个小按钮。盒模型走 border-box：1px 描边要算在 16px 里，否则右侧那条边会被把手的 `overflow: hidden`
+   裁掉。与收起按钮共用同一套描边 / 底 / 圆角（尺寸不同是有意的：收起按钮钉在分隔线上，只能是小药丸）。 */
 .mh-page__split-rail-btn {
   box-sizing: border-box;
   display: flex;
@@ -238,11 +235,10 @@
 }
 
 /* --- 宽度过渡期间**内容不跟着重排**（收起 / 展开都算）---
-   内容按 `--mh-page-split-frozen`（该侧展开时的宽度，组件在收起那一刻实测后下发）定宽排布，
-   多出来的部分由本盒子的 overflow:hidden 裁掉 —— 观感还是「滑出去 / 滑进来」，
-   但栏内的滚动容器（Panel.Body、表格包裹层这些 overflow:auto 的件）不会因为宽度被压缩而现出滚动条。
-   取不到值时退回 100%：那种情形是「没给 width 的自适应侧栏」，容器宽度本身不可插值（auto 不能动画），
-   收起/展开是瞬间跳变，也就无所谓过渡期间的重排。 */
+   内容按 `--mh-page-split-frozen`（该侧展开时的宽度，组件在收起那一刻实测后下发）定宽排布，多出来的部分由本盒子的
+   `overflow: hidden` 裁掉 —— 观感还是「滑出去 / 滑进来」，但栏内的滚动容器（`Panel.Body`、表格包裹层这些
+   `overflow: auto` 的件）不会因宽度被压缩而现出滚动条。取不到值时退回 100%（自适应侧栏的容器宽度不可插值，收起 /
+   展开本就是瞬间跳变，也就无所谓过渡期重排）。 */
 .mh-page__split-sidebar > * {
   width: var(--mh-page-split-frozen, 100%);
 }
@@ -375,11 +371,10 @@
   opacity: 1;
 }
 
-/* --- 收起按钮：**扁高条**（宽 12 / 高 28，跨在分隔线上）；默认不可见也不拦事件。
-   两条位置关系都是踩过的坑：
-   ① 它比 9px 命中带宽，常驻可点会吞掉栏边内容的点击 ⇒ 默认 `opacity: 0` + `pointer-events: none`；
-   ② 高亮线是手柄的**伪元素**，而伪元素默认绘制在子元素（本按钮）**之上** ⇒ 必须给按钮 `z-index`
-      （同层叠上下文内只有定位元素的 z-index 参与比较，`auto` 视作 0），否则那条 1px 线会横穿按钮中央。 */
+/* --- 收起按钮：**扁高条**（宽 12 / 高 28，跨在分隔线上）；默认不可见也不拦事件。两条位置关系都是踩过的坑：
+   ① 它比 9px 命中带宽，常驻可点会吞掉栏边内容的点击 ⇒ 默认 `opacity: 0` + `pointer-events: none`；② 高亮线是手柄的
+   **伪元素**，而伪元素默认绘制在子元素（本按钮）**之上** ⇒ 必须给按钮 `z-index`（同层叠上下文内只有定位元素的
+   z-index 参与比较，`auto` 视作 0），否则那条 1px 线会横穿按钮中央。 */
 .mh-page__split-handle-btn {
   position: absolute;
   top: 50%;
@@ -416,11 +411,10 @@
   pointer-events: auto;
 }
 
-/* 显式清掉 `:focus` 态的轮廓：上游 farris 有 `button:focus { outline: -webkit-focus-ring-color auto 5px }`，
-   特异性 (0,1,1) 高于本按钮基础态的 (0,1,0) —— 只写基础态 `outline: none` 压不住它，
-   鼠标点击（`:focus-visible` 不匹配）就会露出那道 5px 深色环。本规则 (0,2,0) 压过上游；
-   焦点反馈只留给紧随其后的 `:focus-visible`（同特异性、顺序在后 ⇒ 它赢）。
-   注：自绘层零 farris，本包之外的样式链若给全局按钮上过焦点环，本规则同样兜住。 */
+/* 显式清掉 `:focus` 态的轮廓：上游 farris 有 `button:focus { outline: -webkit-focus-ring-color auto 5px }`，特异性
+   (0,1,1) 高于本按钮基础态的 (0,1,0) —— 只写基础态 `outline: none` 压不住它，鼠标点击（`:focus-visible` 不匹配）
+   就会露出那道 5px 深色环。本规则 (0,2,0) 压过上游；焦点反馈只留给紧随其后的 `:focus-visible`（同特异性、顺序在后
+   ⇒ 它赢）。注：本包之外的样式链若给全局按钮上过焦点环，本规则同样兜住。 */
 .mh-page__split-handle-btn:focus {
   outline: none;
 }

package/dist/styles/components/pagination.css

@@ -89,6 +89,8 @@
   color: var(--ui-pagination-text);
   cursor: pointer;
   white-space: nowrap;
+  /* 定位上下文：隐身 input 的包含块必须落在控件内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 .mh-pagination__size-option:hover {
   background: var(--ui-pagination-bg-selected);
@@ -135,6 +137,8 @@
   transition-property: background-color, border-color, color;
   transition-duration: 0.15s;
   transition-timing-function: ease;
+  /* 定位上下文：隐身 input 的包含块必须落在控件内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 /* 滑过 / 按下：只描边转色（底仍透明，规范如此） */
 .mh-pagination__btn:hover,

package/dist/styles/components/radio.css

@@ -23,6 +23,8 @@
   color: var(--ui-base-content);
   cursor: pointer;
   user-select: none;
+  /* 定位上下文：隐身 input 的包含块必须落在开关内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
 /* 组容器：横向 16 / 纵向 12 */

package/dist/styles/components/search.css

@@ -1,18 +1,16 @@
 /**
  * Search —— 搜索框（输入框 + 可选搜索按钮的**组合件面**）。
  *
- * 本面**只声明「一行里怎么摆」**：输入框那一段的面归 `input.css`（框 / 内距 / 清除位 / 聚焦 / 禁用全套
- * 复用），搜索按钮的面归 `button.css`。本件没有自己的几何令牌，也不重画任何控件的框。
+ * 本面**只声明「一行里怎么摆」**：输入框那一段的面归 `input.css`（框 / 内距 / 清除位 / 聚焦 / 禁用全套复用），搜索按钮
+ * 的面归 `button.css`。本件没有自己的几何令牌，也不重画任何控件的框。
  *
- * 两条摆法：输入框 `flex: 1 1 auto` + `min-width: 0`（必须允许收缩，否则会把同行的搜索按钮挤出容器，
- * 窄栏里尤其明显）；搜索按钮 `flex: none`（永远「那么大」，宽度让给输入框）。
- * **按钮是可选的**：不传 `searchText` 时只渲染输入框（框内的放大镜已占住「搜索」语义，再出一个同字形
- * 的图标按钮就是同一个意思画两遍）；此时 `__btn` 那条摆法无对象，输入框自然占满整行。
+ * 两条摆法：输入框 `flex: 1 1 auto` + `min-width: 0`（必须允许收缩，否则会把同行的搜索按钮挤出容器，窄栏里尤其明显）；
+ * 搜索按钮 `flex: none`（永远「那么大」，宽度让给输入框）。**按钮是可选的**：不传 `searchText` 时只渲染输入框（框内的
+ * 放大镜已占住「搜索」语义，再出一个同字形的图标按钮就是同一个意思画两遍），此时 `__btn` 那条摆法无对象。
  *
- * **宽度口径**：整行吃控件那对令牌（`--ui-control-width` / `--ui-control-min-width`，见 theme 的
- * spacing.css）。行内那个输入框是 `Input` 的表壳，它在 `input.css` 里同样吃了这两枚，故这里按导入顺序
- * （本文件在 `input.css` 之后）把它**收回**：宽度归这一行，重复吃会让「240 的输入框 + 右侧按钮」溢出。
- * 类名与面文件名同根（`.mh-search*`）。
+ * **宽度口径**：整行吃控件那对令牌（`--ui-control-width` / `--ui-control-min-width`）。行内那个输入框是 `Input` 的
+ * 表壳、它在 `input.css` 里同样吃了这两枚，故这里按导入顺序（本文件在 `input.css` 之后）把它**收回**：宽度归这一行，
+ * 重复吃会让「240 的输入框 + 右侧按钮」溢出。类名与面文件名同根（`.mh-search*`）。
  */
 .mh-search {
   display: flex;

package/dist/styles/components/switch.css

@@ -14,6 +14,8 @@
   align-items: center;
   gap: var(--ui-switch-label-gap);
   cursor: pointer;
+  /* 定位上下文：隐身 input 的包含块必须落在开关内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 /* 隐身开关（1px 盒 + clip-path + appearance:none，与 checkbox / radio 同配方）：
    不用 display:none / visibility:hidden —— 那会把键盘与读屏一起关掉。 */

package/dist/styles/components/tabbar.css

@@ -22,6 +22,8 @@
   gap: var(--ui-tabbar-gap);
   height: var(--ui-tabbar-height);
   flex-shrink: 0;
+  /* 定位上下文：隐身 input 的包含块必须落在控件内，否则逃出滚动容器裁剪、撑大文档滚动高度 */
+  position: relative;
 }
 
 .mh-tabbar__tab {