@quazardous/qdadm 2.14.0 → 2.15.0

package/README.md

@@ -6,6 +6,7 @@
 
 ```bash
 npm install @quazardous/qdadm primevue @primeuix/themes primeicons vue-router pinia
+npm install -D sass-embedded   # compiles qdadm's shipped .scss styles (or `sass`)
 ```
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -51,16 +51,15 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@quazardous/qdcore": "^1.0.0",
-    "@types/pluralize": "^0.0.33",
+    "@quazardous/qdcore": "^1.1.0",
     "@quazardous/qddebug": "^1.0.0",
     "@quazardous/quarkernel": "^2.1.0",
-    "pluralize": "^8.0.0",
     "yaml": "^2.8.4"
   },
   "peerDependencies": {
     "pinia": "^2.0.0 || ^3.0.0 || ^4.0.0",
     "primevue": "^4.0.0",
+    "sass-embedded": "^1.0.0",
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
     "vue": "^3.3.0",
     "vue-router": "^4.0.0 || ^5.0.0"
@@ -74,6 +73,9 @@
     },
     "primevue": {
       "optional": true
+    },
+    "sass-embedded": {
+      "optional": "true"
     }
   },
   "optionalDependencies": {

package/src/chain/index.ts

@@ -7,6 +7,11 @@
  * - useActiveStack: Composable to build and access the sync stack
  * - useStackHydrator: Composable to access hydrated data
  *
+ * @experimental Navigation-stack plumbing that happens to be exported: the
+ * level shape and the hydration payloads may change in a minor release. The
+ * parent/child routing built on top of it is stable — see
+ * docs/API_STABILITY.md.
+ *
  * @module chain
  */
 

package/src/composables/useEntityItemShowPage.ts

@@ -57,6 +57,7 @@ import {
 import type { OrchestratorLike } from '../entity/EntityManager.interface'
 import type { ButtonSeverity } from '../types'
 import { useActionRegistry } from './useActionRegistry'
+import { useLiveEntity } from './useLiveEntity'
 
 // #1191 — shared structural view (manager tier from useEntityItemPage)
 type Orchestrator = OrchestratorLike<EntityManager>
@@ -306,6 +307,13 @@ export function useEntityItemShowPage<T = Record<string, unknown>>(
   })
 
   const { manager, orchestrator: baseOrchestrator, data, loading, error, entityId, entityLabel, isLoaded, hydrator } = base
+
+  // Reload when THIS record changed outside the session (#1888 lot D).
+  // Scoped by id: an event about another record must not reload every open
+  // detail page. An event carrying no id concerns the whole entity and applies.
+  useLiveEntity(entity, manager, async () => {
+    await base.reload()
+  }, { id: () => entityId.value })
   // Cast orchestrator to include toast methods
   const orchestrator = baseOrchestrator as Orchestrator
 

package/src/composables/useListPage.ts

@@ -34,6 +34,7 @@ import { useHooks } from './useHooks.js'
 import { useEntityItemPage, type ParentConfig, type UseEntityItemPageReturn } from './useEntityItemPage.js'
 import { useActiveStack } from '../chain/useActiveStack.js'
 import { useI18n } from '../i18n/useI18n'
+import { useLiveEntity } from './useLiveEntity'
 import { formatDateOnly } from '../utils/formatters'
 import { humanizeFieldName } from '../utils/humanize'
 
@@ -1047,6 +1048,27 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     window.removeEventListener('resize', handleResize)
   })
 
