@quazardous/qdadm 1.19.3

package/src/components/layout/PageNav.vue

@@ -0,0 +1,192 @@
+<script setup lang="ts">
+/**
+ * PageNav - Navigation provider for navlinks (child/sibling routes)
+ *
+ * This component provides navlinks to AppLayout via provide/inject.
+ * Breadcrumb is now handled automatically by useNavContext + activeStack.
+ *
+ * Layout (rendered in AppLayout):
+ *   Books > "Dune"                    Details | Loans | Reviews
+ *     ↑ breadcrumb (from useNavContext)      ↑ navlinks (from PageNav)
+ *
+ * Auto-detects from current route:
+ * - Navlinks: sibling routes (same parent entity + param) or children routes
+ *
+ * Props:
+ * - showDetailsLink: Show "Details" link in navlinks (default: false)
+ */
+import { computed, watch, inject, type Ref } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { getSiblingRoutes, getChildRoutes, type ModuleRoute, type ParentConfig } from '../../module/moduleRegistry'
+import { useOrchestrator } from '../../orchestrator/useOrchestrator.js'
+import type { EntityManager } from '../../entity/EntityManager'
+import type { EntityRecord } from '../../types'
+
+interface NavLink {
+  label: string
+  to: { name: string | undefined; params: Record<string, unknown> }
+  active: boolean
+}
+
+// Inject override ref from AppLayout
+const navlinksOverride = inject<Ref<NavLink[] | null> | null>('qdadmNavlinksOverride', null)
+
+const props = defineProps<{
+  // Show "Details" link in navlinks (default: false since breadcrumb shows current page)
+  showDetailsLink?: boolean
+}>()
+
+const route = useRoute()
+const router = useRouter()
+const { getManager } = useOrchestrator()
+
+// Parent config from route meta
+const parentConfig = computed<ParentConfig | undefined>(() => route.meta?.parent as ParentConfig | undefined)
+
+/**
+ * Get default item route for an entity manager
+ * Checks which routes actually exist and returns the appropriate one:
+ * - Prefers -edit if it exists (editable entity)
+ * - Falls back to -show if -edit doesn't exist
+ * - Returns null if neither exists
+ */
+function getDefaultItemRoute(manager: EntityManager<EntityRecord> | null): string | null {
+  if (!manager) return null
+
+  const editRoute = `${manager.routePrefix}-edit`
+  const showRoute = `${manager.routePrefix}-show`
+
+  // Check which routes actually exist and return the first available
+  if (router.hasRoute(editRoute)) return editRoute
+  if (router.hasRoute(showRoute)) return showRoute
+
+  return null
+}
+
+// Sibling navlinks (routes with same parent)
+const siblingNavlinks = computed<NavLink[]>(() => {
+  if (!parentConfig.value) return []
+
+  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: ModuleRoute) => {
+    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 navRoutes.map((siblingRoute: ModuleRoute): NavLink => {
+    const manager = siblingRoute.meta?.entity ? getManager(siblingRoute.meta.entity) : null
+    const label = (siblingRoute.meta?.navLabel as string) || manager?.labelPlural || siblingRoute.name || ''
+
+    return {
+      label,
+      to: { name: siblingRoute.name, params: route.params as Record<string, unknown> },
+      active: route.name === siblingRoute.name
+    }
+  })
+})
+
+// Child navlinks (when on parent detail page, show links to children)
+const childNavlinks = computed<NavLink[]>(() => {
+  // Only when NOT on a child route (no parentConfig)
+  if (parentConfig.value) return []
+
+  const entityName = route.meta?.entity as string | undefined
+  if (!entityName) return []
+
+  // Get current entity's manager to determine idField
+  const currentManager = getManager(entityName)
+  const entityId = route.params[currentManager?.idField || 'id'] as string | undefined
+
+  // Only show children when we have an entity ID (not on create pages)
+  if (!entityId) return []
+
+  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: ModuleRoute) => {
+    const name = r.name || ''
+    const path = r.path || ''
+    return !name.match(/-(create|edit|new)$/) && !path.match(/\/(create|edit|new)$/)
+  })
+
+  if (navRoutes.length === 0) return []
+
+  // Build navlinks to child routes
+  return navRoutes.map((childRoute: ModuleRoute): NavLink => {
+    const childManager = childRoute.meta?.entity ? getManager(childRoute.meta.entity) : null
+    const label = (childRoute.meta?.navLabel as string) || childManager?.labelPlural || childRoute.name || ''
+    const parentParam = (childRoute.meta?.parent as ParentConfig)?.param || currentManager?.idField || 'id'
+
+    return {
+      label,
+      to: { name: childRoute.name, params: { [parentParam]: entityId } },
+      active: false
+    }
+  })
+})
+
+// Combined navlinks with optional "Details" link
+const allNavlinks = computed<NavLink[]>(() => {
+  // 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] as string | undefined
+    const parentManager = getManager(parentEntityName)
+
+    // Guard: need valid manager and parentId to build links
+    if (!parentManager || !parentId) return []
+
+    // Details link is optional since breadcrumb already shows parent
+    if (props.showDetailsLink) {
+      const parentRouteName = itemRoute || getDefaultItemRoute(parentManager)
+      const isOnParentRoute = route.name === parentRouteName
+
+      // Details link to parent item page
+      const detailsLink: NavLink = {
+        label: 'Details',
+        to: { name: parentRouteName ?? undefined, params: { [parentManager.idField]: parentId } },
+        active: isOnParentRoute
+      }
+
+      return [detailsLink, ...siblingNavlinks.value]
+    }
+
+    return siblingNavlinks.value
+  }
+
+  // Case 2: On parent detail page - show children + optional Details (active)
+  if (childNavlinks.value.length > 0) {
+    // Details link is optional since breadcrumb already shows current page
+    if (props.showDetailsLink) {
+      const detailsLink: NavLink = {
+        label: 'Details',
+        to: { name: route.name as string | undefined, params: route.params as Record<string, unknown> },
+        active: true
+      }
+      return [detailsLink, ...childNavlinks.value]
+    }
+    return childNavlinks.value
+  }
+
+  return []
+})
+
+// Sync navlinks to AppLayout via provide/inject
+watch([allNavlinks, () => route.fullPath], ([links]) => {
+  if (navlinksOverride) {
+    navlinksOverride.value = links as NavLink[]
+  }
+}, { immediate: true })
+</script>
+
+<template>
+  <!-- PageNav provides navlinks to AppLayout via inject, renders nothing -->
+  <span v-if="false"></span>
+</template>

