@djangocfg/nextjs 2.1.107 → 2.1.109

package/dist/navigation/index.d.mts

@@ -14,6 +14,7 @@ interface RouteMetadata {
     group?: string;
     order?: number;
     show?: boolean;
+    extensionName?: string;
     priority?: number;
     changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
     noindex?: boolean;
@@ -22,6 +23,20 @@ interface RouteDefinition {
     path: string;
     metadata: RouteMetadata;
 }
+interface NavGroup {
+    /** Unique group identifier (matches RouteMetadata.group) */
+    id: string;
+    /** Display label for the group */
+    label: string;
+    /** Sort order */
+    order: number;
+    /** If true, group is only shown when it has items (e.g., extensions) */
+    dynamic?: boolean;
+}
+interface NavGroupWithRoutes extends NavGroup {
+    /** Routes in this group (populated at runtime) */
+    routes: RouteDefinition[];
+}
 interface MenuItem {
     path: string;
     label: string;
@@ -88,5 +103,24 @@ declare function isActive(current: string, target: string, allRoutes?: RouteDefi
  * Filter and convert routes to menu items
  */
 declare function routesToMenuItems(routes: RouteDefinition[], groupName: string): MenuItem[];
+/**
+ * Group routes by navigation groups
+ *
+ * @param routes - Array of route definitions
+ * @param groups - Array of navigation group definitions
+ * @returns Array of groups with their routes, filtered by dynamic flag
+ *
+ * @example
+ * ```ts
+ * const navGroups = [
+ *   { id: 'dashboard', label: 'Dashboard', order: 1 },
+ *   { id: 'extensions', label: 'Extensions', order: 2, dynamic: true },
+ * ];
+ *
+ * const groupedRoutes = groupRoutesByNavGroups(allRoutes, navGroups);
+ * // Returns groups with routes, hiding dynamic groups with no routes
+ * ```
+ */
+declare function groupRoutesByNavGroups(routes: RouteDefinition[], groups: NavGroup[]): NavGroupWithRoutes[];
 
-export { type BreadcrumbItem, type MenuGroup, type MenuItem, type NavigationItem, type NavigationSection, type RouteDefinition, type RouteMetadata, defineRoute, findRoute, findRouteByPattern, getPageTitle, getUnauthenticatedRedirect, isActive, redirectToAuth, routesToMenuItems };
+export { type BreadcrumbItem, type MenuGroup, type MenuItem, type NavGroup, type NavGroupWithRoutes, type NavigationItem, type NavigationSection, type RouteDefinition, type RouteMetadata, defineRoute, findRoute, findRouteByPattern, getPageTitle, getUnauthenticatedRedirect, groupRoutesByNavGroups, isActive, redirectToAuth, routesToMenuItems };

package/dist/navigation/index.mjs

@@ -50,12 +50,26 @@ function routesToMenuItems(routes, groupName) {
     icon: r.metadata.icon
   }));
 }
