@quazardous/qdadm 2.14.0 → 2.16.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.16.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/qddebug": "^1.0.0",
+    "@quazardous/qdcore": "^1.1.0",
+    "@quazardous/qddebug": "^1.1.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/i18n/I18n.ts

@@ -70,6 +70,8 @@ export class I18n {
   // Concurrent domain loads — share one in-flight promise per (locale, domain)
   // pair across providers and t() callers.
   private _inflightDomains: Map<string, Promise<void>> = new Map()
+  // (locale::key) pairs already announced on the bus — see onMissing.
+  private _missingReported: Set<string> = new Set()
 
   constructor(options: I18nOptions = {}, deps: I18nDeps = {}) {
     this._defaultLocale = options.defaultLocale ?? 'en'
@@ -101,7 +103,16 @@ export class I18n {
       fallbackLocale: this._fallbackLocale,
       globalAliases: this._currentStrategyAliases(),
       onMissing: (key, locale) => {
-        if (this._emitMissing) this._signals?.emit('i18n:missing', { key, locale })
+        if (!this._emitMissing) return
+        // A missing key is a FACT, not a stream: knowing it once is the whole
+        // diagnostic value. Emitting on every resolution turned a signal into
+        // a firehose — the same seven nav keys fired 1616 times in two seconds
+        // downstream, and each emission was recorded by two collectors, which
+        // fed the tick that triggered the next resolution (#1896).
+        const seenKey = `${locale}::${key}`
+        if (this._missingReported.has(seenKey)) return
+        this._missingReported.add(seenKey)
+        this._signals?.emit('i18n:missing', { key, locale })
       },
     })
 
@@ -184,6 +195,7 @@ export class I18n {
     if (this.locale.value === locale && this._loadedLocales.has(locale)) return
     await this._loadLocale(locale)
     this.locale.value = locale
+    this._resetMissingReports()
     this._signals?.emit('locale:changed', locale)
   }
 
@@ -247,6 +259,17 @@ export class I18n {
   // Internals
   // ---------------------------------------------------------------------------
 
+  /**
+   * Forget which missing keys were already announced.
+   *
+   * Called whenever new messages arrive or the locale changes: a key that was
+   * missing may now resolve, and one that goes missing again afterwards is
+   * news worth reporting once more.
+   */
+  private _resetMissingReports(): void {
+    this._missingReported.clear()
+  }
+
   private async _loadLocale(locale: string): Promise<void> {
     for (const p of this._providers) {
       const bundle = await p.load(locale)
@@ -300,6 +323,7 @@ export class I18n {
       this._loadedDomains.add(cacheKey)
       this._inflightDomains.delete(cacheKey)
       if (merged) {
+        this._resetMissingReports()
         this._signals?.emit('i18n:domain-loaded', { locale, domain })
       }
     })()

package/src/i18n/__tests__/I18n.missingCap.test.ts

@@ -0,0 +1,82 @@
+/**
+ * A missing key is announced once, not on every resolution (#1896).
+ *
+ * Downstream, seven nav labels fired 1616 `i18n:missing` each in two seconds:
+ * every render resolved them, every resolution emitted, and each emission was
+ * recorded by two collectors that bumped the tick driving the next render.
+ * Capping the signal removes the fuel — the diagnostic value of a missing key
+ * is knowing it exists, which takes exactly one signal.
+ */
+import { describe, it, expect, beforeEach } from 'vitest'
+import { I18n } from '../I18n'
+
+function makeI18n(options = {}) {
+  const emitted: Array<{ signal: string; payload: unknown }> = []
+  const signals = {
+    emit: (signal: string, payload?: unknown) => {
+      emitted.push({ signal, payload })
+    },
+    on: () => () => {},
+  }
+  const i18n = new I18n({ disableDefaultCoreBundle: true, ...options }, { signals })
+  const missing = () => emitted.filter((e) => e.signal === 'i18n:missing')
+  return { i18n, emitted, missing }
+}
+
+describe('I18n — missing keys are announced once', () => {
+  it('emits once however many times the key is resolved', () => {
+    const { i18n, missing } = makeI18n()
+
+    for (let i = 0; i < 200; i++) i18n.t('nav.sections.Control')
+
+    const announced = missing()
+    expect(announced).toHaveLength(1)
+    expect((announced[0]!.payload as { key: string }).key).toBe('nav.sections.Control')
+  })
+
+  it('still announces each distinct key', () => {
+    const { i18n, missing } = makeI18n()
+
+    for (let i = 0; i < 50; i++) {
+      i18n.t('nav.routes.run')
+      i18n.t('nav.routes.job')
+      i18n.t('breadcrumb.details')
+    }
+
+    expect(missing()).toHaveLength(3)
+    expect(missing().map((m) => (m.payload as { key: string }).key).sort()).toEqual([
+      'breadcrumb.details',
+      'nav.routes.job',
+      'nav.routes.run',
+    ])
+  })
+
+  it('keeps returning the fallback — capping the signal changes no output', () => {
+    const { i18n } = makeI18n()
+
+    const first = i18n.t('nav.routes.run')
+    const later = i18n.t('nav.routes.run')
+
+    expect(later).toBe(first)
+  })
+
+  it('honours emitMissing: false', () => {
+    const { i18n, missing } = makeI18n({ emitMissing: false })
+
+    i18n.t('nav.routes.run')
+
+    expect(missing()).toHaveLength(0)
+  })
+
+  it('announces again after the locale changes — the fact may no longer hold', async () => {
+    const { i18n, missing } = makeI18n()
+
+    i18n.t('nav.routes.run')
+    expect(missing()).toHaveLength(1)
+
+    await i18n.changeLocale('fr')
+    i18n.t('nav.routes.run')
+
+    expect(missing()).toHaveLength(2)
+  })
+})

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 {