@manohub/ui 0.10.5 → 1.0.1

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/components/input/bordered.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `bordered` 三档 → 控件类名（**唯一来源**）。
+ *
+ * 输入族三个件（`Input` / `Textarea` / `NumberInput`）共用同一份面与同一个 prop，判定表抄三份必然漂，
+ * 故收在这里。类名口径：prop 是**肯定式**（`bordered`）、类名是**否定式**（`--borderless`）——
+ * 那一对的反差是库内既定口径（见 `docs/guide/naming-and-defaults.md` §2.1）；
+ * `'focus'` 档的类名 `--border-on-focus` 是这套口径下的新成员：它说的就是「聚焦时才有框」。
+ *
+ * | `bordered` | 类名 | 常态 | 悬停 | 聚焦 |
+ * | --- | --- | --- | --- | --- |
+ * | `true`（缺省） | （无） | 有框 | 框变色 | 框变色 + 主色环 |
+ * | `'focus'` | `.mh-input--border-on-focus` | 无框无底 | 复用有框档那句 | 显框 + 主色环（复用） |
+ * | `false` | `.mh-input--borderless` | 无框无底 | 无 | 无（本档效果只有一种） |
+ */
+export declare const borderedClassOf: (bordered: boolean | "focus" | undefined) => string;

package/dist/components/input/bordered.js

@@ -0,0 +1,8 @@
+const borderedClassOf = (bordered) => {
+  if (bordered === "focus") return "mh-input--border-on-focus";
+  if (bordered === false) return "mh-input--borderless";
+  return "";
+};
+export {
+  borderedClassOf
+};

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

