qdadm 0.15.1 → 0.16.0

package/package.json

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

package/src/components/BoolCell.vue

@@ -3,8 +3,8 @@
  * BoolCell - Standardized boolean display for list columns
  *
  * Tristate display:
- * - true: green check
- * - false: red cross
+ * - true / "true" / 1: green check
+ * - false / "false" / 0: red cross
  * - null/undefined: empty
  *
  * Usage:
@@ -14,15 +14,20 @@
  *   </template>
  * </Column>
  */
-defineProps({
+import { computed } from 'vue'
+
+const props = defineProps({
   value: {
-    type: Boolean,
+    type: [Boolean, String, Number],
     default: null
   }
 })
+
+const isTrue = computed(() => props.value === true || props.value === 'true' || props.value === 1)
+const isFalse = computed(() => props.value === false || props.value === 'false' || props.value === 0)
 </script>
 
 <template>
-  <i v-if="value === true" class="pi pi-check" style="color: var(--p-green-500)" />
-  <i v-else-if="value === false" class="pi pi-times" style="color: var(--p-red-500)" />
+  <i v-if="isTrue" class="pi pi-check" style="color: var(--p-green-500)" />
+  <i v-else-if="isFalse" class="pi pi-times" style="color: var(--p-red-500)" />
 </template>

package/src/components/layout/AppLayout.vue

@@ -18,7 +18,7 @@ import { useNavigation } from '../../composables/useNavigation'
 import { useApp } from '../../composables/useApp'
 import { useAuth } from '../../composables/useAuth'
 import { useGuardDialog } from '../../composables/useGuardStore'
-import { useBreadcrumb } from '../../composables/useBreadcrumb'
+import { useNavContext } from '../../composables/useNavContext'
 import Button from 'primevue/button'
 import Breadcrumb from 'primevue/breadcrumb'
 import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
@@ -125,18 +125,18 @@ function handleLogout() {
 const slots = useSlots()
 const hasSlotContent = computed(() => !!slots.default)
 
-// Breadcrumb (auto-generated from route)
-const { breadcrumbItems: defaultBreadcrumb } = useBreadcrumb()
+// Navigation context (breadcrumb + navlinks from route config)
+const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks } = useNavContext()
 
-// Allow child pages to override breadcrumb via provide/inject
+// Allow child pages to override breadcrumb/navlinks via provide/inject
 const breadcrumbOverride = ref(null)
 const navlinksOverride = ref(null)
 provide('qdadmBreadcrumbOverride', breadcrumbOverride)
 provide('qdadmNavlinksOverride', navlinksOverride)
 
-// Use override if provided, otherwise default
+// Use override if provided, otherwise default from useNavContext
 const breadcrumbItems = computed(() => breadcrumbOverride.value || defaultBreadcrumb.value)
-const navlinks = computed(() => navlinksOverride.value || [])
+const navlinks = computed(() => navlinksOverride.value || defaultNavlinks.value)
 
 // Show breadcrumb if enabled, has items, and not on home page
 const showBreadcrumb = computed(() => {
@@ -152,8 +152,10 @@ const showBreadcrumb = computed(() => {
     <!-- Sidebar -->
     <aside class="sidebar">
       <div class="sidebar-header">
-        <img v-if="app.logo" :src="app.logo" :alt="app.name" class="sidebar-logo" />
-        <h1 v-else>{{ app.name }}</h1>
+        <div class="sidebar-header-top">
+          <img v-if="app.logo" :src="app.logo" :alt="app.name" class="sidebar-logo" />
+          <h1 v-else>{{ app.name }}</h1>
+        </div>
         <span v-if="app.version" class="version">v{{ app.version }}</span>
       </div>
 
@@ -288,6 +290,13 @@ const showBreadcrumb = computed(() => {
 .sidebar-header {
   padding: 1.5rem;
   border-bottom: 1px solid var(--p-surface-700, #334155);
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.5rem;
+}
+
+.sidebar-header-top {
   display: flex;
   align-items: center;
   gap: 0.5rem;
@@ -305,7 +314,7 @@ const showBreadcrumb = computed(() => {
 }
 
 .version {
-  font-size: 0.75rem;
+  font-size: 0.625rem;
   color: var(--p-surface-400, #94a3b8);
   background: var(--p-surface-700, #334155);
   padding: 0.125rem 0.375rem;

package/src/components/layout/PageHeader.vue

@@ -42,17 +42,13 @@ const effectiveTitleParts = computed(() => {
   return props.titleParts || injectedTitleParts?.value || null
 })
 
+// Simple title from usePageTitle('My Title')
+const simpleTitle = computed(() => effectiveTitleParts.value?.simple)
+
 // Compute title display
 const hasDecoratedTitle = computed(() => {
   return effectiveTitleParts.value?.entityLabel
 })
-
-const titleBase = computed(() => {
-  if (effectiveTitleParts.value) {
-    return `${effectiveTitleParts.value.action} ${effectiveTitleParts.value.entityName}`
-  }
-  return props.title
-})
 </script>
 
 <template>
@@ -62,8 +58,9 @@ const titleBase = computed(() => {
         <div class="page-header-left">
           <div>
             <h1 class="page-title">
-              <template v-if="hasDecoratedTitle"><span class="entity-label">{{ effectiveTitleParts.entityLabel }}</span></template>
-              <span v-if="effectiveTitleParts" class="action-badge">{{ effectiveTitleParts.action }} {{ effectiveTitleParts.entityName }}</span>
+              <template v-if="simpleTitle">{{ simpleTitle }}</template>
+              <template v-else-if="hasDecoratedTitle"><span class="entity-label">{{ effectiveTitleParts.entityLabel }}</span></template>
+              <span v-if="effectiveTitleParts && !simpleTitle" class="action-badge">{{ effectiveTitleParts.action }} {{ effectiveTitleParts.entityName }}</span>
               <template v-if="!effectiveTitleParts">{{ title }}</template>
             </h1>
             <p v-if="subtitle" class="page-subtitle">{{ subtitle }}</p>

package/src/components/layout/PageNav.vue

@@ -25,6 +25,7 @@ import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
 // Inject override refs from AppLayout
 const breadcrumbOverride = inject('qdadmBreadcrumbOverride', null)
 const navlinksOverride = inject('qdadmNavlinksOverride', null)
+const homeRouteName = inject('qdadmHomeRoute', null)
 
 const props = defineProps({
   entity: { type: Object, default: null },
@@ -60,10 +61,24 @@ watch(() => [parentConfig.value, route.params], async () => {
   }
 }, { 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

package/src/composables/index.js

@@ -10,10 +10,12 @@ export { useForm } from './useForm'
 export * from './useJsonSyntax'
 export { useListPageBuilder, PAGE_SIZE_OPTIONS } from './useListPageBuilder'
 export { usePageBuilder } from './usePageBuilder'
+export { usePageTitle } from './usePageTitle'
 export { useSubEditor } from './useSubEditor'
 export { useTabSync } from './useTabSync'
 export { useApp } from './useApp'
 export { useAuth } from './useAuth'
+export { useNavContext } from './useNavContext'
 export { useNavigation } from './useNavigation'
 export { useStatus } from './useStatus'
 export { useUnsavedChangesGuard } from './useUnsavedChangesGuard'

package/src/composables/useBreadcrumb.js

@@ -1,4 +1,4 @@
-import { computed } from 'vue'
+import { computed, inject } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 
 /**
@@ -35,9 +35,11 @@ import { useRoute, useRouter } from 'vue-router'
 export function useBreadcrumb(options = {}) {
   const route = useRoute()
   const router = useRouter()
+  const homeRouteName = inject('qdadmHomeRoute', null)
 
   // Label mapping for common route names
   const labelMap = {
+    home: 'Home',
     dashboard: 'Dashboard',
     users: 'Users',
     roles: 'Roles',
@@ -102,13 +104,15 @@ export function useBreadcrumb(options = {}) {
   }
 
   /**
-   * Get home breadcrumb item (dashboard if exists, otherwise null)
+   * Get home breadcrumb item from configured homeRoute
    */
   function getHomeItem() {
-    if (routeExists('dashboard')) {
-      return { label: 'Dashboard', to: { name: 'dashboard' }, icon: 'pi pi-home' }
+    if (!homeRouteName || !routeExists(homeRouteName)) {
+      return null
     }
-    return null
+    // Use label from labelMap or capitalize route name
+    const label = labelMap[homeRouteName] || capitalize(homeRouteName)
+    return { label, to: { name: homeRouteName }, icon: 'pi pi-home' }
   }
 
   /**

package/src/composables/useNavContext.js

@@ -0,0 +1,372 @@
+/**
+ * useNavContext - Route-aware navigation context for breadcrumb and navlinks
+ *
+ * Builds navigation from route path pattern analysis (not heuristics).
+ *
+ * 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
+ *
+ * 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"
+ */
+import { ref, computed, watch, inject, unref } 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']
+
+export function useNavContext(options = {}) {
+  const route = useRoute()
+  const router = useRouter()
+
+  // Injected dependencies
+  const orchestrator = inject('qdadmOrchestrator', null)
+  const homeRouteName = inject('qdadmHomeRoute', null)
+
+  // Entity data cache
+  const entityDataCache = ref(new Map())
+
+  function getManager(entityName) {
+    return orchestrator?.get(entityName)
+  }
+
+  function routeExists(name) {
+    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.
+   */
+  function buildNavChain(pathSegments, routeMeta, routeParams) {
+    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
+        })
+      }
+    }
+
+    // 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) {
+        chain.push({
+          type: 'item',
+          entity,
+          manager,
+          id: entityId,
+          routeName: `${manager.routePrefix}-edit`
+        })
+      }
+    }
+
+    // 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
+      }
+    }
+
+    return chain
+  }
+
+  // ============================================================================
+  // COMPUTED NAVIGATION CHAIN
+  // ============================================================================
+
+  /**
+   * 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
+   */
+  const navChain = computed(() => {
+    return buildNavChain(pathSegments.value, route.meta, route.params)
+  })
+
+  // ============================================================================
+  // ENTITY DATA FETCHING
+  // ============================================================================
+
+  const chainData = ref(new Map())  // Map: chainIndex -> entityData
+
+  /**
+   * Fetch entity data for all 'item' segments in the chain
+   */
+  watch([navChain, () => options.entityData], async ([chain]) => {
+    chainData.value.clear()
+    const externalData = unref(options.entityData)
+
+    for (let i = 0; i < chain.length; i++) {
+      const segment = chain[i]
+      if (segment.type !== 'item') continue
+
+      // For the last item, use external data if provided (from useForm)
+      const isLastItem = !chain.slice(i + 1).some(s => s.type === 'item')
+      if (isLastItem && externalData) {
+        chainData.value.set(i, externalData)
+        continue
+      }
+
+      // Fetch from manager
+      try {
+        const data = await segment.manager.get(segment.id)
+        chainData.value.set(i, data)
+      } catch (e) {
+        console.warn(`[useNavContext] Failed to fetch ${segment.entity}:${segment.id}`, e)
+      }
+    }
+  }, { immediate: true, deep: true })
+
+  // ============================================================================
+  // BREADCRUMB
+  // ============================================================================
+
+  const homeItem = computed(() => {
+    if (!homeRouteName || !routeExists(homeRouteName)) return null
+    return {
+      label: homeRouteName === 'dashboard' ? 'Dashboard' : 'Home',
+      to: { name: homeRouteName },
+      icon: 'pi pi-home'
+    }
+  })
+
+  const breadcrumb = computed(() => {
+    const items = []
+    const chain = navChain.value
+
+    // Home
+    if (homeItem.value) {
+      items.push(homeItem.value)
+    }
+
+    // Build from chain
+    for (let i = 0; i < chain.length; i++) {
+      const segment = chain[i]
+      const isLast = i === chain.length - 1
+
+      if (segment.type === 'list') {
+        items.push({
+          label: segment.label,
+          to: { name: segment.routeName }
+        })
+      } else if (segment.type === 'item') {
+        const data = chainData.value.get(i)
+        const label = data ? segment.manager.getEntityLabel(data) : '...'
+
+        items.push({
+          label,
+          to: isLast ? null : { name: segment.routeName, params: { id: segment.id } }
+        })
+      } else if (segment.type === 'child-list') {
+        items.push({
+          label: segment.navLabel || segment.label
+        })
+      }
+    }
+
+    return items
+  })
+
+  // ============================================================================
+  // NAVLINKS (for child routes)
+  // ============================================================================
+
+  const parentConfig = computed(() => route.meta?.parent)
+
+  const parentId = computed(() => {
+    if (!parentConfig.value) return null
+    return route.params[parentConfig.value.param]
+  })
+
+  const navlinks = computed(() => {
+    if (!parentConfig.value) return []
+
+    const { entity: parentEntity, param, itemRoute } = parentConfig.value
+    const parentManager = getManager(parentEntity)
+    if (!parentManager) return []
+
+    const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+    const isOnParent = route.name === parentRouteName
+
+    // Details link
+    const links = [{
+      label: 'Details',
+      to: { name: parentRouteName, params: { id: parentId.value } },
+      active: isOnParent
+    }]
+
+    // Sibling routes
+    const siblings = getSiblingRoutes(parentEntity, param)
+    for (const sibling of siblings) {
+      const sibManager = sibling.meta?.entity ? getManager(sibling.meta.entity) : null
+      links.push({
+        label: sibling.meta?.navLabel || sibManager?.labelPlural || sibling.name,
+        to: { name: sibling.name, params: route.params },
+        active: route.name === sibling.name
+      })
+    }
+
+    return links
+  })
+
+  // ============================================================================
+  // CONVENIENCE ACCESSORS
+  // ============================================================================
+
+  const entityData = computed(() => {
+    const chain = navChain.value
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (chain[i].type === 'item') {
+        return chainData.value.get(i) || null
+      }
+    }
+    return null
+  })
+
+  const parentData = computed(() => {
+    const chain = navChain.value
+    let foundCurrent = false
+    for (let i = chain.length - 1; i >= 0; i--) {
+      if (chain[i].type === 'item') {
+        if (foundCurrent) return chainData.value.get(i) || null
+        foundCurrent = true
+      }
+    }
+    return null
+  })
+
+  return {
+    // Analysis
+    pathSegments,
+    navChain,
+
+    // Data
+    entityData,
+    parentData,
+    chainData,
+
+    // Navigation
+    breadcrumb,
+    navlinks,
+
+    // Helpers
+    parentConfig,
+    parentId
+  }
+}

package/src/composables/usePageTitle.js

@@ -0,0 +1,59 @@
+/**
+ * usePageTitle - Provide custom page title for PageHeader
+ *
+ * Use this composable in custom pages to set the title displayed in PageHeader.
+ * For standard CRUD pages, useForm handles this automatically.
+ *
+ * Usage:
+ * ```js
+ * // Simple title
+ * const { setTitle } = usePageTitle('My Custom Page')
+ *
+ * // Decorated title (entityLabel shown prominently, action+entityName as badge)
+ * usePageTitle({
+ *   action: 'View',
+ *   entityName: 'Stats',
+ *   entityLabel: 'Dashboard'
+ * })
+ *
+ * // Reactive updates
+ * const { setTitle } = usePageTitle('Initial')
+ * setTitle('Updated Title')
+ * ```
+ */
+import { ref, provide, watchEffect, isRef, unref } from 'vue'
+
+export function usePageTitle(initialTitle = null) {
+  const titleParts = ref(null)
+
+  // Convert string to titleParts format (simple title)
+  function normalize(title) {
+    if (!title) return null
+    if (typeof title === 'string') {
+      return { simple: title }
+    }
+    return title
+  }
+
+  // Set title (string or { action, entityName, entityLabel })
+  function setTitle(newTitle) {
+    titleParts.value = normalize(unref(newTitle))
+  }
+
+  // Initialize with provided value
+  if (initialTitle !== null) {
+    if (isRef(initialTitle)) {
+      // Reactive: watch for changes
+      watchEffect(() => {
+        setTitle(initialTitle.value)
+      })
+    } else {
+      setTitle(initialTitle)
+    }
+  }
+
+  // Provide to PageHeader via same key as useForm
+  provide('qdadmPageTitleParts', titleParts)
+
+  return { titleParts, setTitle }
+}

package/src/index.js

@@ -27,3 +27,6 @@ export * from './module/index.js'
 
 // Utils
 export * from './utils/index.js'
+
+// Assets
+export { default as qdadmLogo } from './assets/logo.svg'

package/src/kernel/Kernel.js

@@ -210,6 +210,10 @@ export class Kernel {
     // Router
     app.use(this.router)
 
+    // Extract home route name for breadcrumb
+    const { homeRoute } = this.options
+    const homeRouteName = typeof homeRoute === 'object' ? homeRoute.name : homeRoute
+
     // qdadm plugin
     app.use(createQdadm({
       orchestrator: this.orchestrator,
@@ -218,6 +222,7 @@ export class Kernel {
       router: this.router,
       toast: app.config.globalProperties.$toast,
       app: this.options.app,
+      homeRoute: homeRouteName,
       features: {
         auth: !!authAdapter,
         poweredBy: true,

package/src/plugin.js

@@ -22,6 +22,7 @@ import qdadmLogo from './assets/logo.svg'
  * @param {object} options.features - Optional: Feature toggles (auth, poweredBy)
  * @param {object} options.builtinModules - Optional: Builtin modules configuration
  * @param {object} options.endpoints - Optional: API endpoints configuration
+ * @param {string} options.homeRoute - Optional: Home route name for breadcrumb
  * @returns {object} Vue plugin
  */
 export function createQdadm(options) {
@@ -112,6 +113,10 @@ export function createQdadm(options) {
         app.provide('qdadmSectionOrder', options.modules.sectionOrder)
       }
 
+      if (options.homeRoute) {
+        app.provide('qdadmHomeRoute', options.homeRoute)
+      }
+
       // Add route guard for entity permissions
       options.router.beforeEach((to, from, next) => {
         const entity = to.meta?.entity