@quazardous/qdadm 2.29.0 → 2.30.0

package/package.json

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

package/src/composables/useEntityItemShowPage.ts

@@ -58,7 +58,8 @@ import {
   type ShowResolvedFieldConfig,
 } from './createShowFieldResolver'
 import type { OrchestratorLike } from '../entity/EntityManager.interface'
-import type { ButtonSeverity } from '../types'
+import type { LiveEntityPolicy } from '../entity/EntityManager.types'
+import type { ButtonSeverity, EntityRecord } from '../types'
 import { useActionRegistry } from './useActionRegistry'
 import { useLiveEntity } from './useLiveEntity'
 
@@ -329,17 +330,35 @@ export function useEntityItemShowPage<T = Record<string, unknown>>(
   const notifications = useNotifications()
   const route = useRoute()
   useLiveEntity(entity, manager, async () => {
+    // A burst of events is one reload, so this is the record from before the burst.
+    const before = data.value
     const record = await base.reload()
     // A change made elsewhere to the record on screen leaves a line in the
-    // history (#2677): short-lived, linked back to it, never a pop-up.
+    // history (#2677): short-lived, linked back to it, never a pop-up. The
+    // entity may say the change is not worth one, or what it means (#2685).
     if (!record) return
-    const name = entityLabel.value ? `"${entityLabel.value}"` : `#${entityId.value}`
-    notifications.addNotification({
-      severity: 'info',
-      summary: `${manager.label ?? entity} ${name} updated elsewhere`,
-      keep: 'short',
-      ...(route?.name ? { to: { name: String(route.name), params: { ...route.params } } } : {}),
-    })
+    const to = route?.name ? { to: { name: String(route.name), params: { ...route.params } } } : {}
+    const describeUpdate = (manager as { live?: LiveEntityPolicy }).live?.describeUpdate
+    if (!describeUpdate) {
+      const name = entityLabel.value ? `"${entityLabel.value}"` : `#${entityId.value}`
+      notifications.addNotification({
+        severity: 'info',
+        summary: `${manager.label ?? entity} ${name} updated elsewhere`,
+        keep: 'short',
+        ...to,
+      })
+      return
+    }
+    if (!before) return
+    let entry
+    try {
+      entry = describeUpdate(before as unknown as EntityRecord, record as unknown as EntityRecord)
+    } catch (err) {
+      console.warn(`[qdadm] live.describeUpdate failed for ${entity} #${entityId.value}:`, err)
+      return
+    }
+    if (!entry) return
+    notifications.addNotification({ severity: 'info', keep: 'short', ...to, ...entry })
   }, {
     id: () => entityId.value,
     // The update has arrived: say so on the badge at once — before the reload is

package/src/entity/EntityManager.ts

@@ -105,7 +105,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _warmup: boolean
   protected _authSensitive: boolean
   /** Reaction policy for changes made outside this session (#1888). */
-  protected _live: Required<LiveEntityPolicy>
+  protected _live: LiveEntityPolicy & Required<Pick<LiveEntityPolicy, 'refresh' | 'coalesceMs'>>
   protected _system: boolean
 
   protected _scopeWhitelist: string[] | null
@@ -215,6 +215,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._live = {
       refresh: live?.refresh ?? 'mounted',
       coalesceMs: live?.coalesceMs ?? 300,
+      ...(live?.describeUpdate ? { describeUpdate: live.describeUpdate } : {}),
     }
     this._system = system
 
@@ -640,7 +641,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
    * Check if user can read entities
    */
   /** Reaction policy for changes made outside this session (#1888). */
-  get live(): Required<LiveEntityPolicy> {
+  get live(): LiveEntityPolicy & Required<Pick<LiveEntityPolicy, 'refresh' | 'coalesceMs'>> {
     return this._live
   }
 

package/src/entity/EntityManager.types.ts

@@ -17,6 +17,7 @@ import type { HookRegistry } from '../hooks/HookRegistry'
 // Circular type import — safe because `import type` is erased at runtime
 import type { EntityManager } from './EntityManager'
 import type { RouteStatePersister } from '../routeState'
+import type { NewNotification } from '../notifications/NotificationStore'
 
 // ============ INTERNAL TYPES ============
 
@@ -230,8 +231,24 @@ export interface LiveEntityPolicy {
    * Default 300. `0` reloads on every event — rarely what you want.
    */
   coalesceMs?: number
+  /**
+   * Whether a live reload of a detail page is worth a notification entry, and
+   * what it says (#2685). Called once per reload, with the record that was on
+   * screen and the reloaded one.
+   *
+   * Return `null` / `undefined` for no entry (the badge still flashes), or the
+   * entry: `severity` defaults to `'info'`, `keep` to `'short'`, `to` to the
+   * record's page. Without this hook, the page adds a generic
+   * "… updated elsewhere" entry. If it throws, no entry is added.
+   *
+   * Do not mutate `before` or `after`: they are the page's own records.
+   */
+  describeUpdate?: (before: EntityRecord, after: EntityRecord) => LiveUpdateEntry | null | undefined
 }
 
+/** The notification entry `LiveEntityPolicy.describeUpdate` asks for (#2685). */
+export type LiveUpdateEntry = Omit<NewNotification, 'severity'> & Partial<Pick<NewNotification, 'severity'>>
+
 /**
  * EntityManager constructor options
  */

package/src/index.ts

@@ -41,7 +41,7 @@ export { SSEBridge, createSSEBridge, SSE_SIGNALS } from './kernel/SSEBridge'
 export type { SSEBridgeOptions } from './kernel/SSEBridge'
 export { useLiveEntity } from './composables/useLiveEntity'
 export type { UseLiveEntityOptions } from './composables/useLiveEntity'
-export type { LiveEntityPolicy } from './entity/EntityManager.types'
+export type { LiveEntityPolicy, LiveUpdateEntry } from './entity/EntityManager.types'
 export { LiveEntityRouter, createLiveEntityRouter } from './kernel/LiveEntityRouter'
 export type {
   LiveEntityRouterOptions,

package/src/notifications/NotificationPanel.vue

@@ -8,7 +8,7 @@
  * - Mobile: Full width overlay at bottom of screen
  *
  * Features:
- * - Inline action bar (mark read, clear, close) at top right
+ * - Toolbar row (mark read, clear, close) above the list
  * - Status items section (custom module items)
  * - Notification list (most recent first)
  * - Empty state
@@ -189,16 +189,15 @@ function formatTime(timestamp: number): string {
   left: calc(var(--fad-sidebar-width-collapsed, 2.5rem) + 0.375rem);
 }
 
-/* Inline toolbar - floats top-right inside the panel */
+/* Toolbar - its own row above the list, so its buttons never cover an entry's dismiss button */
 .notification-toolbar {
-  position: absolute;
-  top: 0;
-  right: 0;
   display: flex;
   align-items: center;
+  justify-content: flex-end;
   gap: 1px;
   padding: 0.25rem;
-  z-index: 1;
+  border-bottom: 1px solid var(--p-surface-100, #f1f5f9);
+  flex-shrink: 0;
 }
 
 .notification-toolbar-btn {
@@ -228,7 +227,6 @@ function formatTime(timestamp: number): string {
 /* Status items */
 .notification-panel-status {
   padding: 0.5rem 0.625rem;
-  padding-right: 2.5rem;
   border-bottom: 1px solid var(--p-surface-100, #f1f5f9);
   flex-shrink: 0;
 }
@@ -309,10 +307,6 @@ function formatTime(timestamp: number): string {
   transition: background 0.1s;
 }
 
-.notification-item:first-child {
-  padding-right: 2.5rem;
-}
-
 .notification-item:hover {
   background: var(--p-surface-50, #f8fafc);
 }

package/src/types/index.ts

@@ -175,7 +175,7 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   warmup?: boolean
   authSensitive?: boolean
   /** What this entity does when it changed elsewhere (#1888). */
-  live?: { refresh?: 'mounted' | false; coalesceMs?: number }
+  live?: import('../entity/EntityManager.types').LiveEntityPolicy
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: unknown) => boolean) | null