@quazardous/qdadm 2.23.0 → 2.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.23.0",
+  "version": "2.25.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/entity/EntityManager.ts

@@ -654,7 +654,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   }
 
   /**
-   * Check if entity is system-provided (roles, users)
+   * Whether this entity is one the framework provides (roles, users). Owned
+   * by qdadm — see `EntityManagerOptions.system`.
    */
   get system(): boolean {
     return this._system

package/src/entity/EntityManager.types.ts

@@ -271,6 +271,15 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
    * drop the stale cache but leave the screen alone until the user asks.
    */
   live?: LiveEntityPolicy
+  /**
+   * Marks an entity the framework provides (`roles`, `users`). Owned by
+   * qdadm: set by its system managers (`RolesManager`, `UsersManager`), not
+   * by applications. Behaviour may be attached to it in any release.
+   *
+   * To keep a system entity on your own storage, use its manager with your
+   * storage — `new RolesManager({ storage })` — rather than setting the flag
+   * on a plain entity.
+   */
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: AuthUser) => boolean) | null

package/src/entity/auth/SecurityChecker.ts

@@ -26,8 +26,8 @@ export interface GrantJudgeContext {
    *
    * `install` runs while the Kernel is still being built, before modules
    * register their entities, so `getKeys()` called here returns only the
-   * framework's own namespaces. Read the keys when you pre-warm (after login,
-   * before mount), not in `install`.
+   * framework's own namespaces. Read the keys when you fetch (on `kernel:ready`
+   * or `auth:login`), not in `install`.
    */
   permissionRegistry?: { getKeys(): string[] }
 }
@@ -44,12 +44,29 @@ export interface GrantJudgeContext {
  *   built-in judgement, which stays the default.
  * - A judge that THROWS denies — see `SecurityChecker._judge`.
  *
- * `isGranted` is called synchronously on every check, so answer from memory.
- * Fetch in bulk beforehand and emit `security:changed` when answers change.
+ * `isGranted` is called synchronously on every check, so answer from memory,
+ * and emit `security:changed` when answers change.
+ *
+ * A judge whose answers come from a request cannot have them before the first
+ * navigation: it starts inside `createApp()`. Such a judge implements `ready()`
+ * (#2412), and the route guard waits for it instead of deciding early.
  */
 export interface GrantJudge {
   isGranted(attribute: string, subject: unknown, user: AuthUser): boolean | undefined
   install?(ctx: GrantJudgeContext): void
+  /**
+   * Settles once the answers for the current user are loaded (#2412).
+   *
+   * Return the promise of the load in progress — the one started on
+   * `kernel:ready`, or the new one after `auth:login` — so the route guard
+   * waits for this user's answers, not an earlier user's. A resolved promise
+   * means "decide now". A rejection, or no settling within
+   * `security.readyTimeoutMs`, denies the navigation: the unknown is never
+   * allowed, only no longer decided before the answers can exist.
+   *
+   * Optional: a judge that answers from memory from the start needs none.
+   */
+  ready?(): Promise<void>
 }
 
 /**

package/src/kernel/Kernel.registries.ts

@@ -406,13 +406,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
     this._warnUnknownKeys(
       'security.',
       security,
-      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant']),
+      new Set(['role_hierarchy', 'role_permissions', 'role_labels', 'entity_permissions', 'rolesProvider', 'grant', 'readyTimeoutMs']),
       {
         role_hierarchy: 'roles will not inherit from one another',
         role_permissions: 'no role will carry any permission',
         entity_permissions: 'per-entity permissions will not be generated',
         rolesProvider: "the current user's roles will not be resolved",
         grant: "the application's judgement will not be consulted — the role matrix decides alone",
+        readyTimeoutMs: 'the route guard waits the default 10 s for grant.ready()',
       }
     )
   }

package/src/kernel/Kernel.routing.ts

@@ -15,6 +15,28 @@ type Self = Kernel
 /**
  * Patch Kernel prototype with routing-related methods.
  */
+/**
+ * `judge.ready()`, bounded (#2412): a judge that never settles must not hold a
+ * navigation forever. A synchronous throw from `ready()` counts as a rejection.
+ */
+function waitForJudge(judge: { ready(): Promise<void> }, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`no answer within ${timeoutMs} ms`)), timeoutMs)
+    Promise.resolve()
+      .then(() => judge.ready())
+      .then(
+        () => {
+          clearTimeout(timer)
+          resolve()
+        },
+        (e: unknown) => {
+          clearTimeout(timer)
+          reject(e instanceof Error ? e : new Error(String(e)))
+        }
+      )
+  })
+}
+
 export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
   const proto = KernelClass.prototype
 