package/src/components/layout/SidebarBox.vue

@@ -0,0 +1,87 @@
+<script setup lang="ts">
+/**
+ * SidebarBox - Reusable sidebar footer item component
+ *
+ * Provides consistent structure for icon + text boxes in the sidebar.
+ * Used for user info, impersonation, powered-by, etc.
+ *
+ * Props:
+ *   - icon: PrimeIcons class (e.g., "pi-user") OR slot for custom content
+ *   - title: Primary text
+ *   - subtitle: Secondary text (optional)
+ *   - variant: Color variant ('default' | 'impersonator')
+ *
+ * Slots:
+ *   - icon: Custom icon content (overrides icon prop)
+ *   - subtitle-content: Custom subtitle content (overrides subtitle prop)
+ *   - default: Extra content after text (e.g., logout button)
+ *   - full: Full-width content (bypasses icon+text structure, for controls/dropdowns)
+ *
+ * Usage:
+ *   <SidebarBox icon="pi-user" title="John" subtitle="Admin" />
+ *   <SidebarBox variant="impersonator" title="Impersonating" subtitle="bob" />
+ *   <SidebarBox>
+ *     <template #icon><img src="logo.svg" /></template>
+ *     <template #subtitle-content>powered by qdadm</template>
+ *   </SidebarBox>
+ *   <SidebarBox>
+ *     <template #full>
+ *       <label>Impersonate</label>
+ *       <AutoComplete ... />
+ *     </template>
+ *   </SidebarBox>
+ */
+
+import { useSlots, computed, type ComputedRef } from 'vue'
+
+type SidebarBoxVariant = 'default' | 'impersonator'
+
+interface Props {
+  icon?: string | null
+  title?: string
+  subtitle?: string
+  variant?: SidebarBoxVariant
+}
+
+withDefaults(defineProps<Props>(), {
+  icon: null,
+  title: '',
+  subtitle: '',
+  variant: 'default'
+})
+
+const slots = useSlots()
+const hasFullSlot: ComputedRef<boolean> = computed(() => !!slots.full)
+</script>
+
+<template>
+  <div
+    class="sidebar-box"
+    :class="{
+      'sidebar-box--impersonator': variant === 'impersonator',
+      'sidebar-box--full': hasFullSlot
+    }"
+  >
+    <!-- Full-width mode (for controls/dropdowns) -->
+    <div v-if="hasFullSlot" class="sidebar-box-full">
+      <slot name="full"></slot>
+    </div>
+
+    <!-- Standard icon + text mode -->
+    <div v-else class="sidebar-box-inner">
+      <div class="sidebar-box-icon">
+        <slot name="icon">
+          <i v-if="icon" :class="['pi', icon]"></i>
+        </slot>
+      </div>
+      <div class="sidebar-box-content">
+        <div v-if="title" class="sidebar-box-title">{{ title }}</div>
+        <div v-if="subtitle" class="sidebar-box-subtitle">
+          <slot name="subtitle">{{ subtitle }}</slot>
+        </div>
+        <slot name="subtitle-content"></slot>
+      </div>
+      <slot></slot>
+    </div>
+  </div>
+</template>

