qdadm 0.51.8 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.51.8",
+  "version": "0.52.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",

package/src/chain/ActiveStack.js

@@ -0,0 +1,75 @@
+/**
+ * ActiveStack - Reactive container for the active navigation stack
+ *
+ * Simple container rebuilt from route by useActiveStack.
+ * Each level: { entity, id, data, label }
+ *
+ * @example
+ * // Route /books/123/loans → Stack:
+ * [
+ *   { entity: 'books', id: '123', data: null, label: 'Books' },
+ *   { entity: 'loans', id: null, data: null, label: 'Loans' }
+ * ]
+ */
+
+import { ref, computed } from 'vue'
+
+export class ActiveStack {
+  constructor() {
+    this._stack = ref([])
+  }
+
+  /**
+   * Replace entire stack (called on route change)
+   */
+  set(levels) {
+    this._stack.value = levels
+  }
+
+  /**
+   * Update a level's data and label
+   */
+  updateLevel(index, data, label) {
+    if (index < 0 || index >= this._stack.value.length) return
+    const newStack = [...this._stack.value]
+    newStack[index] = { ...newStack[index], data, label }
+    this._stack.value = newStack
+  }
+
+  /**
+   * Find and update level by entity name
+   */
+  updateByEntity(entity, data, label) {
+    const index = this._stack.value.findIndex(l => l.entity === entity)
+    if (index !== -1) {
+      this.updateLevel(index, data, label)
+    }
+  }
+
+  clear() {
+    this._stack.value = []
+  }
+
+  // Computed accessors
+  get levels() {
+    return computed(() => this._stack.value)
+  }
+
+  get current() {
+    return computed(() => this._stack.value.at(-1) || null)
+  }
+
+  get parent() {
+    return computed(() => this._stack.value.at(-2) || null)
+  }
+
+  get root() {
+    return computed(() => this._stack.value[0] || null)
+  }
+
+  get depth() {
+    return computed(() => this._stack.value.length)
+  }
+}
+
+export default ActiveStack

package/src/chain/index.js

@@ -0,0 +1,12 @@
+/**
+ * Chain Module - Active navigation stack management
+ *
+ * Provides:
+ * - ActiveStack: Reactive container for current navigation stack
+ * - useActiveStack: Composable to build and access the stack
+ *
+ * @module chain
+ */
+
+export { ActiveStack } from './ActiveStack.js'
+export { useActiveStack } from './useActiveStack.js'

package/src/chain/useActiveStack.js

@@ -0,0 +1,135 @@
+/**
+ * useActiveStack - Build navigation stack from route
+ *
+ * The route is the single source of truth:
+ * - route.meta.entity → current entity
+ * - route.meta.parent → parent chain config
+ * - route.params → entity IDs
+ *
+ * Stack is rebuilt on every route change. Data is set by pages when they load.
+ */
+
+import { watch, inject, computed } from 'vue'
+import { useRoute } from 'vue-router'
+
+export function useActiveStack() {
+  const route = useRoute()
+  const activeStack = inject('qdadmActiveStack')
+  const orchestrator = inject('qdadmOrchestrator')
+
+  if (!activeStack) {
+    console.warn('[useActiveStack] ActiveStack not provided')
+    return createEmptyStack()
+  }
+
+  /**
+   * Build stack from current route
+   * Traverses route.meta.parent chain to build all levels
+   */
+  function rebuildStack() {
+    const entity = route.meta?.entity
+    if (!entity) {
+      activeStack.clear()
+      return
+    }
+
+    const levels = []
+    const manager = orchestrator?.get(entity)
+
+    // Build parent chain from route.meta.parent (traverse nested parents)
+    let parentConfig = route.meta?.parent
+    const parentLevels = []
+
+    while (parentConfig) {
+      const parentManager = orchestrator?.get(parentConfig.entity)
+      const id = route.params[parentConfig.param] || null
+
+      parentLevels.unshift({
+        entity: parentConfig.entity,
+        id,
+        data: null,
+        label: parentManager?.labelPlural || parentConfig.entity
+      })
+
+      // Traverse nested parent config (NOT manager.parent)
+      parentConfig = parentConfig.parent || null
+    }
+
+    levels.push(...parentLevels)
+
+    // Add current entity
+    const idField = manager?.idField || 'id'
+    const currentId = route.params[idField] || null
+
+    levels.push({
+      entity,
+      id: currentId,
+      data: null,
+      label: manager?.labelPlural || entity
+    })
+
+    activeStack.set(levels)
+  }
+
+  /**
+   * Set data for current level (called by useEntityItemPage/useForm)
+   */
+  function setCurrentData(data) {
+    const levels = activeStack.levels.value
+    if (levels.length === 0) return
+
+    const index = levels.length - 1
+    const level = levels[index]
+    const manager = orchestrator?.get(level.entity)
+    const label = manager?.getEntityLabel?.(data) || level.label
+
+    activeStack.updateLevel(index, data, label)
+  }
+
+  /**
+   * Set data for a level by entity name
+   */
+  function setEntityData(entity, data) {
+    const manager = orchestrator?.get(entity)
+    const label = manager?.getEntityLabel?.(data) || entity
+
+    activeStack.updateByEntity(entity, data, label)
+  }
+
+  // Rebuild stack on route change
+  watch(() => route.fullPath, rebuildStack, { immediate: true })
+
+  return {
+    // Computed refs from ActiveStack
+    levels: activeStack.levels,
+    current: activeStack.current,
+    parent: activeStack.parent,
+    root: activeStack.root,
+    depth: activeStack.depth,
+
+    // Data setters (called by pages)
+    setCurrentData,
+    setEntityData,
+
+    // Manual rebuild
+    rebuild: rebuildStack
+  }
+}
+
+/**
+ * Fallback when ActiveStack not available
+ */
+function createEmptyStack() {
+  return {
+    levels: computed(() => []),
+    current: computed(() => null),
+    parent: computed(() => null),
+    root: computed(() => null),
+    depth: computed(() => 0),
+    setCurrentData: () => {},
+    setEntityData: () => {},
+    rebuild: () => {}
+  }
+}
+
+export default useActiveStack

