qdadm 0.47.0 → 0.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.47.0",
+  "version": "0.49.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -39,7 +39,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@quazardous/quarkernel": "^2.1.0"
+    "@quazardous/quarkernel": "^2.1.0",
+    "pluralize": "^8.0.0"
   },
   "peerDependencies": {
     "pinia": "^2.0.0",

package/src/components/forms/FormField.vue

@@ -7,7 +7,7 @@
  *   <InputText v-model="form.username" />
  * </FormField>
  *
- * The parent form (useFormPageBuilder) provides:
+ * The parent form (useEntityItemFormPage) provides:
  * - isFieldDirty: function to check if field is dirty
  * - getFieldError: function to get field error message
  * - handleFieldBlur: function to trigger validation on blur
@@ -44,7 +44,7 @@ const props = defineProps({
   }
 })
 
-// Inject from parent form (provided by useFormPageBuilder)
+// Inject from parent form (provided by useEntityItemFormPage)
 const isFieldDirty = inject('isFieldDirty', () => false)
 const getFieldError = inject('getFieldError', () => null)
 const handleFieldBlur = inject('handleFieldBlur', () => {})

package/src/components/forms/FormPage.vue

@@ -9,10 +9,10 @@
  * - FormActions footer
  * - UnsavedChangesDialog integration
  *
