route-ui-sync 0.1.0

package/README.md

@@ -0,0 +1,359 @@
+# route-ui-sync
+
+一个与 UI 框架无关的工具库，用于根据当前路由信息计算选中 key。
+
+## 应用场景
+
+适用于菜单选中、面包屑导航、标签页激活、侧边栏高亮等需要根据路由状态决定 UI 状态的场景，处理路由和 UI 状态不匹配的问题。
+
+## 特性
+
+- 🎯 **框架无关**：不依赖 React、Vue 或任何路由库
+- 🚀 **轻量级**：零依赖，体积小
+- 🔧 **类型安全**：完整的 TypeScript 类型定义
+- ✅ **测试覆盖**：完整的单元测试
+- 📦 **多格式支持**：同时支持 ES 模块和 CommonJS
+
+## 安装
+
+```bash
+npm install route-ui-sync
+```
+
+## 快速开始
+
+### 3 步完成菜单自动选中
+
+```typescript
+// 1. 导入函数和类型
+import { getSelectedKeyFromLocation, RouteSelectionRule } from 'route-ui-sync';
+import { useLocation } from 'react-router-dom';
+
+// 2. 定义规则：哪些路由对应哪些菜单 key
+const rules: RouteSelectionRule[] = [
+  { key: 'page1', match: (loc) => loc.pathname === '/page1' },
+  { key: 'page2', match: (loc) => loc.pathname === '/page2' },
+];
+
+// 3. 获取当前路由，自动计算选中的 key
+const location = useLocation();
+const selectedKey = getSelectedKeyFromLocation(location, rules);
+
+// 使用 selectedKey 来高亮菜单
+<Menu selectedKeys={selectedKey ? [selectedKey] : []} />
+```
+
+## 使用方法
+
+### 基本用法
+
+```typescript
+import { getSelectedKeyFromLocation, RouteSelectionRule } from 'route-ui-sync';
+
+// 定义路由匹配规则
+const rules: RouteSelectionRule[] = [
+  {
+    key: 'page1',
+    match: (location) => location.pathname === '/page1',
+  },
+  {
+    key: 'page2',
+    match: (location) => location.pathname === '/page2',
+  },
+  {
+    key: 'items',
+    match: (location) => location.pathname.startsWith('/items'),
+  },
+];
+
+// 根据当前 location 计算选中的 key
+const location = { pathname: '/page1' };
+const selectedKey = getSelectedKeyFromLocation(location, rules);
+console.log(selectedKey); // 'page1'
+```
+
+### 使用优先级
+
+当多个规则同时匹配时，可以使用 `priority` 属性来控制优先级：
+
+```typescript
+const rules: RouteSelectionRule[] = [
+  {
+    key: 'item-detail',
+    match: (location) => /^\/items\/\d+$/.test(location.pathname),
+    priority: 10, // 高优先级
+  },
+  {
+    key: 'items',
+    match: (location) => location.pathname.startsWith('/items'),
+    priority: 5, // 低优先级
+  },
+];
+
+const location = { pathname: '/items/123' };
+const selectedKey = getSelectedKeyFromLocation(location, rules);
+console.log(selectedKey); // 'item-detail' (因为优先级更高)
+```
+
+### 处理查询参数和哈希
+
+```typescript
+const rules: RouteSelectionRule[] = [
+  {
+    key: 'search',
+    match: (location) => {
+      return location.pathname === '/search' && location.search?.includes('q=');
+    },
+  },
+  {
+    key: 'section',
+    match: (location) => location.hash === '#section1',
+  },
+];
+
+const location = {
+  pathname: '/search',
+  search: '?q=test',
+  hash: '#section1',
+};
+const selectedKey = getSelectedKeyFromLocation(location, rules);
+```
+
+### 与 React Router 集成
+
+#### 基础示例
+
+```typescript
+import { useLocation } from 'react-router-dom';
+import { getSelectedKeyFromLocation, RouteSelectionRule } from 'route-ui-sync';
+import { Menu } from '@arco-design/web-react';
+
+function NavigationMenu() {
+  const location = useLocation();
+  
+  // 定义菜单选中规则
+  const rules: RouteSelectionRule[] = [
+    {
+      key: 'page1',
+      match: (loc) => loc.pathname === '/page1',
+    },
+    {
+      key: 'page2',
+      match: (loc) => loc.pathname === '/page2',
+    },
+    {
+      key: 'items',
+      match: (loc) => loc.pathname.startsWith('/items'),
+    },
+  ];
+  
+  // 根据当前路由自动计算选中的菜单项
+  const selectedKey = getSelectedKeyFromLocation(location, rules);
+  
+  return (
+    <Menu selectedKeys={selectedKey ? [selectedKey] : []}>
+      <Menu.Item key="page1">页面一</Menu.Item>
+      <Menu.Item key="page2">页面二</Menu.Item>
+      <Menu.Item key="items">项目列表</Menu.Item>
+    </Menu>
+  );
+}
+```
+
+#### 实际项目示例：动态菜单规则
+
+在实际项目中，你可能需要根据动态数据（如从 API 获取的产品分类）来生成规则：
+
+```typescript
+import { useLocation } from 'react-router-dom';
+import { useMemo } from 'react';
+import { getSelectedKeyFromLocation, RouteSelectionRule } from 'route-ui-sync';
+import { Menu } from '@arco-design/web-react';
+
+interface Category {
+  categoryId: string;
+  name: string;
+}
+
+function NavigationMenu() {
+  const location = useLocation();
+  const [categories, setCategories] = useState<Category[]>([]);
+  
+  // 从 API 获取分类
+  useEffect(() => {
+    fetchCategories().then(setCategories);
+  }, []);
+  
+  // 动态生成菜单选中规则
+  const menuSelectionRules: RouteSelectionRule[] = useMemo(() => {
+    const rules: RouteSelectionRule[] = [
+      {
+        key: 'page1',
+        match: (loc) => loc.pathname === '/page1',
+      },
+      {
+        key: 'page2',
+        match: (loc) => loc.pathname === '/page2',
+      },
+    ];
+    
+    // 根据分类动态添加规则
+    // 例如：/item?type=category1 对应 item-1
+    categories.forEach((cat, index) => {
+      const key = `item-${index + 1}`;
+      rules.push({
+        key,
+        match: (loc) => {
+          if (loc.pathname !== '/item') return false;
+          const params = new URLSearchParams(loc.search ?? '');
+          return params.get('type') === cat.categoryId;
+        },
+      });
+    });
+    
+    return rules;
+  }, [categories]);
+  
+  // 自动计算当前选中的菜单项
+  const selectedMenuKey = useMemo(
+    () => getSelectedKeyFromLocation(location, menuSelectionRules),
+    [location, menuSelectionRules]
+  );
+  
+  return (
+    <Menu selectedKeys={selectedMenuKey ? [selectedMenuKey] : []}>
+      <Menu.Item key="page1">页面一</Menu.Item>
+      <Menu.Item key="page2">页面二</Menu.Item>
+      {categories.map((cat, index) => (
+        <Menu.Item key={`item-${index + 1}`}>
+          {cat.name}
+        </Menu.Item>
+      ))}
+    </Menu>
+  );
+}
+```
+
+#### 使用优先级处理复杂场景
+
+当路由有嵌套关系时，使用优先级确保精确匹配：
+
+```typescript
+const rules: RouteSelectionRule[] = [
+  // 精确匹配：项目详情页
+  {
+    key: 'item-detail',
+    match: (loc) => /^\/items\/\d+$/.test(loc.pathname),
+    priority: 10, // 高优先级
+  },
+  // 模糊匹配：项目列表页
+  {
+    key: 'items',
+    match: (loc) => loc.pathname.startsWith('/items'),
+    priority: 5, // 低优先级
+  },
+];
+
+// 访问 /items/123 时，会选中 'item-detail'（优先级更高）
+// 访问 /items 时，会选中 'items'
+```
+
+## API
+
+### `getSelectedKeyFromLocation`
+
+根据当前路由信息和一组规则，计算"当前应该选中的 key"。
+
+#### 参数
+
+- `location`: 包含 `pathname`、`search`（可选）、`hash`（可选）的对象
+- `rules`: 路由选择规则数组
+
+#### 返回值
+
+- `string | undefined`: 匹配的 key，如果没有匹配则返回 `undefined`
+
+### `RouteSelectionRule`
+
+路由选择规则接口。
+
+```typescript
+interface RouteSelectionRule {
+  /**
+   * 唯一 key，用于传给 UI 组件
+   */
+  key: string;
+  
+  /**
+   * 匹配函数：根据当前 location 判断这个规则是否命中
+   */
+  match: RouteMatchPredicate;
+  
+  /**
+   * 优先级：数字越大优先级越高（可选）
+   * 当多个规则同时命中时，用它来决定最终选中哪个
+   */
+  priority?: number;
+}
+```
+
+### `RouteMatchPredicate`
+
+匹配函数类型。
+
+```typescript
+type RouteMatchPredicate = (location: {
+  pathname: string;
+  search?: string;
+  hash?: string;
+}) => boolean;
+```
+
+## 开发
+
+### 构建
+
+```bash
+npm run build
+```
+
+### 测试
+
+```bash
+# 运行测试
+npm test
+
+# 监听模式
+npm run test:watch
+
+# 生成覆盖率报告
+npm run test:coverage
+```
+
+### 类型检查
+
+```bash
+npm run type-check
+```
+
+### 测试覆盖
+
+- **测试用例数**: 39 个
+- **代码覆盖率**: 100%
+- **测试场景**: 包括基础功能、复杂场景、边界情况、实际项目场景等
+
+查看 [TEST_COVERAGE.md](./TEST_COVERAGE.md) 了解详细的测试覆盖情况。
+
+## 更多示例
+
+查看 [USAGE_EXAMPLES.md](./USAGE_EXAMPLES.md) 获取更多详细的使用示例，包括：
+- 基础使用场景
+- React Router 集成
+- 动态规则生成
+- 优先级控制
+- 处理查询参数
+- 完整项目示例
+
+## 许可证
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+// 一个与 UI 框架无关的"小核心"，用于根据当前路由信息计算选中 key。
+/**
+ * 根据当前路由信息和一组规则，计算"当前应该选中的 key"
+ *
+ * - 不依赖 React / react-router / 任何 UI 库
+ * - 只关心最基础的 location 对象和规则数组
+ * - 未来做成 npm 包时，只需要把这个函数原样搬过去即可
+ */
+function getSelectedKeyFromLocation(location, rules) {
+    if (!location || !rules || rules.length === 0) {
+        return undefined;
+    }
+    const { pathname, search = "", hash = "" } = location;
+    const safeLocation = { pathname, search, hash };
+    // 找出所有命中的规则
+    const matched = rules.filter((rule) => {
+        try {
+            return rule.match(safeLocation);
+        }
+        catch {
+            // 某个规则内部异常时，忽略该规则，避免影响整体
+            return false;
+        }
+    });
+    if (matched.length === 0)
+        return undefined;
+    // 如果只有一个命中，直接返回
+    if (matched.length === 1)
+        return matched[0].key;
+    // 多个命中时，按 priority 从高到低排序，取第一个
+    matched.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return matched[0].key;
+}
+
+exports.getSelectedKeyFromLocation = getSelectedKeyFromLocation;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;AAwBA;;;;;;AAMG;AACG,SAAU,0BAA0B,CACxC,QAA8D,EAC9D,KAA2B,EAAA;AAE3B,IAAA,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;AAC7C,QAAA,OAAO,SAAS;IAClB;AAEA,IAAA,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,QAAQ;IACrD,MAAM,YAAY,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE;;IAG/C,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,KAAI;AACpC,QAAA,IAAI;AACF,YAAA,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;QACjC;AAAE,QAAA,MAAM;;AAEN,YAAA,OAAO,KAAK;QACd;AACF,IAAA,CAAC,CAAC;AAEF,IAAA,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;AAAE,QAAA,OAAO,SAAS;;AAG1C,IAAA,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;AAAE,QAAA,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG;;IAG/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;AAC7D,IAAA,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG;AACvB;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+type RouteMatchPredicate = (location: {
+    pathname: string;
+    search?: string;
+    hash?: string;
+}) => boolean;
+interface RouteSelectionRule {
+    /**
+     * 唯一 key，用于传给 UI 组件（例如 Menu.Item 的 key 或 className 中的一部分）
+     */
+    key: string;
+    /**
+     * 匹配函数：根据当前 location 判断这个规则是否命中
+     */
+    match: RouteMatchPredicate;
+    /**
+     * 优先级：数字越大优先级越高（可选）
+     * 当多个规则同时命中时，用它来决定最终选中哪个
+     */
+    priority?: number;
+}
+/**
+ * 根据当前路由信息和一组规则，计算"当前应该选中的 key"
+ *
+ * - 不依赖 React / react-router / 任何 UI 库
+ * - 只关心最基础的 location 对象和规则数组
+ * - 未来做成 npm 包时，只需要把这个函数原样搬过去即可
+ */
+declare function getSelectedKeyFromLocation(location: {
+    pathname: string;
+    search?: string;
+    hash?: string;
+}, rules: RouteSelectionRule[]): string | undefined;
+
+export { getSelectedKeyFromLocation };
+export type { RouteMatchPredicate, RouteSelectionRule };

