@manohub/kit 0.6.1 → 0.7.1

package/skills/kit-migrate/references/migration-map.md

@@ -1,294 +1,294 @@
-# 替换映射表：`App*` / 底层组件库 → `@manohub/ui`
-
-0.6.0 起本包不再提供组件。**组件与服务一律从 `@manohub/ui` 引**（无前缀名），
-farris（底层组件库）也不再是依赖。
-
-按类目查；查不到时按 `CONTRACT.md` §8 缺件处置流程办。**逐文件的操作口径与盘点登记格式见
-`migration-playbook.md`。**
-
-> 读法：`旧` → `新`。**只有一行的地方表示「零改动，只换名字」**；
-> 带 ⚠️ 的是必须人工判断的语义差异。
-
----
-
-## 零、0.6.0 增量（主题独立成包 + 容器锚改名 + kit 零样式）
-
-只在**已按 0.6.0 迁完**的仓上做，四步：
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `@import "@manohub/kit/styles.css"` | **删掉**，改引 `@manohub/theme/default.css` + `@manohub/ui/styles.css` | kit **不再发布任何样式**（`src/styles/` 整体删除）：样式汇总入口、reset、富文本预设全没了 |
-| `@import "@manohub/kit/reset.css"` | **删掉**（或应用自己补一份 reset） | 同上；reset 的归属随样式一并退场 |
-| `@import "@manohub/ui/theme/default.css"` | `@import "@manohub/theme/default.css"` | 全局令牌已独立成 **`@manohub/theme`**；ui 的 `theme/*` 出口**已删**（无兼容指针） |
-| `@import "@manohub/ui/theme/farris.css"` | `@import "@manohub/theme/farris.css"` | 同上；用非兜底主题时把它替换掉上面那条 ① |
-| 容器上的 `data-app-container` | **`data-manohub-ui`** | 跨包唯一作用域锚，由入口层**无条件**写；旧属性不再被任何一方识别（无兼容别名） |
-| 依赖里只有 `@manohub/{kit,ui}` | 再加 **`@manohub/theme`** | 样式链第一行由应用直接引它（kit 不再代引） |
-
-- **样式链现在归应用自己**：两行（令牌 → 组件面）+ 应用自身一行，顺序不可换（契约 §1.2）。
-- **reset 与富文本排版要自己补**：原来的 `@manohub/kit/reset.css` 与 `.app-markdown` 预设已删除；
-  富文本排版目前没有合规归属（契约 §10「已知缺口」，其余样式纪律仍然生效）。
-- **自建容器（不走 `createSubApp`）必须自己带 `data-manohub-ui`** —— 不带的话不只丢色，
-  连 `--ui-button-height` 这类几何令牌也拿不到（组件令牌的基础值也锚在容器上）。
-- 类名 `class="app-container"` **不必动**：0.6.0 起降级为 kit 内部命名，不再是跨包约定。
-- 深引内部路径（`@manohub/theme/dist/...`、`@manohub/ui/dist/...`）属契约 §6 L3-1
-  **import 源白名单**之外 —— 一律改走公开入口。
-
----
-
-## 一、页面骨架：`AppShell` → `Page`
-
-`Page` 的能力**覆盖并超过** `AppShell`：成员按类型归位、`Split` 内建拖拽调宽与收起展开。
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `AppShell` | `Page` | 每页唯一 |
-| `AppShell.Header` | `Page.Header` | |
-| `AppShell.Header` 的 `toolbar` prop / `toolbar` 插槽 | `Page.Header` 的 **`extra`** | ⚠️ prop 与插槽**都改名** |
-| `AppShell.Header` 的 `tabs` prop / `tabs` 插槽 | **无对应** | ⚠️ 页头下的页签区改到主体内：`Tabs`（纯页签条）或 `Tabset`（条 + 面板） |
-| `AppShell.Toolbar` | **无对应** | ⚠️ 页面级工具条用 `Page.Filter`，或把控件放 `Page.Header.extra` |
-| `AppShell.Filter` | `Page.Filter` | |
-| `AppShell.Body` | `Page.Body` | `mode` 取值不变（`scroll` / `plain`） |
-| `AppShell.Footer` | `Page.Footer` | |
-| `AppShell.Split` | `Page.Split` | `sidebar` / `rightSidebar` 形状不变；多出「收起动画期内容定宽」 |
-| — | `Page.Header` 的 `subTitle` / `icon` | 旧 `AppShell.Header` 没有这两项 |
-
-**骨架本身不变**：高度仍取 `100%`（禁 `100vh`）、两级滚动归属仍在（契约 §5 组 4）。
-
-⚠️ **迁移期最容易踩的归位坑**：`Page` 的成员**不按书写顺序渲染**，且**必须是 `Page` 的直接子节点**。
-把成员包进 `<template v-if>` 会编译成 Fragment，归位认不出它 —— 该成员会被当自由内容挪进主体区
-（契约 §5 组 2）。旧 `AppShell` 没有这个约束，迁移时要逐个核对。
-
----
-
-## 二、组件对照
-
-### 2.1 零改动（只换名字）
-
-| 旧 | 新 |
-|---|---|
-| `AppPanel` / `AppPanel.Header` / `.Body` / `.Footer` | `Panel` / `Panel.Header` / `.Body` / `.Footer` |
-| `AppCard` / `AppCard.Header` / `.Body` / `.Footer` | `Card` / 同名成员 |
-| `AppListView` / `AppListView.CardItem` | `ListView` / `ListView.CardItem` |
-| `AppTree` | `Tree` |
-| `AppNav` | `Nav` |
-| `AppQueryState` | `QueryState` |
-| `AppStateIllustrationEmpty` / `AppStateIllustrationError` | 不再有独立插画件：空 / 错误两态由 `QueryState` 内建（设计交付的 SVG 原样内联在其 `src/utils/state-illustration.ts`）。要成功 / 异常图形时走 `QueryState` 的 `illustration` 或自备图片 |
-| `AppCheckbox` | `Checkbox`（+ `Checkbox.Group`） |
-| `AppNotice` | `Notice` |
-| `AppBadge` | `Badge` |
-| `AppForm` / `AppForm.Item` | `Form` / `Form.Item` |
-
-可选新能力（不是必须改）：`Card` 的根件 `title`/`subtitle`/`icon`、`Tree` 的 `defaultExpandAll`、
-`Nav` 的 `bordered`、`ListView` 的 `columns`、`Badge` 的 `count`/`status`、
-`QueryState` 的 `illustrationSize`、`Form.Item` 的 `name`（可拿 `{ value, setValue }`）。
-
-⚠️ `Card` 的**内距口径变了**：旧 `AppCard` 根件有 `padding`，新的 `Card` 根件不出内距
-（内距只在 `Header`/`Body`/`Footer` 段上）。改写：把根件的 `padding` 移到三段，或改令牌 `--mh-card-padding`。
-
-### 2.2 有 prop 差异
-
-#### Button
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `tone="primary"` | `variant="primary"` | 缺省档从 `primary` 变成 **`secondary`** |
-| `tone="default"` / `"secondary"` | `variant="secondary"` | |
-| `tone="error"` | `variant="primary" danger` | |
-| `tone="success"` / `"warning"` / `"info"` | **无色档** | ⚠️ 改用 `variant="primary"`/`"secondary"`，或换件（`Badge` / `Tag` / `Notice` 承担语义色） |
-| `shape="link"` | `variant="link"` | ⚠️ `shape` 换域了 |
-| `shape="ghost"` | `variant="icon"`（纯图标）或 `variant="text"` | |
-| `shape="solid"` / `"soft"` / `"outline"` | **无对应** | ⚠️ 由 `variant`（六型）表达 |
-
-新能力：`block` / `shape="round"｜"circle"` / `icon` / `trailingIcon` / `caret` / `menu` / `href`。
-
-#### Input / Textarea
-
-| 旧 | 新 |
-|---|---|
-| 尾缀内容放默认插槽 | ⚠️ 改放 **`#suffix`**（单行不再渲染默认插槽）；前置放 `#prefix` |
-| `autoComplete` | **无对应** | ⚠️ 不落到控件上；确需防回填用原生 attrs（`controlAttrs`） |
-| `Textarea` 的 `maxLength` | **`maxlength`** | ⚠️ 大小写 |
-| — | `Input` 新增 `onEnter` / `showCount` / `invalid` / `status` / `bordered` |
-
-#### Select
-
-| 旧 | 新 |
-|---|---|
-| `placeholder` 缺省空串 | 缺省 `'请选择'` |
-| `readonly` | **无对应** | ⚠️ 用 `disabled` 顶 |
-| `popupHost` | **无对应** | ⚠️ 面板用原生 popover，宿主概念不再需要 |
-| — | 新增 `multiple` / `searchable` / `allowCreate` / `loading` / `maxTagCount` / `status` |
-
-#### Switch / Radio / Checkbox
-
-- `AppSwitch` → `Switch`：⚠️ `size` 缺省从 `sm` 变成 `md`；⚠️ **`onChange` 的返回值契约消失**
-  （旧代码靠返回 `false` / reject 让开关回退视觉 —— 回退逻辑要搬进调用方：`onChange` 里判失败再改回 `modelValue`）。
-- `AppRadioCard` → `Radio.Card`：⚠️ **缺省选中语义变了** —— `Radio.Card` 是单选组，
-  「可全不选」的旧行为要显式处理（组件缺省会选中第一个可选项）。
-- `AppCheckbox` → `Checkbox`：零改动。
-
-#### Tooltip
-
-| 旧 | 新 |
-|---|---|
-| `placement="top"` | `side="top"`（可加 `align`） |
-| `width`（固定宽） | **无对应** | ⚠️ 用 `#content` 插槽内的元素自己限宽 |
-| `disabled` | **无对应** | ⚠️ 不渲染触发器的提示即可 |
-
-新能力：`title` / `action` / `guide` / `onAction`。
-
-#### Table（差异最大）
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `rows` | **`data`** | |
-| `rowKey` 必填业务字段 | `rowKey` 缺省 `'id'` | |
-| `stripe` | **`striped`** | |
-| `selection={{ mode, selected, onSelectedChange, selectable, onSelectAll }}` | `selectable` + `modelValue`（keys 数组）+ `change` | ⚠️ **只有多选**；单选 / 谓词 / `onSelectAll` / 增量语义**无对应** |
-| `columns[].title` 可以是函数 / `render` | `title` 只接受 string，单元格内容走 **`#cell` 插槽**（`{ row, column, value, index }`） | ⚠️ 渲染路径变了 |
-| `columns[].width` 数字权重 | `width` 字符串（`'120px'` / `'20%'`） | |
-| `error` / `errorTitle` / `emptyDescription` / `*ActionText` / `on*Action` | **无对应** | ⚠️ 错误态用 `QueryState` 包住表格；空态用 `emptyText` / `#empty` |
-| `loading`（骨架替换整表） | `loading`（内容上盖罩 + 转圈，行高不塌） | ⚠️ 观感不同 |
-| `rowNumber` / `rowHeight` / `headerHeight` / `framed` | **无对应** | ⚠️ 序号自加一列；外框由承载它的 `Panel` 给 |
-| `refreshKey` / `rowHighlightKey` / `tableKey` / `onContainerResize` / `resizePollInterval` | **无对应** | ⚠️ 自绘表不吃上游「挂载时固化列宽」的问题，整组逃生舱一并退场 |
-| `onRowClick` / `onRowDoubleClick` | `onRow(row, index) => ({ class, onClick })` | ⚠️ **无双击** |
-| — | 新增 `sortKey` / `sortOrder` / `onSort` / `expandable` / `expandedKeys` / `stickyHead` / `stickyCol` / `pagination` | |
-
-> 旧 `AppTable` 有一条「回调交回的行对象必须是消费方那一个」的契约（内部副本挂了非枚举回引）。
-> 新 `Table` 不存在副本问题 —— 交回的就是 `data` 里的那一项。
-
-#### Pagination
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `page`（**0 基**，必填） | `modelValue`（**1 基**，`v-model`） | ⚠️ **差 1**，是最容易漏的一处 |
-| `onPageChange(page)` | `update:modelValue` / `change`（载荷是 **`number`**） | ⚠️ 不再是 `{ page, pageSize }` 对象 |
-| `onPageSizeChange(size)` | `update:pageSize`（`v-model:page-size`） | 两个事件各管各的 |
-| `showInfo` | **无对应** | ⚠️ 「共 n 条」默认就有；要改文案用 `#total` 槽 |
-| — | 新增 `showSizeChanger` / `showQuickJumper` / `simple` / `boxed` / `hideOnSinglePage` | |
-
-> 注意 `Table` 的 `pagination` prop 与独立的 `Pagination` **不是同一套入参**：
-> 前者是 `{ total, current?, pageSize?, pageSizeOptions?, onChange? }`（`onChange` 收页码），
-> 后者是受控的 `v-model` / `v-model:page-size`。
-
-#### Dialog
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `width={640}`（数值，缺省 640） | `width` 缺省 **`'md'`（520）** | ⚠️ 缺省宽度变窄，要 640 就显式传 |
-| `beforeClose`（关闭拦截） | **无对应** | ⚠️ 拦截逻辑移到 `onCancel` / `onClose` 里自己把关（组件只回调） |
-| `height` / `minHeight` / `fitContent` / `showHeader` / `showButtons` | **无对应** | ⚠️ 固定高度用 `#default` 内的容器自己定高；不显示页头用 `:closable="false"` + 不给 `title` |
-| — | 新增 `okText` / `cancelText` / `okDanger` / `confirmLoading` / `showFooter` / `onOk` / `onCancel` / `onClose` / `closeOnBackdrop` / `keyboard` | |
-
-`Dialog` 走**原生 `<dialog>`**：遮罩、Esc、焦点陷阱归浏览器；**开合受控**
-（关闭位 / Esc / 点遮罩都只回调，可见性归调用方）。`onOk` 返回 Promise 时确定按钮自动进加载态。
-
-#### Steps
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `items` | **`steps`** | ⚠️ 形状变：丢 `key` / `disabled`，新增 `icon` |
-| `modelValue`（0 基） | `current`（0 基，基址不变） | |
-| `clickable` / `onBeforeChange` / `onChange` | **无对应** | ⚠️ 步骤条是**只读展现**；跳转与门控搬到页面（按钮 + 自己的校验） |
-| `fill` | **无对应** | |
-| — | 新增 `variant`（`node` / `bar`）/ `size` / `Steps.Progress` | |
-
-#### Tabs
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `modelValue`（必填） | `value`（缺省第一项）/ `defaultValue` | |
-| `items=[{ key, label }]` | `options=[{ label, value }]` | ⚠️ `key` → `value` |
-| **按 `item.key` 命名的内容插槽**（自带面板切换） | `Tabs` **无内容槽** | ⚠️ 要「条 + 面板」用 `Tabset`（`default` 放面板 + `selector`）；只要页签条用 `Tabs` |
-| `fill` | **无对应** | |
-
-#### Filter
-
-| 旧 | 新 | 说明 |
-|---|---|---|
-| `fields=[…]` 声明式（必填） | **`Filter.Item` 子件**（`code` / `label` + 控件自放） | ⚠️ 模型从「声明字段表」变「写子件」 |
-| `defaults` | `defaultValue`（键从「字段 id」变「条件名 code」） | |
-| `searchFields` / `searchPlaceholder` / `keywordCodes` | **无对应** | ⚠️ 「关键字」写成普通 `Filter.Item` + `Input` |
-| `appFilterSelect` / `appFilterInput` 工厂 | **无对应** | ⚠️ 控件直接写 `Select` / `Input` |
-| `onChange(values, meta)` / `onQuery(values, meta)` | `onChange(values)` / `onQuery(values)` | ⚠️ **丢 `meta`**（关键字 / 查询态由页面自持） |
-| `inline` / `expanded` / `readyTries` / `ignoreInitialEmpty` / `onReady` | **无对应** | ⚠️ 就绪时序归页面 |
-| — | 新增 `title` / `description` / `queryText` / `resetText` / `showReset` / `onReset` | |
-
-#### Input 的组合形态
-
-`AppSearchBox` → **`Search`**：`modelValue` / `placeholder` / `disabled` / `size` / `clearable` /
-`loading` / `searchText` 同名同义；`onChange` / `onSearch` / `onClear` 三条回调保留（`onClear` 的补发判据内建）。
-
-#### 旧有新无的其余项
-
-| 旧 | 处置 |
-|---|---|
-| `AppIconButton` | 改用 `Button variant="icon"`（⚠️ 缺省 `size` 从 `sm` 变 `md`，要小号显式传）；无可见文案时给 `title` 或 `aria-label` |
-| `AppSection` / `AppForm.Section` | 表单内区块头 → `Form.Header`（**单头**）；区块分组 → `Panel` |
-| `AppLayout` / `AppLayout.Row` / `.Column` | → `Layout` / `Layout.Row` / `.Column`（方向口径、间距档、`columns` / `span` 全同） |
-| `AppDrawer` | → `Drawer`（`open` / `title` / `width` / 关闭受控同款；`position` → **`side`**；`beforeClose` 无对应，同 `Dialog`） |
-| `AppTabs` 的 `fill`、`AppSteps` 的 `fill` | 无对应，自绘容器定高 |
-
----
-
-## 三、命令式服务：重新设计过，不是改名
-
-| 旧（kit） | 新（`@manohub/ui`） |
-|---|---|
-| `notify.success(text)` / `.info` / `.warning` / `.error` | `toast('success', text)` / `toast('info', …)` … |
-| `notify.error(text, { action })` 之类配置对象 | `toast('error', text, { action: { text: '重试', onClick } })` |
-| — | `toast('loading', text, { duration: 0 })` 返回句柄，`handle.close()` 收掉 |
-| `messageBox.confirm({ title, description, confirmText, cancelText })` | `await confirm({ title, detail, okText, cancelText, okDanger })` → `Promise<boolean>` |
-| `messageBox.show({ … })` 说明弹窗 | `await alert({ title, detail })` |
-| `loading.show()` 返回 `Ref` | `showLoading(text?)` 返回**关闭句柄**（引用计数语义） |
-| `modalService.open(component, options)` | 无对应：用 `Dialog` / `Drawer` 组件（受控），或 `confirm()` / `alert()` |
-| `richText: true`（HTML 说明） | 无对应：`alert` / `confirm` 只收纯文本；长说明用 `Dialog` 组件的默认插槽 |
-
-**服务层的宿主**：落回应用自己的 `[data-manohub-ui]` 容器（`createSubApp` 写的 `data-manohub-ui` 就是锚点）。
-门户里多应用并存时可在 `createSubApp({ onReady })` 里调 `configureHost(el)` 精确指定。
-
----
-
-## 四、样式改写
-
-| 旧 | 新 |
-|---|---|
-| `.ak-*` 选择器（覆写 kit 内部类） | **删掉**；要的效果按契约 §3「局部换肤」翻成主题令牌（在更深容器重设**已有**令牌的值）或组件的 prop |
-| `.ak-markdown` | **删掉**；`.app-markdown` 预设已随 kit 的样式一并删除，富文本排版暂无合规归属（契约 §10「已知缺口」） |
-| `src/style.css` 里引 `@farris/ui-vue/index.css` | **删掉**；组件库两行改由应用自己引（`@manohub/theme` → `@manohub/ui`，契约 §1.2） |
-| `--f-theme-*` / farris 内部类的覆写 | **删掉**（farris 退场，桥接层一并退场） |
-| 自绘遮罩 + 转圈 | `Loading`（`overlay="area"` / `"screen"`）或服务层 `showLoading()` |
-| 自绘 `flex + gap` 排版 | `Layout.Row` / `Layout.Column` |
-| 自绘 `margin-left:auto` 顶右 | `Panel.Header.actions` / `Layout` 的 `justify="between"` |
-| `height: 100vh` | `height: 100%` |
-
-> `.ak-*` 覆写与 `.mh-*` 覆写在新体系里同样违规（契约 §3 L1、§6 L3-2）；
-> 迁移时不要为了「先让它看起来一样」而保留覆写段 —— 那是把旧债换成新债。
-
----
-
-## 五、入口与全局
-
-| 旧 | 新 |
-|---|---|
-| `import { AppTable, AppButton } from '@manohub/kit'` | `import { Table, Button } from '@manohub/ui'` |
-| `import '@farris/ui-vue'`（应用侧直连） | 删掉（契约 §6 L3-1 的 import 源白名单不含它） |
-| 自己 `createI18n` | 删掉：实例由 `createSubApp({ i18n })` 装配（契约 §9） |
-| 自己写 `app.use(Farris)` | 删掉（farris 退场） |
-| `App*` 组件装在应用依赖里 | 换成 `@manohub/ui`（与 `@manohub/kit`、`@manohub/theme` 并列） |
-
----
-
-## 六、迁移中暴露的坑与结论
-
-1. **`Table` 的三态与序号列要自己接**：把表格包进 `QueryState`（错误态），空态用 `emptyText`，
-   序号列自加一列 —— 不要试图在组件里补回来。
-2. **分页基址差 1 是最容易漏的一处**：搜索 `page` 出现的地方（含 URL query 回填、请求参数拼装）。
-3. **不要给 `Radio.Card` 传「空值」当默认**：它是单选组，缺省会选中第一个可选项。
-4. **`Drawer` / `Dialog` 的关闭拦截**：旧 `beforeClose` 无处安放，改成「点确定前校验 + 失败就不关」
-   （受控语义下 `onOk` 里 return 即可）。
-5. **命令式服务要在 `finally` 里配对关闭**：`showLoading` 是引用计数，漏关会留下永久遮罩。
-6. **样式收口顺序**：先删 `.ak-*` 覆写（多半能直接删），再把残留的视觉意图翻成主题令牌 ——
-   逐条「翻译」会把不该存在的样式留成新债。
-7. **`Page` 成员必须直接挂**：`<template v-if>` 包一层会让归位认不出成员（契约 §5 组 2）——
-   旧 `AppShell` 时代的写法在这里会静默走样。
+# 替换映射表：`App*` / 底层组件库 → `@manohub/ui`
+
+0.6.0 起本包不再提供组件。**组件与服务一律从 `@manohub/ui` 引**（无前缀名），
+farris（底层组件库）也不再是依赖。
+
+按类目查；查不到时按 `CONTRACT.md` §8 缺件处置流程办。**逐文件的操作口径与盘点登记格式见
+`migration-playbook.md`。**
+
+> 读法：`旧` → `新`。**只有一行的地方表示「零改动，只换名字」**；
+> 带 ⚠️ 的是必须人工判断的语义差异。
+
+---
+
+## 零、0.6.0 增量（主题独立成包 + 容器锚改名 + kit 零样式）
+
+只在**已按 0.6.0 迁完**的仓上做，四步：
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `@import "@manohub/kit/styles.css"` | **删掉**，改引 `@manohub/theme/default.css` + `@manohub/ui/styles.css` | kit **不再发布任何样式**（`src/styles/` 整体删除）：样式汇总入口、reset、富文本预设全没了 |
+| `@import "@manohub/kit/reset.css"` | **删掉**（或应用自己补一份 reset） | 同上；reset 的归属随样式一并退场 |
+| `@import "@manohub/ui/theme/default.css"` | `@import "@manohub/theme/default.css"` | 全局令牌已独立成 **`@manohub/theme`**；ui 的 `theme/*` 出口**已删**（无兼容指针） |
+| `@import "@manohub/ui/theme/farris.css"` | `@import "@manohub/theme/farris.css"` | 同上；用非兜底主题时把它替换掉上面那条 ① |
+| 容器上的 `data-app-container` | **`data-manohub-ui`** | 跨包唯一作用域锚，由入口层**无条件**写；旧属性不再被任何一方识别（无兼容别名） |
+| 依赖里只有 `@manohub/{kit,ui}` | 再加 **`@manohub/theme`** | 样式链第一行由应用直接引它（kit 不再代引） |
+
+- **样式链现在归应用自己**：两行（令牌 → 组件面）+ 应用自身一行，顺序不可换（契约 §1.2）。
+- **reset 与富文本排版要自己补**：原来的 `@manohub/kit/reset.css` 与 `.app-markdown` 预设已删除；
+  富文本排版目前没有合规归属（契约 §10「已知缺口」，其余样式纪律仍然生效）。
+- **自建容器（不走 `createSubApp`）必须自己带 `data-manohub-ui`** —— 不带的话不只丢色，
+  连 `--ui-button-height` 这类几何令牌也拿不到（组件令牌的基础值也锚在容器上）。
+- 类名 `class="app-container"` **不必动**：0.6.0 起降级为 kit 内部命名，不再是跨包约定。
+- 深引内部路径（`@manohub/theme/dist/...`、`@manohub/ui/dist/...`）属契约 §6 L3-3
+  **import 源白名单**之外 —— 一律改走公开入口。
+
+---
+
+## 一、页面骨架：`AppShell` → `Page`
+
+`Page` 的能力**覆盖并超过** `AppShell`：成员按类型归位、`Split` 内建拖拽调宽与收起展开。
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `AppShell` | `Page` | 每页唯一 |
+| `AppShell.Header` | `Page.Header` | |
+| `AppShell.Header` 的 `toolbar` prop / `toolbar` 插槽 | `Page.Header` 的 **`extra`** | ⚠️ prop 与插槽**都改名** |
+| `AppShell.Header` 的 `tabs` prop / `tabs` 插槽 | **无对应** | ⚠️ 页头下的页签区改到主体内：`TabBar`（纯页签条）或 `Tabs`（条 + 面板） |
+| `AppShell.Toolbar` | **无对应** | ⚠️ 页面级工具条用 `Page.Filter`，或把控件放 `Page.Header.extra` |
+| `AppShell.Filter` | `Page.Filter` | |
+| `AppShell.Body` | `Page.Body` | `mode` 取值不变（`scroll` / `plain`） |
+| `AppShell.Footer` | `Page.Footer` | |
+| `AppShell.Split` | `Page.Split` | `sidebar` / `rightSidebar` 形状不变；多出「收起动画期内容定宽」 |
+| — | `Page.Header` 的 `subTitle` / `icon` | 旧 `AppShell.Header` 没有这两项 |
+
+**骨架本身不变**：高度仍取 `100%`（禁 `100vh`）、两级滚动归属仍在（契约 §5 组 4）。
+
+⚠️ **迁移期最容易踩的归位坑**：`Page` 的成员**不按书写顺序渲染**，且**必须是 `Page` 的直接子节点**。
+把成员包进 `<template v-if>` 会编译成 Fragment，归位认不出它 —— 该成员会被当自由内容挪进主体区
+（契约 §5 组 2）。旧 `AppShell` 没有这个约束，迁移时要逐个核对。
+
+---
+
+## 二、组件对照
+
+### 2.1 零改动（只换名字）
+
+| 旧 | 新 |
+|---|---|
+| `AppPanel` / `AppPanel.Header` / `.Body` / `.Footer` | `Panel` / `Panel.Header` / `.Body` / `.Footer` |
+| `AppCard` / `AppCard.Header` / `.Body` / `.Footer` | `Card` / 同名成员 |
+| `AppListView` / `AppListView.CardItem` | `ListView` / `ListView.CardItem` |
+| `AppTree` | `Tree` |
+| `AppNav` | `Nav` |
+| `AppQueryState` | `QueryState` |
+| `AppStateIllustrationEmpty` / `AppStateIllustrationError` | 不再有独立插画件：空 / 错误两态由 `QueryState` 内建（设计交付的 SVG 原样内联在其 `src/utils/state-illustration.ts`）。要成功 / 异常图形时走 `QueryState` 的 `illustration` 或自备图片 |
+| `AppCheckbox` | `Checkbox`（+ `Checkbox.Group`） |
+| `AppNotice` | `Notice` |
+| `AppBadge` | `Badge` |
+| `AppForm` / `AppForm.Item` | `Form` / `Form.Item` |
+
+可选新能力（不是必须改）：`Card` 的根件 `title`/`subtitle`/`icon`、`Tree` 的 `defaultExpandAll`、
+`Nav` 的 `bordered`、`ListView` 的 `columns`、`Badge` 的 `count`/`status`、
+`QueryState` 的 `illustrationSize`、`Form.Item` 的 `name`（可拿 `{ value, setValue }`）。
+
+⚠️ `Card` 的**内距口径变了**：旧 `AppCard` 根件有 `padding`，新的 `Card` 根件不出内距
+（内距只在 `Header`/`Body`/`Footer` 段上）。改写：把根件的 `padding` 移到三段，或改令牌 `--mh-card-padding`。
+
+### 2.2 有 prop 差异
+
+#### Button
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `tone="primary"` | `variant="primary"` | 缺省档从 `primary` 变成 **`secondary`** |
+| `tone="default"` / `"secondary"` | `variant="secondary"` | |
+| `tone="error"` | `variant="primary" danger` | |
+| `tone="success"` / `"warning"` / `"info"` | **无色档** | ⚠️ 改用 `variant="primary"`/`"secondary"`，或换件（`Badge` / `Tag` / `Notice` 承担语义色） |
+| `shape="link"` | `variant="link"` | ⚠️ `shape` 换域了 |
+| `shape="ghost"` | `variant="icon"`（纯图标）或 `variant="text"` | |
+| `shape="solid"` / `"soft"` / `"outline"` | **无对应** | ⚠️ 由 `variant`（六型）表达 |
+
+新能力：`block` / `shape="round"｜"circle"` / `icon` / `trailingIcon` / `caret` / `menu` / `href`。
+
+#### Input / Textarea
+
+| 旧 | 新 |
+|---|---|
+| 尾缀内容放默认插槽 | ⚠️ 改放 **`#suffix`**（单行不再渲染默认插槽）；前置放 `#prefix` |
+| `autoComplete` | **无对应** | ⚠️ 不落到控件上；确需防回填用原生 attrs（`controlAttrs`） |
+| `Textarea` 的 `maxLength` | **`maxlength`** | ⚠️ 大小写 |
+| — | `Input` 新增 `onEnter` / `showCount` / `invalid` / `status` / `bordered` |
+
+#### Select
+
+| 旧 | 新 |
+|---|---|
+| `placeholder` 缺省空串 | 缺省 `'请选择'` |
+| `readonly` | **无对应** | ⚠️ 用 `disabled` 顶 |
+| `popupHost` | **无对应** | ⚠️ 面板用原生 popover，宿主概念不再需要 |
+| — | 新增 `multiple` / `searchable` / `allowCreate` / `loading` / `maxTagCount` / `status` |
+
+#### Switch / Radio / Checkbox
+
+- `AppSwitch` → `Switch`：⚠️ `size` 缺省从 `sm` 变成 `md`；⚠️ **`onChange` 的返回值契约消失**
+  （旧代码靠返回 `false` / reject 让开关回退视觉 —— 回退逻辑要搬进调用方：`onChange` 里判失败再改回 `modelValue`）。
+- `AppRadioCard` → `Radio.Card`：⚠️ **缺省选中语义变了** —— `Radio.Card` 是单选组，
+  「可全不选」的旧行为要显式处理（组件缺省会选中第一个可选项）。
+- `AppCheckbox` → `Checkbox`：零改动。
+
+#### Tooltip
+
+| 旧 | 新 |
+|---|---|
+| `placement="top"` | `side="top"`（可加 `align`） |
+| `width`（固定宽） | **无对应** | ⚠️ 用 `#content` 插槽内的元素自己限宽 |
+| `disabled` | **无对应** | ⚠️ 不渲染触发器的提示即可 |
+
+新能力：`title` / `action` / `guide` / `onAction`。
+
+#### Table（差异最大）
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `rows` | **`data`** | |
+| `rowKey` 必填业务字段 | `rowKey` 缺省 `'id'` | |
+| `stripe` | **`striped`** | |
+| `selection={{ mode, selected, onSelectedChange, selectable, onSelectAll }}` | `selectable` + `modelValue`（keys 数组）+ `change` | ⚠️ **只有多选**；单选 / 谓词 / `onSelectAll` / 增量语义**无对应** |
+| `columns[].title` 可以是函数 / `render` | `title` 只接受 string，单元格内容走 **`#cell` 插槽**（`{ row, column, value, index }`） | ⚠️ 渲染路径变了 |
+| `columns[].width` 数字权重 | `width` 字符串（`'120px'` / `'20%'`） | |
+| `error` / `errorTitle` / `emptyDescription` / `*ActionText` / `on*Action` | **无对应** | ⚠️ 错误态用 `QueryState` 包住表格；空态用 `emptyText` / `#empty` |
+| `loading`（骨架替换整表） | `loading`（内容上盖罩 + 转圈，行高不塌） | ⚠️ 观感不同 |
+| `rowNumber` / `rowHeight` / `headerHeight` / `framed` | **无对应** | ⚠️ 序号自加一列；外框由承载它的 `Panel` 给 |
+| `refreshKey` / `rowHighlightKey` / `tableKey` / `onContainerResize` / `resizePollInterval` | **无对应** | ⚠️ 自绘表不吃上游「挂载时固化列宽」的问题，整组逃生舱一并退场 |
+| `onRowClick` / `onRowDoubleClick` | `onRow(row, index) => ({ class, onClick })` | ⚠️ **无双击** |
+| — | 新增 `sortKey` / `sortOrder` / `onSort` / `expandable` / `expandedKeys` / `stickyHead` / `stickyCol` / `pagination` | |
+
+> 旧 `AppTable` 有一条「回调交回的行对象必须是消费方那一个」的契约（内部副本挂了非枚举回引）。
+> 新 `Table` 不存在副本问题 —— 交回的就是 `data` 里的那一项。
+
+#### Pagination
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `page`（**0 基**，必填） | `modelValue`（**1 基**，`v-model`） | ⚠️ **差 1**，是最容易漏的一处 |
+| `onPageChange(page)` | `update:modelValue` / `change`（载荷是 **`number`**） | ⚠️ 不再是 `{ page, pageSize }` 对象 |
+| `onPageSizeChange(size)` | `update:pageSize`（`v-model:page-size`） | 两个事件各管各的 |
+| `showInfo` | **无对应** | ⚠️ 「共 n 条」默认就有；要改文案用 `#total` 槽 |
+| — | 新增 `showSizeChanger` / `showQuickJumper` / `simple` / `boxed` / `hideOnSinglePage` | |
+
+> 注意 `Table` 的 `pagination` prop 与独立的 `Pagination` **不是同一套入参**：
+> 前者是 `{ total, current?, pageSize?, pageSizeOptions?, onChange? }`（`onChange` 收页码），
+> 后者是受控的 `v-model` / `v-model:page-size`。
+
+#### Dialog
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `width={640}`（数值，缺省 640） | `width` 缺省 **`'md'`（520）** | ⚠️ 缺省宽度变窄，要 640 就显式传 |
+| `beforeClose`（关闭拦截） | **无对应** | ⚠️ 拦截逻辑移到 `onCancel` / `onClose` 里自己把关（组件只回调） |
+| `height` / `minHeight` / `fitContent` / `showHeader` / `showButtons` | **无对应** | ⚠️ 固定高度用 `#default` 内的容器自己定高；不显示页头用 `:closable="false"` + 不给 `title` |
+| — | 新增 `okText` / `cancelText` / `okDanger` / `confirmLoading` / `showFooter` / `onOk` / `onCancel` / `onClose` / `closeOnBackdrop` / `keyboard` | |
+
+`Dialog` 走**原生 `<dialog>`**：遮罩、Esc、焦点陷阱归浏览器；**开合受控**
+（关闭位 / Esc / 点遮罩都只回调，可见性归调用方）。`onOk` 返回 Promise 时确定按钮自动进加载态。
+
+#### Steps
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `items` | **`steps`** | ⚠️ 形状变：丢 `key` / `disabled`，新增 `icon` |
+| `modelValue`（0 基） | `current`（0 基，基址不变） | |
+| `clickable` / `onBeforeChange` / `onChange` | **无对应** | ⚠️ 步骤条是**只读展现**；跳转与门控搬到页面（按钮 + 自己的校验） |
+| `fill` | **无对应** | |
+| — | 新增 `variant`（`node` / `bar`）/ `size` / `Steps.Progress` | |
+
+#### TabBar
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `modelValue`（必填） | `value`（缺省第一项）/ `defaultValue` | |
+| `items=[{ key, label }]` | `options=[{ label, value }]` | ⚠️ `key` → `value` |
+| **按 `item.key` 命名的内容插槽**（自带面板切换） | `TabBar` **无内容槽** | ⚠️ 要「条 + 面板」用 `Tabs`（面板写成 `TabPanel name="…"`，轨道缺省就是页签条）；只要页签条用 `TabBar` |
+| `fill` | **无对应** | |
+
+#### Filter
+
+| 旧 | 新 | 说明 |
+|---|---|---|
+| `fields=[…]` 声明式（必填） | **`Filter.Item` 子件**（`code` / `label` + 控件自放） | ⚠️ 模型从「声明字段表」变「写子件」 |
+| `defaults` | `defaultValue`（键从「字段 id」变「条件名 code」） | |
+| `searchFields` / `searchPlaceholder` / `keywordCodes` | **无对应** | ⚠️ 「关键字」写成普通 `Filter.Item` + `Input` |
+| `appFilterSelect` / `appFilterInput` 工厂 | **无对应** | ⚠️ 控件直接写 `Select` / `Input` |
+| `onChange(values, meta)` / `onQuery(values, meta)` | `onChange(values)` / `onQuery(values)` | ⚠️ **丢 `meta`**（关键字 / 查询态由页面自持） |
+| `inline` / `expanded` / `readyTries` / `ignoreInitialEmpty` / `onReady` | **无对应** | ⚠️ 就绪时序归页面 |
+| — | 新增 `title` / `description` / `queryText` / `resetText` / `showReset` / `onReset` | |
+
+#### Input 的组合形态
+
+`AppSearchBox` → **`Search`**：`modelValue` / `placeholder` / `disabled` / `size` / `clearable` /
+`loading` / `searchText` 同名同义；`onChange` / `onSearch` / `onClear` 三条回调保留（`onClear` 的补发判据内建）。
+
+#### 旧有新无的其余项
+
+| 旧 | 处置 |
+|---|---|
+| `AppIconButton` | 改用 `Button variant="icon"`（⚠️ 缺省 `size` 从 `sm` 变 `md`，要小号显式传）；无可见文案时给 `title` 或 `aria-label` |
+| `AppSection` / `AppForm.Section` | 表单内区块头 → `Form.Header`（**单头**）；区块分组 → `Panel` |
+| `AppLayout` / `AppLayout.Row` / `.Column` | → `Layout` / `Layout.Row` / `.Column`（方向口径、间距档、`columns` / `span` 全同） |
+| `AppDrawer` | → `Drawer`（`open` / `title` / `width` / 关闭受控同款；`position` → **`side`**；`beforeClose` 无对应，同 `Dialog`） |
+| `@@APPTABS@@` 的 `fill`、`AppSteps` 的 `fill` | 无对应，自绘容器定高 |
+
+---
+
+## 三、命令式服务：重新设计过，不是改名
+
+| 旧（kit） | 新（`@manohub/ui`） |
+|---|---|
+| `notify.success(text)` / `.info` / `.warning` / `.error` | `toast('success', text)` / `toast('info', …)` … |
+| `notify.error(text, { action })` 之类配置对象 | `toast('error', text, { action: { text: '重试', onClick } })` |
+| — | `toast('loading', text, { duration: 0 })` 返回句柄，`handle.close()` 收掉 |
+| `messageBox.confirm({ title, description, confirmText, cancelText })` | `await confirm({ title, detail, okText, cancelText, okDanger })` → `Promise<boolean>` |
+| `messageBox.show({ … })` 说明弹窗 | `await alert({ title, detail })` |
+| `loading.show()` 返回 `Ref` | `showLoading(text?)` 返回**关闭句柄**（引用计数语义） |
+| `modalService.open(component, options)` | 无对应：用 `Dialog` / `Drawer` 组件（受控），或 `confirm()` / `alert()` |
+| `richText: true`（HTML 说明） | 无对应：`alert` / `confirm` 只收纯文本；长说明用 `Dialog` 组件的默认插槽 |
+
+**服务层的宿主**：落回应用自己的 `[data-manohub-ui]` 容器（`createSubApp` 写的 `data-manohub-ui` 就是锚点）。
+门户里多应用并存时可在 `createSubApp({ onReady })` 里调 `configureHost(el)` 精确指定。
+
+---
+
+## 四、样式改写
+
+| 旧 | 新 |
+|---|---|
+| `.ak-*` 选择器（覆写 kit 内部类） | **删掉**；要的效果按契约 §3「局部换肤」翻成主题令牌（在更深容器重设**已有**令牌的值）或组件的 prop |
+| `.ak-markdown` | **删掉**；`.app-markdown` 预设已随 kit 的样式一并删除，富文本排版暂无合规归属（契约 §10「已知缺口」） |
+| `src/style.css` 里引 `@farris/ui-vue/index.css` | **删掉**；组件库两行改由应用自己引（`@manohub/theme` → `@manohub/ui`，契约 §1.2） |
+| `--f-theme-*` / farris 内部类的覆写 | **删掉**（farris 退场，桥接层一并退场） |
+| 自绘遮罩 + 转圈 | `Loading`（`overlay="area"` / `"screen"`）或服务层 `showLoading()` |
+| 自绘 `flex + gap` 排版 | `Layout.Row` / `Layout.Column` |
+| 自绘 `margin-left:auto` 顶右 | `Panel.Header.actions` / `Layout` 的 `justify="between"` |
+| `height: 100vh` | `height: 100%` |
+
+> `.ak-*` 覆写与 `.mh-*` 覆写在新体系里同样违规（契约 §3 L1、§6 L3-2）；
+> 迁移时不要为了「先让它看起来一样」而保留覆写段 —— 那是把旧债换成新债。
+
+---
+
+## 五、入口与全局
+
+| 旧 | 新 |
+|---|---|
+| `import { AppTable, AppButton } from '@manohub/kit'` | `import { Table, Button } from '@manohub/ui'` |
+| `import '@farris/ui-vue'`（应用侧直连） | 删掉（契约 §6 L3-3 的外观来源白名单不含它） |
+| 自己 `createI18n` | 删掉：实例由 `createSubApp({ i18n })` 装配（契约 §9） |
+| 自己写 `app.use(Farris)` | 删掉（farris 退场） |
+| `App*` 组件装在应用依赖里 | 换成 `@manohub/ui`（与 `@manohub/kit`、`@manohub/theme` 并列） |
+
+---
+
+## 六、迁移中暴露的坑与结论
+
+1. **`Table` 的三态与序号列要自己接**：把表格包进 `QueryState`（错误态），空态用 `emptyText`，
+   序号列自加一列 —— 不要试图在组件里补回来。
+2. **分页基址差 1 是最容易漏的一处**：搜索 `page` 出现的地方（含 URL query 回填、请求参数拼装）。
+3. **不要给 `Radio.Card` 传「空值」当默认**：它是单选组，缺省会选中第一个可选项。
+4. **`Drawer` / `Dialog` 的关闭拦截**：旧 `beforeClose` 无处安放，改成「点确定前校验 + 失败就不关」
+   （受控语义下 `onOk` 里 return 即可）。
+5. **命令式服务要在 `finally` 里配对关闭**：`showLoading` 是引用计数，漏关会留下永久遮罩。
+6. **样式收口顺序**：先删 `.ak-*` 覆写（多半能直接删），再把残留的视觉意图翻成主题令牌 ——
+   逐条「翻译」会把不该存在的样式留成新债。
+7. **`Page` 成员必须直接挂**：`<template v-if>` 包一层会让归位认不出成员（契约 §5 组 2）——
+   旧 `AppShell` 时代的写法在这里会静默走样。