+function groupRoutesByNavGroups(routes, groups) {
+  return groups.map((group) => ({
+    ...group,
+    routes: routes.filter(
+      (r) => r.metadata.group === group.id && (r.metadata.show === void 0 || r.metadata.show === true)
+    ).sort((a, b) => (a.metadata.order || 0) - (b.metadata.order || 0))
+  })).filter((group) => {
+    if (group.dynamic) {
+      return group.routes.length > 0;
+    }
+    return true;
+  }).sort((a, b) => a.order - b.order);
+}
 export {
   defineRoute,
   findRoute,
   findRouteByPattern,
   getPageTitle,
   getUnauthenticatedRedirect,
+  groupRoutesByNavGroups,
   isActive,
   redirectToAuth,
   routesToMenuItems

package/dist/navigation/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/navigation/utils.ts"],"sourcesContent":["/**\n * Navigation Utilities\n *\n * Common utilities for route definitions and navigation\n */\n\nimport type { RouteDefinition, RouteMetadata, MenuItem } from './types';\n\n// ─────────────────────────────────────────────────────────────────────────\n// Route Definition Helper\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Define a route with metadata\n *\n * IMPORTANT: Next.js automatically handles basePath for <Link> components when\n * basePath is set in next.config.ts. We should NOT add basePath manually here,\n * as it would cause double-prefixing in static builds.\n *\n * @param path - Route path (e.g., '/dashboard', '/admin/users')\n * @param metadata - Route metadata (label, icon, etc.)\n */\nexport function defineRoute(\n  path: string,\n  metadata: RouteMetadata,\n): RouteDefinition {\n  // Always return path as-is. Next.js will handle basePath automatically\n  // for <Link> components when basePath is set in next.config.ts\n  return {\n    path,\n    metadata,\n  };\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Route Guards\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Get redirect path for unauthenticated users\n */\nexport function getUnauthenticatedRedirect(\n  path: string,\n  authPath: string = '/auth',\n): string | null {\n  if (path.startsWith('/private') || path.startsWith('/admin')) {\n    // Return path as-is. Next.js will handle basePath automatically for router.push()\n    // when basePath is set in next.config.ts\n    return authPath;\n  }\n  return null;\n}\n\n/**\n * Get redirect path to auth page\n */\nexport function redirectToAuth(\n  authPath: string = '/auth',\n): string {\n  // Return path as-is. Next.js will handle basePath automatically for router.push()\n  // when basePath is set in next.config.ts\n  return authPath;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Route Lookup\n// ─────────────────────────────────────────────────────────────────────────\n\nexport function findRoute(\n  routes: RouteDefinition[],\n  path: string\n): RouteDefinition | undefined {\n  return routes.find((r) => r.path === path);\n}\n\nexport function findRouteByPattern(\n  routes: RouteDefinition[],\n  path: string\n): RouteDefinition | undefined {\n  const exact = findRoute(routes, path);\n  if (exact) return exact;\n\n  const segments = path.split('/').filter(Boolean);\n  for (let i = segments.length; i > 0; i--) {\n    const parentPath = '/' + segments.slice(0, i).join('/');\n    const parent = findRoute(routes, parentPath);\n    if (parent) return parent;\n  }\n\n  return undefined;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Page Title\n// ─────────────────────────────────────────────────────────────────────────\n\nexport function getPageTitle(\n  routes: RouteDefinition[],\n  path: string,\n  fallback = 'Dashboard'\n): string {\n  const route = findRouteByPattern(routes, path);\n  return route?.metadata.label || fallback;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Active Route\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Check if a route is active\n *\n * @param current - Current pathname\n * @param target - Target route path to check\n * @param allRoutes - Optional array of all routes to prevent parent paths from being active when child paths are active\n * @returns true if the route is active\n */\nexport function isActive(\n  current: string,\n  target: string,\n  allRoutes?: RouteDefinition[]\n): boolean {\n  const matches =\n    current === target || (target !== '/' && current.startsWith(target + '/'));\n\n  // If allRoutes is provided, check for more specific paths\n  if (matches && allRoutes) {\n    return !allRoutes.some(\n      (otherRoute) =>\n        otherRoute.path !== target &&\n        otherRoute.path.startsWith(target + '/') &&\n        (current === otherRoute.path ||\n          current.startsWith(otherRoute.path + '/'))\n    );\n  }\n\n  return matches;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Menu Generation Helper\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Filter and convert routes to menu items\n */\nexport function routesToMenuItems(\n  routes: RouteDefinition[],\n  groupName: string\n): MenuItem[] {\n  return routes\n    .filter(\n      (r) =>\n        r.metadata.group === groupName &&\n        r.metadata.icon &&\n        (r.metadata.show === undefined || r.metadata.show === true)\n    )\n    .sort((a, b) => (a.metadata.order || 0) - (b.metadata.order || 0))\n    .map((r) => ({\n      path: r.path,\n      label: r.metadata.label,\n      icon: r.metadata.icon!,\n    }));\n}\n\n"],"mappings":";AAsBO,SAAS,YACd,MACA,UACiB;AAGjB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,EACF;AACF;AASO,SAAS,2BACd,MACA,WAAmB,SACJ;AACf,MAAI,KAAK,WAAW,UAAU,KAAK,KAAK,WAAW,QAAQ,GAAG;AAG5D,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAKO,SAAS,eACd,WAAmB,SACX;AAGR,SAAO;AACT;AAMO,SAAS,UACd,QACA,MAC6B;AAC7B,SAAO,OAAO,KAAK,CAAC,MAAM,EAAE,SAAS,IAAI;AAC3C;AAEO,SAAS,mBACd,QACA,MAC6B;AAC7B,QAAM,QAAQ,UAAU,QAAQ,IAAI;AACpC,MAAI,MAAO,QAAO;AAElB,QAAM,WAAW,KAAK,MAAM,GAAG,EAAE,OAAO,OAAO;AAC/C,WAAS,IAAI,SAAS,QAAQ,IAAI,GAAG,KAAK;AACxC,UAAM,aAAa,MAAM,SAAS,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG;AACtD,UAAM,SAAS,UAAU,QAAQ,UAAU;AAC3C,QAAI,OAAQ,QAAO;AAAA,EACrB;AAEA,SAAO;AACT;AAMO,SAAS,aACd,QACA,MACA,WAAW,aACH;AACR,QAAM,QAAQ,mBAAmB,QAAQ,IAAI;AAC7C,SAAO,OAAO,SAAS,SAAS;AAClC;AAcO,SAAS,SACd,SACA,QACA,WACS;AACT,QAAM,UACJ,YAAY,UAAW,WAAW,OAAO,QAAQ,WAAW,SAAS,GAAG;AAG1E,MAAI,WAAW,WAAW;AACxB,WAAO,CAAC,UAAU;AAAA,MAChB,CAAC,eACC,WAAW,SAAS,UACpB,WAAW,KAAK,WAAW,SAAS,GAAG,MACtC,YAAY,WAAW,QACtB,QAAQ,WAAW,WAAW,OAAO,GAAG;AAAA,IAC9C;AAAA,EACF;AAEA,SAAO;AACT;AASO,SAAS,kBACd,QACA,WACY;AACZ,SAAO,OACJ;AAAA,IACC,CAAC,MACC,EAAE,SAAS,UAAU,aACrB,EAAE,SAAS,SACV,EAAE,SAAS,SAAS,UAAa,EAAE,SAAS,SAAS;AAAA,EAC1D,EACC,KAAK,CAAC,GAAG,OAAO,EAAE,SAAS,SAAS,MAAM,EAAE,SAAS,SAAS,EAAE,EAChE,IAAI,CAAC,OAAO;AAAA,IACX,MAAM,EAAE;AAAA,IACR,OAAO,EAAE,SAAS;AAAA,IAClB,MAAM,EAAE,SAAS;AAAA,EACnB,EAAE;AACN;","names":[]}
+{"version":3,"sources":["../../src/navigation/utils.ts"],"sourcesContent":["/**\n * Navigation Utilities\n *\n * Common utilities for route definitions and navigation\n */\n\nimport type { RouteDefinition, RouteMetadata, MenuItem, NavGroup, NavGroupWithRoutes } from './types';\n\n// ─────────────────────────────────────────────────────────────────────────\n// Route Definition Helper\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Define a route with metadata\n *\n * IMPORTANT: Next.js automatically handles basePath for <Link> components when\n * basePath is set in next.config.ts. We should NOT add basePath manually here,\n * as it would cause double-prefixing in static builds.\n *\n * @param path - Route path (e.g., '/dashboard', '/admin/users')\n * @param metadata - Route metadata (label, icon, etc.)\n */\nexport function defineRoute(\n  path: string,\n  metadata: RouteMetadata,\n): RouteDefinition {\n  // Always return path as-is. Next.js will handle basePath automatically\n  // for <Link> components when basePath is set in next.config.ts\n  return {\n    path,\n    metadata,\n  };\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Route Guards\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Get redirect path for unauthenticated users\n */\nexport function getUnauthenticatedRedirect(\n  path: string,\n  authPath: string = '/auth',\n): string | null {\n  if (path.startsWith('/private') || path.startsWith('/admin')) {\n    // Return path as-is. Next.js will handle basePath automatically for router.push()\n    // when basePath is set in next.config.ts\n    return authPath;\n  }\n  return null;\n}\n\n/**\n * Get redirect path to auth page\n */\nexport function redirectToAuth(\n  authPath: string = '/auth',\n): string {\n  // Return path as-is. Next.js will handle basePath automatically for router.push()\n  // when basePath is set in next.config.ts\n  return authPath;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Route Lookup\n// ─────────────────────────────────────────────────────────────────────────\n\nexport function findRoute(\n  routes: RouteDefinition[],\n  path: string\n): RouteDefinition | undefined {\n  return routes.find((r) => r.path === path);\n}\n\nexport function findRouteByPattern(\n  routes: RouteDefinition[],\n  path: string\n): RouteDefinition | undefined {\n  const exact = findRoute(routes, path);\n  if (exact) return exact;\n\n  const segments = path.split('/').filter(Boolean);\n  for (let i = segments.length; i > 0; i--) {\n    const parentPath = '/' + segments.slice(0, i).join('/');\n    const parent = findRoute(routes, parentPath);\n    if (parent) return parent;\n  }\n\n  return undefined;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Page Title\n// ─────────────────────────────────────────────────────────────────────────\n\nexport function getPageTitle(\n  routes: RouteDefinition[],\n  path: string,\n  fallback = 'Dashboard'\n): string {\n  const route = findRouteByPattern(routes, path);\n  return route?.metadata.label || fallback;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Active Route\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Check if a route is active\n *\n * @param current - Current pathname\n * @param target - Target route path to check\n * @param allRoutes - Optional array of all routes to prevent parent paths from being active when child paths are active\n * @returns true if the route is active\n */\nexport function isActive(\n  current: string,\n  target: string,\n  allRoutes?: RouteDefinition[]\n): boolean {\n  const matches =\n    current === target || (target !== '/' && current.startsWith(target + '/'));\n\n  // If allRoutes is provided, check for more specific paths\n  if (matches && allRoutes) {\n    return !allRoutes.some(\n      (otherRoute) =>\n        otherRoute.path !== target &&\n        otherRoute.path.startsWith(target + '/') &&\n        (current === otherRoute.path ||\n          current.startsWith(otherRoute.path + '/'))\n    );\n  }\n\n  return matches;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Menu Generation Helper\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Filter and convert routes to menu items\n */\nexport function routesToMenuItems(\n  routes: RouteDefinition[],\n  groupName: string\n): MenuItem[] {\n  return routes\n    .filter(\n      (r) =>\n        r.metadata.group === groupName &&\n        r.metadata.icon &&\n        (r.metadata.show === undefined || r.metadata.show === true)\n    )\n    .sort((a, b) => (a.metadata.order || 0) - (b.metadata.order || 0))\n    .map((r) => ({\n      path: r.path,\n      label: r.metadata.label,\n      icon: r.metadata.icon!,\n    }));\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Navigation Groups Helper\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Group routes by navigation groups\n *\n * @param routes - Array of route definitions\n * @param groups - Array of navigation group definitions\n * @returns Array of groups with their routes, filtered by dynamic flag\n *\n * @example\n * ```ts\n * const navGroups = [\n *   { id: 'dashboard', label: 'Dashboard', order: 1 },\n *   { id: 'extensions', label: 'Extensions', order: 2, dynamic: true },\n * ];\n *\n * const groupedRoutes = groupRoutesByNavGroups(allRoutes, navGroups);\n * // Returns groups with routes, hiding dynamic groups with no routes\n * ```\n */\nexport function groupRoutesByNavGroups(\n  routes: RouteDefinition[],\n  groups: NavGroup[]\n): NavGroupWithRoutes[] {\n  return groups\n    .map((group) => ({\n      ...group,\n      routes: routes\n        .filter(\n          (r) =>\n            r.metadata.group === group.id &&\n            (r.metadata.show === undefined || r.metadata.show === true)\n        )\n        .sort((a, b) => (a.metadata.order || 0) - (b.metadata.order || 0)),\n    }))\n    .filter((group) => {\n      // Dynamic groups are only shown if they have routes\n      if (group.dynamic) {\n        return group.routes.length > 0;\n      }\n      // Non-dynamic groups are always shown\n      return true;\n    })\n    .sort((a, b) => a.order - b.order);\n}\n\n"],"mappings":";AAsBO,SAAS,YACd,MACA,UACiB;AAGjB,SAAO;AAAA,IACL;AAAA,IACA;AAAA,EACF;AACF;AASO,SAAS,2BACd,MACA,WAAmB,SACJ;AACf,MAAI,KAAK,WAAW,UAAU,KAAK,KAAK,WAAW,QAAQ,GAAG;AAG5D,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAKO,SAAS,eACd,WAAmB,SACX;AAGR,SAAO;AACT;AAMO,SAAS,UACd,QACA,MAC6B;AAC7B,SAAO,OAAO,KAAK,CAAC,MAAM,EAAE,SAAS,IAAI;AAC3C;AAEO,SAAS,mBACd,QACA,MAC6B;AAC7B,QAAM,QAAQ,UAAU,QAAQ,IAAI;AACpC,MAAI,MAAO,QAAO;AAElB,QAAM,WAAW,KAAK,MAAM,GAAG,EAAE,OAAO,OAAO;AAC/C,WAAS,IAAI,SAAS,QAAQ,IAAI,GAAG,KAAK;AACxC,UAAM,aAAa,MAAM,SAAS,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG;AACtD,UAAM,SAAS,UAAU,QAAQ,UAAU;AAC3C,QAAI,OAAQ,QAAO;AAAA,EACrB;AAEA,SAAO;AACT;AAMO,SAAS,aACd,QACA,MACA,WAAW,aACH;AACR,QAAM,QAAQ,mBAAmB,QAAQ,IAAI;AAC7C,SAAO,OAAO,SAAS,SAAS;AAClC;AAcO,SAAS,SACd,SACA,QACA,WACS;AACT,QAAM,UACJ,YAAY,UAAW,WAAW,OAAO,QAAQ,WAAW,SAAS,GAAG;AAG1E,MAAI,WAAW,WAAW;AACxB,WAAO,CAAC,UAAU;AAAA,MAChB,CAAC,eACC,WAAW,SAAS,UACpB,WAAW,KAAK,WAAW,SAAS,GAAG,MACtC,YAAY,WAAW,QACtB,QAAQ,WAAW,WAAW,OAAO,GAAG;AAAA,IAC9C;AAAA,EACF;AAEA,SAAO;AACT;AASO,SAAS,kBACd,QACA,WACY;AACZ,SAAO,OACJ;AAAA,IACC,CAAC,MACC,EAAE,SAAS,UAAU,aACrB,EAAE,SAAS,SACV,EAAE,SAAS,SAAS,UAAa,EAAE,SAAS,SAAS;AAAA,EAC1D,EACC,KAAK,CAAC,GAAG,OAAO,EAAE,SAAS,SAAS,MAAM,EAAE,SAAS,SAAS,EAAE,EAChE,IAAI,CAAC,OAAO;AAAA,IACX,MAAM,EAAE;AAAA,IACR,OAAO,EAAE,SAAS;AAAA,IAClB,MAAM,EAAE,SAAS;AAAA,EACnB,EAAE;AACN;AAwBO,SAAS,uBACd,QACA,QACsB;AACtB,SAAO,OACJ,IAAI,CAAC,WAAW;AAAA,IACf,GAAG;AAAA,IACH,QAAQ,OACL;AAAA,MACC,CAAC,MACC,EAAE,SAAS,UAAU,MAAM,OAC1B,EAAE,SAAS,SAAS,UAAa,EAAE,SAAS,SAAS;AAAA,IAC1D,EACC,KAAK,CAAC,GAAG,OAAO,EAAE,SAAS,SAAS,MAAM,EAAE,SAAS,SAAS,EAAE;AAAA,EACrE,EAAE,EACD,OAAO,CAAC,UAAU;AAEjB,QAAI,MAAM,SAAS;AACjB,aAAO,MAAM,OAAO,SAAS;AAAA,IAC/B;AAEA,WAAO;AAAA,EACT,CAAC,EACA,KAAK,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;AACrC;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.107",
+  "version": "2.1.109",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -133,9 +133,9 @@
     "web-push": "^3.6.7"
   },
   "devDependencies": {
-    "@djangocfg/imgai": "^2.1.107",
-    "@djangocfg/layouts": "^2.1.107",
-    "@djangocfg/typescript-config": "^2.1.107",
+    "@djangocfg/imgai": "^2.1.109",
+    "@djangocfg/layouts": "^2.1.109",
+    "@djangocfg/typescript-config": "^2.1.109",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/navigation/types.ts

@@ -18,6 +18,8 @@ export interface RouteMetadata {
   group?: string;
   order?: number;
   show?: boolean;
+  // Extension mapping (for dynamic filtering based on API response)
+  extensionName?: string;
   // SEO
   priority?: number; // Sitemap priority 0.0-1.0
   changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
@@ -29,6 +31,26 @@ export interface RouteDefinition {
   metadata: RouteMetadata;
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// Navigation Group Types (for horizontal tabs with labels)
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface NavGroup {
+  /** Unique group identifier (matches RouteMetadata.group) */
+  id: string;
+  /** Display label for the group */
+  label: string;
+  /** Sort order */
+  order: number;
+  /** If true, group is only shown when it has items (e.g., extensions) */
+  dynamic?: boolean;
+}
+
+export interface NavGroupWithRoutes extends NavGroup {
+  /** Routes in this group (populated at runtime) */
+  routes: RouteDefinition[];
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 // Menu Types
 // ─────────────────────────────────────────────────────────────────────────

package/src/navigation/utils.ts

@@ -4,7 +4,7 @@
  * Common utilities for route definitions and navigation
  */
 
-import type { RouteDefinition, RouteMetadata, MenuItem } from './types';
+import type { RouteDefinition, RouteMetadata, MenuItem, NavGroup, NavGroupWithRoutes } from './types';
 
 // ─────────────────────────────────────────────────────────────────────────
 // Route Definition Helper
@@ -163,3 +163,51 @@ export function routesToMenuItems(
     }));
 }
 
+// ─────────────────────────────────────────────────────────────────────────
+// Navigation Groups Helper
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Group routes by navigation groups
+ *
+ * @param routes - Array of route definitions
+ * @param groups - Array of navigation group definitions
+ * @returns Array of groups with their routes, filtered by dynamic flag
+ *
+ * @example
+ * ```ts
+ * const navGroups = [
+ *   { id: 'dashboard', label: 'Dashboard', order: 1 },
+ *   { id: 'extensions', label: 'Extensions', order: 2, dynamic: true },
+ * ];
+ *
+ * const groupedRoutes = groupRoutesByNavGroups(allRoutes, navGroups);
+ * // Returns groups with routes, hiding dynamic groups with no routes
+ * ```
+ */
+export function groupRoutesByNavGroups(
+  routes: RouteDefinition[],
+  groups: NavGroup[]
+): NavGroupWithRoutes[] {
+  return groups
+    .map((group) => ({
+      ...group,
+      routes: routes
+        .filter(
+          (r) =>
+            r.metadata.group === group.id &&
+            (r.metadata.show === undefined || r.metadata.show === true)
+        )
+        .sort((a, b) => (a.metadata.order || 0) - (b.metadata.order || 0)),
+    }))
+    .filter((group) => {
+      // Dynamic groups are only shown if they have routes
+      if (group.dynamic) {
+        return group.routes.length > 0;
+      }
+      // Non-dynamic groups are always shown
+      return true;
+    })
+    .sort((a, b) => a.order - b.order);
+}
+