package/src/components/layout/AppLayout.vue

@@ -159,35 +159,16 @@ function handleLogout() {
 const slots = useSlots()
 const hasSlotContent = computed(() => !!slots.default)
 
-// Breadcrumb entity data - multi-level support for parent/child entities
-// Map: level -> entityData (level 1 = parent, level 2 = child, etc.)
-const breadcrumbEntities = ref(new Map())
-
-/**
- * Set entity data for breadcrumb at a specific level
- * @param {object} data - Entity data
- * @param {number} level - Breadcrumb level (1 = main entity, 2 = child, etc.)
- */
-function setBreadcrumbEntity(data, level = 1) {
-  const newMap = new Map(breadcrumbEntities.value)
-  newMap.set(level, data)
-  breadcrumbEntities.value = newMap
-}
-
-provide('qdadmSetBreadcrumbEntity', setBreadcrumbEntity)
-provide('qdadmBreadcrumbEntities', breadcrumbEntities)
-
-// Clear entity data and overrides on route change (before new page mounts)
+// Clear overrides on route change (before new page mounts)
 // This ensures list pages get default breadcrumb, detail pages can override via PageNav
 watch(() => route.fullPath, () => {
-  breadcrumbEntities.value = new Map()
   breadcrumbOverride.value = null
   navlinksOverride.value = null
 })
 
 // Navigation context (breadcrumb + navlinks from route config)
-// Pass breadcrumbEntities directly since we're in the same component that provides it
-const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks } = useNavContext({ breadcrumbEntities })
+// Entity data comes from activeStack (populated by useEntityItemPage/useForm)
+const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks } = useNavContext()
 
 // Allow child pages to override breadcrumb/navlinks via provide/inject
 const breadcrumbOverride = ref(null)

package/src/components/layout/PageNav.vue

@@ -1,150 +1,49 @@
 <script setup>
 /**
- * PageNav - Route-aware navigation provider for breadcrumb + navlinks
+ * PageNav - Navigation provider for navlinks (child/sibling routes)
  *
- * This component doesn't render anything visible. Instead, it provides
- * breadcrumb items and navlinks to AppLayout via provide/inject.
+ * This component provides navlinks to AppLayout via provide/inject.
+ * Breadcrumb is now handled automatically by useNavContext + activeStack.
  *
  * Layout (rendered in AppLayout):
  *   Books > "Dune"                    Details | Loans | Reviews
- *     ↑ breadcrumb (left)                   ↑ navlinks (right)
+ *     ↑ breadcrumb (from useNavContext)      ↑ navlinks (from PageNav)
  *
  * Auto-detects from current route:
- * - Breadcrumb: parent chain from route.meta.parent
- * - Navlinks: sibling routes (same parent entity + param)
+ * - Navlinks: sibling routes (same parent entity + param) or children routes
  *
  * Props:
- * - entity: Current entity data (for dynamic labels in breadcrumb)
- * - parentEntity: Parent entity data (for parent label in breadcrumb)
+ * - showDetailsLink: Show "Details" link in navlinks (default: false)
  */
-import { computed, ref, watch, inject } from 'vue'
-import { useRoute, useRouter } from 'vue-router'
+import { computed, watch, inject } from 'vue'
+import { useRoute } from 'vue-router'
 import { getSiblingRoutes, getChildRoutes } from '../../module/moduleRegistry.js'
 import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
 
-// Inject override refs from AppLayout
-const breadcrumbOverride = inject('qdadmBreadcrumbOverride', null)
+// Inject override ref from AppLayout
 const navlinksOverride = inject('qdadmNavlinksOverride', null)
-const homeRouteName = inject('qdadmHomeRoute', null)
-// Entity data set by useEntityItemPage via setBreadcrumbEntity
-const breadcrumbEntities = inject('qdadmBreadcrumbEntities', null)
 
 const props = defineProps({
-  entity: { type: Object, default: null },
-  parentEntity: { type: Object, default: null },
   // Show "Details" link in navlinks (default: false since breadcrumb shows current page)
   showDetailsLink: { type: Boolean, default: false }
 })
 
 const route = useRoute()
-const router = useRouter()
 const { getManager } = useOrchestrator()
 
 // Parent config from route meta
 const parentConfig = computed(() => route.meta?.parent)
 
