@quazardous/qdadm 2.28.0 → 2.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.28.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,18 +330,41 @@ 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 } } } : {}),
-    })
-  }, { id: () => entityId.value })
+    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
+    // coalesced, let alone finished (#2679).
+    onEvent: () => notifications.flash(),
+  })
   // Cast orchestrator to include toast methods
   const orchestrator = baseOrchestrator as Orchestrator
 

package/src/composables/useLiveEntity.ts

@@ -27,6 +27,12 @@ export interface UseLiveEntityOptions {
    * own id: without it, changing one record reloads every open detail page.
    */
   id?: () => string | number | null | undefined
+  /**
+   * Called at once for every event that concerns this screen, before the
+   * reload is coalesced (#2679) — for a cue that must not wait, like the
+   * notification badge's flash.
+   */
+  onEvent?: () => void
 }
 
 interface LivePolicy {
@@ -129,6 +135,8 @@ export function useLiveEntity(
       }
     }
 
+    options.onEvent?.()
+
     // Coalesce: a backend replaying fifty rows must cost one reload, not fifty.
     if (coalesceMs <= 0) {
       fire()

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/NotificationBadge.vue

@@ -7,7 +7,8 @@
  * - something needs attention: the parent layout blinks the logo via
  *   :has(.notification-badge-zone--alert);
  * - how many entries are unread: a count;
- * - work is in progress: a ring, once tracked work has lasted `activityDelayMs`.
+ * - work is in progress: a ring, once tracked work has lasted `activityDelayMs`;
+ * - something just arrived: a short flash, immediately (#2679).
  *
  * Click toggles the notification panel open/close.
  */
@@ -29,6 +30,7 @@ const unreadLabel = computed(() => (unread.value > 99 ? '99+' : String(unread.va
     @click.stop.prevent="store.toggle()"
   >
     <span v-if="store.isBusy.value" class="notification-badge-ring" role="progressbar" aria-label="Loading" />
+    <span v-if="store.isFlashing.value" class="notification-badge-flash" aria-hidden="true" />
     <span v-if="unread > 0" class="notification-badge-count">{{ unreadLabel }}</span>
   </div>
 </template>
@@ -78,11 +80,30 @@ const unreadLabel = computed(() => (unread.value > 99 ? '99+' : String(unread.va
   to { transform: rotate(360deg); }
 }
 
+/* Something just arrived: a halo that grows out of the logo and fades. */
+.notification-badge-flash {
+  position: absolute;
+  inset: 0;
+  border-radius: 50%;
+  pointer-events: none;
+  animation: notification-badge-flash 0.9s ease-out 1;
+}
+
+@keyframes notification-badge-flash {
+  0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--p-primary-color, #3b82f6) 70%, transparent); }
+  100% { box-shadow: 0 0 0 14px color-mix(in srgb, var(--p-primary-color, #3b82f6) 0%, transparent); }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .notification-badge-ring {
     animation: none;
     border-color: var(--p-primary-color, #3b82f6);
     opacity: 0.5;
   }
+
+  .notification-badge-flash {
+    animation: none;
+    box-shadow: 0 0 0 3px var(--p-primary-color, #3b82f6);
+  }
 }
 </style>

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/notifications/NotificationStore.ts

@@ -118,6 +118,14 @@ export interface NotificationStore {
   track<T>(work: Promise<T>): Promise<T>
   /** True once tracked work has been in progress for `activityDelayMs`. */
   isBusy: ComputedRef<boolean>
+  /**
+   * Flash the badge: something just arrived — an update to the record on
+   * screen (#2679). Immediate, never delayed; a flash already running absorbs
+   * further calls, so a burst flashes once.
+   */
+  flash(): void
+  /** True while the badge flashes. */
+  isFlashing: ComputedRef<boolean>
 
   // Panel state
   isOpen: Ref<boolean>
@@ -288,6 +296,20 @@ export function createNotificationStore(config: NotificationStoreConfig = {}): N
     return work
   }
 
+  // ── Flash ──────────────────────────────────────────────────────────────
+
+  const FLASH_MS = 900
+  const flashing = ref(false)
+
+  function flash(): void {
+    // A burst of updates flashes once: the running flash already says it.
+    if (flashing.value) return
+    flashing.value = true
+    setTimeout(() => {
+      flashing.value = false
+    }, FLASH_MS)
+  }
+
   // ── Panel state ────────────────────────────────────────────────────────
 
   function open(): void {
@@ -338,6 +360,8 @@ export function createNotificationStore(config: NotificationStoreConfig = {}): N
     removeStatus,
     track,
     isBusy: computed(() => busy.value),
+    flash,
+    isFlashing: computed(() => flashing.value),
     isOpen,
     open,
     close,
@@ -383,6 +407,8 @@ export function useNotifications(): NotificationStore {
       removeStatus: () => {},
       track: (work) => work,
       isBusy: computed(() => false),
+      flash: () => {},
+      isFlashing: computed(() => false),
       isOpen: ref(false),
       open: () => {},
       close: () => {},

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