@manohub/ui 0.10.5 → 1.0.0

package/README.md

@@ -1,155 +1,155 @@
-# @manohub/ui
-
-AIHub **自绘组件层**：不依赖 farris 的手写 Vue TSX 组件 + 自带令牌层。
-
-本包分三层，**可分别引用**：
-
-| 层 | 入口 | 内容 |
-|---|---|---|
-| ① 主题 | `@manohub/theme/default.css`（兜底）/ `@manohub/theme/farris.css`（Farris 规范） | **全局**令牌（值）—— 随主题包独立发布，换主题只换这一行 |
-| ② 组件面 | `@manohub/ui/styles.css` | **元素级 reset**（只有盒模型 + 容器基座两面，见下）+ 类与状态协议 + 组件令牌基础值，**无需 JS** 即可使用 |
-| ③ Vue 层 | `@manohub/ui` | Vue 组件：渲染 ② 的类 + 行为增强 |
-| ④ 服务层 | `@manohub/ui` | 命令式反馈：`toast()` / `confirm()` / `alert()` / `showLoading()`（宿主 + 队列 + 生命周期，共用 ③ 的组件） |
-
-- **视觉与几何**：《Farris Web 基础视觉规范》（`@aihub/theme` 的令牌与组件实测值）
-- **令牌命名**：daisyUI 式语义槽位（`--ui-primary` / `--ui-base-content` / `--ui-info*` / `--ui-warning*` …，`default ≠ primary`）
-- **组件 API**：shadcn 通行词汇（变体维度 `tone` × `shape` × `size`、compound 点号子件、受控 prop + 语义事件）
-- **实现**：零依赖手写 CSS，类名 `.mh-*`（bem-lite）
-
-> **0.5.0（破坏性变更）**：`Section` 组件已退役 —— 它的「标题行 + 右端操作位（`extra`）」能力并入
-> **`Form.Header`**（支持 `title` / `description` / `extra`，且成员归位到表单最前）。
-> 旧写法 `Section` / `Form.Section` 统一改为 `Form.Header`；需要「区块分组」时用 `Panel` 或嵌套容器。
-
-## 安装
-
-```bash
-pnpm add @manohub/ui @manohub/theme
-```
-
-## 接入
-
-样式两行，顺序固定（先主题后组件面；若应用的样式链已级联本包，则不必单独引）：
-
-```css
-@import "@manohub/theme/default.css"; /* ① 全局令牌（值） */
-@import "@manohub/ui/styles.css"; /* ② 组件面（类 + 组件令牌值） */
-```
-
-只写静态页（不装 Vue）时引这两行即可 —— 类名与 `data-*` 状态协议直接可用。
-
-**② 的第一条 import 就是元素级 reset**（随包内置，不需要第三行），它只有两面：
-
-1. **盒模型**：`box-sizing: border-box` 覆盖容器、全部后代与伪元素（本包所有面的几何前提）；
-2. **容器基座**：`[data-manohub-ui]` 上的字族 / 字号 / 行高 / 字色 / 底色 / 整链高度（令牌的落点）。
-
-作用域锚 `[data-manohub-ui]` 且特异性为 0 —— 应用侧写任何元素选择器都能盖过它。
-**它有意不再归零标题字阶、列表序号、链接下划线、控件外观**：那些规则在 Tailwind 的层外
-（未分层 > 分层），会把消费方的工具类整片压住（`border*`、`img` 上的 `h-*`、`hidden` …）；
-需要归零的元素各自归到渲染它的组件面上（`img` 在 Avatar / Upload、`a` 在 Button、
-`textarea` 的 `resize` 在 `.mh-input--textarea`、`h1`-`h6` 在 `.mh-text`）。
-Tailwind 消费方另有 preflight 兜底，两者不冲突。
-
-所以**不必再自己写一份全局 reset**；也**不要**用元素级选择器去补（那正是被压住的成因）。
-
-本包**可独立发布**：组件与类型一律从 `@manohub/ui` 直接引；下游（如 `@manohub/kit`）若转出口，是下游自己的选择。
-
-```tsx
-import { Card, Form, Tree, Checkbox } from '@manohub/ui'
-```
-
-## 组件清单
-
-| 分组 | 组件 |
-|---|---|
-| 容器与分区 | `Page`（页面级骨架：`.Header` / `.Body` / `.Footer` / `.Filter` / `.Toolbar` / `.Split`）、`Panel`（+ `.Header` / `.Body` / `.Footer`）、`Card`（+ 三件）、`Nav`、`Layout`（`Layout.Row` 排「行」/ `Layout.Column` 排「列」：轴向 × 间距档 × 对齐） |
-| 数据展示 | `Tree`、`ListView`（+ `.CardItem`）、`Badge`、`Tag`（`Badge` 的可关闭 / 可新增封装） |
-| 展示 | `Avatar`（+ `.Group`）、`Skeleton`（行 / 列表 / 块状） |
-| 表单基础（**自绘**） | `Button`（+ `.Group` / `.Divider`；五型 / 小号 / 加载 / 菜单按钮 / 连体切换）、`Input`（+ `.Group` / `.Chip` / `.Display` / `.Textarea`；清除 / 可见性切换 / 校验）、`Search`（搜索框：值 / 搜索 / 清空三条回调）、`Select`（单选 / 多选 / 搜索 / 加载；面板用原生 popover）、`SelectTree`（树形态：仅叶子可选 + 本地过滤 + 命中高亮；与 `Select` 平级导出、共用触发器与面板）、`Switch`（表格档 / 表单档） |
-| 表单与选择 | `Form`（+ `.Header` / `.Item`；标签体系、成员归位、`v-model` 值收集与命令式 `clear()`）、`Filter`（+ `.Item`；`Form` 的壳：条件字段写成子件、控件自放、查询/重置与快照归一）、`Checkbox`、`Radio`（+ `.Group` / `.Card`；卡片式单选）、`Capsule`（胶囊选择器；胶囊 / 方形两档外形，与 `Tabs` 组合即页签） |
-| 反馈与三态 | `Notice`（条状提示）、`Notification`（通知卡：标题 + 头像 / 标签 / 操作 / 关闭位）、`QueryState`（三态容器；内建空 / 错误插画取自设计交付的四张 SVG，原样内联在 `src/utils/state-illustration.ts`）、`Loading`（转圈 + 遮罩：行内 / 区域 / 全屏三形态） |
-| 反馈与引导（**自绘**） | `Toast`（消息提示：语义四档 / loading + 可选动作 + 自动消失计时 + `.Stack` 堆叠）、`Steps`（步骤条：节点式 / 燕尾段式 / `.Progress` 进度条） |
-| 数据展示（**自绘**） | `Table`（列 × 数据 + 选择列 + 排序事件 + 固定表头 / 固定列 + 批量栏 / 合计行；排序与列宽拖拽算法归调用方）、`Pagination`（总数 / 每页条数 / 页码窗口 / 简单档 / 外框档）、`TabBar`（下划线页签 + 「更多」收纳） |
-| 内容与文件 | `CodeBlock`（**一族三件**：组合件 `CodeBlock` 按 `editable` 切只读 / 编辑两形态；`.View` 只读展示 —— 行内 chip / 代码块 + 语言角标 + 图标复制位；`.Editor` 可编辑 —— 等宽多行 + 按行自适应 / 限高内滚 / 只读、禁用）、`Upload`（+ `.Thumbs`；拖拽 / 点击上传区 + 已传文件列表） |
-| 浮层（**自绘**） | `Dialog`（原生 `<dialog>` + 模态皮肤；关闭受控）、`Tooltip`（**零 JS**：显隐与定位全走操作层 hover 档） |
-| 操作层（跨件原语） | `Collapse`（+ `.Stack`）、`Tabs`（+ `TabPanel`，面板切换骨架 —— 显隐归组件层，非零 JS 原语）；浮层只提供样式层（`styles/operations/popup.css`，零 JS 可直接用），Vue 浮层仍用 farris 适配件 |
-
-## 三态的操作按钮
-
-`QueryState` / `Tree` / `ListView` 的空态·错误态操作按钮就是**本包的 `Button`**（`variant="primary"`），
-与全站按钮同族 —— 应用**不需要**注入任何东西，只要把文案与回调给上：
-
-```vue
-<QueryState
-  :empty="list.length === 0"
-  empty-action-text="新建"
-  :on-empty-action="openCreate"
->
-  <MyList />
-</QueryState>
-```
-
-- 要换外观：改主题令牌（`Button` 的外观档位是 `variant`）；
-- 要换结构（多个按钮 / 自定义动作区）：用 `actions` 插槽自绘。
-
-## 服务层（组件树之外调反馈）
-
-组件是**受控**的（可见性归调用方）；组件树之外（请求回调、路由守卫、工具函数里）要弹提示时用服务层：
-
-```ts
-import { toast, confirm, alert, showLoading, configureHost } from '@manohub/ui'
-
-toast('success', '保存成功')                                  // 3 秒自动消失
-toast('error', '导出失败', { action: { text: '重试', onClick: retry } })
-const pending = toast('loading', '正在导入…', { duration: 0 }) // 常驻，完成后自己收
-pending.close()
-
-if (await confirm({ title: '删除确认', detail: '删除后不可恢复', okDanger: true })) await remove()
-await alert({ title: '导入完成', detail: '共 128 条' })
-
-const done = showLoading('保存中…')   // 引用计数：并发调用要各关各的
-try { await save() } finally { done() }
-```
-
-**四件必须知道的事**：
-
-1. **服务层不新造浮层**：`toast()` 渲染的是本包的 `Toast`、`confirm()` 渲染的是本包的 `Dialog`、
-   `showLoading()` 渲染的是本包的 `Loading` —— 外观改一处两处一起变。
-2. **宿主即渲染位置**：解析顺序是「**显式 `configureHost(el)`** → 带 `[data-manohub-ui]` 作用域锚的容器
-   → `document.body`」。微前端下**必须落回本应用自己的容器**：本包全部令牌（全局值 + 组件值）都锚在
-   `[data-manohub-ui]` 上，落在容器外的浮层会「样式全丢」（变量解析为空 +
-   应用侧样式被 `scopecss` 前缀化后匹配不到）。骨架层只需在包裹节点上补一个
-   `data-manohub-ui` 属性，服务层不必反向依赖它。
-   注：`.app-container` 是 `@manohub/kit` 的输出类名（内部命名），**不是**跨包契约，服务层不认它。
-3. **按需挂载、自动收尾**：首次调用才建宿主与 Vue 实例（模块顶层零 DOM 操作）；
-   `toast` 队列空了、`loading` 计数归零即收掉宿主 —— 反复重挂不留悬挂实例。
-4. **`loading` 是引用计数语义**：并发的两次「显示」只关一次时遮罩仍在（先结束的那个不会把
-   别人的遮罩一起收掉）。推荐用返回的句柄在 `finally` 里关掉自己那一次。
-
-## 主题层
-
-全局令牌（`--ui-primary` / `--ui-space-*` / `--ui-font-*` 这类跨件共用的值）**不在本包**，已拆成独立包
-**`@manohub/theme`**（值层与面层分开：值随主题变、面不随主题变）。每个主题分五片：
-`colors` / `typography` / `spacing` / `radius` / `shadows`，一律锚定 **`[data-manohub-ui]`**
-（库品牌作用域锚；micro-app 的 scopecss 不作用域化 `:root`，定义在 `:root` 会泄漏到宿主）。
-
-只服务单一组件的令牌分两半落在本包：
-
-| 位置 | 内容 | 锚 |
-|---|---|---|
-| `styles/components/<件>.tokens.css` | **基础值**（唯一的、两套主题同值的那一条） | `[data-manohub-ui]` |
-| `styles/components/<件>.css` | **档位改写**（`.mh-<件>--<档>` 覆盖同一令牌）+ `--mh-*` 内部状态变量 | 元件根类 / 档位类 |
-
-后一半必须在面里：它们靠「同一元素上两个选择器改写同一个令牌」生效，搬走就断链。
-
-随包两套：
-
-| 主题 | 入口 | 锚点 | 取值来源 |
-|---|---|---|---|
-| `default` | `@manohub/theme/default.css` | `[data-manohub-ui]`（兜底套） | AIHub 品牌蓝（primary `#2660FF`）|
-| `farris` | `@manohub/theme/farris.css` | `[data-manohub-ui][data-theme='farris']` | 《Farris Web 基础视觉规范》（primary `#2a87ff`，色板编号 Th/Au/Ne/Te 逐条标注）|
-
-换皮只需给容器加属性（`createSubApp({ theme: 'farris' })` 会写 `data-theme`），不动类名、不动组件代码、不重打包。
-新增主题 = `packages/theme/src/<name>/` 新目录，令牌锚 `[data-manohub-ui][data-theme='<name>']`，
-且必须**全量覆盖** default 的令牌。
-
-局部换主题：在更深的容器上重设变量即可，例如 `.role-tree-pane { --ui-primary: #7C3AED; }`。
+# @manohub/ui
+
+AIHub **自绘组件层**：不依赖 farris 的手写 Vue TSX 组件 + 自带令牌层。
+
+本包分三层，**可分别引用**：
+
+| 层 | 入口 | 内容 |
+|---|---|---|
+| ① 主题 | `@manohub/theme/default.css`（兜底）/ `@manohub/theme/farris.css`（Farris 规范） | **全局**令牌（值）—— 随主题包独立发布，换主题只换这一行 |
+| ② 组件面 | `@manohub/ui/styles.css` | **元素级 reset**（只有盒模型 + 容器基座两面，见下）+ 类与状态协议 + 组件令牌基础值，**无需 JS** 即可使用 |
+| ③ Vue 层 | `@manohub/ui` | Vue 组件：渲染 ② 的类 + 行为增强 |
+| ④ 服务层 | `@manohub/ui` | 命令式反馈：`toast()` / `confirm()` / `alert()` / `showLoading()`（宿主 + 队列 + 生命周期，共用 ③ 的组件） |
+
+- **视觉与几何**：《Farris Web 基础视觉规范》（`@aihub/theme` 的令牌与组件实测值）
+- **令牌命名**：daisyUI 式语义槽位（`--ui-primary` / `--ui-base-content` / `--ui-info*` / `--ui-warning*` …，`default ≠ primary`）
+- **组件 API**：shadcn 通行词汇（变体维度 `tone` × `shape` × `size`、compound 点号子件、受控 prop + 语义事件）
+- **实现**：零依赖手写 CSS，类名 `.mh-*`（bem-lite）
+
+> **0.5.0（破坏性变更）**：`Section` 组件已退役 —— 它的「标题行 + 右端操作位（`extra`）」能力并入
+> **`Form.Header`**（支持 `title` / `description` / `extra`，且成员归位到表单最前）。
+> 旧写法 `Section` / `Form.Section` 统一改为 `Form.Header`；需要「区块分组」时用 `Panel` 或嵌套容器。
+
+## 安装
+
+```bash
+pnpm add @manohub/ui @manohub/theme
+```
+
+## 接入
+
+样式两行，顺序固定（先主题后组件面；若应用的样式链已级联本包，则不必单独引）：
+
+```css
+@import "@manohub/theme/default.css"; /* ① 全局令牌（值） */
+@import "@manohub/ui/styles.css"; /* ② 组件面（类 + 组件令牌值） */
+```
+
+只写静态页（不装 Vue）时引这两行即可 —— 类名与 `data-*` 状态协议直接可用。
+
+**② 的第一条 import 就是元素级 reset**（随包内置，不需要第三行），它只有两面：
+
+1. **盒模型**：`box-sizing: border-box` 覆盖容器、全部后代与伪元素（本包所有面的几何前提）；
+2. **容器基座**：`[data-manohub-ui]` 上的字族 / 字号 / 行高 / 字色 / 底色 / 整链高度（令牌的落点）。
+
+作用域锚 `[data-manohub-ui]` 且特异性为 0 —— 应用侧写任何元素选择器都能盖过它。
+**它有意不再归零标题字阶、列表序号、链接下划线、控件外观**：那些规则在 Tailwind 的层外
+（未分层 > 分层），会把消费方的工具类整片压住（`border*`、`img` 上的 `h-*`、`hidden` …）；
+需要归零的元素各自归到渲染它的组件面上（`img` 在 Avatar / Upload、`a` 在 Button、
+`textarea` 的 `resize` 在 `.mh-input--textarea`、`h1`-`h6` 在 `.mh-text`）。
+Tailwind 消费方另有 preflight 兜底，两者不冲突。
+
+所以**不必再自己写一份全局 reset**；也**不要**用元素级选择器去补（那正是被压住的成因）。
+
+本包**可独立发布**：组件与类型一律从 `@manohub/ui` 直接引；下游（如 `@manohub/kit`）若转出口，是下游自己的选择。
+
+```tsx
+import { Card, Form, Tree, Checkbox } from '@manohub/ui'
+```
+
+## 组件清单
+
+| 分组 | 组件 |
+|---|---|
+| 容器与分区 | `Page`（页面级骨架：`.Header` / `.Body` / `.Footer` / `.Filter` / `.Toolbar` / `.Split`）、`Panel`（+ `.Header` / `.Body` / `.Footer`）、`Card`（+ 三件）、`Nav`、`Layout`（`Layout.Row` 排「行」/ `Layout.Column` 排「列」：轴向 × 间距档 × 对齐） |
+| 数据展示 | `Tree`、`ListView`（+ `.CardItem`）、`Badge`、`Tag`（`Badge` 的可关闭 / 可新增封装） |
+| 展示 | `Avatar`（+ `.Group`）、`Skeleton`（行 / 列表 / 块状） |
+| 表单基础（**自绘**） | `Button`（+ `.Group` / `.Divider`；五型 / 小号 / 加载 / 菜单按钮 / 连体切换）、`Input`（+ `.Group` / `.Chip` / `.Display` / `.Textarea`；清除 / 可见性切换 / 校验）、`Search`（搜索框：值 / 搜索 / 清空三条回调）、`Select`（单选 / 多选 / 搜索 / 加载；面板用原生 popover）、`SelectTree`（树形态：仅叶子可选 + 本地过滤 + 命中高亮；与 `Select` 平级导出、共用触发器与面板）、`Switch`（表格档 / 表单档） |
+| 表单与选择 | `Form`（+ `.Header` / `.Item`；标签体系、成员归位、`v-model` 值收集与命令式 `clear()`）、`Filter`（+ `.Item`；`Form` 的壳：条件字段写成子件、控件自放、查询/重置与快照归一）、`Checkbox`、`Radio`（+ `.Group` / `.Card`；卡片式单选）、`Capsule`（胶囊选择器；胶囊 / 方形两档外形，与 `Tabs` 组合即页签） |
+| 反馈与三态 | `Notice`（条状提示）、`Notification`（通知卡：标题 + 头像 / 标签 / 操作 / 关闭位）、`QueryState`（三态容器；内建空 / 错误插画取自设计交付的四张 SVG，原样内联在 `src/utils/state-illustration.ts`）、`Loading`（转圈 + 遮罩：行内 / 区域 / 全屏三形态） |
+| 反馈与引导（**自绘**） | `Toast`（消息提示：语义四档 / loading + 可选动作 + 自动消失计时 + `.Stack` 堆叠）、`Steps`（步骤条：节点式 / 燕尾段式 / `.Progress` 进度条） |
+| 数据展示（**自绘**） | `Table`（列 × 数据 + 选择列 + 排序事件 + 固定表头 / 固定列 + 批量栏 / 合计行；排序与列宽拖拽算法归调用方）、`Pagination`（总数 / 每页条数 / 页码窗口 / 简单档 / 外框档）、`TabBar`（下划线页签 + 「更多」收纳） |
+| 内容与文件 | `CodeBlock`（**一族三件**：组合件 `CodeBlock` 按 `editable` 切只读 / 编辑两形态；`.View` 只读展示 —— 行内 chip / 代码块 + 语言角标 + 图标复制位；`.Editor` 可编辑 —— 等宽多行 + 按行自适应 / 限高内滚 / 只读、禁用）、`Upload`（+ `.Thumbs`；拖拽 / 点击上传区 + 已传文件列表） |
+| 浮层（**自绘**） | `Dialog`（原生 `<dialog>` + 模态皮肤；关闭受控）、`Tooltip`（**零 JS**：显隐与定位全走操作层 hover 档） |
+| 操作层（跨件原语） | `Collapse`（+ `.Stack`）、`Tabs`（+ `TabPanel`，面板切换骨架 —— 显隐归组件层，非零 JS 原语）；浮层只提供样式层（`styles/operations/popup.css`，零 JS 可直接用），Vue 浮层仍用 farris 适配件 |
+
+## 三态的操作按钮
+
+`QueryState` / `Tree` / `ListView` 的空态·错误态操作按钮就是**本包的 `Button`**（`variant="primary"`），
+与全站按钮同族 —— 应用**不需要**注入任何东西，只要把文案与回调给上：
+
+```vue
+<QueryState
+  :empty="list.length === 0"
+  empty-action-text="新建"
+  :on-empty-action="openCreate"
+>
+  <MyList />
+</QueryState>
+```
+
+- 要换外观：改主题令牌（`Button` 的外观档位是 `variant`）；
+- 要换结构（多个按钮 / 自定义动作区）：用 `actions` 插槽自绘。
+
+## 服务层（组件树之外调反馈）
+
+组件是**受控**的（可见性归调用方）；组件树之外（请求回调、路由守卫、工具函数里）要弹提示时用服务层：
+
+```ts
+import { toast, confirm, alert, showLoading, configureHost } from '@manohub/ui'
+
+toast('success', '保存成功')                                  // 3 秒自动消失
+toast('error', '导出失败', { action: { text: '重试', onClick: retry } })
+const pending = toast('loading', '正在导入…', { duration: 0 }) // 常驻，完成后自己收
+pending.close()
+
+if (await confirm({ title: '删除确认', detail: '删除后不可恢复', okDanger: true })) await remove()
+await alert({ title: '导入完成', detail: '共 128 条' })
+
+const done = showLoading('保存中…')   // 引用计数：并发调用要各关各的
+try { await save() } finally { done() }
+```
+
+**四件必须知道的事**：
+
+1. **服务层不新造浮层**：`toast()` 渲染的是本包的 `Toast`、`confirm()` 渲染的是本包的 `Dialog`、
+   `showLoading()` 渲染的是本包的 `Loading` —— 外观改一处两处一起变。
+2. **宿主即渲染位置**：解析顺序是「**显式 `configureHost(el)`** → 带 `[data-manohub-ui]` 作用域锚的容器
+   → `document.body`」。微前端下**必须落回本应用自己的容器**：本包全部令牌（全局值 + 组件值）都锚在
+   `[data-manohub-ui]` 上，落在容器外的浮层会「样式全丢」（变量解析为空 +
+   应用侧样式被 `scopecss` 前缀化后匹配不到）。骨架层只需在包裹节点上补一个
+   `data-manohub-ui` 属性，服务层不必反向依赖它。
+   注：`.app-container` 是 `@manohub/kit` 的输出类名（内部命名），**不是**跨包契约，服务层不认它。
+3. **按需挂载、自动收尾**：首次调用才建宿主与 Vue 实例（模块顶层零 DOM 操作）；
+   `toast` 队列空了、`loading` 计数归零即收掉宿主 —— 反复重挂不留悬挂实例。
+4. **`loading` 是引用计数语义**：并发的两次「显示」只关一次时遮罩仍在（先结束的那个不会把
+   别人的遮罩一起收掉）。推荐用返回的句柄在 `finally` 里关掉自己那一次。
+
+## 主题层
+
+全局令牌（`--ui-primary` / `--ui-space-*` / `--ui-font-*` 这类跨件共用的值）**不在本包**，已拆成独立包
+**`@manohub/theme`**（值层与面层分开：值随主题变、面不随主题变）。每个主题分五片：
+`colors` / `typography` / `spacing` / `radius` / `shadows`，一律锚定 **`[data-manohub-ui]`**
+（库品牌作用域锚；micro-app 的 scopecss 不作用域化 `:root`，定义在 `:root` 会泄漏到宿主）。
+
+只服务单一组件的令牌分两半落在本包：
+
+| 位置 | 内容 | 锚 |
+|---|---|---|
+| `styles/components/<件>.tokens.css` | **基础值**（唯一的、两套主题同值的那一条） | `[data-manohub-ui]` |
+| `styles/components/<件>.css` | **档位改写**（`.mh-<件>--<档>` 覆盖同一令牌）+ `--mh-*` 内部状态变量 | 元件根类 / 档位类 |
+
+后一半必须在面里：它们靠「同一元素上两个选择器改写同一个令牌」生效，搬走就断链。
+
+随包两套：
+
+| 主题 | 入口 | 锚点 | 取值来源 |
+|---|---|---|---|
+| `default` | `@manohub/theme/default.css` | `[data-manohub-ui]`（兜底套） | AIHub 品牌蓝（primary `#2660FF`）|
+| `farris` | `@manohub/theme/farris.css` | `[data-manohub-ui][data-theme='farris']` | 《Farris Web 基础视觉规范》（primary `#2a87ff`，色板编号 Th/Au/Ne/Te 逐条标注）|
+
+换皮只需给容器加属性（`createSubApp({ theme: 'farris' })` 会写 `data-theme`），不动类名、不动组件代码、不重打包。
+新增主题 = `packages/theme/src/<name>/` 新目录，令牌锚 `[data-manohub-ui][data-theme='<name>']`，
+且必须**全量覆盖** default 的令牌。
+
+局部换主题：在更深的容器上重设变量即可，例如 `.role-tree-pane { --ui-primary: #7C3AED; }`。