+  // Reload when this entity changed outside the session (#1888 lot D).
+  //
+  // Only fires for entities the app declared in sse.entities, so an app with
+  // no live backend is untouched. The reload preserves selection: a list
+  // refreshing under someone mid-bulk-action must not silently empty their
+  // checkboxes — the rows are re-matched by key, and anything that vanished
+  // server-side simply drops out.
+  useLiveEntity(entity, manager, async () => {
+    const keptKeys = new Set(
+      selected.value.map((item) => (item as Record<string, unknown>)[resolvedDataKey])
+    )
+
+    await loadItems({}, { force: true })
+
+    if (keptKeys.size) {
+      selected.value = items.value.filter((item) =>
+        keptKeys.has((item as Record<string, unknown>)[resolvedDataKey])
+      ) as T[]
+    }
+  })
+
   // ============ UTILITIES ============
   // Browser-locale by default (unified policy — see utils/formatters).
   function formatDate(
@@ -1112,6 +1134,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
 
   const listProps = computed<ListPageProps>(() => ({
     title: manager.labelPlural,
+    subtitle: config.subtitle !== undefined ? config.subtitle : (manager.description ?? null),
     headerActions: headerActions.value,
     cards: cards.value,
     columns: columns.value,

package/src/composables/useListPage.types.ts

@@ -247,6 +247,8 @@ export interface UseListPageOptions<T = unknown> {
   entityName?: string
   /** Override manager.labelPlural */
   entityNamePlural?: string
+  /** Override manager.description (list page subtitle). Pass null to suppress it. */
+  subtitle?: string | null
   /** Override manager.routePrefix */
   routePrefix?: string
 }
@@ -256,6 +258,7 @@ export interface UseListPageOptions<T = unknown> {
  */
 export interface ListPageProps {
   title: string | undefined
+  subtitle: string | null
   headerActions: ResolvedHeaderAction[]
   cards: CardConfig[]
   columns: ColumnConfig[]

package/src/composables/useLiveEntity.ts

@@ -0,0 +1,115 @@
+/**
+ * useLiveEntity — reload a mounted screen when its entity changed elsewhere
+ * (#1888 lot D, reported in #1887).
+ *
+ * Invalidating marks a cache stale; it does not repaint anything. A list that
+ * is *already on screen* keeps its rows until the user navigates away and back
+ * — which is precisely the case a pushing backend exists for: someone is
+ * looking at the screen right now.
+ *
+ * There is no page-level opt-in, deliberately. The gate is upstream: only an
+ * entity the app declared in `sse.entities` ever produces a remote event, so an
+ * app with no live backend sees no behaviour change and has no flag to forget.
+ * What the entity does about it is its own policy (`live` on the manager).
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+
+import { inject, onUnmounted } from 'vue'
+import type { SignalBus } from '../kernel/SignalBus'
+
+export interface UseLiveEntityOptions {
+  /**
+   * Only react to events carrying this record id. Detail screens pass their
+   * own id: without it, changing one record reloads every open detail page.
+   */
+  id?: () => string | number | null | undefined
+}
+
+interface LivePolicy {
+  refresh?: 'mounted' | false
+  coalesceMs?: number
+}
+
+
+/**
+ * Subscribe the calling component to remote changes of `entityName`.
+ *
+ * @param entityName - entity to watch
+ * @param manager - its manager, read for the `live` policy (may be null)
+ * @param reload - what to run; coalesced, never called concurrently by us
+ * @returns unsubscribe function (also called automatically on unmount)
+ */
+export function useLiveEntity(
+  entityName: string,
+  // Taken as unknown and read defensively: the page composables carry
+  // structural manager views (EntityManagerRead) that predate this policy.
+  manager: unknown,
+  reload: () => void | Promise<void>,
+  options: UseLiveEntityOptions = {}
+): () => void {
+  const signals = inject<SignalBus | null>('qdadmSignals', null)
+  if (!signals || !entityName) return () => {}
+
+  const policy = (manager as { live?: LivePolicy } | null | undefined)?.live ?? {}
+  // `refresh: false` — invalidation still happened upstream, the screen just
+  // does not chase it. Subscribing would only burn a listener.
+  if (policy.refresh === false) return () => {}
+
+  const coalesceMs = policy.coalesceMs ?? 300
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let disposed = false
+
+  const fire = (): void => {
+    timer = null
+    if (disposed) return
+    void reload()
+  }
+
+  const off = signals.on('entity:data-invalidate', (event: { name: string; data: unknown }) => {
+    const payload = (event.data || {}) as {
+      entity?: string
+      id?: string | number
+      source?: string
+    }
+
+    // Local writes are the manager's own echo: it has already repaired its
+    // cache and the page that triggered the write reloads on its own path.
+    if (payload.source !== 'remote') return
+    if (payload.entity !== entityName) return
+
+    if (options.id) {
+      const watched = options.id()
+      // An event carrying no id concerns the whole entity, so it always
+      // applies; one carrying a different id is somebody else's record.
+      if (
+        watched != null &&
+        payload.id !== undefined &&
+        String(payload.id) !== String(watched)
+      ) {
+        return
+      }
+    }
+
+    // Coalesce: a backend replaying fifty rows must cost one reload, not fifty.
+    if (coalesceMs <= 0) {
+      fire()
+      return
+    }
+    if (timer) return
+    timer = setTimeout(fire, coalesceMs)
+  })
+
+  const stop = (): void => {
+    disposed = true
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+    off()
+  }
+
+  onUnmounted(stop)
+
+  return stop
+}

package/src/deferred/index.ts

@@ -2,6 +2,11 @@
  * Deferred Module
  *
  * Named promise registry for loose async coupling between services and components.
+ *
+ * @experimental Shape may change in a minor release — see
+ * docs/API_STABILITY.md.
+ *
+ * @module deferred
  */
 
 export {

package/src/entity/EntityManager.cache.ts

@@ -332,6 +332,26 @@ export function applyCacheMethods(EntityManagerClass: { prototype: any }): void
       )
     }
 
+    // Listen for REMOTE changes to this entity — a mutation nobody here made.
+    //
+    // The invalidation signals were written for local mutations, where the
+    // manager that mutates repairs its own cache on the way out. A change that
+    // happened elsewhere repairs nothing, so the list cache would stay stale
+    // while claiming to be valid (#1887). Gated on the origin marker: without
+    // it, this handler would fire on every local write too and force a refetch
+    // of a list the manager is already holding correctly.
+    cleanups.push(
+      signals.on('entity:data-invalidate', (event: { name: string; data: unknown }) => {
+        const { entity, source } = (event.data || {}) as {
+          entity?: string
+          source?: string
+        }
+        if (source !== 'remote') return
+        if (entity !== this.name) return
+        this.invalidateCache()
+      })
+    )
+
     // Listen for own entity data changes to invalidate detail cache
     if (this.isAsymmetric && this.isDetailCacheEnabled) {
       cleanups.push(

package/src/entity/EntityManager.interface.ts

@@ -37,6 +37,8 @@ export interface EntityManagerBase<T = unknown> {
   readonly idField: string
   label?: string
   labelPlural?: string
+  /** Optional one-liner explaining what the entity is (list page subtitle) */
+  description?: string | null
   routePrefix?: string
   labelField?: string | ((entity: T) => string)
   readOnly?: boolean
@@ -137,6 +139,7 @@ export interface EntityManagerLike {
   idField: string
   label?: string
   labelPlural?: string
+  description?: string | null
   // Function-typed PROPERTY → strictly contravariant param; `never` is the
   // contravariant top, so the canonical `(entity: T) => string` assigns.
   // Cast at the call site when invoking.

package/src/entity/EntityManager.ts

@@ -1,7 +1,7 @@
 import { PermissiveAuthAdapter } from './auth/PermissiveAdapter'
 import { AuthActions, type AuthUser } from './auth/EntityAuthAdapter'
 import type { EntityAuthAdapter as IEntityAuthAdapter } from './auth/EntityAuthAdapter'
-import pluralize from 'pluralize'
+import pluralize from '../utils/pluralize'
 import { applyCacheMethods } from './EntityManager.cache'
 import { applyQueryMethods } from './EntityManager.query'
 import { applyRelationsMethods } from './EntityManager.relations'
@@ -63,6 +63,7 @@ import type {
   SeverityMap,
   SeverityDescriptor,
   EntityManagerOptions,
+  LiveEntityPolicy,
 } from './EntityManager.types'
 
 /**
@@ -82,6 +83,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _badges: ((entity: T) => EntityBadge[]) | null
   protected _label: string | null
   protected _labelPlural: string | null
+  protected _description: string | null
   protected _routePrefix: string | null
   protected _fields: Record<string, FieldConfig>
 
@@ -97,6 +99,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _readOnly: boolean
   protected _warmup: boolean
   protected _authSensitive: boolean
+  /** Reaction policy for changes made outside this session (#1888). */
+  protected _live: Required<LiveEntityPolicy>
   protected _system: boolean
 
   protected _scopeWhitelist: string[] | null
@@ -153,6 +157,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       idField = 'id',
       label = null,
       labelPlural = null,
+      description = null,
       routePrefix = null,
       labelField = 'name',
       badges = null,
@@ -166,6 +171,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       readOnly = false,
       warmup = true,
       authSensitive,
+      live,
       system = false,
       scopeWhitelist = null,
       isOwn = null,
@@ -185,6 +191,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
 
     this._label = label
     this._labelPlural = labelPlural
+    this._description = description
     this._routePrefix = routePrefix
     this._fields = fields
 
@@ -197,6 +204,11 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._readOnly = readOnly
     this._warmup = warmup
     this._authSensitive = authSensitive ?? this._getStorageRequiresAuth()
+    // Pre-wired defaults: the common case declares nothing.
+    this._live = {
+      refresh: live?.refresh ?? 'mounted',
+      coalesceMs: live?.coalesceMs ?? 300,
+    }
     this._system = system
 
     this._scopeWhitelist = scopeWhitelist
@@ -258,6 +270,10 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       entity: this.name,
       action,
       id,
+      // This manager just performed the mutation and has already repaired its
+      // own cache — marking the origin lets it ignore its own echo instead of
+      // refetching a list it is already holding correctly (#1888 lot B).
+      source: 'local',
     })
   }
 
@@ -415,6 +431,13 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     return plural.charAt(0).toUpperCase() + plural.slice(1)
   }
 
+  /**
+   * Optional one-liner explaining what the entity is (list page subtitle)
+   */
+  get description(): string | null {
+    return this._description
+  }
+
   /**
    * Get route prefix for this entity
    */
@@ -554,6 +577,11 @@ 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> {
+    return this._live
+  }
+
   canRead(entity: T | null = null): boolean {
     return this.canAccess(AuthActions.READ, entity)
   }

package/src/entity/EntityManager.types.ts

@@ -200,6 +200,24 @@ export type SeverityMapValue = string | SeverityDescriptor
 /** Severity map: field value → severity string or descriptor */
 export type SeverityMap = Record<string, SeverityMapValue>
 
+/**
+ * Policy for reacting to a change that happened outside this session.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+export interface LiveEntityPolicy {
+  /**
+   * `'mounted'` (default) — a screen currently showing this entity reloads.
+   * `false` — invalidate the cache only; the screen updates next time it asks.
+   */
+  refresh?: 'mounted' | false
+  /**
+   * Window (ms) over which a burst of events collapses into a single reload.
+   * Default 300. `0` reloads on every event — rarely what you want.
+   */
+  coalesceMs?: number
+}
+
 /**
  * EntityManager constructor options
  */
@@ -209,6 +227,8 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   idField?: string
   label?: string
   labelPlural?: string
+  /** Optional one-liner explaining what the entity is — shown under the list page title */
+  description?: string
   routePrefix?: string
   labelField?: string | ((entity: T) => string)
   /** Callback to compute badges for an entity item header */
@@ -228,6 +248,18 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   readOnly?: boolean
   warmup?: boolean
   authSensitive?: boolean
+  /**
+   * What this entity does when it learns it changed elsewhere (#1888).
+   *
+   * The kernel's `sse.entities` declares *that* an entity has an external
+   * writer — a deployment property. This is *what the entity does about it*,
+   * which is behaviour and belongs here. Pre-wired so the common case needs
+   * nothing: mounted screens refresh, bursts coalesce over 300 ms.
+   *
+   * Override per entity — a heavy `logs` list may want `refresh: false`, i.e.
+   * drop the stale cache but leave the screen alone until the user asks.
+   */
+  live?: LiveEntityPolicy
   system?: boolean
   scopeWhitelist?: string[] | null
   isOwn?: ((record: T, user: AuthUser) => boolean) | null

package/src/gen/vite-plugin.ts

@@ -4,6 +4,10 @@
  * Integrates generateManagers with Vite's build pipeline, triggering
  * entity manager file generation during the buildStart hook.
  *
+ * @experimental Undocumented build-time entry. Prefer the programmatic
+ * `generateManagers` entry (`@quazardous/qdadm/gen`), which is stable — see
+ * docs/API_STABILITY.md.
+ *
  * @module gen/vite-plugin
  */
 

package/src/index.ts

@@ -39,6 +39,16 @@ export type {
 } from './kernel/EventRouter'
 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 { LiveEntityRouter, createLiveEntityRouter } from './kernel/LiveEntityRouter'
+export type {
+  LiveEntityRouterOptions,
+  LiveEntityAction,
+  LiveEntitiesDeclaration,
+  LiveOrchestratorLike,
+} from './kernel/LiveEntityRouter'
 export { Module } from './kernel/Module'
 export { KernelContext, createKernelContext } from './kernel/KernelContext'
 export type {

package/src/kernel/Kernel.registries.ts

@@ -9,6 +9,7 @@ import { defaultStorageResolver } from '../entity/storage/factory'
 import { createDeferredRegistry } from '../deferred/DeferredRegistry.js'
 import { createEventRouter } from './EventRouter'
 import { createSSEBridge } from './SSEBridge'
+import { createLiveEntityRouter, type LiveOrchestratorLike } from './LiveEntityRouter'
 import { ActiveStack } from '../chain/ActiveStack.js'
 import { StackHydrator } from '../chain/StackHydrator.js'
 import { Orchestrator } from '../orchestrator/Orchestrator'
@@ -222,9 +223,14 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
 
     const debug = this.options.debug ?? false
 
-    const getToken = authAdapter?.getToken
-      ? () => authAdapter.getToken!()
-      : () => localStorage.getItem('auth_token')
+    // An explicit sse.getToken wins — including an explicit null, which means
+    // "send no token" and must not fall back to the auth adapter.
+    const getToken =
+      sse.getToken !== undefined
+        ? sse.getToken
+        : authAdapter?.getToken
+          ? () => authAdapter.getToken!()
+          : () => localStorage.getItem('auth_token')
 
     this.sseBridge = createSSEBridge({
       signals: this.signals!,
@@ -235,13 +241,33 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
       withCredentials: sse.withCredentials ?? false,
       tokenParam: sse.tokenParam ?? 'token',
       getToken,
+      ...(sse.connectOnSignal !== undefined ? { connectOnSignal: sse.connectOnSignal } : {}),
+      ...(sse.disconnectOnSignal !== undefined ? { disconnectOnSignal: sse.disconnectOnSignal } : {}),
       debug,
     })
 
-    if (sse.events?.length) {
+    // The declared entities imply their own frames: an app that declares
+    // `entities` should not also have to remember to list the event names.
+    const declaredEvents = sse.entities
+      ? ['entity:created', 'entity:updated', 'entity:deleted']
+      : []
+    const events = [...new Set([...(sse.events ?? []), ...declaredEvents])]
+
+    if (events.length) {
       this.signals!.once('sse:connected', () => {
-        this.sseBridge!.registerEvents(sse.events!)
+        this.sseBridge!.registerEvents(events)
+      })
+    }
+
+    if (sse.entities) {
+      this.liveEntityRouter = createLiveEntityRouter({
+        signals: this.signals!,
+        entities: sse.entities,
+        orchestrator: this.orchestrator as unknown as LiveOrchestratorLike,
+        signalPrefix: sse.signalPrefix ?? 'sse',
+        debug,
       })
+      this.liveEntityRouter.attachSignalTransport()
     }
   }
 }

package/src/kernel/Kernel.ts

@@ -39,6 +39,7 @@ import type { KernelContext } from './KernelContext'
 import type { DeferredRegistry } from '../deferred/DeferredRegistry.js'
 import type { EventRouter } from './EventRouter'
 import type { SSEBridge } from './SSEBridge'
+import type { LiveEntityRouter } from './LiveEntityRouter'
 import type { ActiveStack } from '../chain/ActiveStack.js'
 import type { StackHydrator } from '../chain/StackHydrator.js'
 import { NotificationModule } from '../notifications/NotificationModule'
@@ -89,6 +90,8 @@ export class Kernel {
   deferred: DeferredRegistry | null = null
   eventRouter: EventRouter | null = null
   sseBridge: SSEBridge | null = null
+  /** Routes external entity changes to cache invalidation (#1888). */
+  liveEntityRouter: LiveEntityRouter | null = null
   layoutComponents: InternalLayoutComponents | null = null
   securityChecker: SecurityChecker | null = null
   permissionRegistry: PermissionRegistry | null = null

package/src/kernel/Kernel.types.ts

@@ -109,6 +109,37 @@ export interface SSEConfig {
   withCredentials?: boolean
   tokenParam?: string
   events?: string[]
+  /**
+   * Entities this backend writes to out of session.
+   *
+   * The APP declares what it knows about the backend — the backend knows
+   * nothing of this config, it only emits. Declaring an entity here routes the
+   * stream's `entity:{created,updated,deleted}` frames to that entity's cache
+   * invalidation; anything not declared is ignored (a stream carries more than
+   * entity mutations). `true` or `'*'` accepts every registered entity.
+   *
+   * See docs/adr/0009-live-entities.md.
+   */
+  entities?: string[] | true | '*'
+  /**
+   * Token appended to the SSE URL as a query parameter.
+   *
+   * Defaults to the session auth adapter's token. Override it — the function
+   * may be async — when that durable credential must not reach an access log:
+   * return a short-lived, single-use ticket fetched per connect instead. Pass
+   * `null` to send no token at all (e.g. cookie auth with `withCredentials`).
+   */
+  getToken?: (() => string | null | Promise<string | null>) | null
+  /**
+   * Signal that triggers a connect. Defaults to `'auth:login'`;
+   * `null` disables the auth coupling.
+   */
+  connectOnSignal?: string | null
+  /**
+   * Signal that triggers a disconnect. Defaults to `'auth:logout'`;
+   * `null` disables the auth coupling.
+   */
+  disconnectOnSignal?: string | null
 }
 
 /**