qdadm 0.49.0 → 0.50.0

package/package.json

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

package/src/components/layout/AppLayout.vue

@@ -177,9 +177,12 @@ function setBreadcrumbEntity(data, level = 1) {
 provide('qdadmSetBreadcrumbEntity', setBreadcrumbEntity)
 provide('qdadmBreadcrumbEntities', breadcrumbEntities)
 
-// Clear entity data on route change (before new page mounts)
+// Clear entity data and 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)

package/src/components/layout/PageNav.vue

@@ -26,10 +26,14 @@ import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
 const breadcrumbOverride = inject('qdadmBreadcrumbOverride', null)
 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 }
+  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()
@@ -85,10 +89,22 @@ const breadcrumbItems = computed(() => {
     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
@@ -107,8 +123,10 @@ const breadcrumbItems = computed(() => {
     })
 
     // Parent item (with label from data)
-    const parentLabel = parentData.value
-      ? parentManager.getEntityLabel(parentData.value)
+    // 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}`
@@ -135,8 +153,16 @@ const siblingNavlinks = computed(() => {
   const { entity: parentEntityName, param } = parentConfig.value
   const siblings = getSiblingRoutes(parentEntityName, param)
 
+  // Filter out action routes (create, edit) - they're not navigation tabs
+  const navRoutes = siblings.filter(r => {
+    const name = r.name || ''
+    const path = r.path || ''
+    // Exclude routes ending with -create, -edit, -new or paths with /create, /edit, /new
+    return !name.match(/-(create|edit|new)$/) && !path.match(/\/(create|edit|new)$/)
+  })
+
   // Build navlinks with current route params
-  return siblings.map(siblingRoute => {
+  return navRoutes.map(siblingRoute => {
     const manager = siblingRoute.meta?.entity ? getManager(siblingRoute.meta.entity) : null
     const label = siblingRoute.meta?.navLabel || manager?.labelPlural || siblingRoute.name
 
@@ -159,10 +185,19 @@ const childNavlinks = computed(() => {
   const children = getChildRoutes(entityName)
   if (children.length === 0) return []
 
+  // Filter out action routes (create, edit) - they're not navigation tabs
+  const navRoutes = children.filter(r => {
+    const name = r.name || ''
+    const path = r.path || ''
+    return !name.match(/-(create|edit|new)$/) && !path.match(/\/(create|edit|new)$/)
+  })
+
+  if (navRoutes.length === 0) return []
+
   const entityId = route.params.id
 
   // Build navlinks to child routes
-  return children.map(childRoute => {
+  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'
@@ -177,7 +212,7 @@ const childNavlinks = computed(() => {
 
 // Combined navlinks with "Details" link
 const allNavlinks = computed(() => {
-  // Case 1: On a child route - show siblings + Details link to parent
+  // Case 1: On a child route - show siblings + optional Details link to parent
   if (parentConfig.value) {
     const { entity: parentEntityName, param, itemRoute } = parentConfig.value
     const parentId = route.params[param]
@@ -185,43 +220,50 @@ const allNavlinks = computed(() => {
 
     if (!parentManager) return siblingNavlinks.value
 
-    const defaultSuffix = parentManager.readOnly ? '-show' : '-edit'
-    const parentRouteName = itemRoute || `${parentManager.routePrefix}${defaultSuffix}`
-    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)
-    // This is a qdadm convention - all entity detail/edit routes expect 'id' param
-    const detailsLink = {
-      label: 'Details',
-      to: { name: parentRouteName, params: { id: parentId } },
-      active: isOnParentRoute
+    // 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 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 } },
+        active: isOnParentRoute
+      }
+
+      return [detailsLink, ...siblingNavlinks.value]
     }
 
-    return [detailsLink, ...siblingNavlinks.value]
+    return siblingNavlinks.value
   }
 
-  // Case 2: On parent detail page - show children + Details (active)
+  // Case 2: On parent detail page - show children + optional Details (active)
   if (childNavlinks.value.length > 0) {
-    const detailsLink = {
-      label: 'Details',
-      to: { name: route.name, params: route.params },
-      active: true
+    // Details link is optional since breadcrumb already shows current page
+    if (props.showDetailsLink) {
+      const detailsLink = {
+        label: 'Details',
+        to: { name: route.name, params: route.params },
+        active: true
+      }
+      return [detailsLink, ...childNavlinks.value]
     }
-
-    return [detailsLink, ...childNavlinks.value]
+    return childNavlinks.value
   }
 
   return []
 })
 
 // Sync breadcrumb and navlinks to AppLayout via provide/inject
-// Watch computed values + route changes to ensure updates after navigation
-watch([breadcrumbItems, () => route.fullPath], ([items]) => {
+// Watch computed values + route changes + entity data to ensure updates
+watch([breadcrumbItems, () => route.fullPath, breadcrumbEntities], ([items]) => {
   if (breadcrumbOverride) {
     breadcrumbOverride.value = items
   }
-}, { immediate: true })
+}, { immediate: true, deep: true })
 
 watch([allNavlinks, () => route.fullPath], ([links]) => {
   if (navlinksOverride) {

package/src/composables/useEntityItemFormPage.js

@@ -126,12 +126,18 @@ export function useEntityItemFormPage(config = {}) {
     getId
   })
 
-  const { manager, orchestrator, entityId, setBreadcrumbEntity } = itemPage
+  const { manager, orchestrator, entityId, setBreadcrumbEntity, getInitialDataWithParent, parentConfig, parentId, parentData, parentChain, getChainDepth } = itemPage
 
   // Read config from manager with option overrides
   const entityName = config.entityName ?? manager.label
   const routePrefix = config.routePrefix ?? manager.routePrefix
-  const initialData = config.initialData ?? manager.getInitialData()
+
+  // Initial data: merge user-provided with auto-populated parent foreignKey
+  // getInitialDataWithParent() adds the foreignKey from route.meta.parent
+  const baseInitialData = getInitialDataWithParent()
+  const initialData = config.initialData
+    ? { ...baseInitialData, ...config.initialData }
+    : baseInitialData
 
   /**
    * Detect form mode: 'create' or 'edit'
@@ -1094,6 +1100,13 @@ export function useEntityItemFormPage(config = {}) {
     isCreate,
     entityId,
 
+    // Parent chain (from route.meta.parent, supports N-level nesting)
+    parentConfig,
+    parentId,
+    parentData,        // Immediate parent (level 1)
+    parentChain,       // All parents: Map(level -> data)
+    getChainDepth,
+
     // State
     data,
     loading,

package/src/composables/useEntityItemPage.js

@@ -6,6 +6,7 @@
  * - Loading/error state management
  * - Breadcrumb integration (auto-calls setBreadcrumbEntity)
  * - Manager access for child composables
+ * - **Parent chain auto-detection** from route.meta.parent
  *
  * Used as base for:
  * - Show pages (read-only detail pages)
@@ -21,6 +22,21 @@
  * // error.value contains error message if failed
  * ```
  *
+ * ## Parent Chain Auto-Detection
+ *
+ * When route.meta.parent is configured, the composable auto-loads the parent entity:
+ *
+ * ```js
+ * // Route: /authors/:id/books/create
+ * // route.meta.parent = { entity: 'authors', param: 'id', foreignKey: 'author_id' }
+ *
+ * const { parentData, parentId, getInitialDataWithParent } = useEntityItemPage({ entity: 'books' })
+ *
+ * // parentData.value = loaded author entity
+ * // parentId.value = route.params.id
+ * // getInitialDataWithParent() = { ...defaults, author_id: parentId }
+ * ```
+ *
  * ## Usage in parent composables
  *
  * ```js
@@ -45,6 +61,8 @@ export function useEntityItemPage(config = {}) {
     // Loading options
     loadOnMount = true,
     breadcrumb = true,
+    // Parent chain options
+    autoLoadParent = true,  // Auto-load parent entity from route.meta.parent
     // ID extraction
     getId = null,
     idParam = 'id',
@@ -82,6 +100,135 @@ export function useEntityItemPage(config = {}) {
   const loading = ref(false)
   const error = ref(null)
 
+  // ============ PARENT CHAIN ============
+
+  /**
+   * Parent configuration from route.meta.parent
+   * Structure: { entity, param, foreignKey, parent?: {...} }
+   * Supports nested parents for N-level chains
+   */
+  const parentConfig = computed(() => route.meta?.parent || null)
+
+  /**
+   * Parent entity ID from route params (based on parentConfig.param)
+   */
+  const parentId = computed(() => {
+    if (!parentConfig.value) return null
+    return route.params[parentConfig.value.param] || null
+  })
+
+  /**
+   * Loaded parent entities data (Map: level -> data)
+   * Level 1 = immediate parent, Level 2 = grandparent, etc.
+   */
+  const parentChain = ref(new Map())
+  const parentLoading = ref(false)
+
+  /**
+   * Immediate parent data (shortcut for level 1)
+   */
+  const parentData = computed(() => parentChain.value.get(1) || null)
+
+  /**
+   * Calculate the depth of the current entity in the parent chain
+   * Returns number of parent levels + 1 for current entity
+   */
+  function getChainDepth(config = parentConfig.value) {
+    if (!config) return 1
+    let depth = 1
+    let current = config
+    while (current) {
+      depth++
+      current = current.parent
+    }
+    return depth
+  }
+
+  /**
+   * Get parent entity manager (if parent is configured)
+   */
+  function getParentManager() {
+    if (!parentConfig.value) return null
+    return orchestrator.get(parentConfig.value.entity)
+  }
+
+  /**
+   * Load entire parent chain recursively
+   * Sets breadcrumb entities at correct levels (1 = top ancestor, N = immediate parent)
+   */
+  async function loadParentChain() {
+    if (!parentConfig.value || !parentId.value) return
+
+    parentLoading.value = true
+    const newChain = new Map()
+
+    try {
+      // Calculate total depth to set correct breadcrumb levels
+      // If chain is: grandparent -> parent -> current
+      // grandparent = level 1, parent = level 2, current = level 3
+      const totalDepth = getChainDepth()
+
+      // Load chain from immediate parent up to root
+      let currentConfig = parentConfig.value
+      let level = 1  // Level in our chain (1 = immediate parent)
+
+      while (currentConfig) {
+        const parentEntityId = route.params[currentConfig.param]
+        if (!parentEntityId) break
+
+        const parentManager = orchestrator.get(currentConfig.entity)
+        if (!parentManager) {
+          console.warn(`[useEntityItemPage] Parent manager not found: ${currentConfig.entity}`)
+          break
+        }
+
+        const data = await parentManager.get(parentEntityId)
+        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)
+          }
+        }
+
+        currentConfig = currentConfig.parent
+        level++
+      }
+
+      parentChain.value = newChain
+    } catch (err) {
+      console.warn('[useEntityItemPage] Failed to load parent chain:', err)
+    } finally {
+      parentLoading.value = false
+    }
+  }
+
+  // Legacy alias for backwards compatibility
+  const loadParent = loadParentChain
+
+  /**
+   * Get initial data with parent foreignKey auto-populated
+   * Useful for form pages creating child entities
+   */
+  function getInitialDataWithParent() {
+    const baseData = manager.getInitialData()
+
+    if (!parentConfig.value || !parentId.value) {
+      return baseData
+    }
+
+    // Auto-populate foreignKey with parent ID
+    return {
+      ...baseData,
+      [parentConfig.value.foreignKey]: parentId.value
+    }
+  }
+
   // ============ ID EXTRACTION ============
 
   /**
@@ -121,8 +268,10 @@ export function useEntityItemPage(config = {}) {
       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) {
-        setBreadcrumbEntity(transformed)
+        const level = getChainDepth()
+        setBreadcrumbEntity(transformed, level)
       }
 
       if (onLoadSuccess) {
@@ -168,13 +317,17 @@ export function useEntityItemPage(config = {}) {
 
   // ============ LIFECYCLE ============
 
-  if (loadOnMount) {
-    onMounted(() => {
-      if (entityId.value) {
-        load()
-      }
-    })
-  }
+  onMounted(async () => {
+    // Auto-load parent entity if configured
+    if (autoLoadParent && parentConfig.value && parentId.value) {
+      await loadParent()
+    }
+
+    // Load current entity
+    if (loadOnMount && entityId.value) {
+      load()
+    }
+  })
 
   // ============ RETURN ============
 
@@ -189,6 +342,18 @@ export function useEntityItemPage(config = {}) {
     entityLabel,
     isLoaded,
 
+    // Parent chain (supports N-level nesting)
+    parentConfig,
+    parentId,
+    parentData,        // Immediate parent (level 1)
+    parentChain,       // All parents: Map(level -> data)
+    parentLoading,
+    loadParent,        // Alias for loadParentChain
+    loadParentChain,
+    getParentManager,
+    getChainDepth,
+    getInitialDataWithParent,
+
     // Actions
     load,
     reload,

package/src/composables/useListPageBuilder.js

@@ -321,13 +321,37 @@ export function useListPageBuilder(config = {}) {
   /**
    * Add standard "Create" header action
    * Respects manager.canCreate() for visibility
+   *
+   * @param {string|object} labelOrOptions - Label string or options object
+   * @param {string} labelOrOptions.label - Button label
+   * @param {string} labelOrOptions.routeName - Custom route name (overrides auto-detection)
+   * @param {object} labelOrOptions.params - Custom route params (merged with current params)
+   *
+   * @example
+   * // Simple usage
+   * list.addCreateAction('New Book')
+   *
+   * // With custom route (for child entities or special cases)
+   * list.addCreateAction({ label: 'New Command', routeName: 'bot-command-create' })
    */
-  function addCreateAction(label = null) {
-    const createLabel = label || `Create ${entityName.charAt(0).toUpperCase() + entityName.slice(1)}`
+  function addCreateAction(labelOrOptions = null) {
+    const options = typeof labelOrOptions === 'string'
+      ? { label: labelOrOptions }
+      : (labelOrOptions || {})
+
+    const createLabel = options.label || `Create ${entityName.charAt(0).toUpperCase() + entityName.slice(1)}`
+
+    const onClick = options.routeName
+      ? () => router.push({
+          name: options.routeName,
+          params: { ...route.params, ...options.params }
+        })
+      : goToCreate
+
     addHeaderAction('create', {
       label: createLabel,
       icon: 'pi pi-plus',
-      onClick: goToCreate,
+      onClick,
       visible: () => manager.canCreate()
     })
   }
@@ -1128,8 +1152,45 @@ export function useListPageBuilder(config = {}) {
   }
 
   // ============ NAVIGATION ============
+
+  /**
+   * Find create route for current context
+   * For child routes (with parent config), looks for sibling create route
+   * Falls back to standard {routePrefix}-create
+   */
+  function findCreateRoute() {
+    const parentConfig = route.meta?.parent
+
+    if (parentConfig) {
+      // Child route: find create route by path pattern
+      // Current matched route path: /bots/:id/commands → look for /bots/:id/commands/create
+      const currentMatched = route.matched[route.matched.length - 1]
+      if (currentMatched) {
+        const createPath = `${currentMatched.path}/create`
+        const createRoute = router.getRoutes().find(r => r.path === createPath)
+        if (createRoute?.name) {
+          return { name: createRoute.name, params: route.params }
+        }
+      }
+
+      // Fallback: try common naming pattern (list-name → singular-create)
+      // e.g., bot-commands → bot-command-create
+      const currentName = route.name
+      if (currentName && currentName.endsWith('s')) {
+        const singularName = currentName.slice(0, -1)
+        const createRouteName = `${singularName}-create`
+        if (router.hasRoute(createRouteName)) {
+          return { name: createRouteName, params: route.params }
+        }
+      }
+    }
+
+    // Default: standard entity route
+    return { name: `${routePrefix}-create` }
+  }
+
   function goToCreate() {
-    router.push({ name: `${routePrefix}-create` })
+    router.push(findCreateRoute())
   }
 
   function goToEdit(item) {