@quazardous/qdadm 1.19.3

package/src/components/layout/BaseLayout.vue

@@ -0,0 +1,190 @@
+<script setup lang="ts">
+/**
+ * BaseLayout - Root of the 3-level layout inheritance chain
+ *
+ * Defines all standard zones for the admin application:
+ * - header: Top bar with branding
+ * - menu: Navigation sidebar
+ * - breadcrumb: Breadcrumb trail
+ * - sidebar: Optional secondary sidebar (empty by default)
+ * - main: Primary content area (slot for child layouts)
+ * - footer: Footer with optional branding
+ * - toaster: Toast notifications overlay
+ * - user-info: User info in sidebar (separate from footer)
+ *
+ * Each zone renders blocks from ZoneRegistry, with defaults
+ * provided when no blocks are registered.
+ *
+ * Inheritance pattern (Twig-style):
+ *   BaseLayout renders Zone components for each area
+ *   -> Child layouts (List, Form, Dashboard) extend by providing content to main zone
+ *   -> Entity pages extend child layouts with entity-specific customizations
+ *
+ * Usage:
+ * <BaseLayout>
+ *   <template #main>
+ *     <!-- Page content here -->
+ *   </template>
+ * </BaseLayout>
+ *
+ * Or with RouterView for nested routes:
+ * <BaseLayout />
+ */
+import { useSlots, provide, ref } from 'vue'
+import { RouterView } from 'vue-router'
+import ConfirmDialog from 'primevue/confirmdialog'
+import Zone from './Zone.vue'
+import { LAYOUT_ZONES } from '../../zones/zones'
+import { useGuardDialog } from '../../composables/useGuardStore'
+import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
+import type { BreadcrumbItem, NavLinkItem } from '../../composables/useNavContext'
+
+// Default components for zones
+import DefaultHeader from './defaults/DefaultHeader.vue'
+import DefaultMenu from './defaults/DefaultMenu.vue'
+import DefaultFooter from './defaults/DefaultFooter.vue'
+import DefaultUserInfo from './defaults/DefaultUserInfo.vue'
+import DefaultBreadcrumb from './defaults/DefaultBreadcrumb.vue'
+// DefaultToaster removed - Toast is now provided by Kernel at root level
+
+const slots = useSlots()
+const hasMainSlot: boolean = !!slots.main
+
+// Guard dialog from shared store (registered by useBareForm/useForm when a form is active)
+const guardDialog = useGuardDialog()
+
+// Provide breadcrumb/navlinks override mechanism for child pages
+const breadcrumbOverride = ref<BreadcrumbItem[] | null>(null)
+const navlinksOverride = ref<NavLinkItem[] | null>(null)
+provide('qdadmBreadcrumbOverride', breadcrumbOverride)
+provide('qdadmNavlinksOverride', navlinksOverride)
+</script>
+
+<template>
+  <div class="base-layout">
+    <!-- Sidebar (contains header, menu, user-info, footer) -->
+    <aside class="sidebar">
+      <!-- Header zone: branding, logo -->
+      <Zone
+        :name="LAYOUT_ZONES.HEADER"
+        :default-component="DefaultHeader"
+      />
+
+      <!-- Menu zone: navigation -->
+      <Zone
+        :name="LAYOUT_ZONES.MENU"
+        :default-component="DefaultMenu"
+      />
+
+      <!-- User info (special zone between menu and footer) -->
+      <DefaultUserInfo />
+
+      <!-- Footer zone: powered by, etc. -->
+      <Zone
+        :name="LAYOUT_ZONES.FOOTER"
+        :default-component="DefaultFooter"
+      />
+
+      <!-- Always-visible notification status (hidden when collapsed) -->
+      <Zone name="_app:notification-status" class="sidebar-notification-status" />
+    </aside>
+
+    <!-- Main content area -->
+    <div class="main-area">
+      <!-- Breadcrumb zone -->
+      <Zone
+        :name="LAYOUT_ZONES.BREADCRUMB"
+        :default-component="DefaultBreadcrumb"
+      />
+
+      <!-- Sidebar zone (optional secondary sidebar) -->
+      <div class="content-with-sidebar">
+        <Zone :name="LAYOUT_ZONES.SIDEBAR" />
+
+        <!-- Main zone: primary content -->
+        <main class="main-content">
+          <Zone :name="LAYOUT_ZONES.MAIN">
+            <!-- Allow slot override or RouterView for nested routes -->
+            <template v-if="hasMainSlot">
+              <slot name="main" />
+            </template>
+            <RouterView v-else />
+          </Zone>
+        </main>
+      </div>
+    </div>
+
+    <!-- Toast is now provided by Kernel at root level -->
+
+    <!-- Notification panel (rendered outside sidebar, follows sidebar position) -->
+    <Zone name="_app:notifications" />
+
+    <!-- Confirm dialog (global) -->
+    <ConfirmDialog />
+
+    <!-- Unsaved Changes Dialog (auto-rendered when a form registers guardDialog) -->
+    <UnsavedChangesDialog
+      v-if="guardDialog"
+      :visible="guardDialog.visible.value"
+      :saving="guardDialog.saving?.value ?? false"
+      :message="guardDialog.message"
+      :hasOnSave="guardDialog.hasOnSave"
+      @saveAndLeave="guardDialog.onSaveAndLeave"
+      @leave="guardDialog.onLeave"
+      @stay="guardDialog.onStay"
+    />
+  </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.).
+ */
+.base-layout {
+  display: flex;
+  min-height: 100vh;
+}
+
+.sidebar {
+  width: var(--fad-sidebar-width, 18rem);
+  background: var(--p-surface-800, #1e293b);
+  color: var(--p-surface-0, white);
+  display: flex;
+  flex-direction: column;
+  position: fixed;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  z-index: 100;
+}
+
+.main-area {
+  flex: 1;
+  margin-left: var(--fad-sidebar-width, 18rem);
+  background: var(--p-surface-50, #f8fafc);
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.content-with-sidebar {
+  display: flex;
+  flex: 1;
+}
+
+.main-content {
+  flex: 1;
+  padding: 1.5rem;
+  overflow-y: auto;
+}
+
+/* Dark mode support */
+.dark-mode .sidebar {
+  background: var(--p-surface-900);
+}
+
+.dark-mode .main-area {
+  background: var(--p-surface-900);
+}
+</style>

package/src/components/layout/Breadcrumb.vue

@@ -0,0 +1,55 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script setup lang="ts">
+/**
+ * Breadcrumb - Navigation breadcrumb component
+ *
+ * Props:
+ * - items: Array of { label, to?, icon? }
+ *
+ * Last item is always rendered as current page (no link)
+ */
+import { RouterLink, type RouteLocationRaw } from 'vue-router'
+
+interface BreadcrumbItem {
+  label: string
+  to?: RouteLocationRaw
+  icon?: string
+}
+
+withDefaults(defineProps<{
+  items?: BreadcrumbItem[]
+}>(), {
+  items: () => []
+})
+</script>
+
+<template>
+  <nav class="breadcrumb" aria-label="Breadcrumb">
+    <ol class="breadcrumb-list">
+      <li
+        v-for="(item, index) in items"
+        :key="index"
+        class="breadcrumb-item"
+        :class="{ 'is-current': index === items.length - 1 }"
+      >
+        <template v-if="index > 0">
+          <i class="pi pi-chevron-right breadcrumb-separator" ></i>
+        </template>
+
+        <RouterLink
+          v-if="item.to && index < items.length - 1"
+          :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-text">
+          <i v-if="item.icon" :class="item.icon" ></i>
+          <span>{{ item.label }}</span>
+        </span>
+      </li>
+    </ol>
+  </nav>
+</template>

package/src/components/layout/DashboardLayout.vue

@@ -0,0 +1,104 @@
+<script setup lang="ts">
+/**
+ * DashboardLayout - Second level of layout inheritance for dashboard pages
+ *
+ * Extends BaseLayout by providing content to its `main` zone and defining
+ * dashboard-specific zones:
+ * - stats: Top area for KPI cards (CardsGrid component)
+ * - widgets: Main dashboard widgets area
+ * - recent-activity: Recent changes and activity log
+ *
+ * Each zone renders blocks from ZoneRegistry. Empty zones render nothing
+ * (no default widgets). Applications provide dashboard content by
+ * registering blocks to these zones.
+ *
+ * Inheritance pattern:
+ *   BaseLayout renders Zone components for each area
+ *   -> DashboardLayout fills main zone with dashboard structure
+ *   -> Dashboard pages extend with entity-specific customizations
+ *
+ * Usage:
+ * <DashboardLayout>
+ *   <!-- Optional: Override specific zones via slots -->
+ * </DashboardLayout>
+ *
+ * Or register blocks via ZoneRegistry:
+ *   registry.registerBlock(DASHBOARD_ZONES.STATS, {
+ *     component: StatsWidget,
+ *     id: 'kpi-cards',
+ *     weight: 10
+ *   })
+ */
+import { useSlots } from 'vue'
+import BaseLayout from './BaseLayout.vue'
+import Zone from './Zone.vue'
+import { DASHBOARD_ZONES } from '../../zones/zones'
+
+const slots = useSlots()
+</script>
+
+<template>
+  <BaseLayout>
+    <template #main>
+      <div class="dashboard-layout">
+        <!-- Stats zone: KPI cards, metrics -->
+        <section v-if="slots.stats" class="dashboard-stats">
+          <slot name="stats" />
+        </section>
+        <section v-else class="dashboard-stats">
+          <Zone :name="DASHBOARD_ZONES.STATS" />
+        </section>
+
+        <!-- Widgets zone: main dashboard widgets -->
+        <section v-if="slots.widgets" class="dashboard-widgets">
+          <slot name="widgets" />
+        </section>
+        <section v-else class="dashboard-widgets">
+          <Zone :name="DASHBOARD_ZONES.WIDGETS" />
+        </section>
+
+        <!-- Recent activity zone: activity log, recent changes -->
+        <section v-if="slots['recent-activity']" class="dashboard-recent-activity">
+          <slot name="recent-activity" />
+        </section>
+        <section v-else class="dashboard-recent-activity">
+          <Zone :name="DASHBOARD_ZONES.RECENT_ACTIVITY" />
+        </section>
+      </div>
+    </template>
+  </BaseLayout>
+</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.).
+ */
+.dashboard-layout {
+  display: flex;
+  flex-direction: column;
+  gap: 1.5rem;
+}
+
+.dashboard-stats {
+  /* Stats area typically uses CardsGrid */
+}
+
+.dashboard-widgets {
+  /* Main widgets area */
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.dashboard-recent-activity {
+  /* Recent activity area */
+}
+
+/* Empty zones should collapse - Zone renders nothing when no blocks */
+.dashboard-stats:empty,
+.dashboard-widgets:empty,
+.dashboard-recent-activity:empty {
+  display: none;
+}
+</style>

package/src/components/layout/FormLayout.vue

@@ -0,0 +1,256 @@
+<script setup lang="ts">
+/**
+ * FormLayout - Second level of the 3-level layout inheritance chain
+ *
+ * Extends BaseLayout by providing content to the `main` zone, and defines
+ * form-specific zones within that main area:
+ * - form-header: Title, back button, status indicators
+ * - form-fields: Main form fields area
+ * - form-tabs: Optional tabbed sections
+ * - actions: Save, cancel, delete buttons
+ *
+ * Inheritance pattern (Twig-style):
+ *   BaseLayout renders all standard zones (header, menu, footer, main...)
+ *   -> FormLayout fills the main zone with form structure
+ *   -> Entity pages (BooksEditPage.vue) fill form zones with entity fields
+ *
+ * Usage:
+ * <FormLayout>
+ *   <template #form-fields>
+ *     <FormField v-model="data.title" name="title" />
+ *   </template>
+ *   <template #actions>
+ *     <Button @click="save">Save</Button>
+ *   </template>
+ * </FormLayout>
+ *
+ * Or using Zone API for extension points:
+ * <FormLayout />  <!-- Renders zones from registry -->
+ */
+import { useSlots, provide, computed } from 'vue'
+import BaseLayout from './BaseLayout.vue'
+import Zone from './Zone.vue'
+import { FORM_ZONES } from '../../zones/zones'
+
+// Default components for form zones
+import DefaultFormActions from './defaults/DefaultFormActions.vue'
+
+interface Props {
+  /** Form loading state (displays spinner instead of fields) */
+  loading?: boolean
+  /** Form saving state (passed to actions) */
+  saving?: boolean
+  /** Form has unsaved changes (passed to actions) */
+  dirty?: boolean
+  /** Edit mode (changes action button labels) */
+  isEdit?: boolean
+  /** Whether to wrap form in a card component */
+  cardWrapper?: boolean
+  /** Whether to show the actions zone */
+  showActions?: boolean
+}
+
+interface FormEmit {
+  save: () => void
+  saveAndClose: () => void
+  cancel: () => void
+  delete: () => void
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  loading: false,
+  saving: false,
+  dirty: false,
+  isEdit: false,
+  cardWrapper: true,
+  showActions: true
+})
+
+const emit = defineEmits<{
+  'save': []
+  'saveAndClose': []
+  'cancel': []
+  'delete': []
+}>()
+
+const slots = useSlots()
+
+// Check which slots are provided by the parent
+const hasFormHeaderSlot = computed((): boolean => !!slots['form-header'])
+const hasFormFieldsSlot = computed((): boolean => !!slots['form-fields'])
+const hasFormTabsSlot = computed((): boolean => !!slots['form-tabs'])
+const hasActionsSlot = computed((): boolean => !!slots.actions)
+
+// Provide form state to child zones (DefaultFormActions needs these)
+provide('qdadmFormState', computed(() => ({
+  loading: props.loading,
+  saving: props.saving,
+  dirty: props.dirty,
+  isEdit: props.isEdit
+})))
+
+// Provide form events for child zones to emit
+provide<FormEmit>('qdadmFormEmit', {
+  save: () => emit('save'),
+  saveAndClose: () => emit('saveAndClose'),
+  cancel: () => emit('cancel'),
+  delete: () => emit('delete')
+})
+</script>
+
+<template>
+  <BaseLayout>
+    <template #main>
+      <div class="form-layout" :class="{ loading }">
+        <!-- Form Header Zone: title, back button, status indicators -->
+        <div class="form-header-zone">
+          <Zone :name="FORM_ZONES.FORM_HEADER">
+            <template v-if="hasFormHeaderSlot">
+              <slot name="form-header" />
+            </template>
+          </Zone>
+        </div>
+
+        <!-- Loading State -->
+        <div v-if="loading" class="form-loading-state">
+          <i class="pi pi-spin pi-spinner loading-spinner"></i>
+        </div>
+
+        <!-- Form Content -->
+        <template v-else>
+          <!-- Card wrapper or direct content -->
+          <div v-if="cardWrapper" class="form-card">
+            <!-- Form Fields Zone: main form fields area -->
+            <div class="form-fields-zone">
+              <Zone :name="FORM_ZONES.FORM_FIELDS">
+                <template v-if="hasFormFieldsSlot">
+                  <slot name="form-fields" />
+                </template>
+              </Zone>
+            </div>
+
+            <!-- Form Tabs Zone: optional tabbed sections -->
+            <div v-if="hasFormTabsSlot" class="form-tabs-zone">
+              <Zone :name="FORM_ZONES.FORM_TABS">
+                <slot name="form-tabs" />
+              </Zone>
+            </div>
+
+            <!-- Actions Zone: save, cancel, delete buttons -->
+            <div v-if="showActions" class="form-actions-zone">
+              <!-- Slot override takes priority over Zone -->
+              <template v-if="hasActionsSlot">
+                <slot name="actions" />
+              </template>
+              <!-- Otherwise use Zone with default component -->
+              <Zone
+                v-else
+                :name="FORM_ZONES.ACTIONS"
+                :default-component="DefaultFormActions"
+              />
+            </div>
+          </div>
+
+          <!-- Without card wrapper -->
+          <template v-else>
+            <!-- Form Fields Zone -->
+            <div class="form-fields-zone">
+              <Zone :name="FORM_ZONES.FORM_FIELDS">
+                <template v-if="hasFormFieldsSlot">
+                  <slot name="form-fields" />
+                </template>
+              </Zone>
+            </div>
+
+            <!-- Form Tabs Zone -->
+            <div v-if="hasFormTabsSlot" class="form-tabs-zone">
+              <Zone :name="FORM_ZONES.FORM_TABS">
+                <slot name="form-tabs" />
+              </Zone>
+            </div>
+
+            <!-- Actions Zone -->
+            <div v-if="showActions" class="form-actions-zone">
+              <!-- Slot override takes priority over Zone -->
+              <template v-if="hasActionsSlot">
+                <slot name="actions" />
+              </template>
+              <!-- Otherwise use Zone with default component -->
+              <Zone
+                v-else
+                :name="FORM_ZONES.ACTIONS"
+                :default-component="DefaultFormActions"
+              />
+            </div>
+          </template>
+        </template>
+      </div>
+    </template>
+  </BaseLayout>
+</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.).
+ */
+.form-layout {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.form-layout.loading {
+  min-height: 300px;
+}
+
+.form-loading-state {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  padding: 3rem;
+  flex: 1;
+}
+
+.loading-spinner {
+  font-size: 2rem;
+  color: var(--p-primary-500);
+}
+
+.form-card {
+  background: var(--p-surface-0);
+  border-radius: var(--p-border-radius);
+  padding: 1.5rem;
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+}
+
+.form-header-zone {
+  /* Form header inherits page header styles */
+}
+
+.form-fields-zone {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.form-tabs-zone {
+  margin-top: 1rem;
+}
+
+.form-actions-zone {
+  margin-top: 1.5rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--p-surface-200);
+}
+
+/* Dark mode support */
+.dark-mode .form-card {
+  background: var(--p-surface-800);
+  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3);
+}
+
+.dark-mode .form-actions-zone {
+  border-top-color: var(--p-surface-700);
+}
+</style>