@done-coding/admin-core 0.23.0 → 0.23.1-alpha.0

package/es/components/app-layout/AppSidebar.vue.mjs

@@ -1,7 +1,7 @@
 import _sfc_main from "./AppSidebar.vue2.mjs";
 /* empty css                 */
 import _export_sfc from "../../_virtual/_plugin-vue_export-helper.mjs";
-const AppSidebar = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-8aa015fb"]]);
+const AppSidebar = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-6808ecdb"]]);
 export {
   AppSidebar as default
 };

package/es/components/app-layout/AppSidebar.vue2.mjs

@@ -14,9 +14,9 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
   },
   setup(__props) {
     useCssVars((_ctx) => ({
-      "v3ceb1df4": sidebarZIndex.value,
-      "v2c8b87ee": shimTop.value,
-      "baa8be1c": shimBottom.value
+      "a540a4d0": sidebarZIndex.value,
+      "v4433cc00": shimTop.value,
+      "v7d77fda0": shimBottom.value
     }));
     const props = __props;
     const appStore = inject(APP_LAYOUT_APP_STORE_KEY);
@@ -38,6 +38,9 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     };
     const bridge = inject(APP_LAYOUT_BRIDGE_KEY);
     const themeColors = computed(() => bridge.themeColors.value);
+    const menuGroupMode = computed(
+      () => bridge.APP_LAYOUT_SIDEBAR_CONFIG.menuGroupMode ?? false
+    );
     return (_ctx, _cache) => {
       return openBlock(), createElementBlock("div", {
         class: "app-sidebar",
@@ -61,8 +64,9 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             "text-color": themeColors.value.baseColor,
             "active-text-color": themeColors.value.primaryColor,
             menuFlatList: __props.menuFlatList,
+            groupMode: menuGroupMode.value,
             routerMode: ""
-          }, null, 8, ["collapse", "menus", "background-color", "text-color", "active-text-color", "menuFlatList"])
+          }, null, 8, ["collapse", "menus", "background-color", "text-color", "active-text-color", "menuFlatList", "groupMode"])
         ]),
         createVNode(unref(_sfc_main$1), {
           class: "app-sidebar-bottom",
@@ -75,7 +79,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
         }),
         createVNode(AppCollapseToggle, {
           side: "sidebar",
-          show: __props.show,
+          show: __props.show && !menuGroupMode.value,
           collapse: collapse.value,
           onToggle: onToggleCollapse
         }, null, 8, ["show", "collapse"])

package/es/components/form/FormUpload.vue.mjs

@@ -2,7 +2,7 @@ import _sfc_main from "./FormUpload.vue2.mjs";
 /* empty css                 */
 /* empty css                 */
 import _export_sfc from "../../_virtual/_plugin-vue_export-helper.mjs";
-const FormUpload = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-158fc67d"]]);
+const FormUpload = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-9f186e75"]]);
 export {
   FormUpload as default
 };

package/es/components/form/FormUploadCard.vue.mjs

@@ -1,7 +1,7 @@
 import _sfc_main from "./FormUploadCard.vue2.mjs";
 /* empty css                     */
 import _export_sfc from "../../_virtual/_plugin-vue_export-helper.mjs";
-const FormUploadCard = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-48323f64"]]);
+const FormUploadCard = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-3989639c"]]);
 export {
   FormUploadCard as default
 };

package/es/components/menu/MenuTree.vue.mjs

@@ -1,7 +1,7 @@
 import { defineComponent, ref, useAttrs, computed, openBlock, createBlock, unref, mergeProps, withCtx, createElementBlock, Fragment, renderList, resolveDynamicComponent, createCommentVNode, createElementVNode, toDisplayString } from "vue";
 import _sfc_main$1 from "./MenuItemSub.vue.mjs";
 import { useRoute } from "vue-router";