- * Props come from useFormPageBuilder composable:
+ * Props come from useEntityItemFormPage composable:
  *
  * ```vue
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.generateFields()
  * form.addSaveAction()
  *

package/src/components/layout/PageNav.vue

@@ -17,9 +17,9 @@
  * - entity: Current entity data (for dynamic labels in breadcrumb)
  * - parentEntity: Parent entity data (for parent label in breadcrumb)
  */
-import { computed, ref, watch, onMounted, onUnmounted, inject } from 'vue'
+import { computed, ref, watch, inject } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { getSiblingRoutes } from '../../module/moduleRegistry.js'
+import { getSiblingRoutes, getChildRoutes } from '../../module/moduleRegistry.js'
 import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
 
 // Inject override refs from AppLayout
@@ -110,7 +110,8 @@ const breadcrumbItems = computed(() => {
     const parentLabel = parentData.value
       ? parentManager.getEntityLabel(parentData.value)
       : '...'
-    const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+    const defaultSuffix = parentManager.readOnly ? '-show' : '-edit'
+    const parentRouteName = itemRoute || `${parentManager.routePrefix}${defaultSuffix}`
 
     items.push({
       label: parentLabel,
@@ -128,7 +129,7 @@ const breadcrumbItems = computed(() => {
 })
 
 // Sibling navlinks (routes with same parent)
-const navlinks = computed(() => {
+const siblingNavlinks = computed(() => {
   if (!parentConfig.value) return []
 
   const { entity: parentEntityName, param } = parentConfig.value
@@ -147,51 +148,91 @@ const navlinks = computed(() => {
   })
 })
 
-// Also include parent "Details" link
-const allNavlinks = computed(() => {
-  if (!parentConfig.value) return []
+// Child navlinks (when on parent detail page, show links to children)
+const childNavlinks = computed(() => {
+  // Only when NOT on a child route (no parentConfig)
+  if (parentConfig.value) return []
 
-  const { entity: parentEntityName, param, itemRoute } = parentConfig.value
-  const parentId = route.params[param]
-  const parentManager = getManager(parentEntityName)
+  const entityName = route.meta?.entity
+  if (!entityName) return []
+
+  const children = getChildRoutes(entityName)
+  if (children.length === 0) return []
+
+  const entityId = route.params.id
+
+  // Build navlinks to child routes
+  return children.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'
+
+    return {
+      label,
+      to: { name: childRoute.name, params: { [parentParam]: entityId } },
+      active: false
+    }
+  })
+})
+
+// Combined navlinks with "Details" link
+const allNavlinks = computed(() => {
+  // Case 1: On a child route - show siblings + Details link to parent
+  if (parentConfig.value) {
+    const { entity: parentEntityName, param, itemRoute } = parentConfig.value
+    const parentId = route.params[param]
+    const parentManager = getManager(parentEntityName)
+
+    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
+    }
 
-  if (!parentManager) return navlinks.value
+    return [detailsLink, ...siblingNavlinks.value]
+  }
 
-  const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
-  const isOnParentRoute = route.name === parentRouteName
+  // Case 2: On parent detail page - show children + Details (active)
+  if (childNavlinks.value.length > 0) {
+    const detailsLink = {
+      label: 'Details',
+      to: { name: route.name, params: route.params },
+      active: true
+    }
 
-  // Details link to parent edit form
-  const detailsLink = {
-    label: 'Details',
-    to: { name: parentRouteName, params: { id: parentId } },
-    active: isOnParentRoute
+    return [detailsLink, ...childNavlinks.value]
   }
 
-  return [detailsLink, ...navlinks.value]
+  return []
 })
 
 // Sync breadcrumb and navlinks to AppLayout via provide/inject
-watch(breadcrumbItems, (items) => {
+// Watch computed values + route changes to ensure updates after navigation
+watch([breadcrumbItems, () => route.fullPath], ([items]) => {
   if (breadcrumbOverride) {
     breadcrumbOverride.value = items
   }
 }, { immediate: true })
 
-watch(allNavlinks, (links) => {
+watch([allNavlinks, () => route.fullPath], ([links]) => {
   if (navlinksOverride) {
     navlinksOverride.value = links
   }
 }, { immediate: true })
 
-// Clear overrides when component unmounts (so other pages get default breadcrumb)
-onUnmounted(() => {
-  if (breadcrumbOverride) {
-    breadcrumbOverride.value = null
-  }
-  if (navlinksOverride) {
-    navlinksOverride.value = null
-  }
-})
+// 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>

package/src/composables/index.js

@@ -7,13 +7,14 @@ export { useBreadcrumb } from './useBreadcrumb'
 export { useSemanticBreadcrumb, computeSemanticBreadcrumb } from './useSemanticBreadcrumb'
 export { useDirtyState } from './useDirtyState'
 export { useForm } from './useForm'
-export { useFormPageBuilder } from './useFormPageBuilder'
+export { useEntityItemFormPage, useEntityItemFormPage as useFormPageBuilder } from './useEntityItemFormPage'
 export * from './useJsonSyntax'
 export { useListPageBuilder, PAGE_SIZE_OPTIONS } from './useListPageBuilder'
 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'
 export { useUnsavedChangesGuard } from './useUnsavedChangesGuard'

package/src/composables/{useFormPageBuilder.js → useEntityItemFormPage.js}

@@ -1,5 +1,5 @@
 /**
- * useFormPageBuilder - Unified procedural builder for CRUD form pages
+ * useEntityItemFormPage - Unified procedural builder for CRUD form pages
  *
  * Provides a declarative/procedural API to build form pages with:
  * - Mode detection (create vs edit from route params)
@@ -13,7 +13,7 @@
  * ## Basic Usage
  *
  * ```js
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.addSaveAction()
  * form.addDeleteAction()
  *
@@ -27,7 +27,7 @@
  * ## Auto-generated Fields
  *
  * ```js
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.generateFields()  // Auto-generate from manager.fields
  * form.excludeField('internal_id')  // Exclude specific fields
  * form.addField('custom', { type: 'text', label: 'Custom' })  // Manual override
@@ -40,7 +40,7 @@
  * ## Validation
  *
  * ```js
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.generateFields()
  *
  * // Add custom validator
@@ -77,19 +77,18 @@
  * - Unsaved changes guard modal
  * - Permission-aware save/delete actions via EntityManager.canUpdate/canDelete
  */
-import { ref, computed, watch, onMounted, inject, provide } from 'vue'
+import { ref, computed, watch, onMounted, onUnmounted, provide } from 'vue'
 import { useRouter, useRoute } from 'vue-router'
 import { useToast } from 'primevue/usetoast'
 import { useConfirm } from 'primevue/useconfirm'
 import { useDirtyState } from './useDirtyState'
 import { useUnsavedChangesGuard } from './useUnsavedChangesGuard'
 import { useBreadcrumb } from './useBreadcrumb'
-import { useCurrentEntity } from './useCurrentEntity'
+import { useEntityItemPage } from './useEntityItemPage'
 import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
 import { deepClone } from '../utils/transformers'
