qdadm 0.38.0 → 0.40.0

package/src/composables/useNavContext.js

@@ -1,43 +1,33 @@
 /**
  * useNavContext - Route-aware navigation context for breadcrumb and navlinks
  *
- * Builds navigation from route path pattern analysis (not heuristics).
+ * Uses semantic breadcrumb as the source of truth for navigation structure.
+ * Semantic breadcrumb is computed from route path and registered routes.
  *
- * The route path pattern defines the navigation structure:
- *   - Static segments (e.g., 'books') → entity list
- *   - Param segments (e.g., ':id', ':bookId') → entity item
- *   - Action segments (e.g., 'edit', 'create') → ignored
- *
- * Route meta configuration:
- *   - meta.entity: Entity managed by this route (required)
- *   - meta.parent: Parent entity config for nested routes
- *     - parent.entity: Parent entity name
- *     - parent.param: Route param for parent ID
+ * Semantic breadcrumb kinds:
+ *   - entity-list: Entity collection (e.g., /books)
+ *   - entity-show: Entity instance view (e.g., /books/1)
+ *   - entity-edit: Entity instance edit (e.g., /books/1/edit)
+ *   - entity-create: Entity creation (e.g., /books/create)
+ *   - route: Generic route (e.g., /settings)
  *
  * Examples:
- *   Path: /books              meta: { entity: 'books' }
- *   → Home > Books
- *
- *   Path: /books/:id/edit     meta: { entity: 'books' }
- *   → Home > Books > "Le Petit Prince"
- *
- *   Path: /books/:bookId/loans   meta: { entity: 'loans', parent: { entity: 'books', param: 'bookId' } }
- *   → Home > Books > "Le Petit Prince" > Loans
- *
- *   Path: /books/:bookId/loans/:id/edit   meta: { entity: 'loans', parent: { entity: 'books', param: 'bookId' } }
- *   → Home > Books > "Le Petit Prince" > Loans > "Loan #abc123"
+ *   Path: /books              → [{ kind: 'entity-list', entity: 'books' }]
+ *   Path: /books/1/edit       → [{ kind: 'entity-list', entity: 'books' }, { kind: 'entity-edit', entity: 'books', id: '1' }]
+ *   Path: /books/stats        → [{ kind: 'entity-list', entity: 'books' }, { kind: 'route', route: 'book-stats' }]
  */
 import { ref, computed, watch, inject } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { getSiblingRoutes } from '../module/moduleRegistry.js'
