{"_id":"@dbs-portal/core-router","name":"@dbs-portal/core-router","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@dbs-portal/core-router","version":"1.0.0","description":"Type-safe routing functionality and navigation utilities for DBS Portal","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./config":{"import":"./dist/config.js","types":"./dist/config.d.ts"},"./guards":{"import":"./dist/guards.js","types":"./dist/guards.d.ts"},"./navigation":{"import":"./dist/navigation.js","types":"./dist/navigation.d.ts"},"./breadcrumbs":{"import":"./dist/breadcrumbs.js","types":"./dist/breadcrumbs.d.ts"},"./types":{"import":"./dist/types.js","types":"./dist/types.d.ts"},"./module-routes":{"import":"./dist/module-routes.js","types":"./dist/module-routes.d.ts"}},"scripts":{"build":"tsc && vite build","dev":"tsc --watch","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","lint":"biome lint src","format":"biome format src --write","type-check":"tsc --noEmit","clean":"rm -rf dist","validate-boundaries":"node ../../../scripts/validate-package-boundaries.js"},"dependencies":{"@dbs-portal/core-shared":"1.0.0","@floating-ui/react":"^0.27.14","@headlessui/react":"^2.2.6","@tanstack/react-form":"^1.15.0","framer-motion":"^12.23.11"},"peerDependencies":{"@tanstack/react-router":"^1.0.0","history":"^5.0.0","react":"^19.0.0"},"devDependencies":{"@biomejs/biome":"1.9.4","@dbs-portal/tool-build":"1.0.0","@dbs-portal/tool-testing":"1.0.0","@dbs-portal/tool-tsconfig":"1.0.0","@tanstack/react-router":"^1.91.3","@types/node":"^22.10.2","history":"^5.3.0","jsdom":"^26.1.0","react":"^19.0.0","typescript":"^5.7.2","vite":"^6.1.0","vitest":"^3.0.5"},"keywords":["router","navigation","tanstack","routing","dbs-portal"],"author":{"name":"DBS Portal Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/devboost-solutions/dbs-portal.git","directory":"packages/core/router"},"bugs":{"url":"https://github.com/devboost-solutions/dbs-portal/issues"},"homepage":"https://github.com/devboost-solutions/dbs-portal/tree/main/packages/core/router#readme","publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_id":"@dbs-portal/core-router@1.0.0","gitHead":"61a23904a481b624f3e8ed7abb6c944ecfeaca7b","_nodeVersion":"20.19.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-d8EdZYTYcMWdMaVqSG71JIRJps6z2WG1d1URnmqxmBMlLVdOe7T3saboNxYzxL3eCll9KE30yZaAksdM4L/hJw==","shasum":"ecef3fc407c733ce888878745f4d681e11da548b","tarball":"https://registry.npmjs.org/@dbs-portal/core-router/-/core-router-1.0.0.tgz","fileCount":56,"unpackedSize":353583,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFRcQ3+RttF1Y05+rqrrsB1vH9YPviign02yeXROHaVBAiEAg41beDBMxja9FbBAwVVrMBbgpl2Xu8F07z3Xcx7IU+w="}]},"_npmUser":{"name":"longvq","email":"vqlong1604@gmail.com"},"directories":{},"maintainers":[{"name":"longvq","email":"vqlong1604@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core-router_1.0.0_1754218655666_0.7550757404312329"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-03T10:57:35.612Z","1.0.0":"2025-08-03T10:57:35.844Z","modified":"2025-08-03T10:57:36.195Z"},"maintainers":[{"name":"longvq","email":"vqlong1604@gmail.com"}],"description":"Type-safe routing functionality and navigation utilities for DBS Portal","homepage":"https://github.com/devboost-solutions/dbs-portal/tree/main/packages/core/router#readme","keywords":["router","navigation","tanstack","routing","dbs-portal"],"repository":{"type":"git","url":"git+https://github.com/devboost-solutions/dbs-portal.git","directory":"packages/core/router"},"author":{"name":"DBS Portal Team"},"bugs":{"url":"https://github.com/devboost-solutions/dbs-portal/issues"},"license":"MIT","readme":"# @dbs-portal/core-router\n\nType-safe routing functionality and navigation utilities for DBS Portal using TanStack Router.\n\n## Features\n\n- 🚀 **Type-safe routing** with TanStack Router integration\n- 🔒 **Authentication and authorization** route guards\n- 🧭 **Navigation utilities** and programmatic navigation\n- 🍞 **Automatic breadcrumb generation** from route definitions\n- 📱 **History management** and URL manipulation\n- 🔧 **Configurable router setup** with fluent API\n- 🎯 **Seamless integration** with DBS Portal architecture\n- 🛡️ **Route protection** with customizable guards\n- 📊 **Navigation events** and lifecycle hooks\n- 🔄 **State management** integration ready\n\n## Installation\n\nThis package is part of the DBS Portal monorepo and should be installed via the workspace:\n\n```bash\nyarn workspace @dbs-portal/core-router install\n```\n\nFor external projects:\n\n```bash\nnpm install @dbs-portal/core-router @tanstack/react-router history\n# or\nyarn add @dbs-portal/core-router @tanstack/react-router history\n```\n\n## Quick Start\n\n### 1. Basic Router Setup\n\n```typescript\nimport { createAppRouter, setGlobalRouter } from '@dbs-portal/core-router'\n\n// Create router with default configuration\nconst router = createAppRouter()\n\n// Set as global router for navigation utilities\nsetGlobalRouter(router)\n\n// Use in your React app\nimport { RouterProvider } from '@tanstack/react-router'\n\nfunction App() {\n  return <RouterProvider router={router} />\n}\n```\n\n### 2. Advanced Configuration\n\n```typescript\nimport { configureRouter, createAppRouter } from '@dbs-portal/core-router'\n\nconst config = configureRouter()\n  .basePath('/app')\n  .preload('intent')\n  .scrollRestoration(true)\n  .devtools(true)\n  .build()\n\nconst router = createAppRouter(config)\n```\n\n## Core Concepts\n\n### Enhanced Permission System\n\nThe route registry includes a comprehensive permission system with multiple layers of protection and flexible configuration options.\n\n#### Permission Configuration\n\nRoutes can be configured with detailed permission requirements:\n\n```typescript\nimport { route, strictRoute, protectedRoute } from '@dbs-portal/core-router/helpers'\n\n// Basic permission check (user needs ANY of the specified permissions)\nroute('/users', 'User Management', () => import('@/pages/users'), {\n  permissions: ['users.read', 'users.manage'],\n  icon: 'users'\n})\n\n// Strict permission check (user needs ALL specified permissions)\nstrictRoute('/admin/system', 'System Administration', () => import('@/pages/admin/system'), {\n  permissions: ['admin.access', 'system.manage'],\n  icon: 'settings'\n})\n\n// Protected route with custom error handling\nprotectedRoute('/sensitive-data', 'Sensitive Data', () => import('@/pages/sensitive'), {\n  permissions: ['data.sensitive.access'],\n  permissionMode: 'all',\n  errorMessage: 'You need special clearance to access this data',\n  fallback: '/request-access',\n  icon: 'lock'\n})\n```\n\n#### Permission Modes\n\n- **`'any'` (default)**: User needs at least ONE of the specified permissions\n- **`'all'`**: User needs ALL of the specified permissions\n\n#### Permission Validation\n\nValidate permissions before navigation or rendering:\n\n```typescript\nimport {\n  validateRoutePermissions,\n  getAllRequiredPermissions,\n  getRoutesByPermission,\n  canAccessAnyRoute\n} from '@dbs-portal/core-router'\n\n// Check if user can access a specific route\nconst validation = validateRoutePermissions('/admin/users', userPermissions)\nif (!validation.allowed) {\n  console.log('Missing permissions:', validation.missingPermissions)\n  console.log('Error message:', validation.errorMessage)\n  console.log('Fallback route:', validation.fallbackRoute)\n}\n\n// Get all permissions required across the application\nconst allPermissions = getAllRequiredPermissions()\n\n// Find routes that require a specific permission\nconst userManagementRoutes = getRoutesByPermission('users.manage')\n\n// Check if user can access any routes (useful for navigation visibility)\nconst hasAnyAccess = canAccessAnyRoute(userPermissions)\n```\n\n#### Runtime Permission Checking\n\nRoutes include runtime permission checks with detailed error handling:\n\n```typescript\nimport { createRoutesFromRegistry } from '@dbs-portal/core-router'\n\n// Create routes with enhanced permission checking\nconst routes = createRoutesFromRegistry(parentRoute, userPermissions, {\n  enableRuntimeChecks: true, // Default: true\n  defaultFallback: '/unauthorized', // Default fallback route\n  permissionChecker: (requiredPermissions, userPermissions, mode) => {\n    // Custom permission checking logic\n    return mode === 'all'\n      ? requiredPermissions.every(p => userPermissions.includes(p))\n      : requiredPermissions.some(p => userPermissions.includes(p))\n  }\n})\n```\n\n#### Permission Error Handling\n\nWhen permission checks fail, detailed error information is provided:\n\n```typescript\n// Error object includes:\n{\n  routeId: '/admin/users',\n  fallbackRoute: '/unauthorized',\n  requiredPermissions: ['users.manage', 'admin.access'],\n  userPermissions: ['users.read'],\n  message: 'Access denied: Missing required permissions [users.manage, admin.access]'\n}\n```\n\n### Route Guards\n\nRoute guards provide authentication and authorization protection for your routes:\n\n```typescript\nimport {\n  withAuthGuard,\n  withRoleGuard,\n  withPermissionGuard,\n  createCustomGuard\n} from '@dbs-portal/core-router/guards'\n\n// Authentication guard\nconst protectedRoute = withAuthGuard(route)\n\n// Role-based guard\nconst adminRoute = withRoleGuard(route, 'admin')\nconst moderatorRoute = withRoleGuard(route, ['moderator', 'admin'])\n\n// Permission-based guard\nconst manageUsersRoute = withPermissionGuard(route, 'users.manage')\n\n// Custom guard\nconst customGuard = createCustomGuard((authState, route, location) => {\n  if (!authState.user?.isVerified) {\n    return '/verify-email'\n  }\n  return true\n})\n```\n\n### Navigation Utilities\n\nProgrammatic navigation with type safety:\n\n```typescript\nimport {\n  navigate,\n  replace,\n  goBack,\n  goForward,\n  reload,\n  getCurrentLocation\n} from '@dbs-portal/core-router/navigation'\n\n// Navigate to a route\nawait navigate('/dashboard')\n\n// Navigate with options\nawait navigate('/users/123', {\n  search: { tab: 'profile' },\n  state: { from: 'dashboard' }\n})\n\n// Replace current route\nawait replace('/login')\n\n// History navigation\ngoBack()\ngoForward()\nreload()\n\n// Get current location\nconst location = getCurrentLocation()\n```\n\n### Breadcrumb Generation\n\nAutomatic breadcrumb generation from route metadata:\n\n```typescript\nimport {\n  generateBreadcrumbs,\n  breadcrumbUtils,\n  createBreadcrumbBuilder\n} from '@dbs-portal/core-router/breadcrumbs'\n\n// Register route metadata\nbreadcrumbUtils.registerRoutes({\n  '/': { title: 'Home' },\n  '/users': { title: 'Users' },\n  '/users/:id': {\n    title: 'User :id',\n    breadcrumb: { title: 'User Profile' }\n  }\n})\n\n// Generate breadcrumbs\nconst breadcrumbs = generateBreadcrumbs(currentRoute)\n\n// Manual breadcrumb building\nconst customBreadcrumbs = createBreadcrumbBuilder()\n  .home('Dashboard', '/dashboard')\n  .add('Settings', '/settings')\n  .add('Profile', '/settings/profile')\n  .build()\n```\n\n### URL Utilities\n\nPowerful URL manipulation and parsing:\n\n```typescript\nimport { urlUtils } from '@dbs-portal/core-router/navigation'\n\n// Build URLs with parameters\nconst url = urlUtils.buildUrl('/users/:id', { id: '123' }, { tab: 'profile' })\n// Result: '/users/123?tab=profile'\n\n// Parse URLs\nconst parsed = urlUtils.parseUrl('https://example.com/users/123?tab=profile#section')\n// Result: { path: '/users/123', search: { tab: 'profile' }, hash: 'section' }\n\n// Pattern matching\nconst matches = urlUtils.matchesPattern('/users/123', '/users/:id') // true\n```\n\n## Integration with DBS Portal\n\n### Authentication Integration\n\n```typescript\nimport { setAuthStateGetter } from '@dbs-portal/core-router/guards'\nimport { useAuthStore } from '@dbs-portal/core-auth'\n\n// Set up auth state integration\nsetAuthStateGetter(() => {\n  const authStore = useAuthStore.getState()\n  return {\n    isAuthenticated: authStore.isAuthenticated,\n    user: authStore.user\n  }\n})\n```\n\n### State Management Integration\n\n```typescript\nimport { useRouterStore } from '@dbs-portal/core-store'\nimport { setGlobalRouter } from '@dbs-portal/core-router'\n\n// Integrate with Zustand store\nconst router = createAppRouter()\nsetGlobalRouter(router)\n\n// Listen to navigation events\nrouter.addEventListener('afterNavigate', (event) => {\n  useRouterStore.getState().setCurrentRoute(event.to)\n})\n```\n\n## API Reference\n\n### Router Configuration\n\n#### `createAppRouter(config?: RouterConfig): AppRouter`\n\nCreates an enhanced router instance with DBS Portal integrations.\n\n**Parameters:**\n- `config` (optional): Router configuration options\n\n**Returns:** Enhanced router instance\n\n#### `configureRouter(): RouterConfigBuilder`\n\nCreates a fluent configuration builder.\n\n**Example:**\n```typescript\nconst config = configureRouter()\n  .basePath('/app')\n  .preload('intent')\n  .build()\n```\n\n### Navigation\n\n#### `navigate(path: string, options?: NavigationOptions): Promise<void>`\n\nNavigate to a specific path programmatically.\n\n#### `goBack(): void` / `goForward(): void`\n\nNavigate through browser history.\n\n#### `getCurrentLocation(): RouteInfo | null`\n\nGet current route information.\n\n### Route Guards\n\n#### `withAuthGuard<T>(route: T): T`\n\nAdd authentication guard to a route.\n\n#### `withRoleGuard<T>(route: T, roles: string | string[]): T`\n\nAdd role-based authorization guard.\n\n#### `withPermissionGuard<T>(route: T, permissions: string | string[]): T`\n\nAdd permission-based authorization guard.\n\n### Breadcrumbs\n\n#### `generateBreadcrumbs(route: RouteInfo, config?: BreadcrumbGeneratorConfig): BreadcrumbItem[]`\n\nGenerate breadcrumbs from route information.\n\n#### `breadcrumbUtils.registerRoute(path: string, metadata: RouteMetadata): void`\n\nRegister route metadata for breadcrumb generation.\n\n## TypeScript Support\n\nThis package is built with TypeScript and provides comprehensive type definitions:\n\n```typescript\nimport type {\n  AppRouter,\n  RouteInfo,\n  RouteGuard,\n  NavigationOptions,\n  BreadcrumbConfig,\n  RouterConfig\n} from '@dbs-portal/core-router'\n\n// All exports are fully typed\nconst router: AppRouter = createAppRouter()\nconst guard: RouteGuard = (route, location) => true\n```\n\n## Testing\n\nThe package includes comprehensive test coverage. Run tests with:\n\n```bash\nyarn test\n```\n\nFor watch mode:\n\n```bash\nyarn test:watch\n```\n\n## Examples\n\n### Complete Setup Example\n\n```typescript\n// router.ts\nimport {\n  createAppRouter,\n  configureRouter,\n  setGlobalRouter,\n  breadcrumbUtils\n} from '@dbs-portal/core-router'\n\n// Configure router\nconst config = configureRouter()\n  .basePath('/')\n  .preload('intent')\n  .scrollRestoration(true)\n  .devtools(process.env.NODE_ENV === 'development')\n  .build()\n\n// Register route metadata\nbreadcrumbUtils.registerRoutes({\n  '/': { title: 'Home' },\n  '/dashboard': { title: 'Dashboard' },\n  '/users': { title: 'Users' },\n  '/users/:id': { title: 'User Profile' },\n  '/settings': { title: 'Settings' }\n})\n\n// Create and configure router\nexport const router = createAppRouter(config)\nsetGlobalRouter(router)\n```\n\n### Route Protection Example\n\n```typescript\n// routes.ts\nimport { createRoute } from '@tanstack/react-router'\nimport { withAuthGuard, withRoleGuard } from '@dbs-portal/core-router/guards'\n\nconst dashboardRoute = withAuthGuard(\n  createRoute({\n    getParentRoute: () => rootRoute,\n    path: '/dashboard',\n    component: DashboardPage\n  })\n)\n\nconst adminRoute = withRoleGuard(\n  createRoute({\n    getParentRoute: () => rootRoute,\n    path: '/admin',\n    component: AdminPage\n  }),\n  'admin'\n)\n```\n\n## Dependencies\n\n- `@tanstack/react-router` ^1.0.0 - Type-safe routing\n- `history` ^5.0.0 - Browser history management\n- `@dbs-portal/core-shared` 1.0.0 - Shared utilities and types\n\n## Peer Dependencies\n\n- `react` ^19.0.0 - React framework\n\n## Contributing\n\nThis package follows the DBS Portal monorepo conventions. See the main repository documentation for contribution guidelines.\n\n## Simple Route Registration API\n\nFor a more intuitive developer experience, use the new simplified route registration system:\n\n### Register Simple Routes\n\n```typescript\nimport { route } from '@dbs-portal/core-router'\n\n// Basic route\nroute('/settings', 'Settings', () => import('@/pages/settings'))\n\n// Route with icon and permissions\nroute('/admin', 'Admin Panel', () => import('@/pages/admin'), {\n  icon: 'settings',\n  permissions: ['admin.access']\n})\n```\n\n### Register Multiple Routes\n\n```typescript\nimport { routes } from '@dbs-portal/core-router'\n\nroutes([\n  ['/animate', 'Animate', () => import('@/pages/components/animate')],\n  ['/scroll', 'Scroll', () => import('@/pages/components/scroll')],\n  ['/markdown', 'Markdown', () => import('@/pages/components/markdown')],\n  ['/editor', 'Editor', () => import('@/pages/components/editor')],\n  ['/multi-language', 'Multi Language', () => import('@/pages/components/multi-language')],\n  ['/icon', 'Icons', () => import('@/pages/components/icon')],\n  ['/upload', 'Upload', () => import('@/pages/components/upload')],\n  ['/chart', 'Charts', () => import('@/pages/components/chart')]\n])\n```\n\n### Register Route Groups\n\n```typescript\nimport { routeGroup } from '@dbs-portal/core-router'\n\nrouteGroup('Components', {\n  icon: 'component',\n  order: 1,\n  routes: [\n    ['/animate', 'Animate', () => import('@/pages/components/animate')],\n    ['/scroll', 'Scroll', () => import('@/pages/components/scroll')],\n    ['/markdown', 'Markdown', () => import('@/pages/components/markdown')]\n  ]\n})\n```\n\n### Register Admin Routes\n\n```typescript\nimport { adminRoutes } from '@dbs-portal/core-router'\n\nadminRoutes([\n  ['/users', 'User Management', () => import('@/pages/admin/users')],\n  ['/settings', 'System Settings', () => import('@/pages/admin/settings')],\n  ['/audit', 'Audit Logs', () => import('@/pages/admin/audit')]\n])\n```\n\n### Register Module Routes\n\n```typescript\nimport { moduleRoutes } from '@dbs-portal/core-router'\n\nmoduleRoutes('File Management', {\n  basePath: '/files',\n  icon: 'folder',\n  permissions: ['files.access'],\n  routes: [\n    ['/', 'File Browser', () => import('./components/FileBrowser')],\n    ['/upload', 'Upload Files', () => import('./components/FileUpload')],\n    ['/settings', 'File Settings', () => import('./components/FileSettings')]\n  ]\n})\n```\n\n### Create Routes from Registry\n\n```typescript\nimport { createRoutesFromRegistry, getNavigation } from '@dbs-portal/core-router'\n\n// Create routes from registry\nconst dynamicRoutes = createRoutesFromRegistry(appRoute, userPermissions)\n\n// Generate navigation\nconst navigationStructure = getNavigation(userPermissions)\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-4f680e4a9beba3d16eeae2cda93a847c"}