-import { onUnmounted } from 'vue'
 
-export function useFormPageBuilder(config = {}) {
+export function useEntityItemFormPage(config = {}) {
   const {
     entity,
     // Mode detection
@@ -118,41 +117,22 @@ export function useFormPageBuilder(config = {}) {
   const toast = useToast()
   const confirm = useConfirm()
 
-  // Get EntityManager via orchestrator
-  const orchestrator = inject('qdadmOrchestrator')
-  if (!orchestrator) {
-    throw new Error(
-      '[qdadm] Orchestrator not provided.\n' +
-      'Possible causes:\n' +
-      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
-      '2. Component used outside of qdadm app context\n' +
-      '3. Missing entityFactory in Kernel options'
-    )
-  }
-  const manager = orchestrator.get(entity)
-
-  // Provide entity context for child components (e.g., SeverityTag auto-discovery)
-  provide('mainEntity', entity)
+  // Use useEntityItemPage for common infrastructure
+  // (orchestrator, manager, entityId, provide('mainEntity'), breadcrumb)
+  const itemPage = useEntityItemPage({
+    entity,
+    loadOnMount: false,  // Form controls its own loading
+    breadcrumb: false,   // Form calls setBreadcrumbEntity manually after transform
+    getId
+  })
 
-  // Share entity data with navigation context (for breadcrumb)
-  const { setCurrentEntity } = useCurrentEntity()
+  const { manager, orchestrator, entityId, setBreadcrumbEntity } = 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()
 
-  // ============ MODE DETECTION ============
-
-  /**
-   * Extract entity ID from route params
-   * Supports: /books/:id/edit, /books/:id, /books/new
-   */
-  const entityId = computed(() => {
-    if (getId) return getId()
-    return route.params.id || route.params.key || null
-  })
-
   /**
    * Detect form mode: 'create' or 'edit'
    * Based on route name or presence of ID
@@ -263,7 +243,7 @@ export function useFormPageBuilder(config = {}) {
       takeSnapshot()
 
       // Share with navigation context for breadcrumb
-      setCurrentEntity(transformed)
+      setBreadcrumbEntity(transformed)
 
       if (onLoadSuccess) {
         await onLoadSuccess(transformed)
@@ -520,7 +500,7 @@ export function useFormPageBuilder(config = {}) {
         const updatedConfig = { ...config, options }
         fieldsMap.value.set(name, updatedConfig)
       } catch (error) {
-        console.warn(`[useFormPageBuilder] Failed to resolve options for field '${name}':`, error)
+        console.warn(`[useEntityItemFormPage] Failed to resolve options for field '${name}':`, error)
       }
     }
   }

package/src/composables/useEntityItemPage.js

@@ -0,0 +1,201 @@
+/**
+ * useEntityItemPage - Base composable for single entity item pages
+ *
+ * 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)
+ * - Manager access for child composables
+ *
+ * Used as base for:
+ * - Show pages (read-only detail pages)
+ * - useEntityItemFormPage (create/edit forms)
+ *
+ * ## Basic Usage (standalone)
+ *
+ * ```js
+ * const { data, loading, error, reload } = useEntityItemPage({ entity: 'posts' })
+ *
+ * // data.value contains the loaded entity
+ * // loading.value is true while fetching
+ * // error.value contains error message if failed
+ * ```
+ *
+ * ## Usage in parent composables
+ *
+ * ```js
+ * function useEntityItemFormPage(config) {
+ *   const itemPage = useEntityItemPage({
+ *     entity: config.entity,
+ *     loadOnMount: false,  // Form controls its own loading
+ *     transformLoad: config.transformLoad
+ *   })
+ *
+ *   // Use itemPage.load(), itemPage.data, etc.
+ * }
+ * ```
+ */
+import { ref, computed, onMounted, inject, provide } from 'vue'
+import { useRoute } from 'vue-router'
+import { useCurrentEntity } from './useCurrentEntity.js'
+
+export function useEntityItemPage(config = {}) {
+  const {
+    entity,
+    // Loading options
+    loadOnMount = true,
+    breadcrumb = true,
+    // ID extraction
+    getId = null,
+    idParam = 'id',
+    // Transform hook
+    transformLoad = (data) => data,
+    // Callbacks
+    onLoadSuccess = null,
+    onLoadError = null
+  } = config
+
+  const route = useRoute()
+
+  // Get EntityManager via orchestrator
+  const orchestrator = inject('qdadmOrchestrator')
+  if (!orchestrator) {
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
+  }
+  const manager = orchestrator.get(entity)
+
+  // Provide entity context for child components
+  provide('mainEntity', entity)
+
+  // Breadcrumb integration
+  const { setBreadcrumbEntity } = useCurrentEntity()
+
+  // ============ STATE ============
+
+  const data = ref(null)
+  const loading = ref(false)
+  const error = ref(null)
+
+  // ============ ID EXTRACTION ============
+
+  /**
+   * Extract entity ID from route params
+   * Supports custom getId function or param name
+   */
+  const entityId = computed(() => {
+    if (getId) return getId()
+    return route.params[idParam] || route.params.id || route.params.key || null
+  })
+
+  // ============ LOADING ============
+
+  /**
+   * Load entity by ID
+   * @param {string|number} [id] - Optional ID override (defaults to route param)
+   * @returns {Promise<object|null>} Loaded entity data or null on error
+   */
+  async function load(id = entityId.value) {
+    if (!id) {
+      error.value = 'No entity ID provided'
+      return null
+    }
+
+    loading.value = true
+    error.value = null
+
+    try {
+      const responseData = await manager.get(id)
+
+      if (!responseData) {
+        error.value = `${manager.label || entity} not found`
+        return null
+      }
+
+      const transformed = transformLoad(responseData)
+      data.value = transformed
+
+      // Share with navigation context for breadcrumb
+      if (breadcrumb) {
+        setBreadcrumbEntity(transformed)
+      }
+
+      if (onLoadSuccess) {
+        await onLoadSuccess(transformed)
+      }
+
+      return transformed
+    } catch (err) {
+      console.error(`[useEntityItemPage] Failed to load ${entity}:`, err)
+      error.value = err.response?.data?.detail || err.message || `Failed to load ${manager.label || entity}`
+
+      if (onLoadError) {
+        await onLoadError(err)
+      }
+
+      return null
+    } finally {
+      loading.value = false
+    }
+  }
+
+  /**
+   * Reload current entity
+   */
+  async function reload() {
+    return load(entityId.value)
+  }
+
+  // ============ COMPUTED ============
+
+  /**
+   * Entity label (uses manager.getEntityLabel)
+   */
+  const entityLabel = computed(() => {
+    if (!data.value) return null
+    return manager.getEntityLabel(data.value)
+  })
+
+  /**
+   * Check if entity is loaded
+   */
+  const isLoaded = computed(() => data.value !== null)
+
+  // ============ LIFECYCLE ============
+
+  if (loadOnMount) {
+    onMounted(() => {
+      if (entityId.value) {
+        load()
+      }
+    })
+  }
+
+  // ============ RETURN ============
+
+  return {
+    // State
+    data,
+    loading,
+    error,
+
+    // Computed
+    entityId,
+    entityLabel,
+    isLoaded,
+
+    // Actions
+    load,
+    reload,
+
+    // References (for parent composables)
+    manager,
+    orchestrator,
+    setBreadcrumbEntity
+  }
+}

package/src/composables/useNavContext.js

@@ -46,6 +46,19 @@ export function useNavContext(options = {}) {
     return router.getRoutes().some(r => r.name === name)
   }
 
+  /**
+   * Get default item route for an entity manager
+   * - Read-only entities: use -show suffix
+   * - Editable entities: use -edit suffix
+   * @param {EntityManager} manager
+   * @returns {string} Route name
+   */
+  function getDefaultItemRoute(manager) {
+    if (!manager) return null
+    const suffix = manager.readOnly ? '-show' : '-edit'
+    return `${manager.routePrefix}${suffix}`
+  }
+
   /**
    * Convert semantic breadcrumb to navigation chain format
    * Maps semantic kinds to chain types for compatibility
@@ -71,7 +84,7 @@ export function useNavContext(options = {}) {
           entity: item.entity,
           manager,
           id: item.id,
-          routeName: manager ? `${manager.routePrefix}-edit` : null
+          routeName: getDefaultItemRoute(manager)
         })
       } else if (item.kind === 'entity-create') {
         // Create page - treat as special list
@@ -246,7 +259,7 @@ export function useNavContext(options = {}) {
     const parentManager = getManager(parentEntity)
     if (!parentManager) return []
 
-    const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+    const parentRouteName = itemRoute || getDefaultItemRoute(parentManager)
     const isOnParent = route.name === parentRouteName
 
     // Details link

package/src/entity/EntityManager.js

@@ -1,6 +1,7 @@
 import { PermissiveAuthAdapter } from './auth/PermissiveAdapter.js'
 import { AuthActions } from './auth/EntityAuthAdapter.js'
 import { QueryExecutor } from '../query/QueryExecutor.js'
+import pluralize from 'pluralize'
 
 /**
  * EntityManager - Base class for entity CRUD operations
@@ -307,36 +308,34 @@ export class EntityManager {
 
   /**
    * Get entity label (singular)
-   * Default: capitalize name (e.g., 'users' → 'User')
+   * Default: capitalize name (e.g., 'users' → 'User', 'countries' → 'Country')
    */
   get label() {
     if (this._label) return this._label
     if (!this.name) return 'Item'
-    // users → User, book → Book
-    const singular = this.name.endsWith('s') ? this.name.slice(0, -1) : this.name
+    const singular = pluralize.singular(this.name)
     return singular.charAt(0).toUpperCase() + singular.slice(1)
   }
 
   /**
    * Get entity label (plural)
-   * Default: capitalize name or add 's' (e.g., 'user' → 'Users')
+   * Default: capitalize name (e.g., 'user' → 'Users', 'country' → 'Countries')
    */
   get labelPlural() {
     if (this._labelPlural) return this._labelPlural
     if (!this.name) return 'Items'
-    // users → Users, book → Books
-    const plural = this.name.endsWith('s') ? this.name : this.name + 's'
+    const plural = pluralize.plural(this.name)
     return plural.charAt(0).toUpperCase() + plural.slice(1)
   }
 
   /**
    * Get route prefix for this entity
-   * Default: singular form of name (e.g., 'books' → 'book')
+   * Default: singular form of name (e.g., 'books' → 'book', 'countries' → 'country')
    */
   get routePrefix() {
     if (this._routePrefix) return this._routePrefix
     if (!this.name) return 'item'
-    return this.name.endsWith('s') ? this.name.slice(0, -1) : this.name
+    return pluralize.singular(this.name)
   }
 
   /**

package/src/module/moduleRegistry.js

@@ -49,13 +49,21 @@ let alterationPromise = null
 const registry = {
   /**
    * Add routes for this module
-   * @param {string} prefix - Path prefix for all routes (e.g., 'agents')
+   *
+   * 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 (e.g., 'bookId')
+   * @param {string} options.parent.param - Route param for parent ID (MUST be '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)
@@ -341,6 +349,18 @@ export function getSiblingRoutes(parentEntity, parentParam) {
   })
 }
 
+/**
+ * Get child routes (routes that have this entity as parent)
+ * @param {string} entityName - Entity name to find children for
+ * @returns {Array} Routes with this entity as parent
+ */
+export function getChildRoutes(entityName) {
+  return routes.filter(route => {
+    const parent = route.meta?.parent
+    return parent?.entity === entityName
+  })
+}
+
 /**
  * Check if a route belongs to a family
  */

package/src/security/pages/RoleForm.vue

@@ -4,13 +4,13 @@
  */
 
 import { ref, computed, inject } from 'vue'
-import { useFormPageBuilder, FormPage, useOrchestrator, PermissionEditor } from '../../index.js'
+import { useEntityItemFormPage, FormPage, useOrchestrator, PermissionEditor } from '../../index.js'
 import InputText from 'primevue/inputtext'
 import AutoComplete from 'primevue/autocomplete'
 import Chip from 'primevue/chip'
 
 // ============ FORM BUILDER ============
-const form = useFormPageBuilder({ entity: 'roles' })
+const form = useEntityItemFormPage({ entity: 'roles' })
 
 // ============ HELPERS ============
 const { getManager } = useOrchestrator()