package/src/components/layout/Zone.vue

@@ -0,0 +1,182 @@
+<script setup lang="ts">
+/**
+ * Zone - Renders blocks registered in a zone from ZoneRegistry
+ *
+ * Reads blocks from the injected ZoneRegistry and renders them
+ * sorted by weight. Supports default content when no blocks registered.
+ *
+ * **Reactivity**: The Zone component automatically re-renders when blocks
+ * are added, removed, or modified in the registry at runtime.
+ *
+ * Handles wrapped blocks by building nested component structures:
+ * - Outer wrappers (lower weight) wrap inner wrappers
+ * - Innermost component is the original block
+ *
+ * Usage:
+ * <Zone name="header" />
+ * <Zone name="sidebar" :default-component="DefaultSidebar" />
+ * <Zone name="main"><RouterView /></Zone>
+ */
+import { computed, inject, h, defineComponent, useSlots, type Component, type VNode, type PropType, type Slot } from 'vue'
+import type { ZoneRegistry, BlockConfig } from '../../zones/ZoneRegistry'
+
+const props = defineProps({
+  /**
+   * Zone name (required) - must match a zone in ZoneRegistry
+   */
+  name: {
+    type: String,
+    required: true
+  },
+  /**
+   * Default component to render when no blocks are registered
+   */
+  defaultComponent: {
+    type: Object as PropType<Component | null>,
+    default: null
+  },
+  /**
+   * Props to pass to all blocks
+   */
+  blockProps: {
+    type: Object as PropType<Record<string, unknown>>,
+    default: () => ({})
+  }
+})
+
+const slots = useSlots()
+const hasDefaultSlot = computed<boolean>(() => !!slots.default)
+
+const registry = inject<ZoneRegistry | null>('qdadmZoneRegistry', null)
+
+// Get the reactive version ref for tracking changes
+const version = registry?.getVersionRef?.()
+
+const blocks = computed<BlockConfig[]>(() => {
+  if (!registry) {
+    if ((import.meta as { env?: { DEV?: boolean } }).env?.DEV) {
+      console.warn(`[Zone] ZoneRegistry not injected. Zone "${props.name}" will render nothing.`)
+    }
+    return []
+  }
+  // Access version.value to create reactive dependency
+  // This ensures the computed re-evaluates when blocks change
+  if (version) {
+    void version.value
+  }
+  return registry.getBlocks(props.name)
+})
+
+const hasBlocks = computed<boolean>(() => blocks.value.length > 0)
+
+const showDefault = computed<boolean>(() => {
+  return !hasBlocks.value && (props.defaultComponent !== null || registry?.getDefault(props.name) !== null)
+})
+
+const showSlot = computed<boolean>(() => {
+  return !hasBlocks.value && !showDefault.value && hasDefaultSlot.value
+})
+
+const defaultComp = computed<Component | null>(() => {
+  return props.defaultComponent || registry?.getDefault(props.name) || null
+})
+
+/**
+ * Create a wrapper component that renders nested wrappers around inner content
+ *
+ * This creates a functional component that builds the nested structure
+ * once per block, avoiding the infinite re-render issue.
+ *
+ * Slot content from the Zone is passed to the innermost block component,
+ * allowing the block to render Zone's children (e.g., form fields).
+ *
+ * @param block - Block config with wrappers array
+ * @param mergedProps - Props to pass to the innermost component
+ * @param slotFn - Slot function to pass to innermost component
+ * @returns Vue component definition
+ */
+function createWrappedComponent(block: BlockConfig, mergedProps: Record<string, unknown>, slotFn: Slot | undefined): Component {
+  return defineComponent({
+    name: 'WrappedBlock',
+    render(): VNode {
+      // Start with the innermost component (the original block)
+      // Pass Zone's slot content to allow block to render it
+      const innerSlots = slotFn ? { default: slotFn } : {}
+      let current: VNode = h(block.component, mergedProps, innerSlots)
+
+      // Build from inside out: last wrapper in array wraps the innermost
+      // Wrappers are already sorted by weight (lower = outer)
+      // So we reverse to build from inside out
+      const reversedWrappers = [...(block.wrappers || [])].reverse()
+
+      for (const wrapper of reversedWrappers) {
+        const inner = current
+        current = h(wrapper.component, wrapper.props || {}, {
+          default: () => inner
+        })
+      }
+
+      return current
+    }
+  })
+}
+
+/**
+ * Computed map of wrapped block components
+ * Memoizes the wrapped components to avoid re-creating them on every render
+ *
+ * Note: Slot function is passed to allow Zone's children to be rendered
+ * inside the innermost block component.
+ */
+const wrappedComponents = computed<Map<string | number | null | undefined, Component>>(() => {
+  const map = new Map<string | number | null | undefined, Component>()
+  // Get slot function to pass to innermost block
+  const slotFn = slots.default
+  for (const block of blocks.value) {
+    if (block.wrappers && block.wrappers.length > 0) {
+      const key = block.id || block.weight
+      const mergedProps = { ...props.blockProps, ...block.props }
+      map.set(key, createWrappedComponent(block, mergedProps, slotFn))
+    }
+  }
+  return map
+})
+
+/**
+ * Get the wrapped component for a block
+ */
+function getWrappedComponent(block: BlockConfig): Component | undefined {
+  const key = block.id || block.weight
+  return wrappedComponents.value.get(key)
+}
+</script>
+
+<template>
+  <div :data-zone="name" class="qdadm-zone">
+    <template v-if="hasBlocks">
+      <template v-for="block in blocks" :key="block.id || block.weight">
+        <!-- Render wrapped blocks using memoized component -->
+        <component
+          v-if="block.wrappers"
+          :is="getWrappedComponent(block)"
+        />
+        <!-- Render simple blocks directly, passing Zone's slot content -->
+        <component
+          v-else
+          :is="block.component"
+          v-bind="{ ...blockProps, ...block.props }"
+        >
+          <slot />
+        </component>
+      </template>
+    </template>
+    <component
+      v-else-if="showDefault"
+      :is="defaultComp"
+      v-bind="blockProps"
+    >
+      <slot />
+    </component>
+    <slot v-else-if="showSlot" />
+  </div>
+</template>

