@quazardous/qdadm 1.19.3

package/src/components/layout/ListLayout.vue

@@ -0,0 +1,278 @@
+<script setup lang="ts">
+/**
+ * ListLayout - Second level of 3-level layout inheritance for list pages
+ *
+ * Extends BaseLayout by providing content to the "main" zone and
+ * defining list-specific zones within:
+ * - before-table: Filter bar, search, bulk actions
+ * - table: DataTable component
+ * - after-table: Summary, additional actions
+ * - pagination: Paginator controls
+ *
+ * Inheritance pattern (Twig-style):
+ *   BaseLayout (root)
+ *     -> ListLayout (fills main zone, defines list zones)
+ *       -> EntityListPage (fills list-specific slots)
+ *
+ * Usage:
+ * <ListLayout :items="data" :loading="isLoading">
+ *   <template #columns>
+ *     <Column field="name" header="Name" />
+ *   </template>
+ * </ListLayout>
+ *
+ * Zone customization via ZoneRegistry:
+ * ```js
+ * registry.registerBlock(LIST_ZONES.BEFORE_TABLE, {
+ *   component: CustomFilterBar,
+ *   id: 'custom-filter'
+ * })
+ * ```
+ */
+import { computed, useSlots, provide, type ComputedRef } from 'vue'
+import BaseLayout from './BaseLayout.vue'
+import Zone from './Zone.vue'
+import { LIST_ZONES } from '../../zones/zones'
+
+// Default components for list zones
+import DefaultTable from './defaults/DefaultTable.vue'
+import DefaultPagination from './defaults/DefaultPagination.vue'
+import FilterBar from '../lists/FilterBar.vue'
+
+interface PageEvent {
+  first: number
+  rows: number
+  page: number
+  pageCount: number
+}
+
+interface SortEvent {
+  sortField: string | ((item: unknown) => string) | undefined
+  sortOrder: 1 | -1 | 0 | undefined | null
+}
+
+interface TableProps {
+  items: unknown[]
+  loading: boolean
+  dataKey: string
+  selection: unknown[] | undefined
+  selectable: boolean
+  sortField?: string
+  sortOrder: 1 | -1
+}
+
+interface PaginationProps {
+  first: number
+  rows: number
+  totalRecords: number
+  rowsPerPageOptions: number[]
+}
+
+interface ListContext {
+  items: ComputedRef<unknown[]>
+  loading: ComputedRef<boolean>
+  selected: ComputedRef<unknown[] | undefined>
+  selectable: ComputedRef<boolean>
+}
+
+interface Props {
+  // Table data
+  /** Data items to display in the table */
+  items?: unknown[]
+  /** Loading state */
+  loading?: boolean
+  /** Field to use as unique key for rows */
+  dataKey?: string
+  // Selection
+  /** Current selection (v-model compatible) */
+  selected?: unknown[]
+  /** Enable row selection */
+  selectable?: boolean
+  // Sorting
+  /** Current sort field */
+  sortField?: string
+  /** Current sort order (1 = asc, -1 = desc) */
+  sortOrder?: 1 | -1
+  // Pagination
+  /** Enable pagination (in table or separate) */
+  paginator?: boolean
+  /** Use separate pagination zone (outside table) */
+  separatePagination?: boolean
+  /** Number of rows per page */
+  rows?: number
+  /** Options for rows per page dropdown */
+  rowsPerPageOptions?: number[]
+  /** Total number of records (for lazy/server-side pagination) */
+  totalRecords?: number
+  /** First record index (for lazy pagination) */
+  first?: number
+  /** Enable lazy (server-side) loading */
+  lazy?: boolean
+  // Search/Filter
+  /** Current search query (v-model compatible) */
+  searchQuery?: string
+  /** Search input placeholder */
+  searchPlaceholder?: string
+  /** Show filter bar zone */
+  showFilterBar?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  items: () => [],
+  loading: false,
+  dataKey: 'id',
+  selected: undefined,
+  selectable: false,
+  sortField: undefined,
+  sortOrder: 1,
+  paginator: true,
+  separatePagination: false,
+  rows: 10,
+  rowsPerPageOptions: () => [10, 25, 50, 100],
+  totalRecords: 0,
+  first: 0,
+  lazy: false,
+  searchQuery: '',
+  searchPlaceholder: 'Search...',
+  showFilterBar: true
+})
+
+const emit = defineEmits<{
+  'update:selected': [value: unknown[]]
+  'update:searchQuery': [value: string]
+  'page': [event: PageEvent]
+  'sort': [event: SortEvent]
+}>()
+
+const slots = useSlots()
+
+// Check for specific slot content
+const hasColumnsSlot = computed((): boolean => !!slots.columns)
+const hasBeforeTableSlot = computed((): boolean => !!slots['before-table'])
+const hasAfterTableSlot = computed((): boolean => !!slots['after-table'])
+const hasPaginationSlot = computed((): boolean => !!slots.pagination)
+
+// Provide list context to child components (for deep customization)
+provide<ListContext>('qdadmListContext', {
+  items: computed(() => props.items),
+  loading: computed(() => props.loading),
+  selected: computed(() => props.selected),
+  selectable: computed(() => props.selectable)
+})
+
+// Props bundle for table zone
+const tableProps = computed((): TableProps => ({
+  items: props.items,
+  loading: props.loading,
+  dataKey: props.dataKey,
+  selection: props.selected,
+  selectable: props.selectable,
+  sortField: props.sortField,
+  sortOrder: props.sortOrder
+}))
+
+// Props bundle for pagination zone
+const paginationProps = computed((): PaginationProps => ({
+  first: props.first,
+  rows: props.rows,
+  totalRecords: props.totalRecords,
+  rowsPerPageOptions: props.rowsPerPageOptions
+}))
+
+// Event handlers
+function onSelectionChange(value: unknown[]): void {
+  emit('update:selected', value)
+}
+
+function onSearchChange(value: string): void {
+  emit('update:searchQuery', value)
+}
+
+function onPage(event: PageEvent): void {
+  emit('page', event)
+}
+
+function onSort(event: SortEvent): void {
+  emit('sort', event)
+}
+</script>
+
+<template>
+  <BaseLayout>
+    <template #main>
+      <div class="list-layout">
+        <!-- Before-table zone: Filter bar, search, bulk actions -->
+        <Zone
+          v-if="showFilterBar"
+          :name="LIST_ZONES.BEFORE_TABLE"
+          :default-component="FilterBar"
+          :block-props="{
+            modelValue: searchQuery,
+            placeholder: searchPlaceholder,
+            'onUpdate:modelValue': onSearchChange
+          }"
+        >
+          <!-- Slot fallback if no blocks and no default -->
+          <template v-if="hasBeforeTableSlot">
+            <slot name="before-table" />
+          </template>
+        </Zone>
+
+        <!-- Table zone: DataTable -->
+        <!-- When columns slot is provided, we don't set default-component so slot content renders -->
+        <Zone
+          :name="LIST_ZONES.TABLE"
+          :default-component="hasColumnsSlot ? undefined : DefaultTable"
+          :block-props="{
+            ...tableProps,
+            'onUpdate:selection': onSelectionChange,
+            onSort: onSort
+          }"
+        >
+          <!-- Render DefaultTable with columns slot when slot is provided -->
+          <DefaultTable
+            v-bind="tableProps"
+            @update:selection="onSelectionChange"
+            @sort="onSort"
+          >
+            <slot name="columns" />
+          </DefaultTable>
+        </Zone>
+
+        <!-- After-table zone: Summary, additional actions -->
+        <Zone :name="LIST_ZONES.AFTER_TABLE">
+          <template v-if="hasAfterTableSlot">
+            <slot name="after-table" />
+          </template>
+        </Zone>
+
+        <!-- Pagination zone: Paginator (when separate from table) -->
+        <Zone
+          v-if="paginator && separatePagination"
+          :name="LIST_ZONES.PAGINATION"
+          :default-component="DefaultPagination"
+          :block-props="{
+            ...paginationProps,
+            onPage: onPage
+          }"
+        >
+          <template v-if="hasPaginationSlot">
+            <slot name="pagination" />
+          </template>
+        </Zone>
+      </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.).
+ */
+.list-layout {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+</style>

package/src/components/layout/PageHeader.vue

@@ -0,0 +1,156 @@
+<script setup lang="ts">
+/**
+ * PageHeader - Reusable page header with title and actions
+ *
+ * Props:
+ * - title: Page title (simple string) OR
+ * - titleParts: { action, entityName, entityLabel } for decorated rendering
+ * - badges: Custom badges from entity manager [{ label, severity }]
+ *
+ * Title rendering:
+ * - Simple: "Edit Agent" → <h1>Edit Agent</h1>
+ * - Decorated: { action: 'Edit', entityName: 'Agent', entityLabel: 'David' }
+ *   → <h1>Edit Agent: <span class="entity-label">David</span></h1>
+ *
+ * Slots:
+ * - subtitle: Optional content next to title
+ * - actions: Action buttons on the right
+ *
+ * Note: Breadcrumb is handled globally by AppLayout.
+ */
+import { computed, inject, type Ref } from 'vue'
+import Tag from 'primevue/tag'
+
+interface TitleParts {
+  simple?: string
+  action?: string
+  entityName?: string
+  entityLabel?: string
+}
+
+interface BadgeConfig {
+  label: string
+  severity?: string
+}
+
+interface Props {
+  title?: string | null
+  titleParts?: TitleParts | null
+  subtitle?: string | null
+  badges?: BadgeConfig[]
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  title: null,
+  titleParts: null,
+  subtitle: null,
+  badges: () => []
+})
+
+// Auto-injected title from useForm (if available)
+const injectedTitleParts = inject<Ref<TitleParts | null> | null>('qdadmPageTitleParts', null)
+
+// Use props first, then injected, then fallback
+const effectiveTitleParts = computed((): TitleParts | null => {
+  return props.titleParts || injectedTitleParts?.value || null
+})
+
+// Simple title from usePageTitle('My Title')
+const simpleTitle = computed((): string | undefined => effectiveTitleParts.value?.simple)
+
+// Compute title display
+const hasDecoratedTitle = computed((): boolean => {
+  return !!effectiveTitleParts.value?.entityLabel
+})
+</script>
+
+<template>
+  <div class="page-header">
+    <div class="page-header-content">
+      <div class="page-header-row">
+        <div class="page-header-left">
+          <div>
+            <h1 class="page-title">
+              <template v-if="simpleTitle">{{ simpleTitle }}</template>
+              <template v-else-if="effectiveTitleParts">
+                <span v-if="hasDecoratedTitle" class="entity-label">{{ effectiveTitleParts.entityLabel }}</span>
+                <span v-else>{{ effectiveTitleParts.action }} {{ effectiveTitleParts.entityName }}</span>
+              </template>
+              <Tag
+                v-for="badge in badges"
+                :key="badge.label"
+                :value="badge.label"
+                :severity="(badge.severity as any) || 'secondary'"
+                class="entity-badge"
+              />
+              <template v-if="!effectiveTitleParts && !simpleTitle">{{ title }}</template>
+            </h1>
+            <p v-if="subtitle" class="page-subtitle">{{ subtitle }}</p>
+          </div>
+          <slot name="subtitle" ></slot>
+        </div>
+        <div class="header-actions">
+          <slot name="actions" ></slot>
+        </div>
+      </div>
+    </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.).
+ */
+.page-header-content {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.page-header-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  min-height: 2.5rem; /* Consistent height with or without action buttons */
+}
+
+.page-header-left {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.page-subtitle {
+  margin: 0.25rem 0 0 0;
+  font-size: 0.875rem;
+  color: var(--p-text-secondary);
+}
+
+/* Action badge (View Bot / Edit Country) - small grey badge, before title */
+.action-badge {
+  display: inline-block;
+  font-size: 0.5em;
+  font-weight: 600;
+  background: var(--p-surface-200);
+  color: var(--p-surface-600);
+  padding: 0.25em 0.6em;
+  border-radius: 4px;
+  margin-right: 0.5em;
+  vertical-align: middle;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+/* Entity badges from manager callback */
+.entity-badge {
+  vertical-align: middle;
+  margin-left: 0.4em;
+  font-size: 0.5em;
+}
+
+/* Entity label in title - main focus */
+.entity-label {
+  font-weight: 600;
+}
+</style>

package/src/components/layout/PageLayout.vue

@@ -0,0 +1,126 @@
+<script setup lang="ts">
+/**
+ * PageLayout - Base layout for dashboard pages
+ *
+ * Provides:
+ * - PageHeader with title and actions
+ * - CardsGrid zone (optional)
+ * - Main content slot
+ *
+ * Slots:
+ * - #nav: For PageNav component (provides breadcrumb data to AppLayout)
+ * - #header-actions: Custom header action buttons
+ * - default: Main content
+ *
+ * Note: Breadcrumb is handled globally by AppLayout.
+ * Use PageNav in #nav slot to customize breadcrumb for child routes.
+ */
+import PageHeader from './PageHeader.vue'
+import CardsGrid from '../display/CardsGrid.vue'
+import Button from 'primevue/button'
+
+interface TitleParts {
+  action?: string
+  entityName?: string
+  entityLabel?: string
+}
+
+interface HeaderAction {
+  name: string
+  label: string | (() => string)
+  icon?: string
+  severity?: string
+  isLoading?: boolean
+  onClick: () => void
+}
+
+type Severity = 'success' | 'danger' | 'warning' | 'info'
+
+interface Card {
+  name: string
+  value?: string | number
+  label?: string
+  severity?: Severity
+  icon?: string
+  custom?: boolean
+  class?: string
+  onClick?: () => void
+}
+
+interface Props {
+  /** Page title (use title OR titleParts) */
+  title?: string
+  /** Title parts for decorated entity label */
+  titleParts?: TitleParts
+  /** Page subtitle */
+  subtitle?: string
+  /** Header action buttons */
+  headerActions?: HeaderAction[]
+  /** Cards configuration */
+  cards?: Card[]
+  /** Number of card columns or 'auto' */
+  cardsColumns?: number | 'auto'
+}
+
+withDefaults(defineProps<Props>(), {
+  headerActions: () => [],
+  cards: () => [],
+  cardsColumns: 'auto'
+})
+
+function resolveLabel(label: string | (() => string)): string {
+  return typeof label === 'function' ? label() : label
+}
+</script>
+
+<template>
+  <div>
+    <!-- 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>
+        </slot>
+      </template>
+      <template #actions>
+        <slot name="header-actions" ></slot>
+        <Button
+          v-for="action in headerActions"
+          :key="action.name"
+          :label="resolveLabel(action.label)"
+          :icon="action.icon"
+          :severity="action.severity"
+          :loading="action.isLoading"
+          @click="action.onClick"
+        />
+      </template>
+    </PageHeader>
+
+    <!-- Cards Zone -->
+    <CardsGrid v-if="cards.length > 0" :cards="cards" :columns="cardsColumns">
+      <template v-for="(_, slotName) in $slots" :key="slotName" #[slotName]="slotProps">
+        <slot :name="slotName" v-bind="slotProps" ></slot>
+      </template>
+    </CardsGrid>
+
+    <!-- Main Content -->
+    <slot ></slot>
+  </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.).
+ */
+.page-subtitle {
+  color: var(--p-surface-500);
+  font-size: 0.9rem;
+  margin-left: 1rem;
+}
+</style>