qdadm 0.14.3 → 0.15.0

package/package.json

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

package/src/components/index.js

@@ -7,6 +7,7 @@ export { default as AppLayout } from './layout/AppLayout.vue'
 export { default as PageLayout } from './layout/PageLayout.vue'
 export { default as PageHeader } from './layout/PageHeader.vue'
 export { default as Breadcrumb } from './layout/Breadcrumb.vue'
+export { default as PageNav } from './layout/PageNav.vue'
 
 // Forms
 export { default as FormField } from './forms/FormField.vue'

package/src/components/layout/AppLayout.vue

@@ -12,7 +12,7 @@
  *   </AppLayout>
  */
 
-import { ref, watch, onMounted, computed, inject, useSlots } from 'vue'
+import { ref, watch, onMounted, computed, inject, provide, useSlots } from 'vue'
 import { RouterLink, RouterView, useRouter, useRoute } from 'vue-router'
 import { useNavigation } from '../../composables/useNavigation'
 import { useApp } from '../../composables/useApp'
@@ -126,7 +126,18 @@ const slots = useSlots()
 const hasSlotContent = computed(() => !!slots.default)
 
 // Breadcrumb (auto-generated from route)
-const { breadcrumbItems } = useBreadcrumb()
+const { breadcrumbItems: defaultBreadcrumb } = useBreadcrumb()
+
+// Allow child pages to override breadcrumb via provide/inject
+const breadcrumbOverride = ref(null)
+const navlinksOverride = ref(null)
+provide('qdadmBreadcrumbOverride', breadcrumbOverride)
+provide('qdadmNavlinksOverride', navlinksOverride)
+
+// Use override if provided, otherwise default
+const breadcrumbItems = computed(() => breadcrumbOverride.value || defaultBreadcrumb.value)
+const navlinks = computed(() => navlinksOverride.value || [])
+
 // Show breadcrumb if enabled, has items, and not on home page
 const showBreadcrumb = computed(() => {
   if (!features.breadcrumb || breadcrumbItems.value.length === 0) return false
@@ -203,19 +214,35 @@ const showBreadcrumb = computed(() => {
 
     <!-- Main content -->
     <main class="main-content">
-      <!-- Breadcrumb (auto-generated, can be disabled via features.breadcrumb: false) -->
-      <Breadcrumb v-if="showBreadcrumb" :model="breadcrumbItems" class="layout-breadcrumb">
-        <template #item="{ item }">
-          <RouterLink v-if="item.to" :to="item.to" class="breadcrumb-link">
-            <i v-if="item.icon" :class="item.icon"></i>
-            <span>{{ item.label }}</span>
-          </RouterLink>
-          <span v-else class="breadcrumb-current">
-            <i v-if="item.icon" :class="item.icon"></i>
-            <span>{{ item.label }}</span>
-          </span>
-        </template>
-      </Breadcrumb>
+      <!-- Breadcrumb + Navlinks bar -->
+      <div v-if="showBreadcrumb" class="layout-nav-bar">
+        <Breadcrumb :model="breadcrumbItems" class="layout-breadcrumb">
+          <template #item="{ item }">
+            <RouterLink v-if="item.to" :to="item.to" class="breadcrumb-link">
+              <i v-if="item.icon" :class="item.icon"></i>
+              <span>{{ item.label }}</span>
+            </RouterLink>
+            <span v-else class="breadcrumb-current">
+              <i v-if="item.icon" :class="item.icon"></i>
+              <span>{{ item.label }}</span>
+            </span>
+          </template>
+        </Breadcrumb>
+
+        <!-- Navlinks (provided by PageNav for child routes) -->
+        <div v-if="navlinks.length > 0" class="layout-navlinks">
+          <template v-for="(link, index) in navlinks" :key="link.to?.name || index">
+            <span v-if="index > 0" class="layout-navlinks-separator">|</span>
+            <RouterLink
+              :to="link.to"
+              class="layout-navlink"
+              :class="{ 'layout-navlink--active': link.active }"
+            >
+              {{ link.label }}
+            </RouterLink>
+          </template>
+        </div>
+      </div>
 
       <div class="page-content">
         <!-- Use slot if provided, otherwise RouterView for nested routes -->
@@ -455,4 +482,75 @@ const showBreadcrumb = computed(() => {
 .powered-by-text strong {
   color: var(--p-surface-300, #cbd5e1);
 }
+
+/* Nav bar (breadcrumb + navlinks) - aligned with sidebar header */
+.layout-nav-bar {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1.5rem;
+  padding-bottom: 0;
+}
+
+.layout-navlinks {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.875rem;
+}
+
+.layout-navlinks-separator {
+  color: var(--p-surface-400, #94a3b8);
+}
+
+.layout-navlink {
+  color: var(--p-primary-500, #3b82f6);
+  text-decoration: none;
+  transition: color 0.15s;
+}
+
+.layout-navlink:hover {
+  color: var(--p-primary-700, #1d4ed8);
+  text-decoration: underline;
+}
+
+.layout-navlink--active {
+  color: var(--p-surface-700, #334155);
+  font-weight: 500;
+  pointer-events: none;
+}
+
+/* Override PrimeVue Breadcrumb styles for flat look */
+.layout-nav-bar :deep(.p-breadcrumb) {
+  background: transparent;
+  border: none;
+  padding: 0;
+  border-radius: 0;
+}
+
+.layout-nav-bar :deep(.p-breadcrumb-list) {
+  gap: 0.5rem;
+}
+
+.layout-nav-bar :deep(.p-breadcrumb-item-link),
+.layout-nav-bar .breadcrumb-link {
+  color: var(--p-primary-500, #3b82f6);
+  text-decoration: none;
+  font-size: 0.875rem;
+}
+
+.layout-nav-bar :deep(.p-breadcrumb-item-link:hover),
+.layout-nav-bar .breadcrumb-link:hover {
+  color: var(--p-primary-700, #1d4ed8);
+  text-decoration: underline;
+}
+
+.layout-nav-bar .breadcrumb-current {
+  color: var(--p-surface-600, #475569);
+  font-size: 0.875rem;
+}
+
+.layout-nav-bar :deep(.p-breadcrumb-separator) {
+  color: var(--p-surface-400, #94a3b8);
+}
 </style>

package/src/components/layout/PageHeader.vue

@@ -1,11 +1,10 @@
 <script setup>
 /**
- * PageHeader - Reusable page header with breadcrumb, title and actions
+ * PageHeader - Reusable page header with title and actions
  *
  * Props:
  * - title: Page title (simple string) OR
  * - titleParts: { action, entityName, entityLabel } for decorated rendering
- * - breadcrumb: Array of { label, to?, icon? } - optional breadcrumb items
  *
  * Title rendering:
  * - Simple: "Edit Agent" → <h1>Edit Agent</h1>
@@ -16,14 +15,9 @@
  * - subtitle: Optional content next to title
  * - actions: Action buttons on the right
  *
- * Note: When features.breadcrumb is enabled in AppLayout, the layout handles
- * breadcrumb rendering globally. PageHeader only renders its own breadcrumb
- * when the global feature is disabled.
+ * Note: Breadcrumb is handled globally by AppLayout.
  */
 import { computed, inject } from 'vue'
-import Breadcrumb from './Breadcrumb.vue'
-
-const features = inject('qdadmFeatures', { breadcrumb: false })
 
 // Auto-injected title from useForm (if available)
 const injectedTitleParts = inject('qdadmPageTitleParts', null)
@@ -40,10 +34,6 @@ const props = defineProps({
   subtitle: {
     type: String,
     default: null
-  },
-  breadcrumb: {
-    type: Array,
-    default: null
   }
 })
 
@@ -63,17 +53,11 @@ const titleBase = computed(() => {
   }
   return props.title
 })
-
-// Only show PageHeader breadcrumb if global breadcrumb feature is disabled
-const showBreadcrumb = computed(() => {
-  return props.breadcrumb?.length && !features.breadcrumb
-})
 </script>
 
 <template>
   <div class="page-header">
     <div class="page-header-content">
-      <Breadcrumb v-if="showBreadcrumb" :items="breadcrumb" />
       <div class="page-header-row">
         <div class="page-header-left">
           <div>
@@ -105,6 +89,7 @@ const showBreadcrumb = computed(() => {
   display: flex;
   justify-content: space-between;
   align-items: center;
+  min-height: 2.5rem; /* Consistent height with or without action buttons */
 }
 
 .page-header-left {

package/src/components/layout/PageLayout.vue

@@ -3,22 +3,21 @@
  * PageLayout - Base layout for dashboard pages
  *
  * Provides:
- * - Auto-generated breadcrumb
  * - PageHeader with title and actions
  * - CardsGrid zone (optional)
  * - Main content slot
  *
- * Use this for custom pages that don't follow the standard list pattern.
- * For CRUD list pages, use ListPage instead.
+ * Slots:
+ * - #nav: For PageNav component (provides breadcrumb data to AppLayout)
+ * - #header-actions: Custom header action buttons
+ * - default: Main content
  *
- * Note: UnsavedChangesDialog is rendered automatically by AppLayout
- * via provide/inject from useBareForm/useForm.
+ * Note: Breadcrumb is handled globally by AppLayout.
+ * Use PageNav in #nav slot to customize breadcrumb for child routes.
  */
-import { toRef } from 'vue'
 import PageHeader from './PageHeader.vue'
 import CardsGrid from '../display/CardsGrid.vue'
 import Button from 'primevue/button'
-import { useBreadcrumb } from '../../composables/useBreadcrumb'
 
 const props = defineProps({
   // Header - use title OR titleParts (for decorated entity label)
@@ -26,26 +25,12 @@ const props = defineProps({
   titleParts: { type: Object, default: null },  // { action, entityName, entityLabel }
   subtitle: { type: String, default: null },
   headerActions: { type: Array, default: () => [] },
-  breadcrumb: { type: Array, default: null },  // Override auto breadcrumb
-
-  // Entity data for dynamic breadcrumb labels
-  entity: { type: Object, default: null },
-  manager: { type: Object, default: null },  // EntityManager - provides labelField automatically
 
   // Cards
   cards: { type: Array, default: () => [] },
   cardsColumns: { type: [Number, String], default: 'auto' }
 })
 
-// Auto-generate breadcrumb from route, using entity data for labels
-// getEntityLabel from manager handles both string field and callback
-const { breadcrumbItems } = useBreadcrumb({
-  entity: toRef(() => props.entity),  // Make reactive
-  getEntityLabel: props.manager
-    ? (e) => props.manager.getEntityLabel(e)
-    : (e) => e?.name || null  // Fallback if no manager
-})
-
 function resolveLabel(label) {
   return typeof label === 'function' ? label() : label
 }
@@ -53,7 +38,13 @@ function resolveLabel(label) {
 
 <template>
   <div>
-    <PageHeader :title="title" :title-parts="titleParts" :breadcrumb="props.breadcrumb || breadcrumbItems">
+    <!-- Nav slot for PageNav (provides data to AppLayout, renders nothing visible) -->
+    <slot name="nav" />
+
+    <PageHeader
+      :title="title"
+      :title-parts="titleParts"
+    >
       <template #subtitle>
         <slot name="subtitle">
           <span v-if="subtitle" class="page-subtitle">{{ subtitle }}</span>

package/src/components/layout/PageNav.vue

@@ -0,0 +1,184 @@
+<script setup>
+/**
+ * PageNav - Route-aware navigation provider for breadcrumb + navlinks
+ *
+ * This component doesn't render anything visible. Instead, it provides
+ * breadcrumb items and navlinks to AppLayout via provide/inject.
+ *
+ * Layout (rendered in AppLayout):
+ *   Books > "Dune"                    Details | Loans | Reviews
+ *     ↑ breadcrumb (left)                   ↑ navlinks (right)
+ *
+ * Auto-detects from current route:
+ * - Breadcrumb: parent chain from route.meta.parent
+ * - Navlinks: sibling routes (same parent entity + param)
+ *
+ * Props:
+ * - 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 { useRoute, useRouter } from 'vue-router'
+import { getSiblingRoutes } from '../../module/moduleRegistry.js'
+import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
+
+// Inject override refs from AppLayout
+const breadcrumbOverride = inject('qdadmBreadcrumbOverride', null)
+const navlinksOverride = inject('qdadmNavlinksOverride', null)
+
+const props = defineProps({
+  entity: { type: Object, default: null },
+  parentEntity: { type: Object, default: null }
+})
+
+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 })
+
+// Build breadcrumb items
+const breadcrumbItems = computed(() => {
+  const items = []
+
+  if (!parentConfig.value) {
+    // No parent - use simple breadcrumb from entity
+    const entityName = route.meta?.entity
+    if (entityName) {
+      const manager = getManager(entityName)
+      if (manager) {
+        items.push({
+          label: manager.labelPlural || manager.name,
+          to: { name: manager.routePrefix }
+        })
+      }
+    }
+    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)
+    const parentLabel = parentData.value
+      ? parentManager.getEntityLabel(parentData.value)
+      : '...'
+    const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+
+    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
+})
+
+// Sibling navlinks (routes with same parent)
+const navlinks = computed(() => {
+  if (!parentConfig.value) return []
+
+  const { entity: parentEntityName, param } = parentConfig.value
+  const siblings = getSiblingRoutes(parentEntityName, param)
+
+  // Build navlinks with current route params
+  return siblings.map(siblingRoute => {
+    const manager = siblingRoute.meta?.entity ? getManager(siblingRoute.meta.entity) : null
+    const label = siblingRoute.meta?.navLabel || manager?.labelPlural || siblingRoute.name
+
+    return {
+      label,
+      to: { name: siblingRoute.name, params: route.params },
+      active: route.name === siblingRoute.name
+    }
+  })
+})
+
+// Also include parent "Details" link
+const allNavlinks = computed(() => {
+  if (!parentConfig.value) return []
+
+  const { entity: parentEntityName, param, itemRoute } = parentConfig.value
+  const parentId = route.params[param]
+  const parentManager = getManager(parentEntityName)
+
+  if (!parentManager) return navlinks.value
+
+  const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+  const isOnParentRoute = route.name === parentRouteName
+
+  // Details link to parent edit form
+  const detailsLink = {
+    label: 'Details',
+    to: { name: parentRouteName, params: { id: parentId } },
+    active: isOnParentRoute
+  }
+
+  return [detailsLink, ...navlinks.value]
+})
+
+// Sync breadcrumb and navlinks to AppLayout via provide/inject
+watch(breadcrumbItems, (items) => {
+  if (breadcrumbOverride) {
+    breadcrumbOverride.value = items
+  }
+}, { immediate: true })
+
+watch(allNavlinks, (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
+  }
+})
+</script>
+
+<template>
+  <!-- PageNav provides data to AppLayout via inject, renders nothing -->
+</template>

package/src/components/lists/ListPage.vue

@@ -29,7 +29,6 @@ const props = defineProps({
   // Header
   title: { type: String, required: true },
   subtitle: { type: String, default: null },
-  breadcrumb: { type: Array, default: null },
   headerActions: { type: Array, default: () => [] },
 
   // Cards
@@ -207,7 +206,10 @@ function onSort(event) {
 
 <template>
   <div>
-    <PageHeader :title="title" :subtitle="subtitle" :breadcrumb="breadcrumb">
+    <!-- Nav slot for PageNav (child routes) -->
+    <slot name="nav" />
+
+    <PageHeader :title="title" :subtitle="subtitle">
       <template #actions>
         <slot name="header-actions" ></slot>
         <Button

package/src/composables/useListPageBuilder.js

@@ -2,7 +2,6 @@ import { ref, computed, watch, onMounted, inject, provide } from 'vue'
 import { useRouter, useRoute } from 'vue-router'
 import { useToast } from 'primevue/usetoast'
 import { useConfirm } from 'primevue/useconfirm'
-import { useBreadcrumb } from './useBreadcrumb'
 
 // Cookie utilities for pagination persistence
 const COOKIE_NAME = 'qdadm_pageSize'
@@ -146,7 +145,6 @@ export function useListPageBuilder(config = {}) {
   const route = useRoute()
   const toast = useToast()
   const confirm = useConfirm()
-  const { breadcrumbItems } = useBreadcrumb()
 
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
@@ -735,6 +733,16 @@ export function useListPageBuilder(config = {}) {
         if (typeof filterDef?.local_filter === 'function') continue
         filters[name] = value
       }
+
+      // Auto-add parent filter from route config
+      const parentConfig = route.meta?.parent
+      if (parentConfig?.foreignKey && parentConfig?.param) {
+        const parentId = route.params[parentConfig.param]
+        if (parentId) {
+          filters[parentConfig.foreignKey] = parentId
+        }
+      }
+
       if (Object.keys(filters).length > 0) {
         params.filters = filters
       }
@@ -1009,7 +1017,6 @@ export function useListPageBuilder(config = {}) {
   const listProps = computed(() => ({
     // Header
     title: manager.labelPlural,
-    breadcrumb: breadcrumbItems.value,
     headerActions: headerActions.value,
 
     // Cards
@@ -1143,9 +1150,6 @@ export function useListPageBuilder(config = {}) {
     confirm,
     router,
 
-    // Breadcrumb
-    breadcrumb: breadcrumbItems,
-
     // ListPage integration
     props: listProps,
     events: listEvents

package/src/entity/storage/ApiStorage.js

@@ -56,13 +56,18 @@ export class ApiStorage {
 
   /**
    * List entities with pagination/filtering
-   * @param {object} params - { page, page_size, filters, sort_by, sort_order }
+   * @param {object} params - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.page_size=20] - Items per page
+   * @param {string} [params.sort_by] - Field to sort by
+   * @param {string} [params.sort_order='asc'] - Sort order ('asc' or 'desc')
+   * @param {object} [params.filters] - Field filters { field: value }
    * @returns {Promise<{ items: Array, total: number }>}
    */
   async list(params = {}) {
-    const { page = 1, page_size = 20, ...filters } = params
+    const { page = 1, page_size = 20, sort_by, sort_order, filters = {} } = params
     const response = await this.client.get(this.endpoint, {
-      params: { page, page_size, ...filters }
+      params: { page, page_size, sort_by, sort_order, ...filters }
     })
 
     const data = response.data

package/src/entity/storage/LocalStorage.js

@@ -58,26 +58,47 @@ export class LocalStorage {
 
   /**
    * List entities with pagination/filtering
-   * @param {object} params - { page, page_size, sort_by, sort_order, ...filters }
+   * @param {object} params - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.page_size=20] - Items per page
+   * @param {string} [params.sort_by] - Field to sort by
+   * @param {string} [params.sort_order='asc'] - Sort order ('asc' or 'desc')
+   * @param {object} [params.filters] - Field filters { field: value }
+   * @param {string} [params.search] - Search query (substring match on string fields)
    * @returns {Promise<{ items: Array, total: number }>}
    */
   async list(params = {}) {
-    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', ...filters } = params
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {}, search } = params
 
     let items = this._getAll()
 
-    // Apply filters
+    // Apply filters (exact match for dropdown filters)
     for (const [key, value] of Object.entries(filters)) {
       if (value === null || value === undefined || value === '') continue
       items = items.filter(item => {
         const itemValue = item[key]
+        // Use exact match for filters (case-insensitive for strings)
         if (typeof value === 'string' && typeof itemValue === 'string') {
-          return itemValue.toLowerCase().includes(value.toLowerCase())
+          return itemValue.toLowerCase() === value.toLowerCase()
         }
         return itemValue === value
       })
     }
 
+    // Apply search (substring match on all string fields)
+    if (search && search.trim()) {
+      const query = search.toLowerCase().trim()
+      items = items.filter(item => {
+        // Search in all string fields
+        for (const value of Object.values(item)) {
+          if (typeof value === 'string' && value.toLowerCase().includes(query)) {
+            return true
+          }
+        }
+        return false
+      })
+    }
+
     const total = items.length
 
     // Apply sorting

package/src/entity/storage/MemoryStorage.js

@@ -48,11 +48,16 @@ export class MemoryStorage {
 
   /**
    * List entities with pagination/filtering
-   * @param {object} params - { page, page_size, sort_by, sort_order, ...filters }
+   * @param {object} params - Query parameters
+   * @param {number} [params.page=1] - Page number (1-based)
+   * @param {number} [params.page_size=20] - Items per page
+   * @param {string} [params.sort_by] - Field to sort by
+   * @param {string} [params.sort_order='asc'] - Sort order ('asc' or 'desc')
+   * @param {object} [params.filters] - Field filters { field: value }
    * @returns {Promise<{ items: Array, total: number }>}
    */
   async list(params = {}) {
-    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', ...filters } = params
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', filters = {} } = params
 
     let items = this._getAll()
 

package/src/module/moduleRegistry.js

@@ -44,15 +44,25 @@ const registry = {
    * Add routes for this module
    * @param {string} prefix - Path prefix for all routes (e.g., 'agents')
    * @param {Array} moduleRoutes - Route definitions with relative paths
-   * @param {object} options - { entity?: string } - Entity name for permission checking
+   * @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.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)
    */
   addRoutes(prefix, moduleRoutes, options = {}) {
+    const { entity, parent, label } = options
     const prefixedRoutes = moduleRoutes.map(route => ({
       ...route,
       path: route.path ? `${prefix}/${route.path}` : prefix,
       meta: {
         ...route.meta,
-        ...(options.entity && { entity: options.entity })
+        ...(entity && { entity }),
+        ...(parent && { parent }),
+        ...(label && { navLabel: label })
       }
     }))
     routes.push(...prefixedRoutes)
@@ -193,6 +203,19 @@ export function getEntityConfig(name) {
   return entityConfigs.get(name)
 }
 
+/**
+ * Get sibling routes (routes sharing the same parent entity + param)
+ * @param {string} parentEntity - Parent entity name
+ * @param {string} parentParam - Parent route param
+ * @returns {Array} Routes with matching parent config
+ */
+export function getSiblingRoutes(parentEntity, parentParam) {
+  return routes.filter(route => {
+    const parent = route.meta?.parent
+    return parent?.entity === parentEntity && parent?.param === parentParam
+  })
+}
+
 /**
  * Check if a route belongs to a family
  */

package/src/styles/theme/components.css

@@ -284,3 +284,46 @@
   background: var(--p-primary-100);
   color: var(--fad-primary);
 }
+
+/* ==========================================================================
+ * Page Navigation (breadcrumb + navlinks)
+ * ========================================================================== */
+
+.fad-page-nav {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: var(--fad-space-sm);
+}
+
+.fad-page-nav-breadcrumb {
+  flex: 1;
+}
+
+.fad-page-nav-links {
+  display: flex;
+  align-items: center;
+  gap: var(--fad-space-sm);
+  font-size: var(--fad-font-size-sm);
+}
+
+.fad-page-nav-separator {
+  color: var(--fad-text-muted);
+}
+
+.fad-page-nav-link {
+  color: var(--fad-primary);
+  text-decoration: none;
+  transition: color var(--fad-transition-fast);
+}
+
+.fad-page-nav-link:hover {
+  color: var(--fad-primary-hover);
+  text-decoration: underline;
+}
+
+.fad-page-nav-link--active {
+  color: var(--fad-text-primary);
+  font-weight: var(--fad-font-weight-medium);
+  pointer-events: none;
+}