@@ -230,14 +252,17 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
       // declared before its manager loads) — allow. This is the ONLY
       // allowed pass-through; a failing access check must fail CLOSED,
       // not silently allow (#1190).
-      if (entity && this.orchestrator && this.orchestrator.isRegistered(entity)) {
+      const orchestrator = this.orchestrator
+      if (!entity || !orchestrator || !orchestrator.isRegistered(entity)) return
+
+      const checkEntity = (): { path: string } | undefined => {
         try {
-          const manager = this.orchestrator.get(entity)
+          const manager = orchestrator.get(entity)
           if (manager && !manager.canRead()) {
             console.warn(
               `[qdadm] Access denied to ${to.path} (entity: ${entity})`
             )
-            this.orchestrator.toast.error(
+            orchestrator.toast.error(
               'Access Denied',
               `You don't have permission to access ${manager.labelPlural || entity}`,
               'Kernel'
@@ -256,7 +281,23 @@ export function applyRoutingMethods(KernelClass: { prototype: Kernel }): void {
           )
           return { path: '/' }
         }
+        return undefined
       }
+
+      // A judge whose answers come from a request cannot have them yet on the
+      // first navigation, which starts inside createApp() (#2412). Its cache
+      // miss would fall through to an empty role matrix and read as a refusal:
+      // wait for its answers instead of deciding early. Still fail closed — a
+      // judge that rejects or never settles denies.
+      const judge = this.securityChecker?.grant
+      if (typeof judge?.ready !== 'function') return checkEntity()
+      const timeoutMs = this.options.security?.readyTimeoutMs ?? 10_000
+      return waitForJudge(judge as { ready(): Promise<void> }, timeoutMs).then(checkEntity, (reason: Error) => {
+        console.error(
+          `[qdadm] security.grant never became ready for ${to.path} (entity: ${entity}): ${reason.message} — denying navigation`
+        )
+        return { path: '/' }
+      })
     })
   }
 

package/src/kernel/Kernel.types.ts

@@ -105,6 +105,11 @@ export interface SecurityConfig {
    * throws denies. See docs/security.md.
    */
   grant?: GrantJudge
+  /**
+   * How long the route guard waits for `grant.ready()` before denying (#2412).
+   * Default 10000 ms. Only used when the judge implements `ready()`.
+   */
+  readyTimeoutMs?: number
 }
 
 /**

package/src/security/RolesManager.ts

@@ -40,6 +40,22 @@ interface EntityManagerInstance {
   }
 }
 
+/**
+ * The `roles` system entity.
+ *
+ * It is a system entity because this manager makes it one — apps do not set
+ * `system` themselves. To keep roles behind your own API, give it your
+ * storage; it stays a system entity:
+ *
+ * ```ts
+ * ctx.entity('roles', new RolesManager({ storage: myApiStorage }))
+ * ```
+ *
+ * Two things change compared with a plain entity, and both are deliberate:
+ * every `can*` goes through ONE permission (`adminPermission`), and `fields`
+ * / `idField` assume qdadm's shape (`name`, `label`, `permissions`,
+ * `inherits`) — override them when your API serves another one.
+ */
 export class RolesManager extends EntityManager<RoleRecord> {
   private _rolesProvider: RoleProvider | null
   private _permissionRegistry: PermissionRegistry | null
@@ -128,8 +144,12 @@ export class RolesManager extends EntityManager<RoleRecord> {
   canDelete(item?: RoleRecord | null): boolean {
     if (!this._isAdmin()) return false
     if (item) {
-      // Protected system roles cannot be deleted
-      return !RolesManager.PROTECTED_ROLES.includes(item.name)
+      // Protected system roles cannot be deleted. The role code is `name` in qdadm's shape, but an
+      // app whose API keys roles differently overrides `idField` (#2406): read both, or the guard
+      // silently stops matching.
+      const record = item as unknown as Record<string, unknown>
+      const codes = [record.name, record[this.idField]]
+      return !codes.some((code) => typeof code === 'string' && RolesManager.PROTECTED_ROLES.includes(code))
     }
     return true
   }