@quazardous/qdadm 1.19.7 → 1.20.0

package/README.md

@@ -31,7 +31,7 @@ import { SecurityChecker, PermissionMatcher, PermissionRegistry } from '@quazard
 import { PersistableRoleProvider, createLocalStorageRolesProvider } from '@quazardous/qdadm/security'
 
 // Composables
-import { useForm, useBareForm, useListPageBuilder } from '@quazardous/qdadm/composables'
+import { useForm, useBareForm, useListPage } from '@quazardous/qdadm/composables'
 
 // Components
 import { ListPage, PageLayout, AppLayout, FormField, FormActions } from '@quazardous/qdadm/components'
@@ -96,8 +96,18 @@ Options: `transformRequest`, `transformResponse`, `responseFormat`, `clientSideP
 | Doc | Purpose |
 |-----|---------|
 | [QDADM_CREDO](QDADM_CREDO.md) | Philosophy, patterns, concepts |
+| [Page compositions](../../docs/page-compositions.md) | **Start here** — which composition for which need |
+| [CRUD Pages](../../docs/crud.md) | List / form / show / child pages reference |
 | [Architecture](../../docs/architecture.md) | PAC pattern, layers |
-| [Extension](../../docs/extension.md) | Hooks, signals, zones |
+| [Extension](../../docs/extension.md) | Decorators, bundles, multi-storage |
+| [Hooks](../../docs/hooks.md) | Alter / invoke registry |
+| [Signals](../../docs/signals.md) | Event bus, SSE bridge |
+| [Zones](../../docs/zones.md) | Extensible UI blocks |
+| [Security](../../docs/security.md) | Permissions, roles |
+| [i18n](../../docs/i18n.md) | Messages, providers, strategies |
+| [Codegen](../../docs/gen.md) | Generate managers (OpenAPI / manual) |
+| [Deferred](../../docs/deferred.md) | Deferred values & warmup |
+| [AGENT_GUIDE](../../docs/AGENT_GUIDE.md) | Quick index for AI agents |
 
 ## Peer Dependencies
 

package/package.json

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

package/src/components/index.ts

@@ -36,6 +36,7 @@ export { default as LookupPickerDialog } from './edit/LookupPickerDialog.vue'
 export { default as ShowPage } from './show/ShowPage.vue'
 export { default as ShowField } from './show/ShowField.vue'
 export { default as ShowDisplay } from './show/ShowDisplay.vue'
+export { default as ParentCard } from './show/ParentCard.vue'
 
 // Lists
 export { default as ListPage } from './lists/ListPage.vue'

package/src/components/show/ParentCard.vue

@@ -0,0 +1,112 @@
+<script setup lang="ts">
+/**
+ * ParentCard - normalized parent detail embedded at the top of a child ListPage
+ *
+ * The "B2" hybrid composition (see docs/page-compositions.md): a child list is
+ * the host page, and the parent record is shown as a read-only cartouche above
+ * the table. `useListPage` already resolves and exposes the parent on a child
+ * route (`parentData` / `parentLoading`) — this component just renders it, with
+ * the SAME field resolver as `ShowPage` so the look matches real detail pages.
+ * No extra fetch.
+ *
+ * Fields are auto-derived from the parent entity's manager. Pass `fields` to
+ * restrict/order them, or use the default slot to render the parent yourself.
+ *
+ * Usage (inside a child ListPage):
+ *   <template #beforeTable>
+ *     <ParentCard
+ *       :entity="'books'"
+ *       :data="list.parentData.value"
+ *       :loading="list.parentLoading.value"
+ *       :fields="['title', 'author']"
+ *     />
+ *   </template>
+ */
+import { computed, type PropType } from 'vue'
+import { useOrchestrator } from '../../orchestrator/useOrchestrator'
+import { useFieldManager } from '../../composables/useFieldManager'
+import {
+  createShowFieldResolver,
+  type ShowResolvedFieldConfig,
+} from '../../composables/createShowFieldResolver'
+import ShowField from './ShowField.vue'
+
+const props = defineProps({
+  /** Parent entity name (route-stable). */
+  entity: { type: String, required: true },
+  /** Parent record (e.g. `list.parentData.value`). */
+  data: { type: Object as PropType<Record<string, unknown> | null>, default: null },
+  /** Parent loading state (e.g. `list.parentLoading.value`). */
+  loading: { type: Boolean, default: false },
+  /** Restrict/order the displayed fields. Omit to show all manager fields. */
+  fields: { type: Array as PropType<string[] | null>, default: null },
+  /** Exclude these fields (applied when `fields` is not set). */
+  exclude: { type: Array as PropType<string[]>, default: () => [] },
+  /** Render fields horizontally (label beside value). Default true. */
+  horizontal: { type: Boolean, default: true },
+  /** Optional heading above the fields. */
+  title: { type: String, default: '' },
+})
+
+const { orchestrator, getManager } = useOrchestrator()
+const manager = getManager(props.entity)
+
+// Same resolver as ShowPage → identical rendering (types, references, severity).
+const fieldManager = useFieldManager<ShowResolvedFieldConfig>({
+  resolveFieldConfig: createShowFieldResolver(manager, orchestrator),
+  getSchemaFieldConfig: (name) => manager.getFieldConfig?.(name) || null,
+  entity: props.entity,
+})
+
+fieldManager.generateFields(manager.getFormFields?.() || [], {
+  only: props.fields ?? null,
+  exclude: props.fields ? [] : props.exclude,
+})
+// Honor the caller's field order when an explicit list is given.
+if (props.fields) fieldManager.setFieldOrder(props.fields)
+
+const resolvedFields = fieldManager.fields
+const hasData = computed(() => props.data !== null && props.data !== undefined)
+</script>
+
+<template>
+  <div class="parent-card">
+    <div v-if="loading" class="parent-card__loading">
+      <i class="pi pi-spin pi-spinner" />
+    </div>
+
+    <template v-else-if="hasData">
+      <div v-if="title" class="parent-card__title">{{ title }}</div>
+      <!-- Escape hatch: render the parent yourself with the resolved fields. -->
+      <slot :fields="resolvedFields" :data="data">
+        <div class="parent-card__fields">
+          <ShowField
+            v-for="f in resolvedFields"
+            :key="f.name"
+            :field="f"
+            :value="(data?.[f.name] ?? null) as any"
+            :horizontal="horizontal"
+          />
+        </div>
+      </slot>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.parent-card {
+  margin-bottom: 1rem;
+}
+.parent-card__loading {
+  padding: 0.5rem 0;
+}
+.parent-card__title {
+  font-weight: 600;
+  margin-bottom: 0.5rem;
+}
+.parent-card__fields {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+</style>

package/src/composables/createShowFieldResolver.ts

@@ -0,0 +1,170 @@
+/**
+ * createShowFieldResolver - shared read-only field resolver
+ *
+ * Factory producing the field resolver used by read-only display surfaces
+ * (`useEntityItemShowPage`, `<ParentCard>`). Given an entity manager and the
+ * orchestrator, it maps a raw schema field config to a resolved display config:
+ *
+ * - schema type → display type (via {@link SHOW_TYPE_MAPPINGS})
+ * - auto reference route when a field points at another entity
+ * - auto severity (badge) from the manager's severity maps
+ *
+ * Extracted so the parent cartouche of an embedded child list (#1038) renders
+ * fields exactly like a real `ShowPage` — same resolver, same look — without
+ * duplicating the mapping logic.
+ */
+import { snakeCaseToTitle } from './useFieldManager'
+
+/** Severity descriptor returned by a manager's severity maps. */
+type SeverityDescriptor = string | { severity: string; icon?: string; label?: string }
+
+/**
+ * Minimal manager surface the resolver needs — kept structural (not the full
+ * generic `EntityManager`) so it accepts any concrete manager without variance
+ * friction.
+ */
+export interface ShowResolverManager {
+  routePrefix?: string
+  idField: string
+  hasSeverityMap?: (name: string) => boolean
+  getSeverityDescriptor?: (name: string, value: string | number, fallback: string) => SeverityDescriptor
+  getSeverity?: (name: string, value: string | number, fallback: string) => SeverityDescriptor
+}
+
+/**
+ * Field definition from an EntityManager schema.
+ */
+export interface ShowFieldDefinition {
+  name: string
+  type?: string
+  schemaType?: string
+  label?: string
+  reference?: string
+  referenceRoute?: string | ((value: unknown) => { name: string; params: Record<string, unknown> })
+  referenceLabel?: string | ((value: unknown, option?: unknown) => string)
+  options?: unknown[]
+  optionLabel?: string
+  optionValue?: string
+  // Display options
+  dateFormat?: string
+  currencyCode?: string
+  locale?: string
+  booleanLabels?: { true: string; false: string }
+  severity?: string | ((value: unknown) => string | { severity: string; icon?: string; label?: string })
+  imageWidth?: string
+  imageHeight?: string
+  render?: (value: unknown) => string
+  [key: string]: unknown
+}
+
+/**
+ * Resolved field configuration for display rendering.
+ */
+export interface ShowResolvedFieldConfig extends ShowFieldDefinition {
+  name: string
+  type: string
+  schemaType: string
+  label: string
+  group?: string
+}
+
+/**
+ * Minimal orchestrator surface the resolver needs (reference-route lookup).
+ */
+export interface ShowResolverOrchestrator {
+  get: (entityName: string) => ShowResolverManager | undefined
+}
+
+/**
+ * Schema type → display type mapping.
+ */
+export const SHOW_TYPE_MAPPINGS: Record<string, string> = {
+  text: 'text',
+  string: 'text',
+  email: 'email',
+  password: 'password',
+  number: 'number',
+  integer: 'number',
+  float: 'number',
+  decimal: 'number',
+  currency: 'currency',
+  boolean: 'boolean',
+  bool: 'boolean',
+  date: 'date',
+  datetime: 'datetime',
+  time: 'datetime',
+  timestamp: 'datetime',
+  select: 'select',
+  enum: 'select',
+  textarea: 'textarea',
+  longtext: 'textarea',
+  reference: 'reference',
+  foreignKey: 'reference',
+  image: 'image',
+  url: 'url',
+  link: 'url',
+  json: 'json',
+  object: 'json',
+  array: 'json',
+  badge: 'badge',
+  tag: 'badge',
+}
+
+/**
+ * Build a show-style field resolver bound to a manager + orchestrator.
+ */
+export function createShowFieldResolver(
+  manager: ShowResolverManager,
+  orchestrator: ShowResolverOrchestrator
+): (name: string, fieldConfig: Partial<ShowFieldDefinition>) => ShowResolvedFieldConfig {
+  return function resolveFieldConfig(
+    name: string,
+    fieldConfig: Partial<ShowFieldDefinition>
+  ): ShowResolvedFieldConfig {
+    const {
+      type = 'text',
+      schemaType = type,
+      label = '',
+      reference = '',
+      severity,
+      ...rest
+    } = fieldConfig
+
+    let resolvedDisplayType = SHOW_TYPE_MAPPINGS[type] || SHOW_TYPE_MAPPINGS[schemaType] || 'text'
+    const resolvedLabel = label || snakeCaseToTitle(name)
+
+    // Auto-set reference route if reference entity is specified
+    let referenceRoute = rest.referenceRoute
+    if (reference && !referenceRoute) {
+      const refManager = orchestrator.get(reference)
+      if (refManager) {
+        referenceRoute = (value: unknown) => ({
+          name: `${refManager.routePrefix || reference}-show`,
+          params: { [refManager.idField]: value },
+        })
+      }
+    }
+
+    // Auto-inject severity from manager's severity maps
+    let resolvedSeverity = severity
+    if (!resolvedSeverity && manager.hasSeverityMap?.(name)) {
+      resolvedSeverity = manager.getSeverityDescriptor
+        ? (value: unknown) => manager.getSeverityDescriptor!(name, value as string | number, 'secondary')
+        : (value: unknown) => manager.getSeverity!(name, value as string | number, 'secondary')
+      if (resolvedDisplayType === 'text') {
+        resolvedDisplayType = 'badge'
+      }
+    }
+
+    return {
+      name,
+      type: resolvedDisplayType,
+      schemaType,
+      label: resolvedLabel,
+      reference,
+      referenceRoute,
+      severity: resolvedSeverity,
+      ...rest,
+    }
+  }
+}

package/src/composables/useEntityItemShowPage.ts

@@ -33,24 +33,27 @@
  * <ShowPage v-bind="show.props.value" v-on="show.events" />
  * ```
  */
