@manohub/ui 0.10.4 → 1.0.0

package/dist/styles/components/toast.css

@@ -1,185 +1,185 @@
-/**
- * Toast —— 消息提示（一行提示 + 语义图标 + 可选动作；可堆叠）。
- *
- * 出处：`@aihub/theme` 的 `playground/components/toast.css` 与 `src/components/toast.css`
- * （宽 240 / 最大 560 / 最小高 52 / r8 / 1px 描边 / 内距 10 16 10 24 / 图标 18 圆 / 图标与文字间距 12 /
- *  投影 `0 2 12` 黑 10% / 正文 15；loading 样张 240x93 且图标顶对齐；带动作样张宽 360）。
- *
- * **与规范的一处有意偏差**：loading 那张 240x93 的样张是「多行加载文案」的尺寸，照搬成最小高后，
- * 单行提示会撑出一张上挤下空的空卡 —— 故本档高度回归常态（与其它档同为 52 起，内容多时自然撑高），
- * 只保留图标差异（透明底 + 主色转圈）。
- *
- * 三件事必须与规范一致（容易做错）：
- *
- * 1. **图标是「圆形色底 + 白色字形」**，不是一个字形图标 —— 只有 loading 例外（透明底 + 2px 主色描边，
- *    **上边留缺口**造成转圈感）；
- * 2. **动作按钮靠 `margin-left: auto` 顶到最右**，不是跟在文字后面；
- * 3. **转圈动画的键名归本族**（`mh-toast-spin`）：动画名是全局标识，加 `mh-` 前缀避免与页面上别的库撞名。
- *
- * 零 JS 能表达的：全部静态形态 + 转圈。**必须 JS**：自动消失计时、多条的出队、以及把 loading 换成结果态
- * （那三件都在组件层，本面不预设）。
- *
- * 堆叠容器（`.mh-toast-stack`）是随本族给的一层薄皮：定在视口顶部居中、纵向 8 间距 —— 位置与堆叠是
- * 「一族怎么摆」的事，做成类比让每个应用各写一份靠谱。
- */
-.mh-toast {
-  display: flex;
-  align-items: center;
-  gap: var(--ui-toast-gap);
-  /* 宽度：**内容自适应，240 起、最长 560** —— 即规范原文的「宽 240 / 最大 560」。
-     原写法 `width: var(--ui-toast-width)` 是**固定宽**：文本被锁在 240−40=200px 里折行，
-     而 `max-width` 永远轮不到（内容只会折行，撑不宽元素）⇒ 23 字提示被硬折成两行。
-     改 min/max 夹住的 fit-content 后：短文案仍是 240（样张宽不变），长文案按内容展开、到 560 才折行。 */
-  width: fit-content;
-  min-width: var(--ui-toast-width);
-  max-width: var(--ui-toast-width-max);
-  min-height: var(--ui-toast-min-height);
-  padding: var(--ui-space-3) var(--ui-space-4) var(--ui-space-3) var(--ui-space-6);
-  border: 1px solid var(--ui-toast-border);
-  border-radius: var(--ui-toast-radius);
-  background: var(--ui-base-100);
-  box-shadow: var(--ui-shadow-elevated);
-}
-
-/* loading：**不另设样张高**（高度与其它档一致，见文件头的「有意偏差」）—— 本档只差图标（转圈） */
-/* 带动作：**更宽的样张宽**（360 是下限，长文案仍可展开到 560 上限） */
-.mh-toast--action {
-  min-width: 360px;
-}
-
-/* ===== 图标：圆形色底 + 白色字形（18×18） ===== */
-.mh-toast__icon {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  flex: none;
-  width: var(--ui-toast-icon-size);
-  height: var(--ui-toast-icon-size);
-  border-radius: var(--ui-radius-full);
-  color: var(--ui-base-100);
-  font-size: var(--ui-font-caption);
-  line-height: 1;
-}
-
-/* ===== 语义档：色落在**根修饰符**上，由它再作用到图标 =====
- * 本包 tone 维度的统一落点是 `.mh-<件>--<tone>`（`Badge` / `Dialog` / `Notice` / `Notification`
- * / `Tag` / `Text` 同款）。本件此前写成 `.mh-toast__icon--<tone>`，是唯一一个落子元素修饰符的 ——
- * 消费方按直觉拼 `.mh-toast--success` 会落空。现改为「根挂 tone、面里用后代选择器取到图标」，
- * **视觉一字未变**（圆形色底仍然只在图标上）。 */
-.mh-toast--info .mh-toast__icon {
-  background: var(--ui-info);
-}
-.mh-toast--success .mh-toast__icon {
-  background: var(--ui-success);
-}
-.mh-toast--warning .mh-toast__icon {
-  background: var(--ui-warning);
-}
-.mh-toast--error .mh-toast__icon {
-  background: var(--ui-error);
-}
-/* loading 档：透明底 + 主色字形 + 匀速转圈。
-   规范此处是「2px 描边 + 上边缺口」的自画法，本仓改用意形（图标包的 `loading`）——
-  硬约束是「图标一律来自图标包、不用文字符号或自画形状冒充」，视觉等价（都是转圈环）。 */
-.mh-toast--loading .mh-toast__icon {
-  background: transparent;
-  color: var(--ui-primary);
-  animation: mh-toast-spin 0.8s linear infinite;
-}
-@keyframes mh-toast-spin {
-  to {
-    transform: rotate(360deg);
-  }
-}
-
-.mh-toast__text {
-  /* 占满剩余宽度：动作位 / 关闭位都被顶到右端。
-     不写成「每个右侧位各给 margin-left: auto」—— 两个 auto 会平分剩余空间，
-     而本族的常驻提示可能同时带动作与关闭位（那样动作钮会被推到卡片中间）。 */
-  /* ⚠️ 必须是 `flex: 1 1 auto`，不能写成 `flex: 1`（= basis 0%）：父级现在是 `width: fit-content`，
-     容器的固有宽按子项的**内容宽**算，basis 为 0 会让文本对容器宽度的贡献退化
-     ⇒ 容器停在 min-width(240)、长文案照旧折行（改宽度就白改了）。 */
-  flex: 1 1 auto;
-  min-width: 0;
-  margin: 0;
-  font-size: var(--ui-toast-text-size);
-  line-height: var(--ui-line-body);
-  color: var(--ui-base-content);
-}
-
-/* 动作位：文本按钮样，顶到最右（面归按钮族时可直接用 `.mh-button--text`，本类只给定位与默认字色） */
-.mh-toast__action {
-  margin-left: auto;
-  padding: 0;
-  border: none;
-  background: transparent;
-  font-family: inherit;
-  font-size: var(--ui-font-caption);
-  color: var(--ui-primary);
-  cursor: pointer;
-}
-.mh-toast__action:focus-visible {
-  outline: 2px solid var(--ui-primary);
-  outline-offset: 2px;
-}
-
-/* ===== 堆叠容器（顶部居中、纵向 8） =====
-   ⚠️ `z-index` 只对**普通层**有效：原生 `<dialog>.showModal()` 的模态层与 `::backdrop` 在 top layer，
-   对它 z-index 再大也没用（toast 会被遮罩压暗）。故本容器带 `popover="manual"` 进 top layer
-   —— `showPopover()` 由组件层负责（见 `ToastStack` 的说明）。 */
-.mh-toast-stack {
-  position: fixed;
-  top: var(--ui-space-6);
-  left: 50%;
-  transform: translateX(-50%);
-  z-index: 1080; /* 普通层里仍压过页面内容；popover 不可用的浏览器靠它兜底 */
-  display: flex;
-  flex-direction: column;
-  gap: var(--ui-space-2);
-  align-items: center;
-  pointer-events: none; /* 容器不挡点击；每条自己恢复 */
-}
-
-/* `[popover]` 档：清掉 UA 给 popover 的默认，否则会变成「全屏居中、带边框的方块」
-   （UA 给的是 `inset: 0; margin: auto; border: solid; padding: .25em; background: Canvas; overflow: auto`）。
-   ⚠️ `inset: auto` 与 `top` / `left` **必须写在同一条规则里**：只写 `inset: auto` 会把上面那条规则里的
-   `left: 50%` 一并压成 auto（同层冲突按顺序/特异性决胜，本块更高），元素就跑到视口左边缘去了。 */
-.mh-toast-stack[popover] {
-  inset: auto;
-  top: var(--ui-space-6);
-  left: 50%;
-  transform: translateX(-50%);
-  margin: 0;
-  border: 0;
-  padding: 0;
-  background: transparent;
-  overflow: visible;
-  max-width: none;
-  max-height: none;
-}
-.mh-toast-stack > .mh-toast {
-  pointer-events: auto;
-}
-
-/* ===== 关闭位（`duration=0` 的常驻提示必须给用户一个关掉的入口） =====
-   靠右由 `.mh-toast__text` 的弹性占位实现 —— 本件不写 `margin-left: auto`：
-   与动作位同时存在时两个 auto 会平分剩余空间，反而把动作钮推到卡片中间 */
-.mh-toast__close {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex: none;
-  padding: 0;
-  border: none;
-  background: transparent;
-  color: inherit;
-  cursor: pointer;
-  opacity: 0.7;
-  transition: opacity 0.15s ease;
-}
-.mh-toast__close:hover {
-  opacity: 1;
-}
-.mh-toast__close-icon {
-  flex: none;
-}
+/**
+ * Toast —— 消息提示（一行提示 + 语义图标 + 可选动作；可堆叠）。
+ *
+ * 出处：`@aihub/theme` 的 `playground/components/toast.css` 与 `src/components/toast.css`
+ * （宽 240 / 最大 560 / 最小高 52 / r8 / 1px 描边 / 内距 10 16 10 24 / 图标 18 圆 / 图标与文字间距 12 /
+ *  投影 `0 2 12` 黑 10% / 正文 15；loading 样张 240x93 且图标顶对齐；带动作样张宽 360）。
+ *
+ * **与规范的一处有意偏差**：loading 那张 240x93 的样张是「多行加载文案」的尺寸，照搬成最小高后，
+ * 单行提示会撑出一张上挤下空的空卡 —— 故本档高度回归常态（与其它档同为 52 起，内容多时自然撑高），
+ * 只保留图标差异（透明底 + 主色转圈）。
+ *
+ * 三件事必须与规范一致（容易做错）：
+ *
+ * 1. **图标是「圆形色底 + 白色字形」**，不是一个字形图标 —— 只有 loading 例外（透明底 + 2px 主色描边，
+ *    **上边留缺口**造成转圈感）；
+ * 2. **动作按钮靠 `margin-left: auto` 顶到最右**，不是跟在文字后面；
+ * 3. **转圈动画的键名归本族**（`mh-toast-spin`）：动画名是全局标识，加 `mh-` 前缀避免与页面上别的库撞名。
+ *
+ * 零 JS 能表达的：全部静态形态 + 转圈。**必须 JS**：自动消失计时、多条的出队、以及把 loading 换成结果态
+ * （那三件都在组件层，本面不预设）。
+ *
+ * 堆叠容器（`.mh-toast-stack`）是随本族给的一层薄皮：定在视口顶部居中、纵向 8 间距 —— 位置与堆叠是
+ * 「一族怎么摆」的事，做成类比让每个应用各写一份靠谱。
+ */
+.mh-toast {
+  display: flex;
+  align-items: center;
+  gap: var(--ui-toast-gap);
+  /* 宽度：**内容自适应，240 起、最长 560** —— 即规范原文的「宽 240 / 最大 560」。
+     原写法 `width: var(--ui-toast-width)` 是**固定宽**：文本被锁在 240−40=200px 里折行，
+     而 `max-width` 永远轮不到（内容只会折行，撑不宽元素）⇒ 23 字提示被硬折成两行。
+     改 min/max 夹住的 fit-content 后：短文案仍是 240（样张宽不变），长文案按内容展开、到 560 才折行。 */
+  width: fit-content;
+  min-width: var(--ui-toast-width);
+  max-width: var(--ui-toast-width-max);
+  min-height: var(--ui-toast-min-height);
+  padding: var(--ui-space-3) var(--ui-space-4) var(--ui-space-3) var(--ui-space-6);
+  border: 1px solid var(--ui-toast-border);
+  border-radius: var(--ui-toast-radius);
+  background: var(--ui-base-100);
+  box-shadow: var(--ui-shadow-elevated);
+}
+
+/* loading：**不另设样张高**（高度与其它档一致，见文件头的「有意偏差」）—— 本档只差图标（转圈） */
+/* 带动作：**更宽的样张宽**（360 是下限，长文案仍可展开到 560 上限） */
+.mh-toast--action {
+  min-width: 360px;
+}
+
+/* ===== 图标：圆形色底 + 白色字形（18×18） ===== */
+.mh-toast__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: var(--ui-toast-icon-size);
+  height: var(--ui-toast-icon-size);
+  border-radius: var(--ui-radius-full);
+  color: var(--ui-base-100);
+  font-size: var(--ui-font-caption);
+  line-height: 1;
+}
+
+/* ===== 语义档：色落在**根修饰符**上，由它再作用到图标 =====
+ * 本包 tone 维度的统一落点是 `.mh-<件>--<tone>`（`Badge` / `Dialog` / `Notice` / `Notification`
+ * / `Tag` / `Text` 同款）。本件此前写成 `.mh-toast__icon--<tone>`，是唯一一个落子元素修饰符的 ——
+ * 消费方按直觉拼 `.mh-toast--success` 会落空。现改为「根挂 tone、面里用后代选择器取到图标」，
+ * **视觉一字未变**（圆形色底仍然只在图标上）。 */
+.mh-toast--info .mh-toast__icon {
+  background: var(--ui-info);
+}
+.mh-toast--success .mh-toast__icon {
+  background: var(--ui-success);
+}
+.mh-toast--warning .mh-toast__icon {
+  background: var(--ui-warning);
+}
+.mh-toast--error .mh-toast__icon {
+  background: var(--ui-error);
+}
+/* loading 档：透明底 + 主色字形 + 匀速转圈。
+   规范此处是「2px 描边 + 上边缺口」的自画法，本仓改用意形（图标包的 `loading`）——
+  硬约束是「图标一律来自图标包、不用文字符号或自画形状冒充」，视觉等价（都是转圈环）。 */
+.mh-toast--loading .mh-toast__icon {
+  background: transparent;
+  color: var(--ui-primary);
+  animation: mh-toast-spin 0.8s linear infinite;
+}
+@keyframes mh-toast-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.mh-toast__text {
+  /* 占满剩余宽度：动作位 / 关闭位都被顶到右端。
+     不写成「每个右侧位各给 margin-left: auto」—— 两个 auto 会平分剩余空间，
+     而本族的常驻提示可能同时带动作与关闭位（那样动作钮会被推到卡片中间）。 */
+  /* ⚠️ 必须是 `flex: 1 1 auto`，不能写成 `flex: 1`（= basis 0%）：父级现在是 `width: fit-content`，
+     容器的固有宽按子项的**内容宽**算，basis 为 0 会让文本对容器宽度的贡献退化
+     ⇒ 容器停在 min-width(240)、长文案照旧折行（改宽度就白改了）。 */
+  flex: 1 1 auto;
+  min-width: 0;
+  margin: 0;
+  font-size: var(--ui-toast-text-size);
+  line-height: var(--ui-line-body);
+  color: var(--ui-base-content);
+}
+
+/* 动作位：文本按钮样，顶到最右（面归按钮族时可直接用 `.mh-button--text`，本类只给定位与默认字色） */
+.mh-toast__action {
+  margin-left: auto;
+  padding: 0;
+  border: none;
+  background: transparent;
+  font-family: inherit;
+  font-size: var(--ui-font-caption);
+  color: var(--ui-primary);
+  cursor: pointer;
+}
+.mh-toast__action:focus-visible {
+  outline: 2px solid var(--ui-primary);
+  outline-offset: 2px;
+}
+
+/* ===== 堆叠容器（顶部居中、纵向 8） =====
+   ⚠️ `z-index` 只对**普通层**有效：原生 `<dialog>.showModal()` 的模态层与 `::backdrop` 在 top layer，
+   对它 z-index 再大也没用（toast 会被遮罩压暗）。故本容器带 `popover="manual"` 进 top layer
+   —— `showPopover()` 由组件层负责（见 `ToastStack` 的说明）。 */
+.mh-toast-stack {
+  position: fixed;
+  top: var(--ui-space-6);
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 1080; /* 普通层里仍压过页面内容；popover 不可用的浏览器靠它兜底 */
+  display: flex;
+  flex-direction: column;
+  gap: var(--ui-space-2);
+  align-items: center;
+  pointer-events: none; /* 容器不挡点击；每条自己恢复 */
+}
+
+/* `[popover]` 档：清掉 UA 给 popover 的默认，否则会变成「全屏居中、带边框的方块」
+   （UA 给的是 `inset: 0; margin: auto; border: solid; padding: .25em; background: Canvas; overflow: auto`）。
+   ⚠️ `inset: auto` 与 `top` / `left` **必须写在同一条规则里**：只写 `inset: auto` 会把上面那条规则里的
+   `left: 50%` 一并压成 auto（同层冲突按顺序/特异性决胜，本块更高），元素就跑到视口左边缘去了。 */
+.mh-toast-stack[popover] {
+  inset: auto;
+  top: var(--ui-space-6);
+  left: 50%;
+  transform: translateX(-50%);
+  margin: 0;
+  border: 0;
+  padding: 0;
+  background: transparent;
+  overflow: visible;
+  max-width: none;
+  max-height: none;
+}
+.mh-toast-stack > .mh-toast {
+  pointer-events: auto;
+}
+
+/* ===== 关闭位（`duration=0` 的常驻提示必须给用户一个关掉的入口） =====
+   靠右由 `.mh-toast__text` 的弹性占位实现 —— 本件不写 `margin-left: auto`：
+   与动作位同时存在时两个 auto 会平分剩余空间，反而把动作钮推到卡片中间 */
+.mh-toast__close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+  opacity: 0.7;
+  transition: opacity 0.15s ease;
+}
+.mh-toast__close:hover {
+  opacity: 1;
+}
+.mh-toast__close-icon {
+  flex: none;
+}

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