package/src/components/layout/defaults/DefaultBreadcrumb.vue

@@ -0,0 +1,149 @@
+<script setup lang="ts">
+/**
+ * DefaultBreadcrumb - Default breadcrumb component for BaseLayout
+ *
+ * Displays breadcrumb trail and optional navlinks.
+ * Extracted from AppLayout for zone-based architecture.
+ *
+ * This is the default component rendered in the "breadcrumb" zone
+ * when no blocks are registered.
+ */
+import { computed, inject, ref, type Ref } from 'vue'
+import { RouterLink, useRoute } from 'vue-router'
+import { useNavContext, type BreadcrumbItem, type NavLinkItem } from '../../../composables/useNavContext'
+import Breadcrumb from 'primevue/breadcrumb'
+
+interface FeaturesConfig {
+  breadcrumb?: boolean
+  [key: string]: unknown
+}
+
+const route = useRoute()
+const features = inject<FeaturesConfig>('qdadmFeatures', { breadcrumb: true })
+
+// Navigation context (breadcrumb + navlinks from route config)
+const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks } = useNavContext()
+
+// Allow child pages to override breadcrumb/navlinks via provide/inject
+const breadcrumbOverride = inject<Ref<BreadcrumbItem[] | null>>('qdadmBreadcrumbOverride', ref(null))
+const navlinksOverride = inject<Ref<NavLinkItem[] | null>>('qdadmNavlinksOverride', ref(null))
+
+// Use override if provided, otherwise default from useNavContext
+const breadcrumbItems = computed<BreadcrumbItem[]>(() => breadcrumbOverride.value || defaultBreadcrumb.value)
+const navlinks = computed<NavLinkItem[]>(() => navlinksOverride.value || defaultNavlinks.value)
+
+// Show breadcrumb if enabled, has items, and not on home page
+const showBreadcrumb = computed<boolean>(() => {
+  if (!features.breadcrumb || breadcrumbItems.value.length === 0) return false
+  // Don't show on home page (just "Dashboard" with no parents)
+  if (route.name === 'dashboard') return false
+  return true
+})
+</script>
+
+<template>
+  <div v-if="showBreadcrumb" class="default-breadcrumb">
+    <Breadcrumb :model="breadcrumbItems" class="breadcrumb-component">
+      <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="breadcrumb-navlinks">
+      <template v-for="(link, index) in navlinks" :key="link.to?.name || index">
+        <span v-if="index > 0" class="navlinks-separator">|</span>
+        <RouterLink
+          :to="link.to"
+          class="navlink"
+          :class="{ 'navlink--active': link.active }"
+        >
+          {{ link.label }}
+        </RouterLink>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/*
+ * Only keep styles here that REQUIRE scoping (:deep, dynamic binding, component-specific overrides).
+ * Generic/reusable styles belong in src/styles/ partials (see _forms.scss, _cards.scss, etc.).
+ */
+.default-breadcrumb {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 1.5rem;
+  padding-bottom: 0;
+}
+
+.breadcrumb-navlinks {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-size: 0.875rem;
+}
+
+.navlinks-separator {
+  color: var(--p-surface-400, #94a3b8);
+}
+
+.navlink {
+  color: var(--p-primary-500, #3b82f6);
+  text-decoration: none;
+  transition: color 0.15s;
+}
+
+.navlink:hover {
+  color: var(--p-primary-700, #1d4ed8);
+  text-decoration: underline;
+}
+
+.navlink--active {
+  color: var(--p-surface-700, #334155);
+  font-weight: 500;
+  pointer-events: none;
+}
+
+/* Override PrimeVue Breadcrumb styles for flat look */
+.default-breadcrumb :deep(.p-breadcrumb) {
+  background: transparent;
+  border: none;
+  padding: 0;
+  border-radius: 0;
+}
+
+.default-breadcrumb :deep(.p-breadcrumb-list) {
+  gap: 0.5rem;
+}
+
+.default-breadcrumb :deep(.p-breadcrumb-item-link),
+.breadcrumb-link {
+  color: var(--p-primary-500, #3b82f6);
+  text-decoration: none;
+  font-size: 0.875rem;
+}
+
+.default-breadcrumb :deep(.p-breadcrumb-item-link:hover),
+.breadcrumb-link:hover {
+  color: var(--p-primary-700, #1d4ed8);
+  text-decoration: underline;
+}
+
+.breadcrumb-current {
+  color: var(--p-surface-600, #475569);
+  font-size: 0.875rem;
+}
+
+.default-breadcrumb :deep(.p-breadcrumb-separator) {
+  color: var(--p-surface-400, #94a3b8);
+}
+</style>

package/src/components/layout/defaults/DefaultFooter.vue

@@ -0,0 +1,89 @@
+<script setup lang="ts">
+/**
+ * DefaultFooter - Default footer component for BaseLayout
+ *
+ * Displays "powered by qdadm" branding with version.
+ * Extracted from AppLayout for zone-based architecture.
+ *
+ * This is the default component rendered in the "footer" zone
+ * when no blocks are registered.
+ */
+import { inject } from 'vue'
+import Zone from '../Zone.vue'
+import qdadmLogo from '../../../assets/logo.svg'
+import { version as qdadmVersion } from '../../../../package.json'
+
+interface Features {
+  poweredBy?: boolean
+  [key: string]: boolean | undefined
+}
+
+const features = inject<Features>('qdadmFeatures', { poweredBy: true })
+</script>
+
+<template>
+  <div class="default-footer-wrapper">
+    <a
+      v-if="features.poweredBy"
+      href="https://github.com/quazardous/qdadm"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="default-footer"
+    >
+      <div class="footer-logo-wrapper">
+        <img :src="qdadmLogo" alt="qdadm" class="footer-logo" />
+        <!-- Notification badge overlay on logo -->
+        <Zone name="_app:notification-badge" />
+      </div>
+      <span class="footer-text">
+        powered by <strong>qdadm</strong> v{{ qdadmVersion }}
+      </span>
+    </a>
+  </div>
+</template>
+
+<style scoped>
+/*
+ * Only keep styles here that REQUIRE scoping (:deep, dynamic binding, component-specific overrides).
+ * Generic/reusable styles belong in src/styles/ partials (see _forms.scss, _cards.scss, etc.).
+ */
+.default-footer {
+  padding: 0.75rem 1rem;
+  border-top: 1px solid var(--p-surface-700, #334155);
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  opacity: 0.6;
+  transition: opacity 0.15s;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.default-footer:hover {
+  opacity: 1;
+}
+
+.default-footer-wrapper {
+  position: relative;
+}
+
+.footer-logo-wrapper {
+  position: relative;
+  flex-shrink: 0;
+}
+
+.footer-logo {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+.footer-text {
+  font-size: 0.625rem;
+  color: var(--p-surface-400, #94a3b8);
+  letter-spacing: 0.02em;
+}
+
+.footer-text strong {
+  color: var(--p-surface-300, #cbd5e1);
+}
+</style>