-import { ref, computed, watch, type Ref, type ComputedRef } from 'vue'
-import { useRouter, useRoute, type Router } from 'vue-router'
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import { useRouter, type Router } from 'vue-router'
 import { useConfirm } from 'primevue/useconfirm'
 import {
   useEntityItemPage,
   type ParentConfig,
   type EntityManager,
-  type UseEntityItemPageReturn,
 } from './useEntityItemPage'
 import type { StackHydratorReturn } from '../chain/useStackHydrator'
 import {
   useFieldManager,
-  snakeCaseToTitle,
   type FieldGroup,
   type GroupDefinition,
   type GroupOptions,
   type AddFieldOptions,
 } from './useFieldManager'
+import {
+  createShowFieldResolver,
+  type ShowFieldDefinition,
+  type ShowResolvedFieldConfig,
+} from './createShowFieldResolver'
 
 /**
  * Orchestrator interface
@@ -66,41 +69,16 @@ interface Orchestrator {
 }
 
 /**
- * Field definition from EntityManager schema
+ * Field definition from EntityManager schema.
+ * Re-exported from the shared resolver under the historical name.
  */
-export interface FieldDefinition {
-  name: string
-  type?: string
-  schemaType?: string
-  label?: string
-  reference?: string
-  referenceRoute?: string | ((value: unknown) => { name: string; params: Record<string, unknown> })
-  referenceLabel?: string | ((value: unknown, option?: unknown) => string)
-  options?: unknown[]
-  optionLabel?: string
-  optionValue?: string
-  // Display options
-  dateFormat?: string
-  currencyCode?: string
-  locale?: string
-  booleanLabels?: { true: string; false: string }
-  severity?: string | ((value: unknown) => string | { severity: string; icon?: string; label?: string })
-  imageWidth?: string
-  imageHeight?: string
-  render?: (value: unknown) => string
-  [key: string]: unknown
-}
+export type FieldDefinition = ShowFieldDefinition
 
 /**
- * Resolved field configuration for display rendering
+ * Resolved field configuration for display rendering.
+ * Re-exported from the shared resolver under the historical name.
  */