@@ -1,26 +1,26 @@
-/**
- * toast —— 单件令牌（**基础值**）。
- *
- * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
- *
- * ## 抽出说明
- * 本文件从面文件里抽出（原先混写在 `toast.css` 顶部）：这些是**基础值**，锚在
- * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
- * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
- * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
- *
- * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
- * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
- * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
- */
-[data-manohub-ui] {
-  /* 单件令牌 */
-  --ui-toast-width: 240px;
-  --ui-toast-width-max: 560px;
-  --ui-toast-min-height: 52px;
-  --ui-toast-radius: var(--ui-radius-md); /* 规范 r8 */
-  --ui-toast-border: var(--ui-base-300); /* 规范 #d8dce6 */
-  --ui-toast-gap: var(--ui-space-3); /* 图标与文字间距 12 */
-  --ui-toast-icon-size: 18px;
-  --ui-toast-text-size: 15px; /* 规范实测（本仓字阶无 15，按实测值给） */
-}
+/**
+ * toast —— 单件令牌（**基础值**）。
+ *
+ * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
+ *
+ * ## 抽出说明
+ * 本文件从面文件里抽出（原先混写在 `toast.css` 顶部）：这些是**基础值**，锚在
+ * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
+ * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
+ * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
+ *
+ * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
+ * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
+ * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
+ */
+[data-manohub-ui] {
+  /* 单件令牌 */
+  --ui-toast-width: 240px;
+  --ui-toast-width-max: 560px;
+  --ui-toast-min-height: 52px;
+  --ui-toast-radius: var(--ui-radius-md); /* 规范 r8 */
+  --ui-toast-border: var(--ui-base-300); /* 规范 #d8dce6 */
+  --ui-toast-gap: var(--ui-space-3); /* 图标与文字间距 12 */
+  --ui-toast-icon-size: 18px;
+  --ui-toast-text-size: 15px; /* 规范实测（本仓字阶无 15，按实测值给） */
+}