package/dist/components/form/index.js

@@ -111,7 +111,14 @@ const FormItem = /* @__PURE__ */ defineComponent({
         "data-invalid": props.error ? "true" : "false",
         "style": styles
       }, [showLabel ? createVNode("label", {
-        "class": "mh-form-item__label"
+        "class": "mh-form-item__label",
+        "onClick": (
+          // 只在真有点击可转发（有 tip ⇒ label 里才有 labelable 元素）时挂；理由见下方 ③
+          props.tip ? (event) => {
+            if (event.target?.closest(".mh-form-item__tip-btn")) return;
+            event.preventDefault();
+          } : void 0
+        )
       }, [createVNode("span", {
         "class": "mh-form-item__label-text"
       }, [props.label]), props.required ? createVNode("span", {

package/dist/styles/components/avatar.css

@@ -1,131 +1,131 @@
-/**
- * Avatar —— 头像（四档尺寸 / 文字 / 图标 / 占位 / 方角 / 带框 / 计数 / 头像组 / 角标）。
- *
- * 出处：`@aihub/theme` 的 `playground/components/avatar.css` 与 `src/components/avatar.css`
- * （实测四档 24 / 36 / 60 / 80；字母底色取主色；角标高 20 白描边）。
- *
- * 两条来自规范的硬结论，改前先读：
- * 1. **圆形裁切归图片自身，容器不裁**：角上的角标（`__badge`）与徽章（`__chip`）是绝对定位件，
- *    容器若带 `overflow: hidden`，会沿圆弧把它们各切掉一半（实测反馈）。故容器 `overflow: visible`，
- *    图片用 `border-radius: inherit` 跟着形态自裁。
- * 2. **头像组靠负边距堆叠**（`.mh-avatar-group`），每个头像带 2px 的底描边把相邻项隔开。
- */
-.mh-avatar {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  position: relative;
-  flex-shrink: 0;
-  overflow: visible; /* 见文件头第 1 条：裁切归图片 */
-  border-radius: var(--ui-radius-full);
-  background: var(--ui-base-400); /* Ne04 占位底 */
-  color: var(--ui-base-100); /* 占位前景 */
-}
-
-/* 图片：撑满 + 跟随形态自裁（否则去掉容器 overflow 后长宽不符的图会外溢）。
-   `display: block` 必须自己写：元素级基线不再把 `img` 转块级（那条会压消费方的 `h-*` / `hidden`），
-   否则行内基线间隙会把圆形头像顶偏。 */
-.mh-avatar > img {
-  display: block;
-  width: 100%;
-  height: 100%;
-  border-radius: inherit;
-  object-fit: cover;
-}
-
-/* ===== 尺寸四档 ===== */
-.mh-avatar--sm {
-  width: var(--ui-avatar-size-sm);
-  height: var(--ui-avatar-size-sm);
-  font-size: var(--ui-font-caption);
-}
-.mh-avatar--md {
-  width: var(--ui-avatar-size-md);
-  height: var(--ui-avatar-size-md);
-  font-size: var(--ui-font-caption);
-}
-.mh-avatar--lg {
-  width: var(--ui-avatar-size-lg);
-  height: var(--ui-avatar-size-lg);
-  font-size: var(--ui-font-title);
-}
-.mh-avatar--xl {
-  width: var(--ui-avatar-size-xl);
-  height: var(--ui-avatar-size-xl);
-  font-size: var(--ui-font-display);
-}
-
-/* ===== 内容形态 ===== */
-/* 文字头像：底取主色（业务要按人名哈希换色时给 `.mh-avatar--letter` 覆盖 background 即可） */
-.mh-avatar--letter {
-  background: var(--ui-primary);
-}
-/* 图标头像：图标由 @manohub/icon 渲染，这里只给尺寸档 */
-.mh-avatar--icon {
-  color: var(--ui-base-100);
-}
-/* 占位：虚线框 + 说明字（虚线线色取线型档，口径「实线 base-300 / 虚线 base-400」） */
-.mh-avatar--placeholder {
-  border: 1px dashed var(--ui-line-dashed);
-  background: var(--ui-base-100);
-  color: var(--ui-base-content-subtle);
-  font-size: var(--ui-font-caption);
-}
-/* 方角（商业图像）：圆角矩形 */
-.mh-avatar--square {
-  border-radius: var(--ui-radius-control);
-}
-/* 带框：靠阴影画出 2px 底环（不占布局，避免与角标抢位） */
-.mh-avatar--framed {
-  box-shadow: 0 0 0 2px var(--ui-base-100), var(--ui-shadow-card);
-}
-/* 计数档（头像组末位的「+N」） */
-.mh-avatar--count {
-  background: var(--ui-base-200);
-  color: var(--ui-base-content-muted);
-  font-size: var(--ui-font-caption);
-}
-
-/* ===== 角上外挂件（见文件头第 1 条：容器不裁，故它们不会被切）===== */
-.mh-avatar__badge {
-  position: absolute;
-  top: 0;
-  right: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  min-width: var(--ui-avatar-badge-size);
-  height: var(--ui-avatar-badge-size);
-  padding: 0 var(--ui-space-1);
-  border-radius: var(--ui-radius-full);
-  background: var(--ui-error); /* 红底（规范 Badge 专页实测） */
-  border: 2px solid var(--ui-base-100); /* 白描边 */
-  color: var(--ui-error-content);
-  font-size: var(--ui-font-caption);
-}
-.mh-avatar__chip {
-  position: absolute;
-  right: -2px;
-  bottom: -2px;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 24px;
-  height: 24px;
-  border-radius: var(--ui-radius-full);
-  background: var(--ui-primary);
-  border: 2px solid var(--ui-base-100);
-  cursor: pointer;
-}
-
-/* ===== 头像组：负边距堆叠，靠 2px 底描边分隔 ===== */
-.mh-avatar-group {
-  display: inline-flex;
-  align-items: center;
-}
-.mh-avatar-group .mh-avatar {
-  border: 2px solid var(--ui-base-100);
-}
-.mh-avatar-group .mh-avatar + .mh-avatar {
-  margin-left: calc(-1 * var(--ui-avatar-gap));
-}
+/**
+ * Avatar —— 头像（四档尺寸 / 文字 / 图标 / 占位 / 方角 / 带框 / 计数 / 头像组 / 角标）。
+ *
+ * 出处：`@aihub/theme` 的 `playground/components/avatar.css` 与 `src/components/avatar.css`
+ * （实测四档 24 / 36 / 60 / 80；字母底色取主色；角标高 20 白描边）。
+ *
+ * 两条来自规范的硬结论，改前先读：
+ * 1. **圆形裁切归图片自身，容器不裁**：角上的角标（`__badge`）与徽章（`__chip`）是绝对定位件，
+ *    容器若带 `overflow: hidden`，会沿圆弧把它们各切掉一半（实测反馈）。故容器 `overflow: visible`，
+ *    图片用 `border-radius: inherit` 跟着形态自裁。
+ * 2. **头像组靠负边距堆叠**（`.mh-avatar-group`），每个头像带 2px 的底描边把相邻项隔开。
+ */
+.mh-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  flex-shrink: 0;
+  overflow: visible; /* 见文件头第 1 条：裁切归图片 */
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-base-400); /* Ne04 占位底 */
+  color: var(--ui-base-100); /* 占位前景 */
+}
+
+/* 图片：撑满 + 跟随形态自裁（否则去掉容器 overflow 后长宽不符的图会外溢）。
+   `display: block` 必须自己写：元素级基线不再把 `img` 转块级（那条会压消费方的 `h-*` / `hidden`），
+   否则行内基线间隙会把圆形头像顶偏。 */
+.mh-avatar > img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+  object-fit: cover;
+}
+
+/* ===== 尺寸四档 ===== */
+.mh-avatar--sm {
+  width: var(--ui-avatar-size-sm);
+  height: var(--ui-avatar-size-sm);
+  font-size: var(--ui-font-caption);
+}
+.mh-avatar--md {
+  width: var(--ui-avatar-size-md);
+  height: var(--ui-avatar-size-md);
+  font-size: var(--ui-font-caption);
+}
+.mh-avatar--lg {
+  width: var(--ui-avatar-size-lg);
+  height: var(--ui-avatar-size-lg);
+  font-size: var(--ui-font-title);
+}
+.mh-avatar--xl {
+  width: var(--ui-avatar-size-xl);
+  height: var(--ui-avatar-size-xl);
+  font-size: var(--ui-font-display);
+}
+
+/* ===== 内容形态 ===== */
+/* 文字头像：底取主色（业务要按人名哈希换色时给 `.mh-avatar--letter` 覆盖 background 即可） */
+.mh-avatar--letter {
+  background: var(--ui-primary);
+}
+/* 图标头像：图标由 @manohub/icon 渲染，这里只给尺寸档 */
+.mh-avatar--icon {
+  color: var(--ui-base-100);
+}
+/* 占位：虚线框 + 说明字（虚线线色取线型档，口径「实线 base-300 / 虚线 base-400」） */
+.mh-avatar--placeholder {
+  border: 1px dashed var(--ui-line-dashed);
+  background: var(--ui-base-100);
+  color: var(--ui-base-content-subtle);
+  font-size: var(--ui-font-caption);
+}
+/* 方角（商业图像）：圆角矩形 */
+.mh-avatar--square {
+  border-radius: var(--ui-radius-control);
+}
+/* 带框：靠阴影画出 2px 底环（不占布局，避免与角标抢位） */
+.mh-avatar--framed {
+  box-shadow: 0 0 0 2px var(--ui-base-100), var(--ui-shadow-card);
+}
+/* 计数档（头像组末位的「+N」） */
+.mh-avatar--count {
+  background: var(--ui-base-200);
+  color: var(--ui-base-content-muted);
+  font-size: var(--ui-font-caption);
+}
+
+/* ===== 角上外挂件（见文件头第 1 条：容器不裁，故它们不会被切）===== */
+.mh-avatar__badge {
+  position: absolute;
+  top: 0;
+  right: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-width: var(--ui-avatar-badge-size);
+  height: var(--ui-avatar-badge-size);
+  padding: 0 var(--ui-space-1);
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-error); /* 红底（规范 Badge 专页实测） */
+  border: 2px solid var(--ui-base-100); /* 白描边 */
+  color: var(--ui-error-content);
+  font-size: var(--ui-font-caption);
+}
+.mh-avatar__chip {
+  position: absolute;
+  right: -2px;
+  bottom: -2px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 24px;
+  height: 24px;
+  border-radius: var(--ui-radius-full);
+  background: var(--ui-primary);
+  border: 2px solid var(--ui-base-100);
+  cursor: pointer;
+}
+
+/* ===== 头像组：负边距堆叠，靠 2px 底描边分隔 ===== */
+.mh-avatar-group {
+  display: inline-flex;
+  align-items: center;
+}
+.mh-avatar-group .mh-avatar {
+  border: 2px solid var(--ui-base-100);
+}
+.mh-avatar-group .mh-avatar + .mh-avatar {
+  margin-left: calc(-1 * var(--ui-avatar-gap));
+}