-import { ElMenu, ElMenuItem, ElIcon } from "element-plus";
+import { ElMenu, ElMenuItemGroup, ElMenuItem, ElIcon } from "element-plus";
 const _sfc_main = /* @__PURE__ */ defineComponent({
   __name: "MenuTree",
   props: {
@@ -9,7 +9,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     menuFlatList: {},
     routerMode: { type: Boolean },
     collapse: { type: Boolean },
-    autoClose: { type: Boolean }
+    autoClose: { type: Boolean },
+    groupMode: { type: Boolean }
   },
   setup(__props, { expose: __expose }) {
     const props = __props;
@@ -72,12 +73,44 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             return openBlock(), createElementBlock(Fragment, {
               key: menu.path
             }, [
-              menu.children.length ? (openBlock(), createBlock(_sfc_main$1, {
+              __props.groupMode && menu.children.length ? (openBlock(), createBlock(unref(ElMenuItemGroup), {
                 key: 0,
+                title: menu.title
+              }, {
+                default: withCtx(() => [
+                  (openBlock(true), createElementBlock(Fragment, null, renderList(menu.children, (item) => {
+                    return openBlock(), createElementBlock(Fragment, {
+                      key: item.path
+                    }, [
+                      item.children.length ? (openBlock(), createBlock(_sfc_main$1, {
+                        key: 0,
+                        menu: item,
+                        MenuItemSub: _sfc_main$1
+                      }, null, 8, ["menu"])) : (openBlock(), createBlock(unref(ElMenuItem), {
+                        key: 1,
+                        index: item.path
+                      }, {
+                        default: withCtx(() => [
+                          item.menuIcon ? (openBlock(), createBlock(unref(ElIcon), { key: 0 }, {
+                            default: withCtx(() => [
+                              (openBlock(), createBlock(resolveDynamicComponent(item.menuIcon)))
+                            ]),
+                            _: 2
+                          }, 1024)) : createCommentVNode("", true),
+                          createElementVNode("span", null, toDisplayString(item.title), 1)
+                        ]),
+                        _: 2
+                      }, 1032, ["index"]))
+                    ], 64);
+                  }), 128))
+                ]),
+                _: 2
+              }, 1032, ["title"])) : menu.children.length ? (openBlock(), createBlock(_sfc_main$1, {
+                key: 1,
                 menu,
                 MenuItemSub: _sfc_main$1
               }, null, 8, ["menu"])) : (openBlock(), createBlock(unref(ElMenuItem), {
-                key: 1,
+                key: 2,
                 index: menu.path
               }, {
                 default: withCtx(() => [

package/es/components/view-layout/ViewLayout.vue.mjs

@@ -1,7 +1,7 @@
 import _sfc_main from "./ViewLayout.vue2.mjs";
 /* empty css                 */
 import _export_sfc from "../../_virtual/_plugin-vue_export-helper.mjs";
-const ViewLayout = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-f0ed342f"]]);
+const ViewLayout = /* @__PURE__ */ _export_sfc(_sfc_main, [["__scopeId", "data-v-c8a1cb2d"]]);
 export {
   ViewLayout as default
 };

package/es/components/view-layout/ViewLayout.vue2.mjs

@@ -1,4 +1,5 @@
-import { defineComponent, shallowRef, ref, computed, provide, watch, openBlock, createElementBlock, unref, createBlock, withCtx, createElementVNode, normalizeStyle, renderSlot, withDirectives, createVNode, vShow, Fragment } from "vue";
+import { defineComponent, shallowRef, ref, useModel, computed, provide, watch, withDirectives, openBlock, createElementBlock, unref, createBlock, withCtx, createElementVNode, normalizeStyle, renderSlot, createVNode, vShow, Fragment, mergeModels } from "vue";
+import { vLoading } from "element-plus";
 import AutoRefreshGroup from "../misc/AutoRefreshGroup.vue.mjs";
 import _sfc_main$1 from "../display/HeightProvider.vue.mjs";
 import _sfc_main$2 from "../display/ActionBtnGroup.vue.mjs";
@@ -17,7 +18,7 @@ const _hoisted_7 = { class: "view-layout-toolbar__right" };
 const _hoisted_8 = { class: "view-layout-content" };
 const _sfc_main = /* @__PURE__ */ defineComponent({
   __name: "ViewLayout",
-  props: {
+  props: /* @__PURE__ */ mergeModels({
     api: {},
     params: {},
     refine: { type: Boolean, default: void 0 },
@@ -29,7 +30,11 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     showRefresh: { type: Boolean, default: true },
     leftExtraButtons: { default: () => [] },
     rightExtraButtons: { default: () => [] }
-  },
+  }, {
+    "isAutoRefresh": { type: Boolean },
+    "isAutoRefreshModifiers": {}
+  }),
+  emits: ["update:isAutoRefresh"],
   setup(__props) {
     const props = __props;
     const { ctxRefine } = useContextDefaults({
@@ -41,6 +46,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
     const { viewportHeightFinal, nearestScope } = useChannelViewportHeight(props);
     const data = shallowRef(void 0);
     const loading = ref(false);
+    const isAutoRefresh = useModel(__props, "isAutoRefresh");
     const fetch = async () => {
       loading.value = true;
       try {
@@ -50,6 +56,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       }
     };
     const refresh = fetch;
+    const showLoadingMask = computed(() => !isAutoRefresh.value && loading.value);
     const toolbarCtx = computed(() => ({
       loading: loading.value,
       refresh
@@ -84,7 +91,7 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
       () => console.error("[ViewLayout] channel 不支持响应式变更,当前值已忽略。")
     );
     return (_ctx, _cache) => {
-      return openBlock(), createElementBlock("div", _hoisted_1, [
+      return withDirectives((openBlock(), createElementBlock("div", _hoisted_1, [
         unref(ctxRefine) ? (openBlock(), createBlock(unref(_sfc_main$1), {
           key: 0,
           viewportHeight: heightProviderViewportHeight.value,
@@ -107,11 +114,13 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
                   "default-size": "small"
                 }, null, 8, ["configs", "ctx"]),
                 createVNode(unref(AutoRefreshGroup), {
+                  isAutoRefresh: isAutoRefresh.value,
+                  "onUpdate:isAutoRefresh": _cache[0] || (_cache[0] = ($event) => isAutoRefresh.value = $event),
                   refreshFn: fetch,
                   loading: loading.value,
                   showAutoRefresh: __props.showAutoRefresh,
                   showRefresh: __props.showRefresh
-                }, null, 8, ["loading", "showAutoRefresh", "showRefresh"])
+                }, null, 8, ["isAutoRefresh", "loading", "showAutoRefresh", "showRefresh"])
               ])
             ], 512), [
               [vShow, hasToolbarContent.value]
@@ -147,11 +156,13 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
                 "default-size": "small"
               }, null, 8, ["configs", "ctx"]),
               createVNode(unref(AutoRefreshGroup), {
+                isAutoRefresh: isAutoRefresh.value,
+                "onUpdate:isAutoRefresh": _cache[1] || (_cache[1] = ($event) => isAutoRefresh.value = $event),
                 refreshFn: fetch,
                 loading: loading.value,
                 showAutoRefresh: __props.showAutoRefresh,
                 showRefresh: __props.showRefresh
-              }, null, 8, ["loading", "showAutoRefresh", "showRefresh"])
+              }, null, 8, ["isAutoRefresh", "loading", "showAutoRefresh", "showRefresh"])
             ])
           ], 512), [
             [vShow, hasToolbarContent.value]
@@ -165,6 +176,8 @@ const _sfc_main = /* @__PURE__ */ defineComponent({
             }, void 0, true)
           ])
         ], 64))
+      ])), [
+        [unref(vLoading), showLoadingMask.value]
       ]);
     };
   }

package/es/store/app.mjs

@@ -8,8 +8,12 @@ function createAppStore(deps) {
     const footerHeight = computed(() => bridge.APP_LAYOUT_FOOTER_CONFIG.height);
     const name = computed(() => bridge.APP_BASE_INFO.name);
     const sidebarHasMenus = ref(false);
+    const sidebarCollapsedEffective = computed(() => {
+      if (bridge.APP_LAYOUT_SIDEBAR_CONFIG.menuGroupMode) return false;
+      return bridge.layout.sidebarCollapsed.value;
+    });
     const sidebarWidth = computed(() => {
-      return bridge.layout.sidebarCollapsed.value ? bridge.APP_LAYOUT_SIDEBAR_CONFIG.collapseWidth : bridge.APP_LAYOUT_SIDEBAR_CONFIG.width;
+      return sidebarCollapsedEffective.value ? bridge.APP_LAYOUT_SIDEBAR_CONFIG.collapseWidth : bridge.APP_LAYOUT_SIDEBAR_CONFIG.width;
     });
     const route = useRoute();
     const theme = computed(() => bridge.themeColors.value);
@@ -191,7 +195,8 @@ function createAppStore(deps) {
       bodyShimStyle,
       viewportPadding,
       // 折叠态读 bridge 真相（架构反转，名字保留向后兼容）；aside 对称新增。
-      sidebarIsCollapse: computed(() => bridge.layout.sidebarCollapsed.value),
+      // sidebar 侧经 sidebarCollapsedEffective 单点（分组形态闸为 false，见其注释）。
+      sidebarIsCollapse: sidebarCollapsedEffective,
       asideIsCollapse: computed(() => bridge.layout.asideCollapsed.value),
       changeSidebarCollapseStatus,
       changeAsideCollapseStatus,

package/es/style.css

@@ -499,34 +499,34 @@
   display: flex;
   align-items: center;
 }
-.app-sidebar[data-v-8aa015fb] {
+.app-sidebar[data-v-6808ecdb] {
   transition-duration: 0.3s;
   transition-property: width;
   transition-timing-function: linear;
   box-shadow: var(--dc-core-shadow, var(--el-box-shadow));
   overflow: visible;
-  z-index: var(--v3ceb1df4);
+  z-index: var(--a540a4d0);
 }
-.app-sidebar-top[data-v-8aa015fb] {
+.app-sidebar-top[data-v-6808ecdb] {
   position: absolute;
   left: 0;
   right: 0;
   top: 0;
   overflow: hidden;
 }
-.app-sidebar-bottom[data-v-8aa015fb] {
+.app-sidebar-bottom[data-v-6808ecdb] {
   position: absolute;
   left: 0;
   right: 0;
   bottom: 0;
   overflow: hidden;
 }
-.app-sidebar-shim[data-v-8aa015fb] {
+.app-sidebar-shim[data-v-6808ecdb] {
   position: absolute;
   left: 0;
   right: 0;
-  top: var(--v2c8b87ee);
-  bottom: var(--baa8be1c);
+  top: var(--v4433cc00);
+  bottom: var(--v7d77fda0);
   overflow-x: hidden;
   overflow-y: auto;
   --el-menu-border-color: transparent;
@@ -964,7 +964,7 @@ to {
   padding: 0;
   color: var(--el-text-color-secondary);
 }
-.dc-form-upload__placeholder[data-v-158fc67d] {
+.dc-form-upload__placeholder[data-v-9f186e75] {
   margin-top: 4px;
   font-size: 12px;
   line-height: 1.5;
@@ -1035,14 +1035,16 @@ to {
 .dc-form-upload-audio__item:hover .dc-form-upload-audio__remove[data-v-3884f0f6] {
   opacity: 1;
 }
-.dc-form-upload-card[data-v-48323f64] {
+.dc-form-upload-card[data-v-3989639c] {
   position: relative;
   width: 100%;
   height: 100%;
   overflow: hidden;
+  display: flex;
+  align-items: center;
   background: var(--el-fill-color-light);
 }
-.dc-form-upload-card__mask[data-v-48323f64] {
+.dc-form-upload-card__mask[data-v-3989639c] {
   position: absolute;
   inset: 0;
   display: flex;
@@ -1055,17 +1057,17 @@ to {
   color: var(--el-color-white);
   font-size: 12px;
 }
-.dc-form-upload-card__mask-name[data-v-48323f64] {
+.dc-form-upload-card__mask-name[data-v-3989639c] {
   max-width: 100%;
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
 }
-.dc-form-upload-card__mask-percent[data-v-48323f64] {
+.dc-form-upload-card__mask-percent[data-v-3989639c] {
   font-size: 13px;
   font-weight: 600;
 }
-.dc-form-upload-card__mask-bar[data-v-48323f64] {
+.dc-form-upload-card__mask-bar[data-v-3989639c] {
   position: absolute;
   left: 0;
   bottom: 0;
@@ -1073,7 +1075,7 @@ to {
   background: var(--el-color-primary);
   transition: width 0.2s;
 }
-.dc-form-upload-card__remove[data-v-48323f64] {
+.dc-form-upload-card__remove[data-v-3989639c] {
   position: absolute;
   top: 4px;
   right: 4px;
@@ -1091,7 +1093,7 @@ to {
   opacity: 0;
   transition: opacity 0.2s;
 }
-.dc-form-upload-card:hover .dc-form-upload-card__remove[data-v-48323f64] {
+.dc-form-upload-card:hover .dc-form-upload-card__remove[data-v-3989639c] {
   opacity: 1;
 }
 .dc-form-upload-image__thumb[data-v-9d62114a] {
@@ -1269,24 +1271,24 @@ to {
   gap: 8px;
   margin-top: 8px;
 }
-.view-layout[data-v-f0ed342f] {
+.view-layout[data-v-c8a1cb2d] {
   display: flex;
   flex-direction: column;
   gap: 8px;
 }
-.view-layout-toolbar[data-v-f0ed342f] {
+.view-layout-toolbar[data-v-c8a1cb2d] {
   display: flex;
   justify-content: space-between;
   align-items: center;
   padding-bottom: 8px;
   gap: 20px;
 }
-.view-layout-toolbar__left[data-v-f0ed342f],
-.view-layout-toolbar__right[data-v-f0ed342f] {
+.view-layout-toolbar__left[data-v-c8a1cb2d],
+.view-layout-toolbar__right[data-v-c8a1cb2d] {
   display: flex;
   align-items: center;
   gap: 10px;
 }
-.view-layout-content[data-v-f0ed342f] {
+.view-layout-content[data-v-c8a1cb2d] {
   overflow: auto;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@done-coding/admin-core",
-  "version": "0.23.0",
+  "version": "0.23.1-alpha.0",
   "description": "内部前端库",
   "private": false,
   "main": "es/index.mjs",
@@ -83,5 +83,5 @@
   "dependencies": {
     "@tanstack/vue-virtual": "^3.13.35"
   },
-  "gitHead": "345849870494584a62144db4e7bc983d49ed38fa"
+  "gitHead": "1112339ffe6bdb4569c9f1c9f3a2e3b7da9c15dd"
 }

package/src/bridge/docs/README.md

@@ -44,11 +44,38 @@ app.use(appCoreBridge);                 // opt-in：CORE_BRIDGE_KEY 注入
 响应式更新（`update` 改配置视图，全链路即时生效）：
 
 ```ts
-appCoreBridge.update({ APP_LAYOUT_VIEWPORT_CONFIG: { ... } });
+appCoreBridge.update("APP_LAYOUT_VIEWPORT_CONFIG", { ... });   // 单 key + 一级浅合并
 appCoreBridge.theme.setStyle("studio-stage");
 appCoreBridge.theme.setDark(true);
 ```
 
+## 布局配置里的行为开关
+
+布局 8 组配置多为几何数值（宽高 / 间距 / 配色），少数是**行为开关**——需要单独知道语义：
+
+| 配置键 | 字段 | 默认 | 语义 |
+| --- | --- | --- | --- |
+| `APP_LAYOUT_SIDEBAR_CONFIG` | `menuGroupMode?: boolean` | `false` | 侧栏菜单渲染形态：`false` = 树形（父级手风琴，默认收起）；`true` = 分组（父级降格为小字号弱色的 section heading，不可点不可折叠，子项常驻全展开） |
+
+```ts
+// 初始化时定形态
+createCoreBridge({
+  APP_LAYOUT_SIDEBAR_CONFIG: { width: 220, collapseWidth: 64, menuGroupMode: true },
+  // ...
+});
+
+// 或运行时切（本键在 UpdatableConfigKey 联合内，reactive 全链路即时生效）
+appCoreBridge.update("APP_LAYOUT_SIDEBAR_CONFIG", { menuGroupMode: true });
+```
+
+**连带影响（开启 `menuGroupMode` 后）**：
+
+- `AppSidebar` 不渲染折叠把手，侧栏宽度恒取 `width`——`collapseWidth` 在该形态下不生效；
+- `bridge.layout.sidebarCollapsed` 的**读取被屏蔽**（避免历史持久化的 `true` 把无把手的侧栏锁死在窄条），但**持久化值原样保留**，关掉该形态即恢复；
+- 因此该形态下调 `bridge.layout.setSidebarCollapse` / `toggleSidebar` 不报错但视觉无效。
+
+适用判据与三级菜单的混合渲染规则见 [menu 族文档](../../components/menu/README.md) 与 [AppSidebar 文档](../../components/app-layout/docs/README-AppSidebar.md)。
+
 ## 认证与请求接线
 
 ### 认证 facade（bridge 4 钩子 + userInfoAccess）

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

@@ -11,7 +11,7 @@
 | `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) |
+| `AppSidebar` | 侧边栏积木：折叠把手 + MenuTree 菜单（树形/分组双形态）+ #top/#bottom 高度自撑 | `show` `menus`（必填）`menuFlatList`（必填）`aboveHeader`；菜单形态读 bridge `APP_LAYOUT_SIDEBAR_CONFIG.menuGroupMode`（分组态无折叠把手） | [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) |

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

@@ -1,6 +1,6 @@
 # AppSidebar（侧边栏积木）
 
-> 左侧栏积木：折叠把手 + MenuTree 菜单渲染 + #top/#bottom 高度自撑插槽；可 aboveHeader 悬浮盖顶。
+> 左侧栏积木：折叠把手 + MenuTree 菜单渲染（树形 / 分组双形态）+ #top/#bottom 高度自撑插槽；可 aboveHeader 悬浮盖顶。
 > 范式页：`apps/reference/src/pages/app-layout/shell/`（DemoCustomShell 自供 shell 积木直引）、`apps/reference/src/pages/app-layout/layout/`（NoSidebar 显隐变体）
 
 ## 定位
@@ -9,6 +9,22 @@
 - `show` 控制显隐（含折叠把手渲染开关）——false 即不渲染整栏
 - `aboveHeader` 时 z-index 2 盖 header（AppLayout 另有 `sidebarAboveHeader` prop 同源传递）
 - #top/#bottom 高度自撑（WatchSize 反推 shim 边界）——品牌区/挂件放 #top，底部操作放 #bottom
+- 菜单形态由 **bridge 配置**驱动（非 prop）：`bridge.APP_LAYOUT_SIDEBAR_CONFIG.menuGroupMode`（缺省 `false`）
+
+## 菜单形态：树形（默认）/ 分组
+
+`menuGroupMode` 落在 `APP_LAYOUT_SIDEBAR_CONFIG`（`createCoreBridge` 初始化传入，缺省 `false`；因在 `UpdatableConfigKey` 联合内，亦可 `bridge.update("APP_LAYOUT_SIDEBAR_CONFIG", { menuGroupMode: true })` 运行时切换）。AppSidebar 内部读它，**不开放同名 prop**——与 `collapse` 读 `appStore.sidebarIsCollapse` 同范式，业务侧统一在 bridge 一处配置。
+
+| | `menuGroupMode: false`（默认） | `menuGroupMode: true` |
+| --- | --- | --- |
+| 菜单渲染 | MenuTree 树形（父级手风琴，默认收起） | MenuTree 分组（父级 = 小字号弱色分组标题，子项常驻全展开） |
+| 折叠把手 `AppCollapseToggle` | 渲染 | **不渲染**（`show=false`） |
+| 侧栏宽度 | 随折叠态在 `width` / `collapseWidth` 间切换 | 恒取 `width`（展开态） |
+| `bridge.layout.sidebarCollapsed` | 生效 | **读取被屏蔽**，但持久化值原样保留 |
+
+**为什么分组形态没有折叠把手**：分组形态的前提是「全展开常驻」，与折叠成图标栏语义互斥；且 EP 的 `--collapse` 规则对 `el-menu-item-group` 支持不全（标题不隐藏、组内叶子不居中），窄栏必然错乱。故直接关掉该形态下的折叠能力，而非去打 EP 补丁。
+
+**⚠️ 折叠持久化的锁死风险与规避**（实现约束，[MUST] 守）：`bridge.layout` 把 `sidebarCollapsed` 持久化进 localStorage。若用户上次折叠过（落盘 `true`），开发者随后打开 `menuGroupMode`，侧栏会以 `collapseWidth` 窄条渲染却**没有把手可展开 → 永久锁死**。规避方式：`menuGroupMode` 为真时在 `store/app.ts` 单点把折叠态**读取**强制为 `false`（`sidebarWidth` 与 `sidebarIsCollapse` 两处共用同一 computed），**[MUST NOT] 写回** `bridge.layout.setSidebarCollapse`——用户的折叠偏好原样留在存储里，关掉分组形态后照常恢复。
 
 ## 快速上手（最小可用）
 
@@ -27,6 +43,7 @@
 
 - **`#top` / `#bottom` 高度自撑插槽按需**：默认零配置即菜单栏可用；仅当需要品牌区/挂件（`#top`）或底部操作区（`#bottom`）才填——高度自撑（WatchSize 反推 shim 边界），放多少内容撑多高。
 - **`aboveHeader` 默认关**：仅当 sidebar 需要 z-index 2 盖住 header 悬浮时开（与 AppLayout `sidebarAboveHeader` 同源传递，自供 shell 时对齐）。
+- **`menuGroupMode` 默认关（树形）即够用**：仅当菜单量小（经验值 ≤ 25 叶子）/ 层级浅、要求零点击看见全部导航才开；量大或层级深仍用树形，否则全展开会变成长滚动条。开启后自动失去折叠能力（见上表）。
 - `show=false` 整栏不渲染（含折叠把手）——「收起但保留把手」场景走折叠态而非 `show=false`。
 - **完整能力演示**（DemoCustomShell 槽转发范式 + NoSidebar 变体）：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`
 
@@ -59,12 +76,17 @@
 ## 反模式 / 注意
 
 - `show=false` 时折叠把手也随整栏不渲染（把手渲染开关即 show）——「收起但保留把手」场景应走折叠态而非 show=false
+- **`menuGroupMode` 下还想保留折叠把手**：两者语义互斥且 EP 折叠态不支持分组，[MUST NOT] 强开
+- **`menuGroupMode` 下调 `bridge.layout.setSidebarCollapse` / `appStore.changeSidebarCollapseStatus`**：调用不报错但视觉无效（读取被屏蔽），属无效操作
+- **给 AppSidebar 加同名 `menuGroupMode` prop 覆盖 bridge**：[MUST NOT]——形态是全 app 一致的布局配置，双真相源会让自供 shell 与内置 shell 表现分叉
 - `aboveHeader` 与 AppLayout `sidebarAboveHeader` 语义一致，自供 shell 时两者对齐（DemoCustomShell 透传范式）
 - 折叠/展开动画由族内积木承担，[MUST NOT] 自造折叠逻辑
 
 ## 关联
 
 - 折叠积木：`AppCollapseToggle`（族内共享，AppSidebar/AppAside 内部使用，未导出）
+- 菜单积木：`MenuTree`（menu 族，`groupMode` 双形态详见 [menu 族文档](../../menu/README.md)）
+- 配置真源：`APP_LAYOUT_SIDEBAR_CONFIG`（bridge，见 [bridge 文档](../../../bridge/docs/README.md)）
 - 右侧对称积木：`AppAside`
 - 内容锚：`#brand` 等（落位见 AppLayout 文档）
 - 范式页：`apps/reference/src/pages/app-layout/shell/`、`apps/reference/src/pages/app-layout/layout/`

package/src/components/menu/README.md

@@ -1,11 +1,24 @@
 # menu 菜单族
 
-配置化菜单族：`MenuTree`（基于 ElMenu 的树形菜单）+ `MenuItemSub`（递归子菜单分组件，MenuTree 内部递归用）。
+配置化菜单族：`MenuTree`（基于 ElMenu 的菜单，含**树形 / 分组**双渲染形态）+ `MenuItemSub`（递归子菜单分组件，MenuTree 内部递归用）。
+
+## 两种渲染形态（`MenuTree` 的 `groupMode`）
+
+| 形态 | `groupMode` | 父级节点渲染成 | 交互 | 适用 |
+| --- | --- | --- | --- | --- |
+| **树形**（默认） | `false` | `ElSubMenu`（手风琴） | 点击展开 / 收起，默认收起 | 菜单量大 / 层级深，靠折叠控制列表长度 |
+| **分组** | `true` | `ElMenuItemGroup`（分组标题：小字号 + 弱色，**不可点、不可折叠、不导航**） | 无——子项常驻全展开 | 菜单量小（经验值 ≤ 25 叶子）/ 层级浅，要求零点击看见全部导航 |
+
+分组形态即业界通称的 **grouped / sectioned navigation**（父级叫 section heading / group label）：shadcn/ui `SidebarGroupLabel`、Ant Design `Menu type:"group"`、Element Plus `el-menu-item-group`、Material 3 / Fluent 2 的 navigation section header 都是同一范式；Linear / Stripe / Vercel / Supabase / GitHub Settings 等产品的侧栏走的都是它而非手风琴。
+
+本族**不自造分组组件**——EP 的 `el-menu-item-group__title` 原生就是 `font-size: 12px` + `--el-text-color-secondary`，正是「字号偏小、颜色偏弱」，直接复用。
+
+> ⚠️ 分组形态**只吃掉一层**父级：三级及以上菜单中 L1 → 分组标题，L2 若仍有 `children` → 继续走 `ElSubMenu` 手风琴（混合渲染）。详见 [README-MenuTree.md](./docs/README-MenuTree.md)。
 
 ## 组件文档（docs/）
 
-- [MenuTree](./docs/README-MenuTree.md) — 树形菜单（menus 递归出 ElSubMenu + routerMode / autoClose / collapse + open/close expose）
-- [MenuItemSub](./docs/README-MenuItemSub.md) — 递归子菜单分组件（ElSubMenu 递归节点，一般由 MenuTree 自用）
+- [MenuTree](./docs/README-MenuTree.md) — 菜单主体（menus 递归 + `groupMode` 树形 / 分组双形态 + routerMode / autoClose / collapse + open/close expose）
+- [MenuItemSub](./docs/README-MenuItemSub.md) — 递归子菜单分组件（ElSubMenu 递归节点，一般由 MenuTree 自用；分组形态下承接 L2 及更深层级）
 
 ## 关键类型
 
@@ -14,6 +27,6 @@
 
 ## 范式页（apps/reference）
 
-- 真实消费方：`AppSidebar`（packages/core/src/components/app-layout/AppSidebar.vue）——生产级驱动点
+- 真实消费方：`AppSidebar`（packages/core/src/components/app-layout/AppSidebar.vue）——生产级驱动点；其 `groupMode` 由 `bridge.APP_LAYOUT_SIDEBAR_CONFIG.menuGroupMode` 驱动，业务侧不直传
 - 菜单数据契约范式：`apps/reference/src/router/modules/test.ts`（meta.menu 的 show / icon / sort 驱动渲染与排序）
 - 注意：`/menu/showcase/Page1/2/3` 是菜单渲染出的叶子路由页，不是 MenuTree 的用法示范

package/src/components/menu/docs/README-MenuItemSub.md

@@ -8,6 +8,9 @@
 - 递归子菜单分组件：节点含 `children` → `ElSubMenu` + 递归子级；叶子 → `ElMenuItem`
 - 组件自引用：`MenuItemSub` prop 传入组件自身，供 children 递归再实例化
 - 一般由 `MenuTree` 内部使用，独立消费场景少见
+- **两种形态下的角色**：
+  - MenuTree `groupMode=false`（树形）→ 承接 **L1 及以下**全部有子项的节点
+  - MenuTree `groupMode=true`（分组）→ L1 已被 `ElMenuItemGroup` 分组标题接管，本组件**只承接 L2 及更深**层级（即「分组标题内的手风琴」）。分组标题只吃掉一层，深层级仍归本组件——这是分组形态下三级菜单混合渲染的实现落点
 
 ## 快速上手（最小可用）
 
@@ -46,6 +49,7 @@ MenuTree 内部驱动（menu/MenuTree.vue 片段）：
 ## 反模式 / 注意
 
 - **缺自引用 prop**：children 递归靠 `MenuItemSub` prop 再实例化，缺它无法递归展开子级
+- **想在分组形态下把本组件也换成分组标题**：分组标题是视觉聚类不是层级实体，[MUST NOT] 嵌套分组（EP / AntD / shadcn 皆不支持）；L2+ 保持 ElSubMenu 是设计内行为
 
 ## 关联
 

package/src/components/menu/docs/README-MenuTree.md

@@ -1,15 +1,31 @@
 # MenuTree（树形菜单）
 
-> 基于 ElMenu 的配置化树形菜单：menus 树形数据递归出 ElSubMenu，叶子渲染 ElMenuItem；routerMode 路由联动、autoClose 选中收合、collapse 折叠透传。
+> 基于 ElMenu 的配置化菜单：menus 树形数据递归渲染，含**树形（手风琴）/ 分组（section heading）**双形态；routerMode 路由联动、autoClose 选中收合、collapse 折叠透传。
 > 范式页：真实消费方为 `AppSidebar`（packages/core/src/components/app-layout/AppSidebar.vue）；菜单数据契约范式见 `apps/reference/src/router/modules/test.ts`
 
 ## 定位
 
-- **何时用**：侧栏 / 导航需要配置驱动的树形菜单（递归子菜单、路由联动、折叠态）
+- **何时用**：侧栏 / 导航需要配置驱动的菜单（递归子菜单、路由联动、折叠态、分组标题）
 - **何时不用**：单层 / 少量菜单直接用 ElMenu；菜单数据不来自路由配置时自行组装数据再接入
-- 数据驱动：`menus` 树形节点含 `children` 递归出 `ElSubMenu`，叶子渲染 `ElMenuItem`；`menuFlatList` 拍平列表供 autoClose 沿 `parentPath` 递归算父链
+- 数据驱动：`menus` 树形节点含 `children` 递归出父级容器，叶子渲染 `ElMenuItem`；`menuFlatList` 拍平列表供 autoClose 沿 `parentPath` 递归算父链
+- **双形态**：`groupMode=false`（默认）父级 → `ElSubMenu` 手风琴；`groupMode=true` 父级 → `ElMenuItemGroup` 分组标题（详见下节）
 - 增强点：routerMode（defaultActive 取 route.path + ElMenu :router）、autoClose（选中一项收合其它展开子菜单）、collapse 透传、ElMenu 其余 attrs 整包透传、open / close expose
 
+## 树形 / 分组双形态（`groupMode`）
+
+| | `groupMode=false`（默认，树形） | `groupMode=true`（分组） |
+| --- | --- | --- |
+| L1 有子项 | `ElSubMenu`，可点击展开 / 收起，**默认收起** | `ElMenuItemGroup :title`，小字号 + 弱色，**不可点、不导航、不折叠** |
+| L1 叶子 | `ElMenuItem` | `ElMenuItem`（同左） |
+| L2 及更深有子项 | `MenuItemSub` 递归 `ElSubMenu` | **仍是** `MenuItemSub` 递归 `ElSubMenu`（分组只吃掉一层，见下） |
+| 子项可见性 | 需点击父级才展开 | 常驻全展开 |
+
+**分组只吃掉一层——三级菜单是混合渲染。** 分组标题是「视觉聚类」而非「层级实体」，一层标题下不能再嵌一层标题（EP / AntD / shadcn 皆如此）。因此 L1 降格为分组标题后，L2 若仍有 `children`，只能继续用 `ElSubMenu` 手风琴。`apps/reference/src/router/modules/test.ts` 实测存在三级嵌套，分组形态下就会呈现「分组标题 + 组内手风琴」的混合形态，这是设计内行为，非缺陷。
+
+**选型判据**：叶子总量小（经验值 ≤ 25）且层级浅 → 分组（零点击可见全部导航，无手风琴的「东西藏哪了」认知负担）；量大或层级深 → 树形（否则全展开变成长滚动条）。
+
+**视觉不自造**：分组标题吃 EP 原生皮肤（`el-menu-item-group__title` = `font-size:12px` + `--el-text-color-secondary`）；需微调只走主题 var（规则 14），[MUST NOT] 写死颜色。
+
 ## 快速上手（最小可用）
 
 必填只有 `menus` + `menuFlatList`——默认 ElMenu 主题、无路由联动、无选中收合：
@@ -29,6 +45,7 @@
 - **`routerMode`：默认关即够用。** 仅当菜单项与路由 path 联动高亮才开——开启后 `defaultActive` 自动取 `route.path`（useRoute）+ ElMenu `:router` 同步开启；注意依赖 vue-router 上下文。
 - **`autoClose`：默认关即够用。** 仅当「选中一项后收合其它展开子菜单」才开——父链沿 `menuFlatList` 的 `parentPath` 递归计算，数据缺失时路径链断裂、收合不全。
 - **`collapse`：默认不折叠即够用。** 仅当侧栏折叠态需要同步收起菜单才传（透传 ElMenu）。
+- **`groupMode`：默认关（树形）即够用。** 仅当菜单量小 / 层级浅、要求全展开常驻导航才开。⚠️ **与 `collapse` 互斥**：分组形态的前提就是「常驻全展开」，两者同时为 true 无意义且 EP 折叠态对 `el-menu-item-group` 支持不全（EP 的 `--collapse` 规则既没隐藏 `el-menu-item-group__title`，也漏掉了 `> .el-menu-item-group > ul > .el-menu-item` 的「藏文字 + 图标居中」，会溢出窄栏）。消费方 [MUST NOT] 同开两者；`AppSidebar` 已在内部保证互斥（见其文档）。
 - **颜色 attrs（`background-color` / `text-color` / `active-text-color` 等）：默认 ElMenu 主题即够用。** 仅当需贴合页面主题配色才显式传。
 - **完整能力演示**（生产级驱动点 = AppSidebar 内部接线，含折叠 + 路由联动 + 主题配色）：`packages/core/src/components/app-layout/AppSidebar.vue`——能力展示，非推荐默认。
 
@@ -44,6 +61,7 @@
 | `routerMode?` | `boolean` | 未设 | 路由模式：true 时 defaultActive 取 route.path（useRoute）+ ElMenu :router 开启 |
 | `collapse?` | `boolean` | 未设 | 折叠态透传 ElMenu |
 | `autoClose?` | `boolean` | 未设 | 选中一项后关闭其它展开的 ElSubMenu |
+| `groupMode?` | `boolean` | `false` | 分组形态：L1 有子项时渲染 `ElMenuItemGroup` 分组标题（不可点 / 不折叠）替代 `ElSubMenu`；L2+ 仍走 ElSubMenu。与 `collapse` 互斥 |
 
 其余 attrs（`background-color` / `text-color` / `active-text-color` 等 ElMenu props）整包透传。
 
@@ -68,6 +86,9 @@
 - **autoClose 缺 parentPath 数据**：父链沿 `parentPath` 递归计算，数据缺失时路径链断裂、收合不全
 - **想覆盖内部 @select**：`v-bind="attrs"` 展开在前、`@select` 声明在后，外部 `onSelect` 无法覆盖内部 autoClose 逻辑（推断标注）
 - **依赖 vue-router 上下文**：routerMode 使用 `useRoute`，组件须在安装 vue-router 的上下文中使用
+- **`groupMode` + `collapse` 同开**：EP 折叠态不支持 `el-menu-item-group`（标题不隐藏 + 组内叶子不居中），窄栏会溢出错乱；两者语义本身也互斥
+- **指望 `groupMode` 把整棵树拍平**：它只把 L1 降为分组标题，L2+ 仍是手风琴；要全平请先把菜单数据本身收敛到两层
+- **`open` / `close` expose 在分组形态下对 L1 无效**：L1 已不是 `ElSubMenu`（无 index、无展开态），expose 仅对组内仍为 ElSubMenu 的 L2+ 节点有效
 
 ## 关联
 

package/types/bridge/index.d.ts

@@ -157,12 +157,22 @@ export interface AppConfig {
         /** 装饰逃生舱（见 {@link AppLayoutModuleStyle}） */
         style?: AppLayoutModuleStyle;
     };
-    /** 应用布局-sidebar 配置（store/app 取 collapseWidth / width） */
+    /** 应用布局-sidebar 配置（store/app 取 collapseWidth / width / menuGroupMode） */
     APP_LAYOUT_SIDEBAR_CONFIG: {
         /** [展开的]宽度(px) */
         width: number;
         /** 折叠起来的宽度(px) */
         collapseWidth: number;
+        /**
+         * 侧栏菜单渲染形态：`false`(缺省) = 树形（父级 ElSubMenu 手风琴，默认收起）；
+         * `true` = 分组（父级降格为 ElMenuItemGroup 分组标题——小字号弱色、不可点不可折叠，
+         * 子项常驻全展开，即业界 grouped / sectioned navigation 范式）。
+         *
+         * 开启后：AppSidebar 不渲染折叠把手、宽度恒取 `width`（`collapseWidth` 失效），
+         * 且 store 侧把 `bridge.layout.sidebarCollapsed` 的**读取**闸为 false
+         * （避免历史持久化的 true 把无把手的侧栏锁死在窄条）；持久化值原样保留。
+         */
+        menuGroupMode?: boolean;
         /** 字体色；缺省 → 继承 :root color(baseColor) */
         color?: string;
         /** 背景（color / image / gradient 等 CSS background）；缺省 → bodyColor */

package/types/components/menu/MenuTree.vue.d.ts

@@ -5,6 +5,15 @@ type __VLS_Props = {
     routerMode?: boolean;
     collapse?: boolean;
     autoClose?: boolean;
+    /**
+     * 分组形态：L1 有子项时渲染 ElMenuItemGroup 分组标题替代 ElSubMenu 手风琴，
+     * 子项常驻全展开（业界 grouped / sectioned navigation 范式）；L2+ 仍走 ElSubMenu。
+     *
+     * ⚠️ 与 `collapse` 互斥——分组形态前提即「常驻全展开」，且 EP 的 `--collapse` 规则
+     * 对 `el-menu-item-group` 支持不全（标题不隐藏 + 组内叶子不居中）会撑坏窄栏。
+     * 缺省 false = 树形形态，零回归。
+     */
+    groupMode?: boolean;
 };
 declare const _default: import('vue').DefineComponent<__VLS_Props, {
     open: (index: string) => void | undefined;

package/types/components/view-layout/ViewLayout.vue.d.ts

@@ -1,7 +1,11 @@
 import { VNode } from 'vue';
 import { ViewLayoutProps, ViewLayoutScope } from './types';
 declare const _default: <P extends Record<string, any> = Record<string, any>, R = any>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_expose?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
-    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{} & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, never> & ViewLayoutProps<P, R> & Partial<{}>> & import('vue').PublicProps;
+    props: __VLS_PrettifyLocal<Pick<Partial<{}> & Omit<{
+        readonly "onUpdate:isAutoRefresh"?: ((value: boolean) => any) | undefined;
+    } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, never>, "onUpdate:isAutoRefresh"> & ({
+        isAutoRefresh?: boolean;
+    } & ViewLayoutProps<P, R>) & Partial<{}>> & import('vue').PublicProps;
     expose(exposed: import('vue').ShallowUnwrapRef<{}>): void;
     attrs: any;
     slots: Readonly<{
@@ -9,7 +13,7 @@ declare const _default: <P extends Record<string, any> = Record<string, any>, R
     }> & {
         default: (scope: ViewLayoutScope<R>) => VNode[];
     };
-    emit: {};
+    emit: (evt: "update:isAutoRefresh", value: boolean) => void;
 }>) => import('vue').VNode & {
     __ctx?: Awaited<typeof __VLS_setup>;
 };

package/types/injectInfo.json.d.ts

@@ -1,6 +1,6 @@
 declare const _default: {
   "name": "@done-coding/admin-core",
-  "version": "0.23.0",
+  "version": "0.23.1-alpha.0",
   "description": "内部前端库"
 };