package/dist/styles/components/tooltip.css

@@ -1,89 +1,89 @@
-/**
- * Tooltip —— 提示气泡皮肤（与操作层并列组合）。
- *
- * 出处：`@aihub/theme` 的 `playground/components/tooltip.css` 与 `src/components/tooltip.css`
- * （内距 8 / 14、圆角 10、深底反白字、`0 2 8` 黑 15% 投影；引导档另有一套面：蓝渐变底 + 12/14 内距 +
- *  `0 2 14` 投影；标题 medium；动作是白色文本按钮；显隐纯淡入、不位移不缩放）。
- *
- * **类名与面文件名同根**：族名 `tooltip` → 类名 `.mh-tooltip*`（与令牌 `--ui-tooltip-*` 同根），
- * 一律 `mh-` 前缀 —— 本包独立发布，不迁就任何下游的既有类名（有用例盯着这条口径）。
- *
- * 显隐与定位全归操作层：宿主态（`.mh-popup-host:hover` / `:focus-within`）切 display、`data-side` / `data-align`
- * 给定位、`.mh-popup-anchor` / `--anchored` 给锚。本件只给面 + 淡入（进出对称）。
- */
-.mh-tooltip {
-  display: inline-block;
-  padding: var(--ui-space-2) var(--ui-tooltip-padding-x);
-  border-radius: var(--ui-tooltip-radius);
-  background: var(--ui-tooltip-bg);
-  color: var(--ui-tooltip-text);
-  font-size: var(--ui-font-caption);
-  line-height: var(--ui-line-body);
-  box-shadow: var(--ui-tooltip-shadow);
-}
-
-/* 引导档（自己的面：更亮的内距 + 蓝渐变 + 更大投影） */
-.mh-tooltip--guide {
-  padding: var(--ui-space-3) var(--ui-tooltip-padding-x);
-  background: var(--ui-tooltip-guide-bg);
-  box-shadow: var(--ui-tooltip-guide-shadow);
-}
-
-/* 标题位（medium）与动作位（白色文本按钮，面不另开按钮族之外的类） */
-.mh-tooltip__title {
-  font-weight: var(--ui-weight-medium);
-}
-.mh-tooltip__action {
-  padding: 0;
-  border: none;
-  background: transparent;
-  font-family: inherit;
-  font-size: inherit;
-  color: var(--ui-tooltip-text);
-  cursor: pointer;
-}
-.mh-tooltip__action:focus-visible {
-  outline: 2px solid var(--ui-tooltip-text);
-  outline-offset: 2px;
-}
-
-/* ===== 淡入（hover 档：display 由操作层切，本层只管透明度补间，进出对称） =====
- * 规范：提示不位移不缩放，纯淡入淡出 —— `opacity` 与触发态同源绑定。
- * 域定在 `.mh-popup--hover`：静态摆样（不带该档）恒可见，不落收起末帧。 */
-.mh-tooltip.mh-popup--hover {
-  opacity: 0;
-  transition: opacity 0.2s ease-out;
-}
-.mh-popup-host:hover .mh-tooltip.mh-popup--hover,
-.mh-popup-host:focus-within .mh-tooltip.mh-popup--hover {
-  opacity: 1;
-}
-@starting-style {
-  .mh-popup-host:hover .mh-tooltip.mh-popup--hover {
-    opacity: 0;
-  }
-}
-
-/* ===== 点击档（原生 popover）=====
- * 触发器按钮化：清掉 UA 的按钮外观，让它看起来仍是页面里原来那个元素。 */
-.mh-tooltip__trigger {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--ui-space-1);
-  padding: 0;
-  border: none;
-  background: transparent;
-  font-family: inherit;
-  font-size: inherit;
-  line-height: inherit;
-  color: inherit;
-  cursor: pointer;
-}
-.mh-tooltip__trigger:focus-visible {
-  outline: 2px solid var(--ui-primary);
-  outline-offset: 2px;
-}
-/* 点击档的气泡要限宽：进了 top layer 就不再受容器约束，长文案会被拉成一整行 */
-.mh-tooltip--click {
-  max-width: 280px;
-}
+/**
+ * Tooltip —— 提示气泡皮肤（与操作层并列组合）。
+ *
+ * 出处：`@aihub/theme` 的 `playground/components/tooltip.css` 与 `src/components/tooltip.css`
+ * （内距 8 / 14、圆角 10、深底反白字、`0 2 8` 黑 15% 投影；引导档另有一套面：蓝渐变底 + 12/14 内距 +
+ *  `0 2 14` 投影；标题 medium；动作是白色文本按钮；显隐纯淡入、不位移不缩放）。
+ *
+ * **类名与面文件名同根**：族名 `tooltip` → 类名 `.mh-tooltip*`（与令牌 `--ui-tooltip-*` 同根），
+ * 一律 `mh-` 前缀 —— 本包独立发布，不迁就任何下游的既有类名（有用例盯着这条口径）。
+ *
+ * 显隐与定位全归操作层：宿主态（`.mh-popup-host:hover` / `:focus-within`）切 display、`data-side` / `data-align`
+ * 给定位、`.mh-popup-anchor` / `--anchored` 给锚。本件只给面 + 淡入（进出对称）。
+ */
+.mh-tooltip {
+  display: inline-block;
+  padding: var(--ui-space-2) var(--ui-tooltip-padding-x);
+  border-radius: var(--ui-tooltip-radius);
+  background: var(--ui-tooltip-bg);
+  color: var(--ui-tooltip-text);
+  font-size: var(--ui-font-caption);
+  line-height: var(--ui-line-body);
+  box-shadow: var(--ui-tooltip-shadow);
+}
+
+/* 引导档（自己的面：更亮的内距 + 蓝渐变 + 更大投影） */
+.mh-tooltip--guide {
+  padding: var(--ui-space-3) var(--ui-tooltip-padding-x);
+  background: var(--ui-tooltip-guide-bg);
+  box-shadow: var(--ui-tooltip-guide-shadow);
+}
+
+/* 标题位（medium）与动作位（白色文本按钮，面不另开按钮族之外的类） */
+.mh-tooltip__title {
+  font-weight: var(--ui-weight-medium);
+}
+.mh-tooltip__action {
+  padding: 0;
+  border: none;
+  background: transparent;
+  font-family: inherit;
+  font-size: inherit;
+  color: var(--ui-tooltip-text);
+  cursor: pointer;
+}
+.mh-tooltip__action:focus-visible {
+  outline: 2px solid var(--ui-tooltip-text);
+  outline-offset: 2px;
+}
+
+/* ===== 淡入（hover 档：display 由操作层切，本层只管透明度补间，进出对称） =====
+ * 规范：提示不位移不缩放，纯淡入淡出 —— `opacity` 与触发态同源绑定。
+ * 域定在 `.mh-popup--hover`：静态摆样（不带该档）恒可见，不落收起末帧。 */
+.mh-tooltip.mh-popup--hover {
+  opacity: 0;
+  transition: opacity 0.2s ease-out;
+}
+.mh-popup-host:hover .mh-tooltip.mh-popup--hover,
+.mh-popup-host:focus-within .mh-tooltip.mh-popup--hover {
+  opacity: 1;
+}
+@starting-style {
+  .mh-popup-host:hover .mh-tooltip.mh-popup--hover {
+    opacity: 0;
+  }
+}
+
+/* ===== 点击档（原生 popover）=====
+ * 触发器按钮化：清掉 UA 的按钮外观，让它看起来仍是页面里原来那个元素。 */
+.mh-tooltip__trigger {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ui-space-1);
+  padding: 0;
+  border: none;
+  background: transparent;
+  font-family: inherit;
+  font-size: inherit;
+  line-height: inherit;
+  color: inherit;
+  cursor: pointer;
+}
+.mh-tooltip__trigger:focus-visible {
+  outline: 2px solid var(--ui-primary);
+  outline-offset: 2px;
+}
+/* 点击档的气泡要限宽：进了 top layer 就不再受容器约束，长文案会被拉成一整行 */
+.mh-tooltip--click {
+  max-width: 280px;
+}

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