package/dist/index.js

@@ -0,0 +1,36 @@
+// 一个与 UI 框架无关的"小核心"，用于根据当前路由信息计算选中 key。
+/**
+ * 根据当前路由信息和一组规则，计算"当前应该选中的 key"
+ *
+ * - 不依赖 React / react-router / 任何 UI 库
+ * - 只关心最基础的 location 对象和规则数组
+ * - 未来做成 npm 包时，只需要把这个函数原样搬过去即可
+ */
+function getSelectedKeyFromLocation(location, rules) {
+    if (!location || !rules || rules.length === 0) {
+        return undefined;
+    }
+    const { pathname, search = "", hash = "" } = location;
+    const safeLocation = { pathname, search, hash };
+    // 找出所有命中的规则
+    const matched = rules.filter((rule) => {
+        try {
+            return rule.match(safeLocation);
+        }
+        catch {
+            // 某个规则内部异常时，忽略该规则，避免影响整体
+            return false;
+        }
+    });
+    if (matched.length === 0)
+        return undefined;
+    // 如果只有一个命中，直接返回
+    if (matched.length === 1)
+        return matched[0].key;
+    // 多个命中时，按 priority 从高到低排序，取第一个
+    matched.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return matched[0].key;
+}
+
+export { getSelectedKeyFromLocation };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;AAwBA;;;;;;AAMG;AACG,SAAU,0BAA0B,CACxC,QAA8D,EAC9D,KAA2B,EAAA;AAE3B,IAAA,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE;AAC7C,QAAA,OAAO,SAAS;IAClB;AAEA,IAAA,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,EAAE,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,QAAQ;IACrD,MAAM,YAAY,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE;;IAG/C,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,KAAI;AACpC,QAAA,IAAI;AACF,YAAA,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC;QACjC;AAAE,QAAA,MAAM;;AAEN,YAAA,OAAO,KAAK;QACd;AACF,IAAA,CAAC,CAAC;AAEF,IAAA,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;AAAE,QAAA,OAAO,SAAS;;AAG1C,IAAA,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;AAAE,QAAA,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG;;IAG/C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,CAAC;AAC7D,IAAA,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG;AACvB;;;;"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "route-ui-sync",
+  "version": "0.1.0",
+  "description": "A lightweight, framework-agnostic utility for automatically matching routes to menu keys. Zero dependencies, TypeScript support, for navigation menus.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "route",
+    "routing",
+    "navigation",
+    "location",
+    "selection",
+    "framework-agnostic"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^12.1.1",
+    "@types/node": "^22.7.4",
+    "@vitest/coverage-v8": "^4.0.15",
+    "rollup": "^4.22.0",
+    "rollup-plugin-dts": "^6.1.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.5.3",
+    "vitest": "^4.0.15"
+  }
+}