@robot-admin/layout 2.3.1 → 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,144 @@
+# Changelog
+
+## 3.0.0
+
+### Major Changes
+
+- Release the 3.0 architecture upgrade while preserving the existing Naive UI layouts, interactions, slots, and visual styling.
+
+  - Add a UI-independent `@robot-admin/layout/core` entrypoint for validated settings and shared contracts.
+  - Make layout/store injection and collapsed state work reliably with custom stores and multi-instance hosts.
+  - Replace destructive built-in storage clearing with explicit host actions and add stable SettingsDrawer extension slots.
+  - Validate complete imported configuration files before applying state and restore host-owned global classes on teardown.
+  - Respect the transition enable switch, harden route caching and responsive measurement, and improve built-in menu keyboard semantics.
+  - Verify all six layout modes in SSR and validate both ESM and CommonJS package entrypoints before publishing.
+
+## 2.3.2
+
+### Patch Changes
+
+- Validate imported settings at runtime, support short hex colors safely, and preserve invalid color input instead of silently turning it black.
+- Use route-segment-aware menu matching so `/users` no longer activates `/users-admin`.
+- Disable cache debug logging and global window helpers by default; add configurable Settings Store ids.
+- Standardize the automatic theme value on `system` and roll back settings if asynchronous theme synchronization fails.
+- Improve menu/drawer keyboard navigation, focus restoration and ARIA state; guard browser and Canvas APIs for SSR or unsupported environments.
+- Synchronize the exported version constant with package version 2.3.2 and add regression tests for the critical settings and routing contracts.
+
+## 2.2.0
+
+### 🐛 Bug 修复
+
+- **ReverseHorizontalMixLayout 右侧菜单错位**: 修复右侧菜单显示在底部而非右侧的问题（`.main-area` 添加 `flex-direction: row`）
+- **MixLayout 二级菜单消失**: 修复鼠标离开后二级菜单内容消失的问题（新增 `displayMenuItem` 作为 `hoveredMenuItem` 的 fallback）
+- **MixTopLayout 全局 CSS 泄漏**: 修复 `.main-area`、`.content-layout` 等选择器污染其他布局的问题（嵌套到 `.mix-top-layout-container` 内）
+
+### ✨ 功能优化
+
+- **ResponsiveMenu 字符宽度估算**: 区分 CJK 字符（15px）和 ASCII 字符（8px），顶部菜单文字完整显示不截断
+- **ReverseHorizontalMixLayout 折叠动画**: 用 width 过渡替代 Transition，避免黑色闪烁，动画更流畅（0.35s cubic-bezier）
+- **MixLayout 交互模式**: 从悬停触发改为纯点击模式，点击同一菜单切换展开/折叠，点击不同菜单切换内容不关闭
+
+### 🎨 视觉设计
+
+- **ReverseHorizontalMixLayout 玻璃质感**: 参考搜索组件样式，应用 indigo 渐变玻璃设计（`linear-gradient` + `backdrop-filter` + 顶部高光线）
+- **pure CSS 图标**: 替换所有 UnoCSS 图标（`i-ri:*`）为纯 CSS 实现（dots-icon、grid-icon、hamburger-icon、collapse-arrow），减少外部依赖
+
+### 📦 依赖
+
+- 移除对 UnoCSS 图标的依赖，提升包的独立性
+
+---
+
+## 2.1.0
+
+### Minor Changes
+
+- 重构目录结构 + 代码优化
+
+  - **目录重构**: 6 种布局骨架迁入 `components/layouts/` 子目录，层次更清晰
+  - **文件分离**: 每个布局的样式从 `<style>` 标签提取到独立的 `index.scss` 文件
+  - **注释统一**: 所有组件注释标准化为 `@robot-admin/layout - ComponentName` 格式
+  - **文档优化**: 重写 README，精简核心内容、添加目录树、API 参考更清晰
+
+All notable changes to this project will be documented in this file.
+
+## [2.0.2] - 2026-02-11
+
+### 🗑️ Removed
+
+- **Dead files**: Removed unused `tsup.config.ts` (actual build uses Vite)
+- **Empty directories**: Removed `composables/`, `core/`, `layouts/` (8 empty directories total)
+- **Unused dependencies**: Removed `vue-router` from peerDependencies and devDependencies (never used in source code)
+
+### 🔧 Fixed
+
+- **package.json**:
+  - Refined `sideEffects` to `["*.css", "*.scss"]` for better tree-shaking
+  - Removed blocking patterns `"*.vue"` and `"src/index.ts"`
+- **Source code**:
+
+  - `constants/index.ts`: Removed commented-out code, fixed version from `"1.0.0"` to `"2.0.2"`
+  - `types/index.ts`: Removed unimplemented `storageKey` option from `SettingsStoreOptions`
+  - `stores/settings.ts`:
+    - Exported `adjustColor` utility function (was private)
+    - Removed redundant `|| false` in collapsed state initialization
+  - `data.ts`:
+    - Fixed `COLOR_SWATCHES` duplication (now imports from constants)
+    - Renamed `LAYOUT_MODES` to `LAYOUT_MODE_OPTIONS` to avoid naming conflict
+
+- **SettingsDrawer component**:
+
+  - Removed unimplemented `storageKey` prop
+  - Fixed hardcoded timezone `"XIAn"` → `Intl.DateTimeFormat().resolvedOptions().timeZone`
+  - Fixed `handleResetLayout` missing `fixedHeader` and `tagsViewStyle` resets
+  - Fixed `handleImportConfig` to use `$patch` instead of `Object.assign` for proper reactivity
+
+- **Styles (`settings.scss`)**:
+
+  - Replaced hardcoded `#409EFF` with `var(--primary-color, #409eff)` for theme color support
+  - Replaced hardcoded `rgba(32, 128, 240)` shadows with CSS variable fallbacks
+
+- **Build config**:
+  - Removed unused `globals` from `vite.config.ts` (no UMD output)
+
+### 📖 Documentation
+
+- **README.md**: Fixed multiple inconsistencies with actual code:
+  - `themeMode` default: `'system'` → `'light'`
+  - `transitionType` default: `'fade'` → `'slide'`
+  - `tagsViewHeight` default: `40` → `44`
+  - `showFooter` default: `false` → `true`
+  - Removed non-existent store properties: `enableWatermark`, `watermarkText`, `enableGrayMode`, `enableColorWeakMode`
+  - Removed non-existent methods: `exportSettings()`, `importSettings()`
+  - Removed unimplemented feature: "持久化存储"
+  - Removed all `storageKey` parameter references
+  - Added `adjustColor` utility function documentation
+  - Fixed `ThemeMode` type: `'system'` → `'auto'`
+
+### ✨ Enhanced
+
+- Exported `adjustColor` utility function for external use
+- Improved CSS variable support for theme customization
+
+---
+
+## [2.0.1] - 2026-02-09
+
+### ✨ Added
+
+- Initial v2.0 release with decoupled architecture
+- Complete settings management system
+- SettingsDrawer UI component
+- 6 layout mode presets
+- Theme customization with CSS variables
+- Full TypeScript support
+
+---
+
+## [2.0.0] - 2026-02-09
+
+### 🎉 Initial Release
+
+- Layout and settings management system
+- Integration with @robot-admin/theme
+- Naive UI components support

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CHENY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,11 @@
 
 > 布局和设置管理系统 - 为 Robot Admin 提供完整的布局配置管理能力（含 UI 组件）
 
