@quazardous/qdadm 2.25.0 → 2.26.0

package/package.json

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

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()