@done-coding/admin-core 0.17.1-alpha.0 → 0.18.1-alpha.0

package/es/utils/dom.mjs

@@ -1,22 +1,26 @@
-function n(e) {
-  let t = e == null ? void 0 : e.parentElement;
-  for (; t && t !== document.body && t !== document.documentElement; ) {
-    const { overflowY: o } = getComputedStyle(t);
-    if (/(auto|scroll|overlay)/.test(o) && t.scrollHeight > t.clientHeight)
-      return t;
-    t = t.parentElement;
+function domClosestScrollableAncestor(el) {
+  let cur = el == null ? void 0 : el.parentElement;
+  while (cur && cur !== document.body && cur !== document.documentElement) {
+    const { overflowY } = getComputedStyle(cur);
+    if (/(auto|scroll|overlay)/.test(overflowY) && cur.scrollHeight > cur.clientHeight) {
+      return cur;
+    }
+    cur = cur.parentElement;
   }
+  return void 0;
 }
-function r(e) {
-  let t = e == null ? void 0 : e.parentElement;
-  for (; t && t !== document.body && t !== document.documentElement; ) {
-    const o = getComputedStyle(t);
-    if (o.display !== "contents" && /(auto|scroll|overlay|hidden)/.test(o.overflowY))
-      return t;
-    t = t.parentElement;
+function domClosestStickyScrollport(el) {
+  let cur = el == null ? void 0 : el.parentElement;
+  while (cur && cur !== document.body && cur !== document.documentElement) {
+    const cs = getComputedStyle(cur);
+    if (cs.display !== "contents" && /(auto|scroll|overlay|hidden)/.test(cs.overflowY)) {
+      return cur;
+    }
+    cur = cur.parentElement;
   }
+  return void 0;
 }
 export {
-  n as domClosestScrollableAncestor,
-  r as domClosestStickyScrollport
+  domClosestScrollableAncestor,
+  domClosestStickyScrollport
 };

package/es/utils/export.mjs

@@ -1,23 +1,39 @@
-const f = "OPERATE", E = 1e4, O = (t) => t.filter((e) => !(!e.prop || e.prop === f || e.type && e.type !== "default")).map((e) => ({
-  prop: e.prop,
-  label: e.label
-})), b = "\uFEFF", R = ({
-  columns: t,
-  list: e,
-  filename: a = "导出数据"
+const OPERATE_COLUMN_PROP = "OPERATE";
+const EXPORT_MAX_LIMIT = 1e4;
+const pickExportColumns = (columns) => columns.filter((col) => {
+  if (!col.prop) return false;
+  if (col.prop === OPERATE_COLUMN_PROP) return false;
+  if (col.type && col.type !== "default") return false;
+  return true;
+}).map((col) => ({
+  prop: col.prop,
+  label: col.label
+}));
+const BOM = "\uFEFF";
+const exportCSV = ({
+  columns,
+  list,
+  filename = "导出数据"
 }) => {
-  const s = t.map((r) => r.label).join(","), c = e.map(
-    (r) => t.map((o) => {
-      const i = o.valueMap ? o.valueMap(r) : r[o.prop] ?? "";
-      return `"${String(i).replace(/"/g, '""')}"`;
+  const header = columns.map((c) => c.label).join(",");
+  const rows = list.map(
+    (row) => columns.map((c) => {
+      const raw = c.valueMap ? c.valueMap(row) : row[c.prop] ?? "";
+      return `"${String(raw).replace(/"/g, '""')}"`;
     }).join(",")
-  ), l = b + [s, ...c].join(`
-`), u = new Blob([l], { type: "text/csv;charset=utf-8;" }), p = URL.createObjectURL(u), n = document.createElement("a");
-  n.href = p, n.download = `${a}.csv`, n.click(), URL.revokeObjectURL(p);
+  );
+  const csv = BOM + [header, ...rows].join("\n");
+  const blob = new Blob([csv], { type: "text/csv;charset=utf-8;" });
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement("a");
+  link.href = url;
+  link.download = `${filename}.csv`;
+  link.click();
+  URL.revokeObjectURL(url);
 };
 export {
-  E as EXPORT_MAX_LIMIT,
-  f as OPERATE_COLUMN_PROP,
-  R as exportCSV,
-  O as pickExportColumns
+  EXPORT_MAX_LIMIT,
+  OPERATE_COLUMN_PROP,
+  exportCSV,
+  pickExportColumns
 };

package/es/utils/id.mjs

@@ -1,5 +1,7 @@
-let t = 0;
-const n = (e = "") => `_${e}_${t++}`;
+let index = 0;
+const getId = (prefix = "") => {
+  return `_${prefix}_${index++}`;
+};
 export {
-  n as getId
+  getId
 };

package/es/utils/router.mjs

@@ -1,18 +1,25 @@
-const r = ({
-  path: s,
-  permission: e
+const getRoutePermissionKey = ({
+  path,
+  permission: permissionConfig
 }) => {
-  if (!e)
+  if (!permissionConfig) {
     return;
-  const { key: t, keyUsePath: n } = e;
-  if (t)
-    return t;
-  if (n)
-    return s;
-}, o = (s, e = []) => (s.forEach((t) => {
-  e.push(t), o(t.children, e);
-}), e);
+  }
+  const { key, keyUsePath } = permissionConfig;
+  if (key) {
+    return key;
+  } else if (keyUsePath) {
+    return path;
+  }
+};
+const flatRouteMetaResolveRaw = (list, arr = []) => {
+  list.forEach((item) => {
+    arr.push(item);
+    flatRouteMetaResolveRaw(item.children, arr);
+  });
+  return arr;
+};
 export {
-  o as flatRouteMetaResolveRaw,
-  r as getRoutePermissionKey
+  flatRouteMetaResolveRaw,
+  getRoutePermissionKey
 };

package/es/utils/theme-scale.mjs

@@ -1,44 +1,59 @@
-const c = (s) => {
-  const t = s.trim().replace(/^#/, "");
-  if (t.length === 3) {
-    const n = parseInt(t[0] + t[0], 16), e = parseInt(t[1] + t[1], 16), r = parseInt(t[2] + t[2], 16);
-    return [n, e, r].some(Number.isNaN) ? null : [n, e, r];
+const themeScaleParseHex = (hex) => {
+  const m = hex.trim().replace(/^#/, "");
+  if (m.length === 3) {
+    const r = parseInt(m[0] + m[0], 16);
+    const g = parseInt(m[1] + m[1], 16);
+    const b = parseInt(m[2] + m[2], 16);
+    return [r, g, b].some(Number.isNaN) ? null : [r, g, b];
   }
-  if (t.length === 6) {
-    const n = parseInt(t.slice(0, 2), 16), e = parseInt(t.slice(2, 4), 16), r = parseInt(t.slice(4, 6), 16);
-    return [n, e, r].some(Number.isNaN) ? null : [n, e, r];
+  if (m.length === 6) {
+    const r = parseInt(m.slice(0, 2), 16);
+    const g = parseInt(m.slice(2, 4), 16);
+    const b = parseInt(m.slice(4, 6), 16);
+    return [r, g, b].some(Number.isNaN) ? null : [r, g, b];
   }
   return null;
-}, i = (s, t, n) => {
-  const e = (r) => Math.min(255, Math.max(0, Math.round(r))).toString(16).padStart(2, "0");
-  return `#${e(s)}${e(t)}${e(n)}`;
-}, o = (s, t, n) => {
-  const e = c(s), r = c(t);
-  return !e || !r ? t : i(
-    e[0] * n + r[0] * (1 - n),
-    e[1] * n + r[1] * (1 - n),
-    e[2] * n + r[2] * (1 - n)
+};
+const themeScaleToHex = (r, g, b) => {
+  const h = (n) => {
+    const v = Math.min(255, Math.max(0, Math.round(n)));
+    return v.toString(16).padStart(2, "0");
+  };
+  return `#${h(r)}${h(g)}${h(b)}`;
+};
+const themeScaleMix = (c1, c2, w1) => {
+  const a = themeScaleParseHex(c1);
+  const b = themeScaleParseHex(c2);
+  if (!a || !b) return c2;
+  return themeScaleToHex(
+    a[0] * w1 + b[0] * (1 - w1),
+    a[1] * w1 + b[1] * (1 - w1),
+    a[2] * w1 + b[2] * (1 - w1)
   );
-}, l = (s, t) => {
-  const n = c(s);
-  if (!n) return s;
-  const e = Math.min(1, Math.max(0, t));
-  return `rgba(${n[0]}, ${n[1]}, ${n[2]}, ${e})`;
-}, h = (s, t) => {
-  const n = t === "light" ? "#ffffff" : "#141414", e = t === "light" ? "#000000" : "#ffffff", r = (a) => o(n, s, a / 10);
+};
+const themeScaleToRgba = (hex, alpha) => {
+  const rgb = themeScaleParseHex(hex);
+  if (!rgb) return hex;
+  const a = Math.min(1, Math.max(0, alpha));
+  return `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${a})`;
+};
+const themeScaleDerive = (base, mode) => {
+  const lightMix = mode === "light" ? "#ffffff" : "#141414";
+  const darkMix = mode === "light" ? "#000000" : "#ffffff";
+  const li = (i) => themeScaleMix(lightMix, base, i / 10);
   return {
-    base: s,
-    "light-3": r(3),
-    "light-5": r(5),
-    "light-7": r(7),
-    "light-8": r(8),
-    "light-9": r(9),
-    "dark-2": o(e, s, 0.2)
+    base,
+    "light-3": li(3),
+    "light-5": li(5),
+    "light-7": li(7),
+    "light-8": li(8),
+    "light-9": li(9),
+    "dark-2": themeScaleMix(darkMix, base, 0.2)
   };
 };
 export {
-  h as themeScaleDerive,
-  o as themeScaleMix,
-  c as themeScaleParseHex,
-  l as themeScaleToRgba
+  themeScaleDerive,
+  themeScaleMix,
+  themeScaleParseHex,
+  themeScaleToRgba
 };

package/es/utils/time.mjs

@@ -1,18 +1,24 @@
-const p = (o, t, a) => {
-  let e;
-  const n = Date.now() + o * 1e3, c = 1e3;
-  function i() {
-    e = setTimeout(() => {
-      const m = Date.now();
-      if (n - m > 0) {
-        const s = Math.round((n - m) / 1e3);
-        t(Math.max(s, 0)), i();
-      } else
-        t(0), a();
-    }, c);
+const timeCountDown = (time, handler, endHandler) => {
+  let timer;
+  const initTimeStamp = Date.now();
+  const targetTimeStamp = initTimeStamp + time * 1e3;
+  const timeStep = 1e3;
+  function main() {
+    timer = setTimeout(() => {
+      const nowTimeStamp = Date.now();
+      if (targetTimeStamp - nowTimeStamp > 0) {
+        const newTime = Math.round((targetTimeStamp - nowTimeStamp) / 1e3);
+        handler(Math.max(newTime, 0));
+        main();
+      } else {
+        handler(0);
+        endHandler();
+      }
+    }, timeStep);
   }
-  return i(), () => clearTimeout(e);
+  main();
+  return () => clearTimeout(timer);
 };
 export {
-  p as timeCountDown
+  timeCountDown
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.17.1-alpha.0",
+  "version": "0.18.1-alpha.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -17,7 +17,8 @@
   },
   "files": [
     "es",
-    "types"
+    "types",
+    "src/**/README*.md"
   ],
   "scripts": {
     "serve": "vite",
@@ -79,5 +80,5 @@
     "node": ">=18.0.0",
     "pnpm": ">=9.0.0"
   },
-  "gitHead": "086ea9d0440acd89ef5b553654f787c0184a3eae"
+  "gitHead": "f439b08f77c84f7e15e3f7286de9978e9aae9ff4"
 }

package/src/bridge/README.md

@@ -0,0 +1,5 @@
+# bridge 模块（接线中枢）
+
+`createCoreBridge(options)` 产出 `CoreBridge` 单例——认证 / 布局 / 主题 / 路由派生的总接线口，经 `app.use(bridge)` 全局注入（`CORE_BRIDGE_KEY`）。
+
+> 详情见 [docs/README.md](./docs/README.md)（导出面 / 接线范式 / 认证与请求接线）

package/src/bridge/docs/README.md

@@ -0,0 +1,72 @@
+# bridge 模块引导（接线中枢）
+
+core 的「实例化中枢」：`createCoreBridge(options)` 产出 `CoreBridge` 单例——认证 / 布局 / 主题 / 路由派生的总接线口，经 `app.use(bridge)` 全局注入（`CORE_BRIDGE_KEY`），AppLayout 接收后 provide 给全部子组件。
+
+**范式**：桥是 app 侧唯一的接线点（参考 `apps/reference/src/config/bridge.ts` 的实例化），core 组件/页面不直接持有 app 依赖。
+
+## 导出面（`bridge/index.ts` 聚合）
+
+| 符号 | 职责 |
+| --- | --- |
+| `createCoreBridge` | 工厂：传入 `CoreBridgeInitOptions`（配置 schema + auth facade + 存储 + 主题初值等），产出 `CoreBridge` |
+| `CoreBridge` | 实例接口：`update()` 响应式更新 8 组配置视图 + `theme` 模块 + `layout` 折叠模块 + auth/api/路由派生方法 |
+| `CoreBridgeRegisterOptions` | 注册选项类型（配置键 → 默认值/访问器） |
+| `AppConfig` / `AppEnvInfo` | 配置 schema 顶层类型 |
+| `AppLayout*Config`（Header/Footer/Sidebar/Aside/Body/Viewport/Gap） | 布局 7 组配置视图类型（`update` 改它们即响应式生效） |
+| `AppThemeConfig` | 主题配置视图 |
+| `AppRouterConfig` / `AppRouterPathsConfig` | 路由配置 + 8 个基础 path 常量真源 |
+| `AppCacheConfig` | 缓存配置（命名空间 localStorage 由 `bridge/storage.ts` 工厂实例化） |
+| `UserInfoAccess` / `UserInfoFieldAccessor` / `UserInfoPermissionAccessor` | userInfo 字段/权限访问器契约 |
+| `AppBaseInfo` 等类型别名 | 各配置视图的便捷类型 |
+
+**模块拆分**（规则 12：按耦合度独立文件）：`theme/`（createBridgeThemeHook：风格 map + setStyle/setDark + 响应式 + 持久化）、`layout.ts`（折叠）、`plugin.ts`（插件注册）、`config-hook.ts`、`route.ts`（路由派生）、`state.ts`（useState 工厂）、`storage.ts`（命名空间存储）。
+
+## 快速上手（接线范式）
+
+```ts
+// apps/reference/src/config/bridge.ts（完整实例化参照）
+const appCoreBridge = createCoreBridge({
+  APP_BASE_INFO: { name: "参考应用" },
+  APP_ENV: { ... },
+  APP_CACHE_CONFIG: { ... },
+  APP_LAYOUT_HEADER_CONFIG: { ... },   // 布局 5 组
+  APP_LAYOUT_VIEWPORT_CONFIG: { ... },
+  APP_THEME_CONFIG: { themeStyle: "default", themeIsDark: false },
+  APP_ROUTER_CONFIG: { meta: { default: ... } },
+  APP_ROUTER_PATHS_CONFIG: { rootPath, homePath, loginPath, ... },  // 8 path 真源
+  userInfoAccess: { ... },              // userInfo 字段/权限访问器
+  storage: storageLike,                 // 命名空间 localStorage
+  auth: { getToken, goToLogin, refreshToken, refreshAuth },
+});
+app.use(appCoreBridge);                 // opt-in：CORE_BRIDGE_KEY 注入
+```
+
+响应式更新（`update` 改配置视图，全链路即时生效）：
+
+```ts
+appCoreBridge.update({ APP_LAYOUT_VIEWPORT_CONFIG: { ... } });
+appCoreBridge.theme.setStyle("studio-stage");
+appCoreBridge.theme.setDark(true);
+```
+
+## 认证与请求接线
+
+### 认证 facade（bridge 4 钩子 + userInfoAccess）
+
+`CoreBridge` 提供 4 个**零参** auth facade（core 对 `UserInfo` 不透明）：`getToken?` / `goToLogin?` / `refreshToken?` / `refreshAuth?`；另有 4 个增量可选业务 api（`loginApi` / `logoutApi` / `getUserInfoApi` / `refreshTokenApi`，由 `createUserStore` 薄壳 register 注入）。
+
+- `userInfoAccess`：token / refreshToken / permission 三字段访问器（get + set），createCoreBridge 时注入
+- 接线样板：`apps/reference/src/config/bridge.ts`（userInfoAccess + auth facade + 8 path 配置全量实例化）
+
+### 请求实例（@done-coding/request-axios）
+
+请求层**不在 core 包内**——消费方用 `@done-coding/request-axios` 的 `createRequest` 自建全局实例（peer 依赖）：
+
+- 样板：`apps/reference/src/api/request.ts`——`businessSuccessCodeList` + `getBusinessCode/getBusinessData/getBusinessMsg`（业务模型 key 由 `APP_API_BUSINESS_MODEL_KEY_CONFIG` 定）+ `beforeRequest` 注入 `Authorization`（token 取 `appCoreBridge.getToken()`）+ 拦截链（业务错误码分发 / token 刷新 / 跳登录 / 重拉权限）
+- 业务 API 函数定义样板：`apps/reference/src/api/common.ts`（登录/登出/刷新/getUserInfo）
+
+## 关联
+
+- `CORE_BRIDGE_KEY`：`app.use(bridge)` 后的 inject 入口（未 use 时 inject 返回 undefined）
+- 主题模块完整能力见 `apps/reference/src/config/theme-plugin.ts`（35 套资产注册）与 plugin-theme 包
+- 范式演示：`apps/reference/src/pages/integration/bridge-update/`（update 响应式示例）

package/src/components/README.md

@@ -0,0 +1,84 @@
+# components 组件族总引导
+
+core 共 11 个组件族，全部经顶层 barrel 导出（`import { FormMain } from "@done-coding/admin-core"`）。各族目录内均有 `README.md` 入口（组件清单 + 指向 `docs/` 组件详情文档，`README-<PascalName>.md`）。
+
+**页面范式**：`AppPage`（页面容器）→ `ListPage`（列表）/ `FormMain`（表单）/ `ViewLayout`（详情展示，**后续迭代，未实现**）→ `TableMain` / `FormSearch` 子配置。⚠️ 存量 `PanelMain` 的页级展示一等公民地位已撤销、将废弃——新页面 [MUST NOT] 以 PanelMain 作页级展示根容器（详见 panel 族文档）。
+
+## 配置化体系契约（设计引导）
+
+> 提炼自配置化体系设计范式（2026-08 对照 MIGRATION 与源码验证时效）。开发/接入前 [MUST] 先读本节。
+
+### 第一性原理
+
+- **万物皆表单项**：任何输入形态（upload / JSON / 选择器 / 验证码…）都是 `FormItemConfig` 的 render/component 变体——[MUST NOT] 另造「输入组件」形态
+- **万物皆 Nest 递归组合**：嵌套子表单/子面板不手写 HTML，走 `nestFormItem` / `nestFormItemList` / `nestPanelItem` / `nestPanelForm`（配置一个容器的产物本身又是合法 item 内容，跨等级递归自嵌套）
+- **编排即组合、不是分类**：customView 是列表视图变体不单列一类；横排/竖排/分步同源不为布局差异另造范式——组合自由、非封闭模板
+- **容器即 prop**：弹窗/抽屉一个 `layerType` 切、大小一个 `width` 切——不另造形态
+
+### 空间一等公民（组合件优先）
+
+| 空间 | 一等公民（优先用） | 零件（底层，一般经一等公民使用） |
+| --- | --- | --- |
+| 列表 | `ListPage` | `TableMain`（表格侧）/ `FormSearch`（搜索侧） |
+| 纯表单提交 | `FormSubmitPanel` | `FormMain`（底座）/ `FormSubmitBtn` |
+| 弹窗 CRUD / 表单 | `ModalDetail` / `ModalForm` | `ModalConfirm`（原语底座） |
+| 弹窗命令式 | `ModalPorter` + `ModalShelf`（app/page 内置） | — |
+| 详情展示 | `ViewLayout`（**后续迭代，未实现**）；存量 `PanelMain` 将废弃（仅表单预览 / 就地编辑场景保留） | `PanelItem` / `PanelEditSwitch` |
+| 多 tab | `TabsMain` | `TabsRefineFlow` 等（内部件） |
+
+业务层 [MUST] 一等公民优先：能用 `TableMain` 处用 `ListPage`、能用 `FormMain` 处用 `FormSubmitPanel`；裸用仅限特例（详见各族文档定位段断言）。
+
+### 配置化字段归位四机制
+
+`ignore`（视图在数据不在）/ `hide`（数据在视图不在）/ `staticQuery`（列表查询固定参数）/ `init`（可被用户覆盖的初值）——字段落位先按四机制归位，[MUST NOT] 硬编码过滤。
+
+### 弹窗即空间
+
+- 内容型弹窗 [MUST] 走 `modalList` item + `shelf:"page"` + `ModalPorter.evoke(key, payload)`；[MUST NOT] 直挂 `ModalDetail`/`ModalForm` 组件到页面、[MUST NOT] 自声明 app/page 级 `ModalShelf`（AppLayout/AppPage 已内置）
+- 确认类弹窗 [MUST NOT] 注册进 modalList：一句话确认走 `ActionBtn.confirmConfig`（popconfirm / messageConfirm）
+
+### 页面反模式红线
+
+- 所有业务页面 [MUST] `AppPage` 包裹（自带 page 级 ModalShelf + 视口高度链）
+- 单向数据流：[MUST NOT] 跨层/跨 tab 全局 store 通信（props / emit / payload 回调）
+- keepAlive 页返回刷新 core 内置（onActivated refresh 留页码），app 侧 [MUST NOT] 补偿（双重请求反模式）
+- 新增按钮 [MUST] 走 `toolbar.leftExtraButtons`（ActionBtn 配置驱动）；操作列 [MUST] 用 `column.render` 工厂 + `ActionBtnGroup`（`#table-OPERATE` 槽已非推荐通道）
+- 跨包纪律：桶级导出 / `Symbol.for` / 双链验证 / style.css 显式导入 / `ActionBtn` 替代 ElButton（细则见项目 CLAUDE.md 规则 6–11）
+- app 层范式：`useSpaceConfig` 单一配置出口 + handlers 出界注入（config 不 import router/不持 ref）——见 `apps/reference/src/pages/_shared/space.ts`
+
+## 族清单
+
+| 族 | 组件 | 入口 |
+| --- | --- | --- |
+| form 表单族 | FormMain / FormSearch / FormSubmitBtn / FormSubmitPanel / FormItemNestForm / FormItemNestFormList / FormSelect / FormRadioGroup / FormTree / FormVerifyImage / FormVerifyCode | [README](./form/README.md) |
+| list-page 列表族 | ListPage（FormSearch + TableMain 组合页） | [README](./list-page/README.md) |
+| table 表格族 | TableMain | [README](./table/README.md) |
+| modal 弹窗族 | ModalConfirm / ModalForm / ModalDetail / ModalShelf / ModalPorter | [README](./modal/README.md) |
+| panel 面板族 | PanelMain / PanelItem / PanelEditSwitch / PanelItemNestPanel / PanelItemNestForm | [README](./panel/README.md) |
+| display 展示族 | TabsMain / ActionBtn / ActionBtnGroup / ActionConfirm / WatchSize / HeightProvider / BooleanTag | [README](./display/README.md) |
+| app-layout 布局族 | AppLayout / AppPage / AppBody / AppHeader / AppSidebar / AppAside / AppBreadcrumb / AppFooter / AppTheme / AppCollapseToggle（未导出） | [README](./app-layout/README.md) |
+| menu 菜单族 | MenuTree / MenuItemSub | [README](./menu/README.md) |
+| slot-layout 插槽布局族 | SlotLayoutTemplate / SlotLayoutFlowAside | [README](./slot-layout/README.md) |
+| data-view 数据视图族 | DataListView / DataListViewItem（TableMain 内部件，customView 模式；不进顶层 export） | [README](./data-view/README.md) |
+| misc 杂项族 | AutoRefresh / AutoRefreshGroup / SelectModule / TriggerAutoImport（@deprecated） | [README](./misc/README.md) |
+
+## 写作与维护约定
+
+- 各族 `README.md` = 入口（组件清单 + 一句话），组件详情在 `docs/README-<PascalName>.md`
+- **快速上手 = 最小可用形态**（默认值即够用，5–20 行可直接抄的代码）——[MUST NOT] 把能力全开示例当快速上手（AI 会按示例最大化使用，全能力示例反而误导）
+- **空间一等公民断言**：组合件（ListPage / FormSearch / FormSubmitPanel / ModalDetail 等）与零件（TableMain / FormMain / ModalConfirm / PanelItem 等）的文档 [MUST] 在定位段断言「优先经 <空间组件> 使用 + 直接使用仅当 <特例>」——配置化体系「空间一等公民优先」范式，[MUST NOT] 让 AI 把零件当默认起点。⚠️ `PanelMain` 已撤销一等公民地位（将废弃，待 `ViewLayout` 承接），文档 [MUST NOT] 再以 PanelMain 作详情展示组合件示例
+- **每篇必含「能力边界 / 按需使用」段**（快速上手之后）：逐条断言「默认关/默认即够用 + 仅当 X 场景才开（判据）」，末行给「完整能力演示」reference 指针——全能力代码不复制进文档正文（活代码在 reference showcase 页，零重复维护）
+- 新增/改造对外组件 [MUST] 同步补 `docs/README-<PascalName>.md`（随 `docs/specs/` 任务闭环）
+- API 段以 `types.ts` + 组件源码为真相源；与文档冲突时以源码为准
+- 内部件（不导出）**也写独立文档，但仅 API 段**（props/emits/slots/expose + 机制契约真相，以源码为真相源）——[MUST NOT] 写定位 / 快速上手 / 基础应用等消费向叙事段（无对外使用场景，写了反而误导 AI 当公共组件用）；族入口标注「内部件 · 仅 API」
+
+### 开发流程（API 契约先行）
+
+新组件 / 组件改造（含 API 变更）[MUST] 按四步走，[MUST NOT] 先实现后补文档：
+
+1. **API 契约先行**：先写 `types.ts`（props/emits 类型）并**同步更新**对应 `docs/README-<PascalName>.md` 的 API 段（props/emits/slots/expose 表）——API 表先于实现存在、锁定契约；同时补「类型测试」锚（types.ts 形态断言——文档先行里唯一可执行的部分，把契约落成机器可验）
+2. **实现**：满足契约；实现中 API 微调属正常，同步回改 API 表（文档是承诺不是枷锁，但 [MUST NOT] 实现完成时 API 表与 types.ts 不一致）
+3. **验收**：reference 更新 demo（规则 10：范式页 + 手验 + build 静态验证）+ 单测 + 双链 build（规则 9.1）
+4. **非 API 文档收尾**（[MUST] 作为 spec TASK 单列，[MUST NOT] 靠「收尾顺手补」）：定位 / 快速上手（最小可用，从 demo 最小形态提炼）/ 能力边界 / 反模式——此时实现与 demo 已定型，写出的姿势全部经实证
+
+**复核闸**：第 4 步执行时 [MUST] 对照 `types.ts` + `withDefaults` 复核 API 表（预言 vs 兑现兑平）——「API 以 types.ts 为真相源」双向执行：实现前 API 表当契约写，实现后 types.ts 当真相校。

package/src/components/app-layout/README.md

@@ -0,0 +1,46 @@
+# app-layout（应用布局族）
+
+> 应用壳族：AppLayout 数据桥/机制 + AppPage 页面容器 + AppBody 内容主体 + 六件布局积木（Header/Sidebar/Aside/Breadcrumb/Footer/Theme）。
+> 范式页：`apps/reference/src/App.vue`（族总装配）、`apps/reference/src/pages/app-layout/shell/`（自供 shell 积木直引）、`apps/reference/src/pages/app-layout/page-slots/`（AppPage 四向悬浮槽）、`apps/reference/src/pages/app-layout/layout/`（布局显隐变体）
+
+## 组件清单
+
+| 组件 | 一句话 | 核心 props | 文档 |
+| --- | --- | --- | --- |
+| `AppLayout` | 应用布局总控：bridge/appStore/userStore 三注入 + 5 内容锚 + 内置默认经典布局 shell | `bridge`（必填）`appStore`（必填）`userStore`（必填）`watermarkContent` `sidebarAboveHeader` | [README-AppLayout.md](./docs/README-AppLayout.md) |
+| `AppPage` | 页面主体容器：撑满视口 + 四向悬浮 fixed 插槽 | `fullViewport` `fullMode` `gap` `topBg`/`bottomBg`/`leftBg`/`rightBg` `nextViewportMaxHeight` | [README-AppPage.md](./docs/README-AppPage.md) |
+| `AppBody` | 内容主体：内置 RouterView + KeepAlive + 面包屑 affix + #footer 槽 | `menuFlatList` | [README-AppBody.md](./docs/README-AppBody.md) |
+| `AppHeader` | 顶栏积木：#left 品牌 + 路由模块菜单 + #right 操作区 | `menus` `menuFlatList`（必填）`show`（未消费） | [README-AppHeader.md](./docs/README-AppHeader.md) |
+| `AppSidebar` | 侧边栏积木：折叠把手 + MenuTree 菜单 + #top/#bottom 高度自撑 | `show` `menus`（必填）`menuFlatList`（必填）`aboveHeader` | [README-AppSidebar.md](./docs/README-AppSidebar.md) |
+| `AppAside` | 右侧补充区积木（对称 AppSidebar），无内置内容 | `show` | [README-AppAside.md](./docs/README-AppAside.md) |
+| `AppBreadcrumb` | 面包屑积木：menuFlatList 匹配 route.matched 出链 | `height`（必填）`menuFlatList`（必填） | [README-AppBreadcrumb.md](./docs/README-AppBreadcrumb.md) |
+| `AppFooter` | 底部状态条积木：高度/样式随 appStore.footerStyle 驱动，零 props | 无 | [README-AppFooter.md](./docs/README-AppFooter.md) |
+| `AppTheme` | 主题切换器积木：bridge.theme 直读直写（亮/暗/系统 + 风格下拉） | 无 | [README-AppTheme.md](./docs/README-AppTheme.md) |
+
+## 契约与类型（types.ts）
+
+契约集中在 `app-layout/types.ts`（族内无每组件独立 types.ts），导出：
+
+| 类型 | 语义 |
+| --- | --- |
+| `AppLayoutAppStoreSlice<UserInfo>` | createAppStore 返回类型窄化 |
+| `AppLayoutUserStoreSlice<UserInfo>` | createUserStore 返回类型窄化 |
+| `AppLayoutBridgeSlice` | CoreBridge Pick 窄化：12+ readonly 配置 + theme* 系列 + getRoutes/generateRouteMetaRawTree |
+| `AppShellContentAnchor` | 内容锚名联合：`"brand" \| "userEntry" \| "settings" \| "themeSwitcher" \| "aside"` |
+| `AppShellProps` / `AppShellEmits`（空）/ `AppShellDefaultSlotScope`（`{ Footer: Component }`）/ `AppShellAnchorScope`（`{ Default?: Component }`）/ `AppShellSlots` | 布局插件自供 shell 的契约 |
+
+## 内部件（不导出）
+
+- `AppShell`：内置默认经典布局 shell（左 sidebar + 顶 header + 主体 body 1:1 镜像）——仅 AppLayout 内部 import；布局插件自供 shell（可照搬内置实现、复用上述积木）
+- `AppCollapseToggle`：族内共享折叠积木（AppSidebar/AppAside 内部使用），未导出
+- `keep-alive.ts`：AppBody depth-0 KeepAlive 缓存判据（真叶子 + meta.keepAlive），内部工具不入公共 barrel
+
+## 导出面（index.ts）
+
+9 组件 + `export * from "./types"` + `./viewport`（`CORE_VIEWPORT_DECOR_ZINDEX_BELOW`=800 弹窗下档 / `CORE_VIEWPORT_DECOR_ZINDEX_ABOVE`=10000 弹窗上档）+ `./app-page-geometry`（`computeAppPageReducedViewportHeight`/`computeAppPageReducedViewportWidth`、`computeAppPageContentInset`、`computeAppPageSlotStyles`、`computeAppPageSlotShimStyles` + `APP_PAGE_SLOT_Z_INDEX`=1）
+
+## 关联
+
+- 布局插件自供 shell 契约：`AppShellProps` / `AppShellSlots`（types.ts）
+- 页面级骨架（ListPage 等）以 `AppPage` 为宿主：`apps/reference/src/pages/app-layout/page-slots/`
+- 范式页：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/page-slots/`、`apps/reference/src/pages/app-layout/layout/`

package/src/components/app-layout/docs/README-AppAside.md

@@ -0,0 +1,69 @@
+# AppAside（右侧补充区积木）
+
+> 右侧补充区积木（对称 AppSidebar）：默认 slot 承载右侧面板内容；核内默认宽 0，app/preset 加宽启用。
+> 范式页：`apps/reference/src/App.vue`（AppLayout #aside 锚经 shell 落位到 AppAside 默认槽）、`apps/reference/src/pages/app-layout/shell/`
+
+## 定位
+
+- **何时用**：右侧补充区（对话面板/属性栏等）——AppLayout `#aside` 内容锚的落位目标
+- 始终渲染（对称 sidebar）；核内默认宽 0 → 经典布局 1:1 无右间隙；app/preset 加宽即启用
+- 无内置内容——内容完全由默认 slot 提供
+- `show=false` 整列不渲染
+
+## 快速上手（最小可用）
+
+业务侧只填 AppLayout `#aside` 锚（App.vue 范式——内容经 shell 中转喂进 AppAside 默认槽）：
+
+```vue
+<AppLayout :bridge="appCoreBridge" :appStore="appStore" :userStore="userStore">
+  <template #brand><AppBrand /></template>
+  <template #userEntry><UserHeaderAction /></template>
+  <template #aside><ChatAsidePanel /></template>
+</AppLayout>
+```
+
+**要点**：
+
+- `#aside` 内容锚单实例（同 #brand/#userEntry 范式），落位权归 shell
+
+## 能力边界 / 按需使用
+
+- **宽度不在组件自身**：核内默认宽 0（经典布局 1:1 无右间隙）——加宽由 app/preset 配置（`bridge.APP_LAYOUT_ASIDE_CONFIG.width`）启用，[MUST NOT] 在 AppAside 自身调宽度。
+- **无 `#aside` 内容即空渲染**：始终渲染（对称 sidebar）但无内置内容——不填即零右间隙，填了才出现右侧补充区。
+- `show` 显隐基线来自路由 `meta.layout.aside`（store showAside），false 整列不渲染。
+- **完整能力演示**（#aside 锚 + 自供 shell）：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`
+
+## API
+> ⚠️ API 以 types.ts 与组件源码为真相源；与文档冲突时以源码为准。
+
+### Props
+
+| name | type | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `show` | `boolean`（必填） | — | 显隐（false 整列不渲染） |
+
+### Emits
+
+无
+
+### Slots
+
+| 槽 | scope | 语义 |
+| --- | --- | --- |
+| `default` | 无 | 右侧补充区内容（无内置内容） |
+
+### Expose
+
+无
+
+## 反模式 / 注意
+
+- **别给 AppAside 塞「布局默认内容」**：内容全部来自默认 slot（经 `#aside` 锚），无内置内容
+- **别在 AppAside 自身调宽度**：核内默认宽 0，加宽由 app/preset 决定
+- 无填 `#aside` 则空渲染——经典布局无右间隙（1:1 镜像）
+
+## 关联
+
+- 对称积木：`AppSidebar`
+- 内容锚：`#aside`（AppLayout 5 锚之一，`AppShellContentAnchor`）
+- 范式页：`apps/reference/src/App.vue`、`apps/reference/src/pages/app-layout/shell/`