+[![npm version](https://img.shields.io/npm/v/@robot-admin/layout.svg)](https://www.npmjs.com/package/@robot-admin/layout)
+[![license](https://img.shields.io/npm/l/@robot-admin/layout.svg)](https://github.com/ChenyCHENYU/robot-admin-packages/blob/main/LICENSE)
+
+当前版本：`3.0.0`。
+
 ---
 
 ## ✨ 特性
@@ -13,6 +18,8 @@
 - 🧭 **菜单展开方式** - 内置传统展开 / 右侧面板两种菜单展开模式配置
 - 🔌 **插槽系统** - 灵活的 slot 机制，主项目仅关注业务组件
 - 🎨 **CSS 变量同步** - 配置变更自动同步到 CSS 变量，样式实时响应
+- ♿ **键盘与焦点可访问性** - 抽屉/菜单支持 Escape、方向键、焦点恢复与语义属性
+- 🛡️ **安全设置导入** - 对枚举、布尔值、数值范围与主题色进行运行时校验
 - 🚀 **TypeScript** - 完整类型支持
 
 ---
@@ -103,10 +110,13 @@ src/
 ## 📦 安装
 
 ```bash
-bun add @robot-admin/layout @robot-admin/theme naive-ui
+bun add @robot-admin/layout naive-ui
 ```
 
-**Peer Dependencies**: `vue ^3.4` · `vue-router ^4.0` · `pinia ^2.0 || ^3.0` · `naive-ui ^2.38` · `@robot-admin/theme ^0.1`
+**Peer Dependencies**: `vue ^3.4` · `vue-router ^4.0` · `pinia ^2.0 || ^3.0` · `naive-ui ^2.38`
+
+> 3.0 仍完整保留现有 Naive UI 组件、交互和样式。状态校验等无 UI 能力可从
+> `@robot-admin/layout/core` 独立导入，为后续适配其他 UI 框架预留稳定边界；当前版本不包含 Element Plus 视图适配器。
 
 ---
 
@@ -119,18 +129,15 @@ bun add @robot-admin/layout @robot-admin/theme naive-ui
 import { createApp } from "vue";
 import { createPinia } from "pinia";
 import { setupLayout } from "@robot-admin/layout";
-import { useThemeStore } from "@robot-admin/theme";
-import "@robot-admin/layout/style";  // 导入样式
+import "@robot-admin/layout/style"; // 导入样式
 import App from "./App.vue";
 
 const app = createApp(App);
 app.use(createPinia());
 
-const themeStore = useThemeStore();
-themeStore.init();
-
 setupLayout(app, {
-  onThemeModeChange: (mode) => themeStore.setMode(mode),
+  // 可选：同步到宿主自己的主题系统
+  onThemeModeChange: (mode) => syncAppTheme(mode),
   defaults: {
     layoutMode: "side",
     primaryColor: "#409eff",
@@ -147,7 +154,9 @@ app.mount("#app");
 <template>
   <C_LayoutContainer>
     <template #logo><AppLogo /></template>
-    <template #menu="{ collapsed }"><AppMenu :collapsed="collapsed" /></template>
+    <template #menu="{ collapsed }"
+      ><AppMenu :collapsed="collapsed"
+    /></template>
     <template #header><AppHeader /></template>
     <template #tags-view><AppTags /></template>
     <template #footer><AppFooter /></template>
@@ -167,39 +176,51 @@ import { ref } from "vue";
 import { SettingsDrawer } from "@robot-admin/layout";
 
 const visible = ref(false);
+const settingsActions = {
+  clearCache: () => localStorage.removeItem("my-app-disposable-cache"),
+};
 </script>
 
 <template>
   <button @click="visible = true">⚙️ 设置</button>
-  <SettingsDrawer v-model:show="visible" />
+  <SettingsDrawer v-model:show="visible" :actions="settingsActions">
+    <template #appearance-prepend>
+      <AppThemeExtension />
+    </template>
+  </SettingsDrawer>
 </template>
 ```
 
+`SettingsDrawer` 不再自行清空 `localStorage` / `sessionStorage`。缓存清理由宿主通过
+`actions.clearCache` 明确实现，避免误删登录态、语言和业务数据。可用扩展插槽：
+`appearance-prepend/append`、`layout-prepend/after-mode/append`、
+`features-prepend/append`；插槽均暴露当前 `settings`。
+
 ---
 
 ## 📐 布局模式
 
-| 模式 | 常量值 | 一级菜单 | 二级菜单 | 适用场景 |
-|------|--------|----------|----------|----------|
-| **左侧菜单** | `side` | 左侧栏 | 左侧栏（折叠） | 经典后台管理（ERP、CRM） |
-| **顶部菜单** | `top` | 顶部横向 | 顶部下拉 | 菜单少，需更宽内容区 |
-| **混合布局** | `mix` | 左侧图标栏 | 悬浮弹出 | 一级菜单少，二级多 |
-| **顶部混合** | `mix-top` | 左侧图标栏 | 顶部横向 | 全局导航 + 侧边详情 |
-| **反转混合** | `reverse-horizontal-mix` | 顶部横向 | 右侧栏 | 特殊需求，右手操作 |
-| **卡片布局** | `card-layout` | hover 抽屉 | 网格铺开 | 应用首页 / 工作台 |
+| 模式         | 常量值                   | 一级菜单   | 二级菜单       | 适用场景                 |
+| ------------ | ------------------------ | ---------- | -------------- | ------------------------ |
+| **左侧菜单** | `side`                   | 左侧栏     | 左侧栏（折叠） | 经典后台管理（ERP、CRM） |
+| **顶部菜单** | `top`                    | 顶部横向   | 顶部下拉       | 菜单少，需更宽内容区     |
+| **混合布局** | `mix`                    | 左侧图标栏 | 悬浮弹出       | 一级菜单少，二级多       |
+| **顶部混合** | `mix-top`                | 左侧图标栏 | 顶部横向       | 全局导航 + 侧边详情      |
+| **反转混合** | `reverse-horizontal-mix` | 顶部横向   | 右侧栏         | 特殊需求，右手操作       |
+| **卡片布局** | `card-layout`            | hover 抽屉 | 网格铺开       | 应用首页 / 工作台        |
 
 ---
 
 ## 🎨 主题预设
 
-| 预设 | 主题色 | 图标 |
-|------|--------|------|
-| 科技蓝 | `#409eff` | 💙 |
-| 清新绿 | `#52c41a` | 💚 |
-| 商务灰 | `#595959` | 🖤 |
-| 活力橙 | `#fa8c16` | 🧡 |
-| 优雅紫 | `#722ed1` | 💜 |
-| 经典红 | `#f5222d` | ❤️ |
+| 预设   | 主题色    | 图标 |
+| ------ | --------- | ---- |
+| 科技蓝 | `#409eff` | 💙   |
+| 清新绿 | `#52c41a` | 💚   |
+| 商务灰 | `#595959` | 🖤   |
+| 活力橙 | `#fa8c16` | 🧡   |
+| 优雅紫 | `#722ed1` | 💜   |
+| 经典红 | `#f5222d` | ❤️   |
 
 ---
 
@@ -213,10 +234,10 @@ import { useSettingsStore } from "@robot-admin/layout";
 const settings = useSettingsStore();
 
 // 读取
-settings.layoutMode;       // 'side' | 'top' | 'mix' | ...
-settings.menuExpandMode;   // 'inline' | 'panel'
-settings.primaryColor;     // '#409eff'
-settings.themeMode;        // 'light' | 'dark' | 'auto'
+settings.layoutMode; // 'side' | 'top' | 'mix' | ...
+settings.menuExpandMode; // 'inline' | 'panel'
+settings.primaryColor; // '#409eff'
+settings.themeMode; // 'light' | 'dark' | 'system'
 
 // 修改
 settings.layoutMode = "mix";
@@ -228,21 +249,21 @@ settings.resetSettings();
 
 ### 设置属性一览
 
-| 属性 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `themeMode` | `ThemeMode` | `'light'` | 主题模式 |
-| `primaryColor` | `string` | `'#409eff'` | 主题色 |
-| `layoutMode` | `LayoutMode` | `'side'` | 布局模式 |
-| `menuExpandMode` | `MenuExpandMode` | `'inline'` | 菜单展开方式 |
-| `borderRadius` | `BorderRadiusSize` | `'medium'` | 圆角大小 |
-| `transitionType` | `TransitionType` | `'slide'` | 页面动画 |
-| `fixedHeader` | `boolean` | `true` | 固定头部 |
-| `showBreadcrumb` | `boolean` | `true` | 显示面包屑 |
-| `showTagsView` | `boolean` | `true` | 显示标签页 |
-| `showFooter` | `boolean` | `true` | 显示页脚 |
-| `sidebarWidth` | `number` | `220` | 侧边栏宽度 (px) |
-| `sidebarCollapsedWidth` | `number` | `64` | 折叠宽度 (px) |
-| `headerHeight` | `number` | `56` | 头部高度 (px) |
+| 属性                    | 类型               | 默认值      | 说明            |
+| ----------------------- | ------------------ | ----------- | --------------- |
+| `themeMode`             | `ThemeMode`        | `'light'`   | 主题模式        |
+| `primaryColor`          | `string`           | `'#409eff'` | 主题色          |
+| `layoutMode`            | `LayoutMode`       | `'side'`    | 布局模式        |
+| `menuExpandMode`        | `MenuExpandMode`   | `'inline'`  | 菜单展开方式    |
+| `borderRadius`          | `BorderRadiusSize` | `'medium'`  | 圆角大小        |
+| `transitionType`        | `TransitionType`   | `'slide'`   | 页面动画        |
+| `fixedHeader`           | `boolean`          | `true`      | 固定头部        |
+| `showBreadcrumb`        | `boolean`          | `true`      | 显示面包屑      |
+| `showTagsView`          | `boolean`          | `true`      | 显示标签页      |
+| `showFooter`            | `boolean`          | `true`      | 显示页脚        |
+| `sidebarWidth`          | `number`           | `220`       | 侧边栏宽度 (px) |
+| `sidebarCollapsedWidth` | `number`           | `64`        | 折叠宽度 (px)   |
+| `headerHeight`          | `number`           | `56`        | 头部高度 (px)   |
 
 ### CSS 变量
 
@@ -263,33 +284,39 @@ settings.resetSettings();
 
 ## 🧩 C_LayoutContainer Slots
 
-| Slot 名称 | 说明 | 适用布局 |
-|-----------|------|----------|
-| `#logo` | 品牌 Logo | 全部 |
-| `#menu` | 垂直菜单 | Side |
-| `#header` | 完整头部 | Side / Mix |
+| Slot 名称       | 说明           | 适用布局                      |
+| --------------- | -------------- | ----------------------------- |
+| `#logo`         | 品牌 Logo      | 全部                          |
+| `#menu`         | 垂直菜单       | Side                          |
+| `#header`       | 完整头部       | Side / Mix                    |
 | `#header-extra` | 头部右侧操作区 | Top / MixTop / Reverse / Card |
-| `#top-menu` | 水平菜单 | Top / MixTop / Reverse |
-| `#tags-view` | 标签页 | 全部 |
-| `#footer` | 页脚 | 全部 |
-| `#brand` | 顶部品牌区 | MixTop |
-| `#menu-trigger` | 菜单触发区 | Card |
-| `#drawer-menu` | 抽屉菜单 | Card |
+| `#top-menu`     | 水平菜单       | Top / MixTop / Reverse        |
+| `#tags-view`    | 标签页         | 全部                          |
+| `#footer`       | 页脚           | 全部                          |
+| `#brand`        | 顶部品牌区     | MixTop                        |
+| `#menu-trigger` | 菜单触发区     | Card                          |
+| `#drawer-menu`  | 抽屉菜单       | Card                          |
 
 ---
 
 ## 📖 类型定义
 
 ```typescript
-type LayoutMode = "side" | "top" | "mix" | "mix-top" | "reverse-horizontal-mix" | "card-layout";
+type LayoutMode =
+  "side" | "top" | "mix" | "mix-top" | "reverse-horizontal-mix" | "card-layout";
 type MenuExpandMode = "inline" | "panel";
 type TransitionType = "fade" | "slide" | "zoom" | "none";
 type BorderRadiusSize = "small" | "medium" | "large";
 type TagsViewStyle = "default" | "card" | "smart";
-type ThemeMode = "light" | "dark" | "auto";
+type ThemeMode = "light" | "dark" | "system";
 
-interface ThemePreset { name: string; icon: string; primaryColor: string; }
+interface ThemePreset {
+  name: string;
+  icon: string;
+  primaryColor: string;
+}
 interface SettingsStoreOptions {
+  id?: string;
   defaults?: Partial<SettingsState>;
   onThemeModeChange?: (mode: ThemeMode) => void | Promise<void>;
 }
@@ -305,6 +332,8 @@ interface SettingsStoreOptions {
 import { createSettingsStore } from "@robot-admin/layout";
 
 export const useSettingsStore = createSettingsStore({
+  // 多实例或微前端中必须保证唯一；单实例可省略
+  id: "workspace-settings",
   defaults: { layoutMode: "mix", primaryColor: "#722ed1" },
   onThemeModeChange: async (mode) => {
     const themeStore = useThemeStore();
@@ -313,6 +342,42 @@ export const useSettingsStore = createSettingsStore({
 });
 ```
 
+### 校验外部设置
+
+从文件、URL 或远端接口加载的设置属于不可信输入，写入 Store 前应先校验：
+
+```typescript
+import { sanitizeLayoutSettingsConfig } from "@robot-admin/layout/core";
+import { useSettingsStore } from "@robot-admin/layout";
+
+const imported = JSON.parse(await file.text());
+// 一次校验完整文件，失败时不会产生部分状态写入。
+const config = sanitizeLayoutSettingsConfig(imported);
+const safePatch = config.settings ?? {};
+const settings = useSettingsStore();
+
+if (safePatch.themeMode !== undefined) {
+  await settings.updateThemeMode(safePatch.themeMode);
+  delete safePatch.themeMode;
+}
+settings.$patch(safePatch);
+```
+
+未知字段会被忽略以便向前兼容；已知字段类型错误、越界值、非法主题色或旧的
+`themeMode: "auto"` 会抛出明确错误。设置抽屉内置的导入功能已执行同一校验。
+
+`useLayoutCache()` 默认不会输出开发日志，也不会向 `window` 暴露调试函数；仅在
+受控的本地开发场景显式设置 `enableDevLog` / `exposeToWindow`。
+
+### 3.0 升级说明
+
+- 现有根入口、6 种布局、组件名、slot 名和 CSS 入口保持兼容。
+- `LayoutContext.collapsed` 为可选的双向状态；提供后，侧栏与宿主头部共享同一折叠状态。
+- 自定义 Store 可通过 `setupLayout()` 注入，也可用 `SettingsDrawer :store="store"` 显式传入。
+- `enableTransition: false` 现在会真正关闭路由过渡，但保留已选择的动画类型。
+- 缓存清理改为宿主白名单动作；从 2.x 升级时请传入 `actions.clearCache`。
+- `@robot-admin/theme` 不再是 peer dependency；需要主题联动时使用 `onThemeModeChange`。
+
 ### 单独使用布局骨架
 
 ```typescript