@quazardous/qdadm 2.24.0 → 2.26.0

package/package.json

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

package/src/components/item/FieldGroups.vue

@@ -20,7 +20,7 @@
  * </FieldGroups>
  * ```
  */
-import { computed, type PropType } from 'vue'
+import { computed, ref, watch, type PropType } from 'vue'
 import Tabs from 'primevue/tabs'
 import TabList from 'primevue/tablist'
 import Tab from 'primevue/tab'
@@ -84,8 +84,21 @@ const props = defineProps({
     type: String as PropType<LayoutMode>,
     default: 'sections',
   },
+  /**
+   * The active group (`tabs`: a group name) or the open ones (`accordion`:
+   * names), for `v-model:active` (#2435). Optional: without it the component
+   * keeps its own, starting on the first group.
+   */
+  active: {
+    type: [String, Array] as PropType<string | string[] | null>,
+    default: undefined,
+  },
 })
 
+const emit = defineEmits<{
+  'update:active': [value: string | string[]]
+}>()
+
 // Expose slots for field rendering
 defineSlots<{
   field: (props: { field: BaseFieldConfig; value: unknown; groupName: string }) => unknown
@@ -105,6 +118,34 @@ const displayGroups = computed(() => {
   })
 })
 
+// The active tab / open panels are state, not a constant: a re-render must not
+// send the user back to the first group (#2435). An app owning it passes
+// v-model:active; otherwise this is the only copy.
+const localActive = ref<string | string[] | null | undefined>(props.active)
+watch(
+  () => props.active,
+  (value) => {
+    if (value !== undefined) localActive.value = value
+  }
+)
+const firstGroupName = () => displayGroups.value[0]?.name || '0'
+const activeTab = computed(() => (typeof localActive.value === 'string' ? localActive.value : firstGroupName()))
+const openPanels = computed(() => {
+  const value = localActive.value
+  if (Array.isArray(value)) return value
+  return typeof value === 'string' ? [value] : [firstGroupName()]
+})
+function setActive(value: string | string[]) {
+  localActive.value = value
+  emit('update:active', value)
+}
+function onTabChange(value: string | number) {
+  setActive(String(value))
+}
+function onPanelsChange(value: unknown) {
+  setActive(Array.isArray(value) ? value.map(String) : value == null ? [] : [String(value)])
+}
+
 // Get value from data
 function getValue(fieldName: string): unknown {
   return props.data?.[fieldName]
@@ -227,7 +268,7 @@ function getBadgeValue(group: FieldGroup): string | number | null {
 
     <!-- Tabs layout -->
     <template v-else-if="layout === 'tabs'">
-      <Tabs :value="displayGroups[0]?.name || '0'">
+      <Tabs :value="activeTab" @update:value="onTabChange">
         <TabList>
           <Tab
             v-for="group in displayGroups"
@@ -275,7 +316,7 @@ function getBadgeValue(group: FieldGroup): string | number | null {
 
     <!-- Accordion layout -->
     <template v-else-if="layout === 'accordion'">
-      <Accordion :value="[displayGroups[0]?.name || '0']" multiple>
+      <Accordion :value="openPanels" multiple @update:value="onPanelsChange">
         <AccordionPanel
           v-for="group in displayGroups"
           :key="group.name"

package/src/components/show/ShowPage.vue

@@ -35,7 +35,8 @@
  * - #fields: Field content (required) - renders in right column (or full width if no media)
  * - #footer: Custom footer (replaces ShowActions if provided)
  * - #error: Custom error display
- * - #loading: Custom loading display
+ * - #loading: Custom display for the first load. A reload of a record already
+ *   on screen keeps it there, marked busy (#2435).
  */
 import { computed, type PropType } from 'vue'
 import PageHeader from '../layout/PageHeader.vue'
@@ -203,8 +204,11 @@ type ShowFieldValue = string | number | boolean | Date | Record<string, unknown>
     <!-- Toolbar slot (between header and content) -->
     <slot name="toolbar" />
 
-    <!-- Loading State -->
-    <template v-if="loading">
+    <!-- First load only. A reload of a record already shown keeps the content
+         mounted (#2435): unmounting it threw away the active tab, open panels,
+         scroll and any local state — on every action reload and every live
+         update of the record. -->
+    <template v-if="loading && !data">
       <slot name="loading">
         <div class="loading-state">
           <i class="pi pi-spin pi-spinner" style="font-size: 2rem"></i>
@@ -223,6 +227,7 @@ type ShowFieldValue = string | number | boolean | Date | Record<string, unknown>
 
     <!-- Content -->
     <template v-else>
+      <div v-if="loading" class="show-refreshing" role="progressbar" aria-label="Refreshing" />
       <!-- Single content body; Card wrapper is conditional (#1193) -->
       <CardShell :card="cardWrapper">
         <!-- Grid layout with optional media zone -->
@@ -230,6 +235,7 @@ type ShowFieldValue = string | number | boolean | Date | Record<string, unknown>
           class="show-content"
           :class="{ 'show-content--with-media': slots.media }"
           :style="slots.media ? { '--media-width': mediaWidth } : {}"
+          :aria-busy="loading ? 'true' : undefined"
         >
           <!-- Media zone (optional) -->
           <div v-if="slots.media" class="show-media">
@@ -304,6 +310,29 @@ type ShowFieldValue = string | number | boolean | Date | Record<string, unknown>
   padding: 3rem;
 }
 
+/* A record being refreshed stays on screen: a thin bar says so (#2435). */
+.show-refreshing {
+  height: 3px;
+  margin-bottom: -1rem; /* inside the page gap: the content does not move */
+  background: linear-gradient(90deg, transparent, var(--p-primary-color, #3b82f6), transparent);
+  background-size: 40% 100%;
+  background-repeat: no-repeat;
+  animation: show-refreshing 1.1s ease-in-out infinite;
+}
+
+@keyframes show-refreshing {
+  from { background-position: -40% 0; }
+  to { background-position: 140% 0; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .show-refreshing {
+    animation: none;
+    background: var(--p-primary-color, #3b82f6);
+    opacity: 0.4;
+  }
+}
+
 .show-error-message {
   margin: 1rem 0;
 }

package/src/composables/useEntityItemFormPage.ts

@@ -24,7 +24,7 @@
  * </FormPage>
  * ```
  */
