@navojs/react-router 1.0.1

package/README.md

@@ -0,0 +1,148 @@
+# @navojs/react-router
+
+React Router integration for [Navo](https://github.com/flycran/navo) — declarative navigation and permission-based routing.
+
+## Installation
+
+```bash
+npm install @navojs/react-router react-router
+```
+
+## Quick Start
+
+### 1. Define your navigation structure
+
+```tsx
+import { createNavo } from '@navojs/react-router'
+
+const navo = createNavo([
+  { id: 'dashboard', label: 'Dashboard', path: '/dashboard' },
+  {
+    id: 'users',
+    label: 'Users',
+    path: '/users',
+    children: [
+      { id: 'user-list', label: 'User List', path: 'list' },
+      { id: 'user-detail', label: 'User Detail', path: ':id', affiliated: true },
+    ],
+  },
+  { id: 'settings', label: 'Settings', path: '/settings' },
+])
+```
+
+### 2. Wrap your app with `NavoProvider`
+
+```tsx
+import { NavoProvider } from '@navojs/react-router'
+import { BrowserRouter } from 'react-router'
+
+function App() {
+  return (
+    <BrowserRouter>
+      <NavoProvider navo={navo}>
+        <AppRoutes />
+      </NavoProvider>
+    </BrowserRouter>
+  )
+}
+```
+
+### 3. Generate routes from your navo structure
+
+```tsx
+import { generateRoutes } from '@navojs/react-router'
+import { useRoutes } from 'react-router'
+
+function AppRoutes() {
+  const routes = generateRoutes(navo)
+  return useRoutes(routes)
+}
+```
+
+## Permission Control
+
+```tsx
+import { useCanAccess } from '@navojs/react-router'
+
+function PermissionGate() {
+  const onCanAccess = useCanAccess()
+
+  useEffect(() => {
+    // Provide your access control logic
+    onCanAccess((node) => {
+      return userPermissions.includes(node.id)
+    })
+  }, [])
+
+  return null
+}
+```
+
+## Hooks
+
+### `useCanAccess()`
+
+Returns the `onCanAccess` callback for setting up permission checks.
+
+### `useMatchedNodes()`
+
+Returns the currently active navigation nodes and their IDs — useful for highlighting menus and breadcrumbs.
+
+```tsx
+const { matchedNodes, matchedIds } = useMatchedNodes()
+// matchedIds: ['dashboard', 'users', 'user-list']
+// matchedNodes: corresponding NavoNode objects
+```
+
+### `useNavo()`
+
+Returns utility functions for working with the navigation tree:
+
+```tsx
+const { nodes, getNodeById, getPathById, hasCanAccess } = useNavo()
+
+// Get all authorized nodes
+nodes.forEach(node => console.log(node.label))
+
+// Check access
+if (hasCanAccess('settings')) { /* ... */ }
+
+// Get path by id
+const path = getPathById('user-list') // '/users/list'
+```
+
+## Route Escape Hatch
+
+You can pass native React Router route properties through the `route` field:
+
+```tsx
+createNavo([
+  {
+    id: 'home',
+    path: '/',
+    route: {
+      loader: () => fetchData(),
+      caseSensitive: true,
+      errorElement: <ErrorPage />,
+    },
+  },
+])
+```
+
+## API
+
+### `generateRoutes(navo)`
+
+Converts a Navo instance into an array of React Router `RouteObject`s with automatic index redirects.
+
+### `NavoProvider`
+
+React context provider that holds the Navo instance and authentication state.
+
+### `NavoRedirect`
+
+Internal component that handles automatic redirection to the resolved path (e.g., redirecting `/users` to `/users/list`).
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,134 @@
+// src/index.ts
+export * from "@navojs/core";
+
+// src/hooks.ts
+import { Navo } from "@navojs/core";
+import { useContext as useContext2, useMemo as useMemo2 } from "react";
+import { useMatches } from "react-router";
+
+// src/main.tsx
+import { createContext, useContext, useMemo, useState } from "react";
+import {
+  Navigate,
+  useLocation
+} from "react-router";
+import { jsxDEV } from "react/jsx-dev-runtime";
+function NavoRedirect({ navNode }) {
+  const navo = useContext(NavoContext);
+  const location = useLocation();
+  const resolveNode = navNode ? navo?.authedIdMap.get(navNode.id) : null;
+  if (resolveNode)
+    return /* @__PURE__ */ jsxDEV(Navigate, {
+      to: resolveNode.path,
+      replace: true
+    }, undefined, false, undefined, this);
+  if (navo && location.pathname === navo.originNavo.basePath)
+    return /* @__PURE__ */ jsxDEV(Navigate, {
+      to: navo.authedRootResolvePath,
+      replace: true
+    }, undefined, false, undefined, this);
+}
+var NavoContext = createContext(null);
+function NavoProvider({ children, navo }) {
+  const [state, setState] = useState({
+    nodes: navo.nodes,
+    idMap: navo.idMap,
+    authedNodes: navo.authedNodes,
+    authedIdMap: navo.authedIdMap,
+    authedRootResolvePath: navo.authedRootResolvePath
+  });
+  const value = useMemo(() => ({
+    ...state,
+    originNavo: navo,
+    onCanAccess: (canAccess) => {
+      navo.authenticat(canAccess);
+      setState({
+        nodes: navo.nodes,
+        idMap: navo.idMap,
+        authedNodes: navo.authedNodes,
+        authedIdMap: navo.authedIdMap,
+        authedRootResolvePath: navo.authedRootResolvePath
+      });
+    }
+  }), [navo, state]);
+  return /* @__PURE__ */ jsxDEV(NavoContext.Provider, {
+    value,
+    children
+  }, undefined, false, undefined, this);
+}
+function generateRoutes(navo) {
+  const navNodes = navo.nodes;
+  const r = (navNodes2) => {
+    const routes = [];
+    for (let i = 0;i < navNodes2.length; i++) {
+      const navNode = navNodes2[i];
+      const route = {
+        ...navNode.route,
+        id: navNode.id,
+        path: navNode.originPath
+      };
+      if (navNode.children?.length) {
+        route.children = r(navNode.children);
+      }
+      routes.push(route);
+    }
+    if (navNodes2.length) {
+      routes.push({
+        index: true,
+        element: /* @__PURE__ */ jsxDEV(NavoRedirect, {
+          navNode: navNodes2[0].parent
+        }, undefined, false, undefined, this)
+      });
+    }
+    return routes;
+  };
+  return r(navNodes);
+}
+
+// src/hooks.ts
+var useCanAccess = () => {
+  const navo = useContext2(NavoContext);
+  if (!navo)
+    throw new Error("useCanAccess must be used within a NavoProvider.");
+  return navo.onCanAccess;
+};
+var useMatchedNodes = () => {
+  const navo = useContext2(NavoContext);
+  if (!navo)
+    throw new Error("useCurrentNode must be used within a NavoProvider.");
+  const matches = useMatches();
+  return useMemo2(() => {
+    const matchedNodes = [];
+    const matchedIds = [];
+    for (let i = matches.length - 1;i >= 0; i--) {
+      const element = matches[i];
+      const node = navo.authedIdMap.get(element.id);
+      if (node && !Navo.isAffiliated(node)) {
+        matchedNodes.push(node);
+        matchedIds.push(node.id);
+      }
+    }
+    return {
+      matchedNodes: matchedNodes.reverse(),
+      matchedIds: matchedIds.reverse()
+    };
+  }, [matches, navo.authedIdMap]);
+};
+var useNavo = () => {
+  const navo = useContext2(NavoContext);
+  if (!navo)
+    throw new Error("useNavoIdMap must be used within a NavoProvider.");
+  return {
+    nodes: navo.authedNodes,
+    getNodeById: (id) => navo.authedIdMap.get(id),
+    getPathById: (id) => navo.authedIdMap.get(id)?.path,
+    hasCanAccess: (id) => navo.authedIdMap.has(id)
+  };
+};
+export {
+  useNavo,
+  useMatchedNodes,
+  useCanAccess,
+  generateRoutes,
+  NavoProvider
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@navojs/react-router",
+  "version": "1.0.1",
+  "description": "React Router integration for Navo — declarative navigation and permission-based routing",
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch ./build.ts",
+    "build": "bun ./build.ts",
+    "check": "tsgo --noEmit --project tsconfig.json",
+    "test": "tsgo --noEmit --project tsconfig.test.json && bun test"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "src/index.ts",
+  "exports": {
+    "import": "./dist/index.js",
+    "require": "./dist/index.js",
+    "types": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "keywords": [
+    "navo",
+    "react-router",
+    "navigation",
+    "routing",
+    "permissions",
+    "acl"
+  ],
+  "author": "flycran",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flycran/navo",
+    "directory": "packages/react-router"
+  },
+  "dependencies": {
+    "@navojs/core": "workspace:*",
+    "@types/react": "19.2.14"
+  },
+  "devDependencies": {
+    "@navojs/config": "workspace:*"
+  },
+  "peerDependencies": {
+    "react-router": "^7.18.0",
+    "react": ">=18"
+  }
+}

package/src/hooks.ts

@@ -0,0 +1,80 @@
+import { Navo, type NavoNode } from '@navojs/core'
+import { useContext, useMemo } from 'react'
+import { useMatches } from 'react-router'
+import { NavoContext } from './main'
+
+/**
+ * 鉴权回调
+ * @example
+ * ```ts
+ * const onCanAccess = useCanAccess()
+ * useEffect(() => {
+ *   onCanAccess((node) => {
+ *     return accessList.includes(node.id)
+ *   })
+ * }, [])
+ * ```
+ */
+export const useCanAccess = () => {
+  const navo = useContext(NavoContext)
+  if (!navo) throw new Error('useCanAccess must be used within a NavoProvider.')
+  return navo.onCanAccess
+}
+
+/**
+ * 返回当前活动的节点匹配项
+ * @example
+ * ```ts
+ * const { matchedIds } = useMatchedNodes()
+ * const openKeys = matchedIds.slice(0, -1)
+ * const selectedKey = matchedIds.at(-1)
+ * ```
+ */
+export const useMatchedNodes = () => {
+  const navo = useContext(NavoContext)
+  if (!navo) throw new Error('useCurrentNode must be used within a NavoProvider.')
+  const matches = useMatches()
+
+  return useMemo(() => {
+    const matchedNodes: NavoNode[] = []
+    const matchedIds: string[] = []
+    for (let i = matches.length - 1; i >= 0; i--) {
+      const element = matches[i]
+      const node = navo.authedIdMap.get(element.id)
+
+      if (node && !Navo.isAffiliated(node)) {
+        matchedNodes.push(node)
+        matchedIds.push(node.id)
+      }
+    }
+
+    return {
+      matchedNodes: matchedNodes.reverse(),
+      matchedIds: matchedIds.reverse(),
+    }
+  }, [matches, navo.authedIdMap])
+}
+
+export type UseNavoReturn = {
+  /** 已鉴权节点 */
+  nodes: NavoNode[]
+  /** 根据id获取节点 */
+  getNodeById: (id: string) => NavoNode | undefined
+  /** 根据id获取路径 */
+  getPathById: (id: string) => string | undefined
+  /** 判断是否有权限访问该节点 */
+  hasCanAccess: (id: string) => boolean
+}
+
+/** 获取Navo节点和实用工具 */
+export const useNavo = (): UseNavoReturn => {
+  const navo = useContext(NavoContext)
+  if (!navo) throw new Error('useNavoIdMap must be used within a NavoProvider.')
+
+  return {
+    nodes: navo.authedNodes,
+    getNodeById: (id: string) => navo.authedIdMap.get(id),
+    getPathById: (id: string) => navo.authedIdMap.get(id)?.path,
+    hasCanAccess: (id: string) => navo.authedIdMap.has(id),
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from '@navojs/core'
+export * from './hooks'
+export type * from './main'
+export { generateRoutes, NavoProvider } from './main'

package/src/main.tsx

@@ -0,0 +1,106 @@
+import type { CanAccess, Navo, NavoNode, NavoNodeInput } from '@navojs/core'
+import { createContext, useContext, useMemo, useState } from 'react'
+import {
+  type BaseRouteObject,
+  Navigate,
+  type NonIndexRouteObject,
+  type RouteObject,
+  useLocation,
+} from 'react-router'
+
+export type NavNodeEscapeHatch = Omit<BaseRouteObject, 'id' | 'path'>
+
+declare module '@navojs/core' {
+  interface NavoNodeInput {
+    route?: NavNodeEscapeHatch
+  }
+}
+
+/** 内置的自动重定向到真实页面 */
+function NavoRedirect({ navNode }: { navNode?: NavoNode | null }) {
+  const navo = useContext(NavoContext)
+  const location = useLocation()
+
+  const resolveNode = navNode ? navo?.authedIdMap.get(navNode.id) : null
+  if (resolveNode) return <Navigate to={resolveNode.path} replace />
+  if (navo && location.pathname === navo.originNavo.basePath)
+    return <Navigate to={navo.authedRootResolvePath} replace />
+}
+
+export interface NavoContextProps {
+  originNavo: Navo<NavoNodeInput[]>
+  nodes: NavoNode[]
+  idMap: Map<string, NavoNode>
+  authedNodes: NavoNode[]
+  authedIdMap: Map<string, NavoNode>
+  authedRootResolvePath: string
+  onCanAccess: (node: CanAccess) => void
+}
+
+export const NavoContext = createContext<NavoContextProps | null>(null)
+
+export type NavoProviderProps<T extends NavoNodeInput[]> = {
+  navo: Navo<T>
+  children?: React.ReactNode
+}
+
+/** Navo Provider */
+export function NavoProvider<T extends NavoNodeInput[]>({ children, navo }: NavoProviderProps<T>) {
+  const [state, setState] = useState({
+    nodes: navo.nodes,
+    idMap: navo.idMap,
+    authedNodes: navo.authedNodes,
+    authedIdMap: navo.authedIdMap,
+    authedRootResolvePath: navo.authedRootResolvePath,
+  })
+
+  const value = useMemo(
+    () => ({
+      ...state,
+      originNavo: navo,
+      onCanAccess: (canAccess?: CanAccess) => {
+        navo.authenticat(canAccess)
+        setState({
+          nodes: navo.nodes,
+          idMap: navo.idMap,
+          authedNodes: navo.authedNodes,
+          authedIdMap: navo.authedIdMap,
+          authedRootResolvePath: navo.authedRootResolvePath,
+        })
+      },
+    }),
+    [navo, state]
+  )
+
+  return <NavoContext.Provider value={value}>{children}</NavoContext.Provider>
+}
+
+/** 生成react router routes */
+export function generateRoutes<T extends NavoNodeInput[]>(navo: Navo<T>): RouteObject[] {
+  const navNodes = navo.nodes
+  const r = (navNodes: NavoNode[]) => {
+    const routes: RouteObject[] = []
+    for (let i = 0; i < navNodes.length; i++) {
+      const navNode = navNodes[i]
+      const route: NonIndexRouteObject = {
+        ...navNode.route,
+        id: navNode.id,
+        path: navNode.originPath,
+      }
+      if (navNode.children?.length) {
+        route.children = r(navNode.children)
+      }
+      routes.push(route)
+    }
+
+    if (navNodes.length) {
+      routes.push({
+        index: true,
+        element: <NavoRedirect navNode={navNodes[0].parent} />,
+      })
+    }
+    return routes
+  }
+
+  return r(navNodes)
+}