@@ -1,25 +1,25 @@
-/**
- * tooltip —— 单件令牌（**基础值**）。
- *
- * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
- *
- * ## 抽出说明
- * 本文件从面文件里抽出（原先混写在 `tooltip.css` 顶部）：这些是**基础值**，锚在
- * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
- * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
- * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
- *
- * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
- * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
- * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
- */
-[data-manohub-ui] {
-  /* 单件令牌 */
-  --ui-tooltip-radius: 10px; /* 规范 r10（本仓圆角刻度最大 8） */
-  --ui-tooltip-padding-x: 14px; /* 规范间距档 5 = 14 */
-  --ui-tooltip-bg: var(--ui-base-content); /* 深底：规范用深色蒙层色，本仓无深色面令牌，取正文档（与输入说明气泡同一映射） */
-  --ui-tooltip-text: var(--ui-base-100); /* 反白字 */
-  --ui-tooltip-shadow: 0 2px 8px rgba(0, 0, 0, 0.15); /* 规范实测值（本仓阴影令牌几何不同族，故按出处给） */
-  --ui-tooltip-guide-bg: linear-gradient(180deg, #2e77ff, #2a87ff); /* 规范引导档蓝渐变 */
-  --ui-tooltip-guide-shadow: 0 2px 14px rgba(45, 47, 51, 0.2);
-}
+/**
+ * tooltip —— 单件令牌（**基础值**）。
+ *
+ * 本件自己的几何 / 尺寸 / 色彩槽位；只服务本件，故不随主题进 `@manohub/theme`。
+ *
+ * ## 抽出说明
+ * 本文件从面文件里抽出（原先混写在 `tooltip.css` 顶部）：这些是**基础值**，锚在
+ * `[data-manohub-ui]` —— 跨包唯一作用域锚，由入口层无条件写在应用容器上，因此**任何落在
+ * 容器里的分件都取得到值**，不再依赖「声明在某个组件根类上」这条脆弱假设
+ * （历史症状：跨件消费的 `--ui-*-group-*` 取不到值，组内间距变 0）。
+ *
+ * ⚠️ `.mh-<件>--<档>` 这类**档位改写**留在面文件的修饰符块里 —— 它们靠「同一元素上两个
+ * 选择器改写同一个令牌」生效，搬到本文件会让档位失效。
+ * ⚠️ 新增组件要登记两处：本文件 + `src/styles/index.css`（见其文件头「五处齐备」）。
+ */
+[data-manohub-ui] {
+  /* 单件令牌 */
+  --ui-tooltip-radius: 10px; /* 规范 r10（本仓圆角刻度最大 8） */
+  --ui-tooltip-padding-x: 14px; /* 规范间距档 5 = 14 */
+  --ui-tooltip-bg: var(--ui-base-content); /* 深底：规范用深色蒙层色，本仓无深色面令牌，取正文档（与输入说明气泡同一映射） */
+  --ui-tooltip-text: var(--ui-base-100); /* 反白字 */
+  --ui-tooltip-shadow: 0 2px 8px rgba(0, 0, 0, 0.15); /* 规范实测值（本仓阴影令牌几何不同族，故按出处给） */
+  --ui-tooltip-guide-bg: linear-gradient(180deg, #2e77ff, #2a87ff); /* 规范引导档蓝渐变 */
+  --ui-tooltip-guide-shadow: 0 2px 14px rgba(45, 47, 51, 0.2);
+}