-
-// Action segments that don't appear in breadcrumb
-const ACTION_SEGMENTS = ['edit', 'create', 'new', 'show', 'view', 'delete']
+import { useSemanticBreadcrumb } from './useSemanticBreadcrumb.js'
 
 export function useNavContext(options = {}) {
   const route = useRoute()
   const router = useRouter()
 
+  // Semantic breadcrumb as source of truth
+  const { breadcrumb: semanticBreadcrumb } = useSemanticBreadcrumb()
+
   // Injected dependencies
   const orchestrator = inject('qdadmOrchestrator', null)
   const homeRouteName = inject('qdadmHomeRoute', null)
@@ -48,9 +38,6 @@ export function useNavContext(options = {}) {
   // or injected from parent (for child pages)
   const breadcrumbEntities = options.breadcrumbEntities ?? inject('qdadmBreadcrumbEntities', null)
 
-  // Entity data cache
-  const entityDataCache = ref(new Map())
-
   function getManager(entityName) {
     return orchestrator?.get(entityName)
   }
@@ -59,122 +46,53 @@ export function useNavContext(options = {}) {
     return router.getRoutes().some(r => r.name === name)
   }
 
-  // ============================================================================
-  // PATH PATTERN ANALYSIS
-  // ============================================================================
-
-  /**
-   * Parse route path pattern into typed segments
-   *
-   * Input: '/books/:bookId/loans/:id/edit'
-   * Output: [
-   *   { type: 'static', value: 'books' },
-   *   { type: 'param', value: 'bookId' },
-   *   { type: 'static', value: 'loans' },
-   *   { type: 'param', value: 'id' },
-   *   { type: 'action', value: 'edit' }
-   * ]
-   */
-  function parsePathPattern(pathPattern) {
-    const segments = []
-    const parts = pathPattern.split('/').filter(Boolean)
-
-    for (const part of parts) {
-      if (part.startsWith(':')) {
-        // Param segment: :id, :bookId
-        segments.push({ type: 'param', value: part.slice(1) })
-      } else if (ACTION_SEGMENTS.includes(part.toLowerCase())) {
-        // Action segment: edit, create, show
-        segments.push({ type: 'action', value: part })
-      } else {
-        // Static segment: books, loans
-        segments.push({ type: 'static', value: part })
-      }
-    }
-
-    return segments
-  }
-
   /**
-   * Build navigation chain from parsed path segments + route meta
-   *
-   * Uses route meta to know which entity each static segment represents.
-   * The meta.parent chain declares the entity hierarchy.
+   * Convert semantic breadcrumb to navigation chain format
+   * Maps semantic kinds to chain types for compatibility
    */
-  function buildNavChain(pathSegments, routeMeta, routeParams) {
+  function semanticToNavChain(semantic) {
     const chain = []
-    const meta = routeMeta || {}
-
-    // Collect all entities in the hierarchy (parent chain + current)
-    const entityHierarchy = []
-
-    // Build parent chain (oldest ancestor first)
-    function collectParents(parentConfig) {
-      if (!parentConfig) return
-      const parentManager = getManager(parentConfig.entity)
-      if (!parentManager) return
-
-      // Check if this parent has its own parent
-      const parentRoute = router.getRoutes().find(r =>
-        r.name === `${parentManager.routePrefix}-edit`
-      )
-      if (parentRoute?.meta?.parent) {
-        collectParents(parentRoute.meta.parent)
-      }
-
-      entityHierarchy.push({
-        entity: parentConfig.entity,
-        manager: parentManager,
-        idParam: parentConfig.param
-      })
-    }
-
-    collectParents(meta.parent)
 
-    // Add current entity
-    if (meta.entity) {
-      const currentManager = getManager(meta.entity)
-      if (currentManager) {
-        entityHierarchy.push({
-          entity: meta.entity,
-          manager: currentManager,
-          idParam: 'id'  // Standard param for current entity
+    for (const item of semantic) {
+      if (item.kind === 'entity-list') {
+        const manager = getManager(item.entity)
+        chain.push({
+          type: 'list',
+          entity: item.entity,
+          manager,
+          label: manager?.labelPlural || item.entity,
+          routeName: manager?.routePrefix || item.entity.slice(0, -1)
         })
-      }
-    }
-
-    // Now build chain from hierarchy
-    for (const { entity, manager, idParam } of entityHierarchy) {
-      const entityId = routeParams[idParam]
-
-      // Add list segment
-      chain.push({
-        type: 'list',
-        entity,
-        manager,
-        label: manager.labelPlural || manager.name,
-        routeName: manager.routePrefix
-      })
-
-      // Add item segment if we have an ID for this entity
-      if (entityId) {
+      } else if (item.kind.startsWith('entity-') && item.id) {
+        // entity-show, entity-edit, entity-delete
+        const manager = getManager(item.entity)
         chain.push({
           type: 'item',
-          entity,
+          entity: item.entity,
           manager,
-          id: entityId,
-          routeName: `${manager.routePrefix}-edit`
+          id: item.id,
+          routeName: manager ? `${manager.routePrefix}-edit` : null
+        })
+      } else if (item.kind === 'entity-create') {
+        // Create page - treat as special list
+        const manager = getManager(item.entity)
+        chain.push({
+          type: 'create',
+          entity: item.entity,
+          manager,
+          label: 'Create',
+          routeName: manager ? `${manager.routePrefix}-create` : null
+        })
+      } else if (item.kind === 'route') {
+        // Generic route (like /books/stats)
+        // Use label from semantic item if provided (custom breadcrumb), else lookup route
+        const routeRecord = router.getRoutes().find(r => r.name === item.route)
+        chain.push({
+          type: 'route',
+          route: item.route,
+          label: item.label || routeRecord?.meta?.navLabel || routeRecord?.meta?.title || item.route,
+          routeName: item.route
         })
-      }
-    }
-
-    // Handle child-list case: when on a child route without :id
-    // The last segment is a child-list, not a regular list
-    if (meta.parent && !routeParams.id && chain.length > 0) {
-      const lastSegment = chain[chain.length - 1]
-      if (lastSegment.type === 'list') {
-        lastSegment.type = 'child-list'
-        lastSegment.navLabel = meta.navLabel
       }
     }
 
@@ -186,23 +104,10 @@ export function useNavContext(options = {}) {
   // ============================================================================
 
   /**
-   * Parsed path segments from current route
-   */
-  const pathSegments = computed(() => {
-    // Get the matched route's path pattern
-    const matched = route.matched
-    if (!matched.length) return []
-
-    // Use the last matched route's full path
-    const lastMatch = matched[matched.length - 1]
-    return parsePathPattern(lastMatch.path)
-  })
-
-  /**
-   * Navigation chain built from path analysis
+   * Navigation chain built from semantic breadcrumb
    */
   const navChain = computed(() => {
-    return buildNavChain(pathSegments.value, route.meta, route.params)
+    return semanticToNavChain(semanticBreadcrumb.value)
   })
 
   // ============================================================================
@@ -293,15 +198,25 @@ export function useNavContext(options = {}) {
       if (segment.type === 'list') {
         items.push({
           label: segment.label,
-          to: { name: segment.routeName }
+          to: isLast ? null : (segment.routeName && routeExists(segment.routeName) ? { name: segment.routeName } : null)
         })
       } else if (segment.type === 'item') {
         const data = chainData.value.get(i)
-        const label = data ? segment.manager.getEntityLabel(data) : '...'
+        const label = data && segment.manager ? segment.manager.getEntityLabel(data) : '...'
 
         items.push({
           label,
-          to: isLast ? null : { name: segment.routeName, params: { id: segment.id } }
+          to: isLast ? null : (segment.routeName && routeExists(segment.routeName) ? { name: segment.routeName, params: { id: segment.id } } : null)
+        })
+      } else if (segment.type === 'create') {
+        items.push({
+          label: segment.label
+        })
+      } else if (segment.type === 'route') {
+        // Generic route (e.g., /books/stats)
+        items.push({
+          label: segment.label,
+          to: isLast ? null : (segment.routeName && routeExists(segment.routeName) ? { name: segment.routeName } : null)
         })
       } else if (segment.type === 'child-list') {
         items.push({
@@ -383,8 +298,8 @@ export function useNavContext(options = {}) {
 
   return {
     // Analysis
-    pathSegments,
     navChain,
+    semanticBreadcrumb,
 
     // Data
     entityData,

package/src/composables/useNavigation.js

@@ -11,7 +11,8 @@
 
 import { computed, inject, ref, onMounted } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { getNavSections, isRouteInFamily, alterMenuSections, isMenuAltered } from '../module/moduleRegistry'
+import { getNavSections, alterMenuSections, isMenuAltered } from '../module/moduleRegistry'
+import { useSemanticBreadcrumb } from './useSemanticBreadcrumb'
 
 /**
  * Navigation composable
@@ -31,6 +32,9 @@ export function useNavigation() {
   const orchestrator = inject('qdadmOrchestrator', null)
   const hooks = inject('qdadmHooks', null)
 
+  // Semantic breadcrumb for entity-based active detection
+  const { breadcrumb } = useSemanticBreadcrumb()
+
   // Track whether menu:alter has completed
   const isReady = ref(isMenuAltered())
 
@@ -74,17 +78,29 @@ export function useNavigation() {
 
   /**
    * Check if a nav item is currently active
+   * Uses semantic breadcrumb only - no route segment deduction
    */
   function isNavActive(item) {
-    const currentRouteName = route.name
-
     // Exact match mode
     if (item.exact) {
-      return currentRouteName === item.route
+      return route.name === item.route
+    }
+
+    // Check semantic breadcrumb for match
+    const bc = breadcrumb.value
+
+    // Entity-based menu item: match ONLY by entity (don't fall through)
+    if (item.entity) {
+      const firstEntityItem = bc.find(b => b.kind.startsWith('entity-'))
+      return firstEntityItem ? firstEntityItem.entity === item.entity : false
+    }
+
+    // Route-based menu item: check if route is in breadcrumb
+    if (item.route) {
+      return bc.some(b => b.kind === 'route' && b.route === item.route)
     }
 
-    // Use registry's family detection
-    return isRouteInFamily(currentRouteName, item.route)
+    return false
   }
 
   /**

package/src/composables/useSemanticBreadcrumb.js

@@ -0,0 +1,182 @@
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+/**
+ * Action segments mapping to entity kinds
+ */
+const ACTION_MAP = {
+  edit: 'entity-edit',
+  create: 'entity-create',
+  new: 'entity-create',
+  show: 'entity-show',
+  view: 'entity-show',
+  delete: 'entity-delete'
+}
+
+/**
+ * Compute semantic breadcrumb from route path and routes list
+ *
+ * Pure function that can be used both in Vue composables and outside components.
+ *
+ * If the matched route has `meta.breadcrumb`, that array is used directly.
+ * This allows routes to define a custom breadcrumb structure.
+ *
+ * @param {string} path - Current route path (e.g., '/books/1/edit')
+ * @param {Array} routes - List of all registered routes from router.getRoutes()
+ * @param {object} [currentRoute] - Current route object (optional, for meta.breadcrumb support)
+ * @returns {Array} Semantic breadcrumb items
+ */
+export function computeSemanticBreadcrumb(path, routes, currentRoute = null) {
+  if (!path) return []
+
+  // Check if route defines a custom breadcrumb
+  if (currentRoute?.meta?.breadcrumb) {
+    return currentRoute.meta.breadcrumb
+  }
+
+  const items = []
+
+  // Filter out catch-all and not-found routes
+  const validRoutes = routes.filter(r =>
+    r.name !== 'not-found' &&
+    !r.path.includes('*') &&
+    !r.path.includes(':pathMatch')
+  )
+
+  // Note: Home is NOT included in semantic breadcrumb
+  // It's a display concern - add it in useBreadcrumb if needed
+
+  const segments = path.split('/').filter(Boolean)
+  let currentPath = ''
+  let lastEntity = null
+  let pendingId = null // Track unmatched segments that could be IDs
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i]
+    const nextSegment = segments[i + 1]
+    currentPath += `/${segment}`
+
+    // Check if this is an action segment
+    const actionKind = ACTION_MAP[segment.toLowerCase()]
+    if (actionKind && lastEntity) {
+      // If we have a pending ID, add a new entity item with action kind
+      if (pendingId) {
+        items.push({ kind: actionKind, entity: lastEntity, id: pendingId })
+        pendingId = null
+      } else {
+        // No pending ID - update last item's kind (e.g., /books/create)
+        const lastItem = items[items.length - 1]
+        if (lastItem && lastItem.kind.startsWith('entity-') && !lastItem.id) {
+          lastItem.kind = actionKind
+        }
+      }
+      continue
+    }
+
+    // Find matching route
+    const matchedRoute = validRoutes.find(r => {
+      if (r.path === currentPath) return true
+      const routeSegs = r.path.split('/').filter(Boolean)
+      const pathSegs = currentPath.split('/').filter(Boolean)
+      if (routeSegs.length !== pathSegs.length) return false
+      return routeSegs.every((rs, idx) => rs.startsWith(':') || rs === pathSegs[idx])
+    })
+
+    if (!matchedRoute) {
+      // No route found - this segment could be an ID (e.g., /books/1 when route is /books/:id/edit)
+      if (lastEntity) {
+        pendingId = segment
+      }
+      continue
+    }
+
+    const entity = matchedRoute.meta?.entity || null
+    const isParam = matchedRoute.path.split('/').filter(Boolean).some((s, idx) => {
+      const pathSegs = currentPath.split('/').filter(Boolean)
+      return s.startsWith(':') && idx === pathSegs.length - 1
+    })
+
+    if (entity) {
+      lastEntity = entity
+      pendingId = null // Clear pending ID when we match a route
+      if (isParam) {
+        // Entity instance - get param value (the ID)
+        const paramValue = segment
+        // Determine kind based on next segment or route name
+        let kind = 'entity-show'
+        if (nextSegment && ACTION_MAP[nextSegment.toLowerCase()]) {
+          kind = ACTION_MAP[nextSegment.toLowerCase()]
+        } else if (matchedRoute.name?.includes('edit')) {
+          kind = 'entity-edit'
+        }
+        items.push({ kind, entity, id: paramValue })
+      } else {
+        // Entity list
+        items.push({ kind: 'entity-list', entity })
+      }
+    } else {
+      // Generic route
+      items.push({ kind: 'route', route: matchedRoute.name || segment })
+    }
+  }
+
+  return items
+}
+
+/**
+ * useSemanticBreadcrumb - Vue composable for semantic breadcrumb
+ *
+ * Returns semantic objects per level - adapters resolve labels/paths for display.
+ *
+ * Kinds:
+ * - route: Generic route (e.g., home, dashboard)
+ * - entity-list: Entity collection (e.g., /books)
+ * - entity-show: Entity instance view (e.g., /books/1)
+ * - entity-edit: Entity instance edit (e.g., /books/1/edit)
+ * - entity-create: Entity creation (e.g., /books/create)
+ *
+ * @example
+ * const { breadcrumb } = useSemanticBreadcrumb()
+ * // For /books/1/edit returns:
+ * // [
+ * //   { kind: 'route', route: 'home' },
+ * //   { kind: 'entity-list', entity: 'books' },
+ * //   { kind: 'entity-edit', entity: 'books', id: '1' }
+ * // ]
+ */
+export function useSemanticBreadcrumb() {
+  const route = useRoute()
+  const router = useRouter()
+
+  const breadcrumb = computed(() => {
+    return computeSemanticBreadcrumb(route.path, router.getRoutes(), route)
+  })
+
+  /**
+   * Check if an entity is active (present in current breadcrumb)
+   * Useful for menu highlighting
+   *
+   * @param {string} entity - Entity name to check
+   * @returns {boolean}
+   */
+  function isEntityActive(entity) {
+    return breadcrumb.value.some(item =>
+      item.kind.startsWith('entity-') && item.entity === entity
+    )
+  }
+
+  /**
+   * Get the active entity from breadcrumb (first entity found)
+   * @returns {string|null}
+   */
+  const activeEntity = computed(() => {
+    const entityItem = breadcrumb.value.find(item => item.kind.startsWith('entity-'))
+    return entityItem?.entity || null
+  })
+
+  return {
+    breadcrumb,
+    isEntityActive,
+    activeEntity
+  }
+}

package/src/debug/DebugModule.js

@@ -27,6 +27,7 @@ import { ToastCollector } from './ToastCollector.js'
 import { ZonesCollector } from './ZonesCollector.js'
 import { AuthCollector } from './AuthCollector.js'
 import { EntitiesCollector } from './EntitiesCollector.js'
+import { RouterCollector } from './RouterCollector.js'
 import DebugBar from './components/DebugBar.vue'
 
 /**
@@ -92,6 +93,7 @@ export class DebugModule extends Module {
    * @param {boolean} [options.zonesCollector=true] - Include ZonesCollector
    * @param {boolean} [options.authCollector=true] - Include AuthCollector
    * @param {boolean} [options.entitiesCollector=true] - Include EntitiesCollector
+   * @param {boolean} [options.routerCollector=true] - Include RouterCollector
    */
   constructor(options = {}) {
     super(options)
@@ -155,6 +157,10 @@ export class DebugModule extends Module {
       this._bridge.addCollector(new EntitiesCollector(collectorOptions))
     }
 
+    if (this.options.routerCollector !== false) {
+      this._bridge.addCollector(new RouterCollector(collectorOptions))
+    }
+
     // Install collectors with context
     this._bridge.install(ctx)