-// Parent entity data (loaded if not provided via prop)
-const parentData = ref(props.parentEntity)
-
-// Load parent entity if needed
-watch(() => [parentConfig.value, route.params], async () => {
-  if (!parentConfig.value || props.parentEntity) return
-
-  const { entity: parentEntityName, param } = parentConfig.value
-  const parentId = route.params[param]
-
-  if (parentEntityName && parentId) {
-    try {
-      const manager = getManager(parentEntityName)
-      if (manager) {
-        parentData.value = await manager.get(parentId)
-      }
-    } catch (e) {
-      console.warn('[PageNav] Failed to load parent entity:', e)
-    }
-  }
-}, { immediate: true })
-
-// Home breadcrumb item
-const homeItem = computed(() => {
-  if (!homeRouteName) return null
-  const routes = router.getRoutes()
-  if (!routes.some(r => r.name === homeRouteName)) return null
-  const label = homeRouteName === 'dashboard' ? 'Dashboard' : 'Home'
-  return { label, to: { name: homeRouteName }, icon: 'pi pi-home' }
-})
-
-// Build breadcrumb items
-const breadcrumbItems = computed(() => {
-  const items = []
-
-  // Always start with Home if configured
-  if (homeItem.value) {
-    items.push(homeItem.value)
-  }
-
-  if (!parentConfig.value) {
-    // No parent - use simple breadcrumb from entity
-    const entityName = route.meta?.entity
-    if (entityName) {
-      const manager = getManager(entityName)
-      if (manager) {
-        // Entity list link
-        items.push({
-          label: manager.labelPlural || manager.name,
-          to: { name: manager.routePrefix }
-        })
-
-        // If on detail page (has :id param), add current entity item
-        const entityId = route.params.id
-        if (entityId) {
-          // Get entity data from props or from breadcrumbEntities (set by useEntityItemPage)
-          const entityData = props.entity || breadcrumbEntities?.value?.get(1)
-          const entityLabel = entityData
-            ? manager.getEntityLabel(entityData)
-            : '...'
-          items.push({ label: entityLabel })
-        }
-      }
-    }
-    return items
-  }
-
-  // Has parent - build parent chain
-  const { entity: parentEntityName, param, itemRoute } = parentConfig.value
-  const parentId = route.params[param]
-  const parentManager = getManager(parentEntityName)
-
-  if (parentManager) {
-    // Parent list
-    items.push({
-      label: parentManager.labelPlural || parentManager.name,
-      to: { name: parentManager.routePrefix }
-    })
-
-    // Parent item (with label from data)
-    // Prefer breadcrumbEntities (set by useEntityItemPage) over local parentData
-    const parentEntityData = breadcrumbEntities?.value?.get(1) || parentData.value
-    const parentLabel = parentEntityData
-      ? parentManager.getEntityLabel(parentEntityData)
-      : '...'
-    const defaultSuffix = parentManager.readOnly ? '-show' : '-edit'
-    const parentRouteName = itemRoute || `${parentManager.routePrefix}${defaultSuffix}`
-
-    items.push({
-      label: parentLabel,
-      to: { name: parentRouteName, params: { id: parentId } }
-    })
-  }
-
-  // Current entity (last item, no link)
-  const currentLabel = route.meta?.navLabel
-  if (currentLabel) {
-    items.push({ label: currentLabel })
-  }
-
-  return items
-})
+/**
+ * Get default item route for an entity manager
+ * - Read-only entities: use -show suffix
+ * - Editable entities: use -edit suffix
+ */
+function getDefaultItemRoute(manager) {
+  if (!manager) return null
+  const suffix = manager.readOnly ? '-show' : '-edit'
+  return `${manager.routePrefix}${suffix}`
+}
 
 // Sibling navlinks (routes with same parent)
 const siblingNavlinks = computed(() => {
@@ -194,13 +93,15 @@ const childNavlinks = computed(() => {
 
   if (navRoutes.length === 0) return []
 
-  const entityId = route.params.id
+  // Get current entity's manager to determine idField
+  const currentManager = getManager(entityName)
+  const entityId = route.params[currentManager?.idField || 'id']
 
   // Build navlinks to child routes
   return navRoutes.map(childRoute => {
     const childManager = childRoute.meta?.entity ? getManager(childRoute.meta.entity) : null
     const label = childRoute.meta?.navLabel || childManager?.labelPlural || childRoute.name
-    const parentParam = childRoute.meta?.parent?.param || 'id'
+    const parentParam = childRoute.meta?.parent?.param || currentManager?.idField || 'id'
 
     return {
       label,
@@ -210,7 +111,7 @@ const childNavlinks = computed(() => {
   })
 })
 
-// Combined navlinks with "Details" link
+// Combined navlinks with optional "Details" link
 const allNavlinks = computed(() => {
   // Case 1: On a child route - show siblings + optional Details link to parent
   if (parentConfig.value) {
@@ -218,19 +119,18 @@ const allNavlinks = computed(() => {
     const parentId = route.params[param]
     const parentManager = getManager(parentEntityName)
 
-    if (!parentManager) return siblingNavlinks.value
+    // Guard: need valid manager and parentId to build links
+    if (!parentManager || !parentId) return []
 
     // Details link is optional since breadcrumb already shows parent
     if (props.showDetailsLink) {
-      const defaultSuffix = parentManager.readOnly ? '-show' : '-edit'
-      const parentRouteName = itemRoute || `${parentManager.routePrefix}${defaultSuffix}`
+      const parentRouteName = itemRoute || getDefaultItemRoute(parentManager)
       const isOnParentRoute = route.name === parentRouteName
 
       // Details link to parent item page
-      // CONVENTION: Entity item routes MUST use :id as param name (e.g., /books/:id)
       const detailsLink = {
         label: 'Details',
-        to: { name: parentRouteName, params: { id: parentId } },
+        to: { name: parentRouteName, params: { [parentManager.idField]: parentId } },
         active: isOnParentRoute
       }
 
@@ -257,26 +157,14 @@ const allNavlinks = computed(() => {
   return []
 })
 
-// Sync breadcrumb and navlinks to AppLayout via provide/inject
-// Watch computed values + route changes + entity data to ensure updates
-watch([breadcrumbItems, () => route.fullPath, breadcrumbEntities], ([items]) => {
-  if (breadcrumbOverride) {
-    breadcrumbOverride.value = items
-  }
-}, { immediate: true, deep: true })
-
+// Sync navlinks to AppLayout via provide/inject
 watch([allNavlinks, () => route.fullPath], ([links]) => {
   if (navlinksOverride) {
     navlinksOverride.value = links
   }
 }, { immediate: true })
-
-// Note: We intentionally do NOT clear overrides in onUnmounted.
-// When navigating between routes, the new PageNav's watch will overwrite the values.
-// Clearing in onUnmounted causes a race condition where the old PageNav clears
-// AFTER the new PageNav has already set its values.
 </script>
 
 <template>
-  <!-- PageNav provides data to AppLayout via inject, renders nothing -->
+  <!-- PageNav provides navlinks to AppLayout via inject, renders nothing -->
 </template>

package/src/composables/index.js

@@ -13,7 +13,6 @@ export { useListPage, PAGE_SIZE_OPTIONS } from './useListPage'
 export { usePageTitle } from './usePageTitle'
 export { useApp } from './useApp'
 export { useAuth } from './useAuth'
-export { useCurrentEntity } from './useCurrentEntity'
 export { useEntityItemPage } from './useEntityItemPage'
 export { useNavContext } from './useNavContext'
 export { useNavigation } from './useNavigation'

package/src/composables/useCurrentEntity.js

@@ -1,45 +1,40 @@
 /**
- * useCurrentEntity - Share page entity data with navigation context (breadcrumb)
+ * @deprecated Use useActiveStack() instead
  *
- * When a page loads an entity, it calls setBreadcrumbEntity() to share
- * the data with AppLayout for breadcrumb display.
+ * Legacy composable for setting breadcrumb entity data.
+ * This has been replaced by the activeStack system.
  *
- * Usage in a detail page:
+ * Migration:
  * ```js
+ * // Before (deprecated)
  * const { setBreadcrumbEntity } = useCurrentEntity()
+ * setBreadcrumbEntity(data)
  *
- * async function loadProduct() {
- *   product.value = await productsManager.get(productId)
- *   setBreadcrumbEntity(product.value)  // Level 1 (main entity)
- * }
- * ```
- *
- * For nested routes with parent/child entities:
- * ```js
- * // Parent page loaded first
- * setBreadcrumbEntity(book, 1)  // Level 1: the book
- *
- * // Child page
- * setBreadcrumbEntity(loan, 2)  // Level 2: the loan under the book
+ * // After
+ * const stack = useActiveStack()
+ * stack.setCurrentData(data)
  * ```
  */
-import { inject } from 'vue'
+import { useActiveStack } from '../chain/useActiveStack.js'
 
 /**
- * Composable to share page entity data with breadcrumb
- * @returns {{ setBreadcrumbEntity: (data: object, level?: number) => void }}
+ * @deprecated Use useActiveStack() instead
  */
 export function useCurrentEntity() {
-  const setBreadcrumbEntityFn = inject('qdadmSetBreadcrumbEntity', null)
+  console.warn('[qdadm] useCurrentEntity is deprecated. Use useActiveStack() instead.')
+
+  const stack = useActiveStack()
 
   /**
-   * Set entity data for breadcrumb at a specific level
-   * @param {object} data - Entity data
-   * @param {number} level - Breadcrumb level (1 = main entity, 2 = child, etc.)
+   * @deprecated Use stack.setCurrentData() instead
    */
   function setBreadcrumbEntity(data, level = 1) {
-    if (setBreadcrumbEntityFn) {
-      setBreadcrumbEntityFn(data, level)
+    if (level === 1) {
+      stack.setCurrentData(data)
+    } else {
+      // For parent levels, use setEntityData with entity name
+      // But we don't have entity name here - just set current
+      stack.setCurrentData(data)
     }
   }
 
@@ -48,6 +43,6 @@ export function useCurrentEntity() {
 
   return {
     setBreadcrumbEntity,
-    setCurrentEntity  // deprecated alias
+    setCurrentEntity
   }
 }

package/src/composables/useEntityItemFormPage.js

@@ -121,15 +121,14 @@ export function useEntityItemFormPage(config = {}) {
   const confirm = useConfirm()
 
   // Use useEntityItemPage for common infrastructure
-  // (orchestrator, manager, entityId, provide('mainEntity'), breadcrumb)
+  // (orchestrator, manager, entityId, provide('mainEntity'), stack)
   const itemPage = useEntityItemPage({
     entity,
     loadOnMount: false,  // Form controls its own loading
-    breadcrumb: false,   // Form calls setBreadcrumbEntity manually after transform
     getId
   })
 
-  const { manager, orchestrator, entityId, setBreadcrumbEntity, getInitialDataWithParent, parentConfig, parentId, parentData, parentChain, getChainDepth } = itemPage
+  const { manager, orchestrator, entityId, getInitialDataWithParent, parentConfig, parentId, parentData, parentChain, getChainDepth, stack } = itemPage
 
   // Read config from manager with option overrides
   const entityName = config.entityName ?? manager.label
@@ -251,8 +250,8 @@ export function useEntityItemFormPage(config = {}) {
       originalData.value = deepClone(transformed)
       takeSnapshot()
 
-      // Share with navigation context for breadcrumb
-      setBreadcrumbEntity(transformed)
+      // Update active stack
+      stack.setCurrentData(transformed)
 
       if (onLoadSuccess) {
         await onLoadSuccess(transformed)
@@ -328,14 +327,14 @@ export function useEntityItemFormPage(config = {}) {
         router.push(listRoute)
       } else if (!isEdit.value) {
         // "Create" without close: navigate to edit route for the created entity
-        const createdId = responseData?.id || responseData?.uuid
+        const createdId = responseData?.[manager.idField]
         if (createdId) {
-          // Build edit route: replace 'create' suffix with ':id/edit'
+          // Build edit route: replace 'create' suffix with 'edit'
           const currentRouteName = route.name || ''
           const editRouteName = currentRouteName.replace(/(-create|-new)$/, '-edit')
           router.push({
             name: editRouteName,
-            params: { ...route.params, id: createdId }
+            params: { ...route.params, [manager.idField]: createdId }
           })
         }
       }
@@ -1290,7 +1289,10 @@ export function useEntityItemFormPage(config = {}) {
 
     // FormPage integration
     props: formProps,
-    events: formEvents
+    events: formEvents,
+
+    // Active navigation stack (unified context)
+    stack
   }
 
   // Auto-generate fields from manager schema if enabled

package/src/composables/useEntityItemPage.js

@@ -4,7 +4,7 @@
  * Provides common functionality for pages that display a single entity:
  * - Entity loading by ID from route params
  * - Loading/error state management
- * - Breadcrumb integration (auto-calls setBreadcrumbEntity)
+ * - Active stack integration (auto-updates navigation context)
  * - Manager access for child composables
  * - **Parent chain auto-detection** from route.meta.parent
  *
@@ -53,19 +53,17 @@
  */
 import { ref, computed, onMounted, inject, provide } from 'vue'
 import { useRoute } from 'vue-router'
-import { useCurrentEntity } from './useCurrentEntity.js'
+import { useActiveStack } from '../chain/useActiveStack.js'
 
 export function useEntityItemPage(config = {}) {
   const {
     entity,
     // Loading options
     loadOnMount = true,
-    breadcrumb = true,
     // Parent chain options
     autoLoadParent = true,  // Auto-load parent entity from route.meta.parent
-    // ID extraction
+    // ID extraction (custom function for special cases, otherwise uses manager.idField)
     getId = null,
-    idParam = 'id',
     // Transform hook
     transformLoad = (data) => data,
     // Callbacks
@@ -91,8 +89,8 @@ export function useEntityItemPage(config = {}) {
   // Provide entity context for child components
   provide('mainEntity', entity)
 
-  // Breadcrumb integration
-  const { setBreadcrumbEntity } = useCurrentEntity()
+  // Active stack integration (unified navigation context)
+  const stack = useActiveStack()
 
   // ============ STATE ============
 
@@ -186,14 +184,8 @@ export function useEntityItemPage(config = {}) {
         if (data) {
           newChain.set(level, data)
 
-          // Set breadcrumb at correct level
-          // breadcrumbLevel = totalDepth - level (so immediate parent is totalDepth-1, grandparent is totalDepth-2, etc.)
-          // Actually we want: root ancestor = 1, next = 2, ..., immediate parent = totalDepth-1, current = totalDepth
-          // So breadcrumbLevel = totalDepth - level
-          if (breadcrumb) {
-            const breadcrumbLevel = totalDepth - level
-            setBreadcrumbEntity(data, breadcrumbLevel)
-          }
+          // Update active stack
+          stack.setEntityData(currentConfig.entity, data)
         }
 
         currentConfig = currentConfig.parent
@@ -233,11 +225,13 @@ export function useEntityItemPage(config = {}) {
 
   /**
    * Extract entity ID from route params
-   * Supports custom getId function or param name
+   * Uses manager.idField as route param name (single source of truth)
+   * Supports custom getId function for special cases
    */
   const entityId = computed(() => {
     if (getId) return getId()
-    return route.params[idParam] || route.params.id || route.params.key || null
+    // Use manager.idField as route param name, with fallbacks for common patterns
+    return route.params[manager.idField] || route.params.id || route.params.key || null
   })
 
   // ============ LOADING ============
@@ -267,12 +261,8 @@ export function useEntityItemPage(config = {}) {
       const transformed = transformLoad(responseData)
       data.value = transformed
 
-      // Share with navigation context for breadcrumb
-      // Level = depth of chain (1 if no parent, 2 if 1 parent, 3 if 2 parents, etc.)
-      if (breadcrumb) {
-        const level = getChainDepth()
-        setBreadcrumbEntity(transformed, level)
-      }
+      // Update active stack
+      stack.setCurrentData(transformed)
 
       if (onLoadSuccess) {
         await onLoadSuccess(transformed)
@@ -361,6 +351,8 @@ export function useEntityItemPage(config = {}) {
     // References (for parent composables)
     manager,
     orchestrator,
-    setBreadcrumbEntity
+
+    // Active navigation stack (unified context)
+    stack
   }
 }

package/src/composables/useForm.js

@@ -65,7 +65,7 @@
 import { ref, computed, watch, onMounted, inject, provide } from 'vue'
 import { useBareForm } from './useBareForm'
 import { useHooks } from './useHooks'
-import { useCurrentEntity } from './useCurrentEntity'
+import { useActiveStack } from '../chain/useActiveStack.js'
 import { deepClone } from '../utils/transformers'
 
 export function useForm(options = {}) {
@@ -94,8 +94,8 @@ export function useForm(options = {}) {
   // Get HookRegistry for form:alter hook (optional, may not exist in tests)
   const hooks = useHooks()
 
-  // Share entity data with navigation context (for breadcrumb)
-  const { setCurrentEntity } = useCurrentEntity()
+  // Active stack for navigation context
+  const stack = useActiveStack()
 
   // Read config from manager with option overrides
   const routePrefix = options.routePrefix ?? manager.routePrefix
@@ -245,8 +245,8 @@ export function useForm(options = {}) {
       originalData.value = deepClone(data)
       takeSnapshot()
 
-      // Share with navigation context for breadcrumb
-      setCurrentEntity(data)
+      // Update active stack
+      stack.setCurrentData(data)
 
       // Invoke form:alter hooks after data is loaded
       await invokeFormAlterHook()
@@ -305,7 +305,7 @@ export function useForm(options = {}) {
         router.push({ name: routePrefix })
       } else if (!isEdit.value && redirectOnCreate) {
         // Redirect to edit mode after create
-        const newId = responseData.id || responseData.key
+        const newId = responseData[manager.idField]
         router.replace({ name: `${routePrefix}-edit`, params: { id: newId } })
       }
 

package/src/composables/useListPage.js

@@ -1249,11 +1249,11 @@ export function useListPage(config = {}) {
   }
 
   function goToEdit(item) {
-    router.push({ name: `${routePrefix}-edit`, params: { id: item[resolvedDataKey] } })
+    router.push({ name: `${routePrefix}-edit`, params: { [manager.idField]: item[resolvedDataKey] } })
   }
 
   function goToShow(item) {
-    router.push({ name: `${routePrefix}-show`, params: { id: item[resolvedDataKey] } })
+    router.push({ name: `${routePrefix}-show`, params: { [manager.idField]: item[resolvedDataKey] } })
   }
 
   // ============ DELETE ============

package/src/composables/useNavContext.js

@@ -2,7 +2,7 @@
  * useNavContext - Route-aware navigation context for breadcrumb and navlinks
  *
  * Uses semantic breadcrumb as the source of truth for navigation structure.
- * Semantic breadcrumb is computed from route path and registered routes.
+ * Entity data comes from activeStack (set by useEntityItemPage/useForm).
  *
  * Semantic breadcrumb kinds:
  *   - entity-list: Entity collection (e.g., /books)
@@ -20,6 +20,7 @@ import { ref, computed, watch, inject } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { getSiblingRoutes } from '../module/moduleRegistry.js'
 import { useSemanticBreadcrumb } from './useSemanticBreadcrumb.js'
+import { useActiveStack } from '../chain/useActiveStack.js'
 
 export function useNavContext(options = {}) {
   const route = useRoute()
@@ -32,11 +33,8 @@ export function useNavContext(options = {}) {
   const orchestrator = inject('qdadmOrchestrator', null)
   const homeRouteName = inject('qdadmHomeRoute', null)
 
-  // Breadcrumb entity data - multi-level Map from AppLayout
-  // Updated by pages via setBreadcrumbEntity(data, level)
-  // Can be passed directly (for layout component that provides AND uses breadcrumb)
-  // or injected from parent (for child pages)
-  const breadcrumbEntities = options.breadcrumbEntities ?? inject('qdadmBreadcrumbEntities', null)
+  // Active stack for entity data (replaces legacy breadcrumbEntities)
+  const stack = useActiveStack()
 
   function getManager(entityName) {
     return orchestrator?.get(entityName)
@@ -124,57 +122,35 @@ export function useNavContext(options = {}) {
   })
 
   // ============================================================================
-  // ENTITY DATA FETCHING
+  // ENTITY DATA FROM ACTIVESTACK
   // ============================================================================
 
   const chainData = ref(new Map())  // Map: chainIndex -> entityData
 
   /**
-   * Fetch entity data for all 'item' segments in the chain
+   * Build chainData from activeStack levels
    *
-   * For the LAST item (current entity):
-   * - Uses entityData if provided by the page via setCurrentEntity()
-   * - Does NOT fetch automatically - page is responsible for providing data
-   * - Breadcrumb shows "..." until page provides the data
-   *
-   * For PARENT items: always fetches from manager
+   * ActiveStack is populated by useEntityItemPage/useForm when pages load.
+   * Each level in the stack corresponds to an entity in the navigation chain.
    */
-  // Watch navChain and breadcrumbEntities to populate chainData
-  // breadcrumbEntities is a ref to Map: level -> entityData (set by pages via setBreadcrumbEntity)
-  // Note: watch ref directly, not () => ref.value, for proper reactivity tracking
-  watch([navChain, breadcrumbEntities], async ([chain, entitiesMap]) => {
-    // Build new Map (reassignment triggers Vue reactivity, Map.set() doesn't)
+  watch([navChain, stack.levels], ([chain, levels]) => {
+    // Build new Map (reassignment triggers Vue reactivity)
     const newChainData = new Map()
 
-    // Count item segments to determine their level (1-based)
-    let itemLevel = 0
+    // Count item segments to match with stack levels
+    let itemIndex = 0
 
     for (let i = 0; i < chain.length; i++) {
       const segment = chain[i]
       if (segment.type !== 'item') continue
 
-      itemLevel++
-      const isLastItem = !chain.slice(i + 1).some(s => s.type === 'item')
-
-      // Check if page provided data for this level via setBreadcrumbEntity
-      const providedData = entitiesMap?.get(itemLevel)
-      if (providedData) {
-        newChainData.set(i, providedData)
-        continue
+      // Find matching data in activeStack by entity name
+      const stackLevel = levels.find(l => l.entity === segment.entity && String(l.id) === String(segment.id))
+      if (stackLevel?.data) {
+        newChainData.set(i, stackLevel.data)
       }
 
-      // For items without provided data:
-      // - Last item: show "..." (page should call setBreadcrumbEntity)
-      // - Parent items: fetch from manager
-      if (!isLastItem) {
-        try {
-          const data = await segment.manager.get(segment.id)
-          newChainData.set(i, data)
-        } catch (e) {
-          console.warn(`[useNavContext] Failed to fetch ${segment.entity}:${segment.id}`, e)
-        }
-      }
-      // Last item without data will show "..." in breadcrumb
+      itemIndex++
     }
 
     // Assign new Map to trigger reactivity
@@ -216,10 +192,11 @@ export function useNavContext(options = {}) {
       } else if (segment.type === 'item') {
         const data = chainData.value.get(i)
         const label = data && segment.manager ? segment.manager.getEntityLabel(data) : '...'
+        const idField = segment.manager?.idField || 'id'
 
         items.push({
           label,
-          to: isLast ? null : (segment.routeName && routeExists(segment.routeName) ? { name: segment.routeName, params: { id: segment.id } } : null)
+          to: isLast ? null : (segment.routeName && routeExists(segment.routeName) ? { name: segment.routeName, params: { [idField]: segment.id } } : null)
         })
       } else if (segment.type === 'create') {
         items.push({
@@ -262,10 +239,10 @@ export function useNavContext(options = {}) {
     const parentRouteName = itemRoute || getDefaultItemRoute(parentManager)
     const isOnParent = route.name === parentRouteName
 
-    // Details link
+    // Details link - use manager's idField for param name
     const links = [{
       label: 'Details',
-      to: { name: parentRouteName, params: { id: parentId.value } },
+      to: { name: parentRouteName, params: { [parentManager.idField]: parentId.value } },
       active: isOnParent
     }]
 

package/src/entity/EntityManager.js

@@ -72,7 +72,9 @@ export class EntityManager {
       parents = {},       // { book: { entity: 'books', foreignKey: 'book_id' } } - multi-parent support
       relations = {},     // { groups: { entity: 'groups', through: 'user_groups' } }
       // Auth adapter (for permission checks)
-      authAdapter = null  // AuthAdapter instance or null (uses PermissiveAuthAdapter)
+      authAdapter = null,  // AuthAdapter instance or null (uses PermissiveAuthAdapter)
+      // Navigation config (for auto-generated menus)
+      nav = {}  // { icon, section, weight, visible }
     } = options
 
     this.name = name
@@ -110,6 +112,9 @@ export class EntityManager {
     // Auth adapter (fallback to permissive if not provided)
     this._authAdapter = authAdapter
 
+    // Navigation config (for auto-generated menus via ChainRegistry)
+    this._nav = nav
+
     // HookRegistry reference for lifecycle hooks (set by Orchestrator)
     this._hooks = null
 
@@ -415,6 +420,16 @@ export class EntityManager {
     return entity[this._labelField] || null
   }
 
+  /**
+   * Get navigation config for auto-generated menus
+   * Used by ChainRegistry to build nav sections
+   *
+   * @returns {object} Nav config { icon, section, weight, visible }
+   */
+  get nav() {
+    return this._nav || {}
+  }
+
   // ============ PERMISSIONS ============
 
   /**

package/src/index.js

@@ -38,6 +38,9 @@ export * from './module/index.js'
 // Zones
 export * from './zones/index.js'
 
+// Chain (active navigation stack)
+export * from './chain/index.js'
+
 // Hooks
 export * from './hooks/index.js'
 

package/src/kernel/Kernel.js

@@ -63,6 +63,7 @@ import { defaultStorageResolver } from '../entity/storage/factory.js'
 import { createDeferredRegistry } from '../deferred/DeferredRegistry.js'
 import { createEventRouter } from './EventRouter.js'
 import { createSSEBridge } from './SSEBridge.js'
+import { ActiveStack } from '../chain/ActiveStack.js'
 
 // Debug imports are dynamic to enable tree-shaking in production
 // When debugBar: false/undefined, no debug code is bundled
@@ -198,6 +199,7 @@ export class Kernel {
     this._createSignalBus()
     this._createHookRegistry()
     this._createZoneRegistry()
+    this._createActiveStack()
     this._createDeferredRegistry()
     // 2. Create orchestrator early (modules need it for ctx.entity())
     this._createOrchestrator()
@@ -248,6 +250,7 @@ export class Kernel {
     this._createSignalBus()
     this._createHookRegistry()
     this._createZoneRegistry()
+    this._createActiveStack()
     this._createDeferredRegistry()
     // 2. Create orchestrator early (modules need it for ctx.entity())
     this._createOrchestrator()
@@ -868,6 +871,14 @@ export class Kernel {
     this.zoneRegistry = createZoneRegistry({ debug })
   }
 
+  /**
+   * Create active stack for navigation state
+   * Holds the current stack of active items (entity, id, data, label).
+   */
+  _createActiveStack() {
+    this.activeStack = new ActiveStack()
+  }
+
   /**
    * Create deferred registry for async service loading
    * Enables loose coupling between services and components via named promises.
@@ -1040,6 +1051,9 @@ export class Kernel {
     // Zone registry injection
     app.provide('qdadmZoneRegistry', this.zoneRegistry)
 
+    // Active stack injection (for navigation context)
+    app.provide('qdadmActiveStack', this.activeStack)
+
     // Dev mode: expose qdadm services on window for DevTools inspection
     if (this.options.debug && typeof window !== 'undefined') {
       window.__qdadm = {
@@ -1048,6 +1062,7 @@ export class Kernel {
         signals: this.signals,
         hooks: this.hookRegistry,
         zones: this.zoneRegistry,
+        activeStack: this.activeStack,
         deferred: this.deferred,
         router: this.router,
         // Helper to get a manager quickly

package/src/kernel/KernelContext.js

@@ -25,7 +25,7 @@
  */
 
 import { managerFactory } from '../entity/factory.js'
-import { registry } from '../module/moduleRegistry.js'
+import { registry, getRoutes } from '../module/moduleRegistry.js'
 import { UsersManager } from '../security/UsersManager.js'
 
 export class KernelContext {
@@ -320,6 +320,7 @@ export class KernelContext {
    * Generates routes following qdadm conventions:
    * - Entity 'books' → route prefix 'book'
    * - List: /books → name 'book'
+   * - Show: /books/:id → name 'book-show' (optional)
    * - Create: /books/create → name 'book-create'
    * - Edit: /books/:id/edit → name 'book-edit'
    *
@@ -328,6 +329,7 @@ export class KernelContext {
    * @param {string} entity - Entity name (plural, e.g., 'books', 'users')
    * @param {object} pages - Page components (lazy imports)
    * @param {Function} pages.list - List page: () => import('./pages/List.vue')
+   * @param {Function} [pages.show] - Show page (read-only detail view)
    * @param {Function} [pages.form] - Single form for create+edit (recommended)
    * @param {Function} [pages.create] - Separate create page (alternative to form)
    * @param {Function} [pages.edit] - Separate edit page (alternative to form)
@@ -336,7 +338,10 @@ export class KernelContext {
    * @param {string} options.nav.section - Nav section (e.g., 'Library')
    * @param {string} [options.nav.icon] - Icon class (e.g., 'pi pi-book')
    * @param {string} [options.nav.label] - Display label (default: capitalized entity)
-   * @param {string} [options.routePrefix] - Override route prefix (default: singularized entity)
+   * @param {string} [options.routePrefix] - Override route prefix (default: singularized entity, or parentPrefix-singularized for children)
+   * @param {string} [options.parentRoute] - Parent route name for child entities (e.g., 'book' to mount under books/:bookId)
+   * @param {string} [options.foreignKey] - Foreign key field linking to parent (e.g., 'book_id')
+   * @param {string} [options.label] - Label for navlinks (defaults to entity labelPlural from manager)
    * @returns {this}
    *
    * @example
@@ -344,6 +349,13 @@ export class KernelContext {
    * ctx.crud('countries', { list: () => import('./pages/CountriesList.vue') })
    *
    * @example
+   * // List + show (read-only with detail view)
+   * ctx.crud('countries', {
+   *   list: () => import('./pages/CountriesList.vue'),
+   *   show: () => import('./pages/CountryShow.vue')
+   * })
+   *
+   * @example
    * // Single form pattern (recommended)
    * ctx.crud('books', {
    *   list: () => import('./pages/BookList.vue'),
@@ -353,6 +365,17 @@ export class KernelContext {
    * })
    *
    * @example
+   * // Child entity mounted under parent route
+   * ctx.crud('loans', {
+   *   list: () => import('./pages/BookLoans.vue'),
+   *   form: () => import('./pages/BookLoanForm.vue')
+   * }, {
+   *   parentRoute: 'book',
+   *   foreignKey: 'book_id',
+   *   routePrefix: 'book-loan'  // Optional: defaults to 'book-loan'
+   * })
+   *
+   * @example
    * // Separate create/edit pages
    * ctx.crud('users', {
    *   list: () => import('./pages/UserList.vue'),
@@ -363,18 +386,60 @@ export class KernelContext {
    * })
    */
   crud(entity, pages, options = {}) {
-    // Derive route prefix: 'books' → 'book', 'countries' → 'country'
-    const routePrefix = options.routePrefix || this._singularize(entity)
+    // Entity name is always used for permission binding
+    // Manager may not be registered yet (child entity before parent module loads)
+    const entityBinding = entity
+    const manager = this._kernel.orchestrator?.isRegistered(entity)
+      ? this._kernel.orchestrator.get(entity)
+      : null
+    const idParam = manager?.idField || 'id'
+
+    // Handle parent route configuration
+    let basePath = entity
+    let parentConfig = null
+    let parentRoutePrefix = null
+
+    if (options.parentRoute) {
+      // Find parent route info from registered routes
+      const parentRouteName = options.parentRoute
+      const allRoutes = getRoutes()
+      const parentRoute = allRoutes.find(r => r.name === parentRouteName)
+
+      if (parentRoute) {
+        // Get parent entity from route meta
+        const parentEntityName = parentRoute.meta?.entity
+        const parentManager = parentEntityName
+          ? this._kernel.orchestrator?.get(parentEntityName)
+          : null
+        const parentIdParam = parentManager?.idField || 'id'
+
+        // Build base path: parentPath/:parentId/entity
+        // e.g., books/:bookId/loans
+        const parentBasePath = parentRoute.path.replace(/\/(create|:.*)?$/, '') || parentEntityName
+        basePath = `${parentBasePath}/:${parentIdParam}/${entity}`
+
+        // Build parent config for route meta
+        parentConfig = {
+          entity: parentEntityName,
+          param: parentIdParam,
+          foreignKey: options.foreignKey || `${this._singularize(parentEntityName)}_id`
+        }
+
+        // Store parent route prefix for derived naming
+        parentRoutePrefix = parentRouteName
+      }
+    }
 
-    // Check if entity is actually registered in orchestrator (for permission binding)
-    // If not registered, don't bind entity to routes/nav (allows pure route registration)
-    const hasEntity = this._kernel.orchestrator?.isRegistered(entity) ?? false
-    const entityBinding = hasEntity ? entity : undefined
+    // Derive route prefix
+    // - With parent: 'book' + '-loan' → 'book-loan'
+    // - Without parent: 'books' → 'book'
+    const routePrefix = options.routePrefix
+      || (parentRoutePrefix ? `${parentRoutePrefix}-${this._singularize(entity)}` : this._singularize(entity))
 
     // Build routes array
     const routes = []
 
-    // List route (always required)
+    // List route
     if (pages.list) {
       routes.push({
         path: '',
@@ -384,6 +449,16 @@ export class KernelContext {
       })
     }
 
+    // Show route (read-only detail view)
+    if (pages.show) {
+      routes.push({
+        path: `:${idParam}`,
+        name: `${routePrefix}-show`,
+        component: pages.show,
+        meta: { layout: 'show' }
+      })
+    }
+
     // Form routes - single form or separate create/edit
     if (pages.form) {
       // Single form pattern (recommended)
@@ -393,7 +468,7 @@ export class KernelContext {
         component: pages.form
       })
       routes.push({
-        path: ':id/edit',
+        path: `:${idParam}/edit`,
         name: `${routePrefix}-edit`,
         component: pages.form
       })
@@ -408,21 +483,35 @@ export class KernelContext {
       }
       if (pages.edit) {
         routes.push({
-          path: ':id/edit',
+          path: `:${idParam}/edit`,
           name: `${routePrefix}-edit`,
           component: pages.edit
         })
       }
     }
 
-    // Register routes (with entity binding only if entity exists)
-    const routeOpts = entityBinding ? { entity: entityBinding } : {}
-    this.routes(entity, routes, routeOpts)
+    // Build route options
+    const routeOpts = {}
+    // Set entity if:
+    // 1. Entity is registered (manager exists), OR
+    // 2. This is a child route (parentConfig) - needs entity binding for permission checks
+    if (manager || parentConfig) {
+      routeOpts.entity = entityBinding
+    }
+    if (parentConfig) {
+      routeOpts.parent = parentConfig
+    }
+    if (options.label) {
+      routeOpts.label = options.label
+    }
+
+    // Register routes
+    this.routes(basePath, routes, routeOpts)
 
     // Register route family for active state detection
     this.routeFamily(routePrefix, [`${routePrefix}-`])
 
-    // Register nav item if provided
+    // Register nav item if provided (typically not for child entities)
     if (options.nav) {
       const label = options.nav.label || this._capitalize(entity)
       const navItem = {
@@ -431,7 +520,9 @@ export class KernelContext {
         icon: options.nav.icon,
         label
       }
-      if (entityBinding) {
+      // Only set entity on nav item if registered (to avoid permission check failure)
+      // Routes always get entity binding, but nav items need it to be resolvable
+      if (manager) {
         navItem.entity = entityBinding
       }
       this.navItem(navItem)

package/src/module/moduleRegistry.js

@@ -50,20 +50,13 @@ const registry = {
   /**
    * Add routes for this module
    *
-   * CONVENTION: Entity item routes MUST use :id as param name
-   * - List route: 'books' → /books
-   * - Item route: 'books/:id' → /books/:id (MUST be :id, not :bookId or :uuid)
-   * - Child route: 'books/:id/reviews' → parent.param = 'id'
-   *
-   * This convention is required for PageNav, breadcrumbs, and navigation to work correctly.
-   *
    * @param {string} prefix - Path prefix for all routes (e.g., 'books' or 'books/:id/reviews')
    * @param {Array} moduleRoutes - Route definitions with relative paths
    * @param {object} options - Route options
    * @param {string} [options.entity] - Entity name for permission checking
    * @param {object} [options.parent] - Parent entity config for child routes
    * @param {string} options.parent.entity - Parent entity name (e.g., 'books')
-   * @param {string} options.parent.param - Route param for parent ID (MUST be 'id')
+   * @param {string} options.parent.param - Route param for parent ID
    * @param {string} options.parent.foreignKey - Foreign key field (e.g., 'book_id')
    * @param {string} [options.parent.itemRoute] - Override parent item route (auto: parentEntity.routePrefix + '-edit')
    * @param {string} [options.label] - Label for navlinks (defaults to entity labelPlural)