-import { ref, computed, watch, onMounted, onUnmounted, provide, type Ref } from 'vue'
+import { ref, computed, watch, onMounted, onUnmounted, provide, inject, type Ref } from 'vue'
 import { useRouter, useRoute } from 'vue-router'
 import { useConfirm } from 'primevue/useconfirm'
 import { requireDeleteConfirmation } from './confirmDelete'
@@ -56,6 +56,9 @@ import { createOrchestratorToast } from './useOrchestratorToast'
 import { useActionRegistry } from './useActionRegistry'
 import { TYPE_MAPPINGS, TYPE_VALIDATORS, snakeCaseToTitle, isEmpty } from './useEntityItemFormPage.types'
 
+/** Missing fields already reported, as `entity:field` — each is said once per page load of the app (#2484). */
+const reportedMissingFields = new Set<string>()
+
 // Re-export public types
 export type {
   FieldDefinition,
@@ -126,6 +129,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
   const router = useRouter()
   const route = useRoute()
   const confirm = useConfirm() as ConfirmService
+  const debug = inject<boolean>('qdadmDebug', false)
 
   // Use useEntityItemPage for common infrastructure
   const itemPage = useEntityItemPage({
@@ -247,6 +251,28 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
 
   // ============ LOADING ============
 
+  /**
+   * A field the form edits that the loaded record does not carry at all —
+   * `undefined`, not empty — is shown empty and saved back empty (#2484). Said
+   * in debug mode only, once per entity and field: some APIs omit null fields.
+   * Password fields are left out: no API returns one.
+   */
+  function reportMissingFields(record: Record<string, unknown> | null): void {
+    if (!record || typeof record !== 'object') return
+    const entityName = String((manager as { name?: unknown }).name ?? entity)
+    for (const field of fields.value) {
+      if (field.type === 'password' || field.name.includes('.')) continue
+      if (record[field.name] !== undefined) continue
+      const key = `${entityName}:${field.name}`
+      if (reportedMissingFields.has(key)) continue
+      reportedMissingFields.add(key)
+      console.warn(
+        `[qdadm] ${entityName} #${entityId.value} loaded without "${field.name}", which the form edits: ` +
+          'saving would send it back empty. Check that the record endpoint returns it.'
+      )
+    }
+  }
+
   async function load(): Promise<void> {
     if (!isEdit.value) {
       data.value = deepClone(initialData) as T
@@ -256,8 +282,11 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
 
     loading.value = true
     try {
-      const responseData = await manager.get(entityId.value!)
+      // The item itself, never a cached list row: a list row may be a summary,
+      // and whatever this form shows empty it saves back empty (#2484).
+      const responseData = await manager.get(entityId.value!, undefined, { listCache: false })
       const transformed = transformLoad(responseData)
+      if (debug) reportMissingFields(transformed as Record<string, unknown>)
       data.value = transformed as T
       originalData.value = deepClone(transformed)
       takeSnapshot()

package/src/composables/useNavigation.ts

@@ -93,15 +93,27 @@ export function useNavigation(): UseNavigationReturn {
   const alterVersion = ref(0)
 
   /**
-   * Check if user can access a nav item based on its entity's canRead()
+   * Check if user can access a nav item: canList() when it opens a list route, canRead() otherwise
    */
   function canAccessNavItem(item: NavItem): boolean {
     if (!item.entity || !orchestrator) return true
     const manager = orchestrator.get(item.entity)
     if (!manager) return true
+    // A menu entry is shown to whoever may do what its page does (#2497): a
+    // ctx.crud() entry opens a list, so it follows `list`. A route that
+    // declares no action, or is not registered, keeps `read`.
+    if (routeAction(item.route) === 'list' && manager.canList) return manager.canList()
     return manager.canRead()
   }
 
+  function routeAction(name: string): string | undefined {
+    try {
+      return router.resolve({ name }).meta?.entityAction as string | undefined
+    } catch {
+      return undefined
+    }
+  }
+
   // Note: Auth signal listeners removed - Kernel.invalidateApp() remounts entire app
   // on auth changes, so composable is re-initialized with fresh state
 

package/src/entity/EntityManager.crud.ts

@@ -1,5 +1,5 @@
 import type { ListParams, ListResult } from '../types'
-import type { EntityManagerInternal, Orchestrator, RoutingContext } from './EntityManager.types'
+import type { EntityManagerInternal, GetOptions, Orchestrator, RoutingContext } from './EntityManager.types'
 
 type Self = EntityManagerInternal<any>
 
@@ -208,7 +208,8 @@ export function applyCrudMethods(EntityManagerClass: { prototype: any }): void {
   proto.get = async function (
     this: Self,
     id: string | number,
-    context?: RoutingContext
+    context?: RoutingContext,
+    options: GetOptions = {}
   ): Promise<any> {
     const { storage, endpoint } = this._normalizeResolveResult(
       this.resolveStorage('get', context),
@@ -287,8 +288,9 @@ export function applyCrudMethods(EntityManagerClass: { prototype: any }): void {
 
     // ── Symmetric mode (default): try list cache ──
 
-    // Try cache first if valid and complete
-    if (cache.valid && !this.overflow) {
+    // Try cache first if valid and complete — unless the caller needs the item
+    // itself: a list row may be a summary (#2484).
+    if (options.listCache !== false && cache.valid && !this.overflow) {
       const cached = cache.items.find(
         (item: any) => String(item[this.idField]) === idStr
       )

package/src/entity/EntityManager.interface.ts

@@ -71,7 +71,7 @@ export interface EntityManagerPermissions<T = unknown> {
  * Read operations + delete — used by list pages and other read-oriented views.
  */
 export interface EntityManagerRead<T = unknown> extends EntityManagerBase<T>, EntityManagerPermissions<T> {
-  get: (id: string | number, context?: unknown) => Promise<T>
+  get: (id: string | number, context?: unknown, options?: { listCache?: boolean }) => Promise<T>
   list: (params?: unknown, context?: unknown) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
   // query/invalidateCache/getFieldConfig are required since #1253: they are
   // unconditionally implemented on the class (prototype-applied) and called
@@ -160,6 +160,8 @@ export interface EntityManagerLike {
   getEntityLabel(data: unknown): string | null
   getEntityBadges?(data: unknown): EntityBadge[]
   canRead(entity?: unknown): boolean
+  /** Whether the user may list — what a list page and its menu entry need (#2497). */
+  canList?(): boolean
   canCreate(): boolean
   canUpdate(entity?: unknown): boolean
   canDelete(entity?: unknown): boolean
@@ -168,7 +170,7 @@ export interface EntityManagerLike {
     total?: number
     fromCache?: boolean
   }>
-  get(id: string | number, context?: unknown): Promise<unknown>
+  get(id: string | number, context?: unknown, options?: { listCache?: boolean }): Promise<unknown>
   create(data: Record<string, unknown>, context?: unknown): Promise<unknown>
   update(id: string | number, data: Record<string, unknown>, context?: unknown): Promise<unknown>
   delete(id: string | number, context?: unknown): Promise<unknown>

package/src/entity/EntityManager.ts

@@ -29,6 +29,7 @@ import type {
   ResolvedStorage,
   StorageResolution,
   Orchestrator,
+  GetOptions,
 } from './EntityManager.types'
 import type { NullSortMode } from '../query/clientFilter'
 
@@ -48,6 +49,7 @@ export type {
   SeverityMapValue,
   SeverityMap,
   EntityManagerOptions,
+  GetOptions,
 } from './EntityManager.types'
 
 // Import concrete types needed in method signatures
@@ -1001,7 +1003,7 @@ export interface EntityManager<T extends EntityRecord = EntityRecord> {
 
   // --- CRUD methods ---
   list(params?: ListParams & { _internal?: boolean }, context?: RoutingContext): Promise<ListResult<T>>
-  get(id: string | number, context?: RoutingContext): Promise<T>
+  get(id: string | number, context?: RoutingContext, options?: GetOptions): Promise<T>
   getMany(ids: Array<string | number>, context?: RoutingContext): Promise<T[]>
   create(data: Partial<T>, context?: RoutingContext): Promise<T>
   update(id: string | number, data: Partial<T>, context?: RoutingContext): Promise<T>

package/src/entity/EntityManager.types.ts

@@ -32,6 +32,19 @@ export interface CacheState<T> {
   overflowed?: boolean
 }
 
+/**
+ * Options for `EntityManager.get()` (#2484).
+ */
+export interface GetOptions {
+  /**
+   * `false` reads the item from storage instead of a cached list row. A list
+   * row may be a summary: whoever loads a record in order to write it back
+   * needs the item itself. Default true — in symmetric mode, a valid list
+   * cache answers `get()`. Asymmetric entities never read the list cache.
+   */
+  listCache?: boolean
+}
+
 /**
  * Detail cache entry for asymmetric entities (full detail per item)
  */

package/src/kernel/Kernel.routing.ts

@@ -255,12 +255,17 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
       const orchestrator = this.orchestrator
       if (!entity || !orchestrator || !orchestrator.isRegistered(entity)) return
 
+      // The action the route declares (#2497): a list route is governed by
+      // `list`. A route that declares none — any custom page — checks `read`.
+      const action = to.meta?.entityAction === 'list' ? 'list' : 'read'
+
       const checkEntity = (): { path: string } | undefined => {
         try {
           const manager = orchestrator.get(entity)
-          if (manager && !manager.canRead()) {
+          const allowed = manager && (action === 'list' ? manager.canList() : manager.canRead())
+          if (manager && !allowed) {
             console.warn(
-              `[qdadm] Access denied to ${to.path} (entity: ${entity})`
+              `[qdadm] Access denied to ${to.path} (entity: ${entity}, action: ${action})`
             )
             orchestrator.toast.error(
               'Access Denied',

package/src/kernel/Kernel.vue.ts

@@ -323,6 +323,9 @@ export function applyVueMethods(KernelClass: { prototype: Kernel }): void {
     }
 
     app.provide('qdadmSignals', this.signals)
+    // Whether the app runs in debug mode, for composables that only speak up
+    // then (#2484). Until now it reached nothing but window.__qdadm.
+    app.provide('qdadmDebug', !!this.options.debug)
 
     if (this.i18nInstance) {
       app.provide(I18N_INJECTION_KEY, this.i18nInstance)

package/src/kernel/KernelContext.routing.ts

@@ -245,7 +245,9 @@ export function applyRoutingMethods(KernelContextClass: { prototype: KernelConte
         path: '',
         name: routePrefix,
         component: pages.list,
-        meta: { layout: 'list' },
+        // The action this route performs, for the guard and the menu (#2497):
+        // a list page is governed by `list`, not by `read`.
+        meta: { layout: 'list', entityAction: 'list' },
       })
     }
 
@@ -254,7 +256,7 @@ export function applyRoutingMethods(KernelContextClass: { prototype: KernelConte
         path: `:${idParam}`,
         name: `${routePrefix}-show`,
         component: pages.show,
-        meta: { layout: 'show' },
+        meta: { layout: 'show', entityAction: 'read' },
       })
     }
 

package/src/security/RolesManager.ts

@@ -129,6 +129,12 @@ export class RolesManager extends EntityManager<RoleRecord> {
     return this._isAdmin()
   }
 
+  // The list page and its menu entry check `list` (#2497): without this, they
+  // would follow `entity:<x>:list` and show a system entity to non-admins.
+  canList(): boolean {
+    return this._isAdmin()
+  }
+
   canCreate(): boolean {
     return this._isAdmin()
   }

package/src/security/UsersManager.ts

@@ -146,6 +146,12 @@ export class UsersManager extends EntityManager {
     return this._isAdmin()
   }
 
+  // The list page and its menu entry check `list` (#2497): without this, they
+  // would follow `entity:<x>:list` and show a system entity to non-admins.
+  canList(): boolean {
+    return this._isAdmin()
+  }
+
   canCreate(): boolean {
     // little dumb but should work for simple storages
     return this._isAdmin()