@@ -109,11 +109,19 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
-     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     * 有无边框，三档（判定表见 `./bordered.ts`，输入族三件共用）：
+     *
+     * - `true`（缺省）**常有框**；
+     * - `false` **无框** —— 常态、悬停、聚焦都不出现（本档的效果只有一种）；
+     * - `'focus'` **聚焦（与悬停）才显出框** —— 行内编辑那档：常态看着像「值」，点进去才亮框；
+     *   悬停 / 聚焦的表现**复用有框档那两条**，不另写一套。
+     *
+     * 配 `readonly` 即**只读值档**（摘要 / 详情里回显业务值的推荐写法，也是 `Form.Item` 的
+     * `readonly` 行配的那一档）：几何与可编辑输入框完全一致，但不给任何「可编辑」线索。
+     * 只读值档请写 `readonly` + `bordered={false}`；`readonly` + `'focus'` 会被中和（兜底，不推荐）。
      */
     bordered: {
-        type: BooleanConstructor;
+        type: PropType<boolean | "focus">;
         default: boolean;
     };
     maxlength: {
@@ -228,11 +236,19 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
         default: boolean;
     };
     /**
-     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
-     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     * 有无边框，三档（判定表见 `./bordered.ts`，输入族三件共用）：
+     *
+     * - `true`（缺省）**常有框**；
+     * - `false` **无框** —— 常态、悬停、聚焦都不出现（本档的效果只有一种）；
+     * - `'focus'` **聚焦（与悬停）才显出框** —— 行内编辑那档：常态看着像「值」，点进去才亮框；
+     *   悬停 / 聚焦的表现**复用有框档那两条**，不另写一套。
+     *
+     * 配 `readonly` 即**只读值档**（摘要 / 详情里回显业务值的推荐写法，也是 `Form.Item` 的
+     * `readonly` 行配的那一档）：几何与可编辑输入框完全一致，但不给任何「可编辑」线索。
+     * 只读值档请写 `readonly` + `bordered={false}`；`readonly` + `'focus'` 会被中和（兜底，不推荐）。
      */
     bordered: {
-        type: BooleanConstructor;
+        type: PropType<boolean | "focus">;
         default: boolean;
     };
     maxlength: {
@@ -289,7 +305,7 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
     type: string;
     onChange: (v: string) => void;
     invalid: boolean;
-    bordered: boolean;
+    bordered: boolean | "focus";
     defaultValue: string;
     placeholder: string;
     autofocus: boolean;
@@ -297,10 +313,10 @@ export declare const Input: import("vue").DefineComponent<import("vue").ExtractP
     status: InputStatus;
     as: "button" | "input";
     readonly: boolean;
+    onEnter: (v: string) => void;
     clearable: boolean;
     maxlength: number;
     showCount: boolean;
-    onEnter: (v: string) => void;
     controlClass: string;
     controlAttrs: Record<string, unknown>;
     hasValue: boolean;
@@ -328,8 +344,8 @@ export interface TextareaProps {
     invalid?: boolean;
     /** 校验状态（`invalid` 的显式写法） */
     status?: InputStatus;
-    /** 是否带边框 */
-    bordered?: boolean;
+    /** 是否带边框（三档口径见 `Input` 的同名 prop：`true` / `false` / `'focus'`） */
+    bordered?: boolean | 'focus';
     maxlength?: number;
     /** 右下角字数统计（须给 `maxlength` 才渲染） */
     showCount?: boolean;
@@ -388,8 +404,9 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
         type: PropType<InputStatus>;
         default: undefined;
     };
+    /** 是否带边框（三档口径见 `Input` 的同名 prop：`true` 常有框 / `false` 无框 / `'focus'` 聚焦才显框） */
     bordered: {
-        type: BooleanConstructor;
+        type: PropType<boolean | "focus">;
         default: boolean;
     };
     maxlength: {
@@ -453,8 +470,9 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
         type: PropType<InputStatus>;
         default: undefined;
     };
+    /** 是否带边框（三档口径见 `Input` 的同名 prop：`true` 常有框 / `false` 无框 / `'focus'` 聚焦才显框） */
     bordered: {
-        type: BooleanConstructor;
+        type: PropType<boolean | "focus">;
         default: boolean;
     };
     maxlength: {
@@ -481,7 +499,7 @@ export declare const Textarea: import("vue").DefineComponent<import("vue").Extra
     disabled: boolean;
     onChange: (v: string) => void;
     invalid: boolean;
-    bordered: boolean;
+    bordered: boolean | "focus";
     defaultValue: string;
     placeholder: string;
     rows: number;
@@ -558,11 +576,19 @@ export declare const InputCompound: {
             default: boolean;
         };
         /**
-         * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
-         * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+         * 有无边框，三档（判定表见 `./bordered.ts`，输入族三件共用）：
+         *
+         * - `true`（缺省）**常有框**；
+         * - `false` **无框** —— 常态、悬停、聚焦都不出现（本档的效果只有一种）；
+         * - `'focus'` **聚焦（与悬停）才显出框** —— 行内编辑那档：常态看着像「值」，点进去才亮框；
+         *   悬停 / 聚焦的表现**复用有框档那两条**，不另写一套。
+         *
+         * 配 `readonly` 即**只读值档**（摘要 / 详情里回显业务值的推荐写法，也是 `Form.Item` 的
+         * `readonly` 行配的那一档）：几何与可编辑输入框完全一致，但不给任何「可编辑」线索。
+         * 只读值档请写 `readonly` + `bordered={false}`；`readonly` + `'focus'` 会被中和（兜底，不推荐）。
          */
         bordered: {
-            type: BooleanConstructor;
+            type: PropType<boolean | "focus">;
             default: boolean;
         };
         maxlength: {
@@ -621,7 +647,7 @@ export declare const InputCompound: {
         type: string;
         onChange: (v: string) => void;
         invalid: boolean;
-        bordered: boolean;
+        bordered: boolean | "focus";
         defaultValue: string;
         placeholder: string;
         autofocus: boolean;
@@ -629,10 +655,10 @@ export declare const InputCompound: {
         status: InputStatus;
         as: "button" | "input";
         readonly: boolean;
+        onEnter: (v: string) => void;
         clearable: boolean;
         maxlength: number;
         showCount: boolean;
-        onEnter: (v: string) => void;
         controlClass: string;
         controlAttrs: Record<string, unknown>;
         hasValue: boolean;
@@ -711,11 +737,19 @@ export declare const InputCompound: {
             default: boolean;
         };
         /**
-         * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
-         * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+         * 有无边框，三档（判定表见 `./bordered.ts`，输入族三件共用）：
+         *
+         * - `true`（缺省）**常有框**；
+         * - `false` **无框** —— 常态、悬停、聚焦都不出现（本档的效果只有一种）；
+         * - `'focus'` **聚焦（与悬停）才显出框** —— 行内编辑那档：常态看着像「值」，点进去才亮框；
+         *   悬停 / 聚焦的表现**复用有框档那两条**，不另写一套。
+         *
+         * 配 `readonly` 即**只读值档**（摘要 / 详情里回显业务值的推荐写法，也是 `Form.Item` 的
+         * `readonly` 行配的那一档）：几何与可编辑输入框完全一致，但不给任何「可编辑」线索。
+         * 只读值档请写 `readonly` + `bordered={false}`；`readonly` + `'focus'` 会被中和（兜底，不推荐）。
          */
         bordered: {
-            type: BooleanConstructor;
+            type: PropType<boolean | "focus">;
             default: boolean;
         };
         maxlength: {
@@ -772,7 +806,7 @@ export declare const InputCompound: {
         type: string;
         onChange: (v: string) => void;
         invalid: boolean;
-        bordered: boolean;
+        bordered: boolean | "focus";
         defaultValue: string;
         placeholder: string;
         autofocus: boolean;
@@ -780,10 +814,10 @@ export declare const InputCompound: {
         status: InputStatus;
         as: "button" | "input";
         readonly: boolean;
+        onEnter: (v: string) => void;
         clearable: boolean;
         maxlength: number;
         showCount: boolean;
-        onEnter: (v: string) => void;
         controlClass: string;
         controlAttrs: Record<string, unknown>;
         hasValue: boolean;
@@ -855,11 +889,19 @@ export declare const InputCompound: {
         default: boolean;
     };
     /**
-     * 是否带边框；`false` 用于表格内编辑 / 行内编辑（无框、无底，靠悬停与聚焦给反馈）。
-     * 配 `readonly` 即**只读值档**：连悬停底与聚焦框环都退掉（见 `readonly`）。
+     * 有无边框，三档（判定表见 `./bordered.ts`，输入族三件共用）：
+     *
+     * - `true`（缺省）**常有框**；
+     * - `false` **无框** —— 常态、悬停、聚焦都不出现（本档的效果只有一种）；
+     * - `'focus'` **聚焦（与悬停）才显出框** —— 行内编辑那档：常态看着像「值」，点进去才亮框；
+     *   悬停 / 聚焦的表现**复用有框档那两条**，不另写一套。
+     *
+     * 配 `readonly` 即**只读值档**（摘要 / 详情里回显业务值的推荐写法，也是 `Form.Item` 的
+     * `readonly` 行配的那一档）：几何与可编辑输入框完全一致，但不给任何「可编辑」线索。
+     * 只读值档请写 `readonly` + `bordered={false}`；`readonly` + `'focus'` 会被中和（兜底，不推荐）。
      */
     bordered: {
-        type: BooleanConstructor;
+        type: PropType<boolean | "focus">;
         default: boolean;
     };
     maxlength: {
@@ -918,7 +960,7 @@ export declare const InputCompound: {
     type: string;
     onChange: (v: string) => void;
     invalid: boolean;
-    bordered: boolean;
+    bordered: boolean | "focus";
     defaultValue: string;
     placeholder: string;
     autofocus: boolean;
@@ -926,10 +968,10 @@ export declare const InputCompound: {
     status: InputStatus;
     as: "button" | "input";
     readonly: boolean;
+    onEnter: (v: string) => void;
     clearable: boolean;
     maxlength: number;
     showCount: boolean;
-    onEnter: (v: string) => void;
     controlClass: string;
     controlAttrs: Record<string, unknown>;
     hasValue: boolean;
@@ -980,8 +1022,9 @@ export declare const InputCompound: {
             type: PropType<InputStatus>;
             default: undefined;
         };
+        /** 是否带边框（三档口径见 `Input` 的同名 prop：`true` 常有框 / `false` 无框 / `'focus'` 聚焦才显框） */
         bordered: {
-            type: BooleanConstructor;
+            type: PropType<boolean | "focus">;
             default: boolean;
         };
         maxlength: {
@@ -1045,8 +1088,9 @@ export declare const InputCompound: {
             type: PropType<InputStatus>;
             default: undefined;
         };
+        /** 是否带边框（三档口径见 `Input` 的同名 prop：`true` 常有框 / `false` 无框 / `'focus'` 聚焦才显框） */
         bordered: {
-            type: BooleanConstructor;
+            type: PropType<boolean | "focus">;
             default: boolean;
         };
         maxlength: {
@@ -1073,7 +1117,7 @@ export declare const InputCompound: {
         disabled: boolean;
         onChange: (v: string) => void;
         invalid: boolean;
-        bordered: boolean;
+        bordered: boolean | "focus";
         defaultValue: string;
         placeholder: string;
         rows: number;
@@ -1102,3 +1146,10 @@ export declare const InputCompound: {
     }>, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 };
 export type InputCompoundType = typeof InputCompound;
+/**
+ * 数字输入与 `Input` **同族**（同一个表壳 / 内距 / 状态协议，同一份面 `input.css`），
+ * 故与 `Textarea` 同款处置：**平级导出、共用本目录**（`AGENTS.md` 硬约束 1）。
+ * 它**不是** `Input` 的点号成员 —— 成员位留给「同一件自己的形态」（`.Textarea` / `.Display`），
+ * 而数字输入是另一件（值模型 `number | null` vs `string`）。
+ */
+export { NumberInput, type NumberInputProps } from './number-input';