-export interface ResolvedFieldConfig extends FieldDefinition {
-  name: string
-  type: string
-  schemaType: string
-  label: string
-  group?: string
-}
+export type ResolvedFieldConfig = ShowResolvedFieldConfig
 
 // FieldGroup, GroupDefinition, GroupOptions imported from useFieldManager
 
@@ -176,43 +154,6 @@ export interface ShowPageEvents {
   back: () => void
 }
 
-/**
- * Type mapping from schema types to display types
- */
-const TYPE_MAPPINGS: Record<string, string> = {
-  text: 'text',
-  string: 'text',
-  email: 'email',
-  password: 'password',
-  number: 'number',
-  integer: 'number',
-  float: 'number',
-  decimal: 'number',
-  currency: 'currency',
-  boolean: 'boolean',
-  bool: 'boolean',
-  date: 'date',
-  datetime: 'datetime',
-  time: 'datetime',
-  timestamp: 'datetime',
-  select: 'select',
-  enum: 'select',
-  textarea: 'textarea',
-  longtext: 'textarea',
-  reference: 'reference',
-  foreignKey: 'reference',
-  image: 'image',
-  url: 'url',
-  link: 'url',
-  json: 'json',
-  object: 'json',
-  array: 'json',
-  badge: 'badge',
-  tag: 'badge',
-}
-
-// snakeCaseToTitle imported from useFieldManager
-
 /**
  * Options for useEntityItemShowPage
  */
@@ -327,7 +268,6 @@ export function useEntityItemShowPage<T = unknown>(
   const { entity, loadOnMount = true, transformLoad, onLoadSuccess, onLoadError } = options
 
   const router: Router = useRouter()
-  const route = useRoute()
   const confirm = useConfirm() as ConfirmService
 
   // Lazy action state (declared before base so onLoadSuccess wrapper can reference it)
@@ -376,56 +316,8 @@ export function useEntityItemShowPage<T = unknown>(
 
   // ============ FIELD & GROUP MANAGEMENT (via useFieldManager) ============
 
-  /**
-   * Show-specific field resolver with reference route auto-detection
-   */
-  function resolveFieldConfig(name: string, fieldConfig: Partial<FieldDefinition>): ResolvedFieldConfig {
-    const {
-      type = 'text',
-      schemaType = type,
-      label = '',
-      reference = '',
-      severity,
-      ...rest
-    } = fieldConfig
-
-    let resolvedDisplayType = TYPE_MAPPINGS[type] || TYPE_MAPPINGS[schemaType] || 'text'
-    const resolvedLabel = label || snakeCaseToTitle(name)
-
-    // Auto-set reference route if reference entity is specified
-    let referenceRoute = rest.referenceRoute
-    if (reference && !referenceRoute) {
-      const refManager = orchestrator.get(reference)
-      if (refManager) {
-        referenceRoute = (value: unknown) => ({
-          name: `${refManager.routePrefix || reference}-show`,
-          params: { [refManager.idField]: value },
-        })
-      }
-    }
-
-    // Auto-inject severity from manager's severity maps
-    let resolvedSeverity = severity
-    if (!resolvedSeverity && manager.hasSeverityMap?.(name)) {
-      resolvedSeverity = manager.getSeverityDescriptor
-        ? (value: unknown) => manager.getSeverityDescriptor!(name, value as string | number, 'secondary')
-        : (value: unknown) => manager.getSeverity!(name, value as string | number, 'secondary')
-      if (resolvedDisplayType === 'text') {
-        resolvedDisplayType = 'badge'
-      }
-    }
-
-    return {
-      name,
-      type: resolvedDisplayType,
-      schemaType,
-      label: resolvedLabel,
-      reference,
-      referenceRoute,
-      severity: resolvedSeverity,
-      ...rest,
-    }
-  }
+  // Show-specific field resolver (shared with <ParentCard>, see #1038)
+  const resolveFieldConfig = createShowFieldResolver(manager, orchestrator)
 
   // Create field manager with show-specific resolver
   const fieldManager = useFieldManager<ResolvedFieldConfig>({