@quazardous/qdadm 2.30.0 → 2.31.0

package/package.json

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

package/src/components/show/ShowDisplay.vue

@@ -28,7 +28,7 @@
 import { computed, type PropType } from 'vue'
 import { RouterLink, type RouteLocationRaw } from 'vue-router'
 import Tag from 'primevue/tag'
-import { formatDate, formatNumber, formatCurrency } from '../../utils/formatters'
+import { formatDate, formatNumber, formatCurrency, getEmptyPlaceholder } from '../../utils/formatters'
 
 type DisplayType =
   | 'text'
@@ -80,6 +80,8 @@ interface FieldConfig {
   imageHeight?: string
   // Custom render
   render?: (value: unknown) => string
+  /** Shown for an empty value; defaults to the kernel's `display.emptyPlaceholder` (#2772). */
+  emptyText?: string
 }
 
 const props = defineProps({
@@ -97,16 +99,19 @@ const isEmpty = computed(() => {
   return props.value === null || props.value === undefined || props.value === ''
 })
 
+// What an empty value shows: the field's own, else the app-wide placeholder (#2772)
+const emptyText = computed(() => props.field.emptyText ?? getEmptyPlaceholder())
+
 // Format text value
 const textValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   if (props.field.render) return props.field.render(props.value)
   return String(props.value)
 })
 
 // Format number value (browser locale by default — utils/formatters policy)
 const numberValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   const num = Number(props.value)
   if (isNaN(num)) return String(props.value)
   // useGrouping: false → no locale digit grouping (years, ids… "1965",
@@ -117,7 +122,7 @@ const numberValue = computed(() => {
 
 // Format currency value
 const currencyValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   const num = Number(props.value)
   if (isNaN(num)) return String(props.value)
   return formatCurrency(num, props.field.currencyCode || 'USD', props.field.locale)
@@ -125,7 +130,7 @@ const currencyValue = computed(() => {
 
 // Format boolean value
 const booleanValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   const labels = props.field.booleanLabels || { true: 'Yes', false: 'No' }
   return props.value ? labels.true : labels.false
 })
@@ -142,7 +147,7 @@ const booleanIconClass = computed(() => {
 
 // Format date value
 const dateValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   const v = props.value as unknown
   const date = (typeof v === 'object' && v instanceof Date) ? v : new Date(String(v))
   if (isNaN(date.getTime())) return String(props.value)
@@ -152,7 +157,7 @@ const dateValue = computed(() => {
 
 // Format datetime value
 const datetimeValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   const v = props.value as unknown
   const date = (typeof v === 'object' && v instanceof Date) ? v : new Date(String(v))
   if (isNaN(date.getTime())) return String(props.value)
@@ -161,7 +166,7 @@ const datetimeValue = computed(() => {
 
 // Format select value (lookup label from options)
 const selectValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   const options = props.field.options || []
   const optionValue = props.field.optionValue || 'value'
   const optionLabel = props.field.optionLabel || 'label'
@@ -184,7 +189,7 @@ const referenceRoute = computed<RouteLocationRaw | null>(() => {
 
 // Reference label
 const referenceLabel = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   if (typeof props.field.referenceLabel === 'function') {
     return props.field.referenceLabel(props.value)
   }
@@ -215,7 +220,7 @@ const badgeIcon = computed(() => badgeDescriptor.value.icon)
 
 // JSON formatted
 const jsonValue = computed(() => {
-  if (isEmpty.value) return '-'
+  if (isEmpty.value) return emptyText.value
   try {
     return JSON.stringify(props.value, null, 2)
   } catch {
@@ -232,7 +237,7 @@ const imageStyle = computed(() => ({
 
 <template>
   <!-- Empty value -->
-  <span v-if="isEmpty" class="show-display show-display--empty">-</span>
+  <span v-if="isEmpty" class="show-display show-display--empty">{{ emptyText }}</span>
 
   <!-- Text -->
   <span v-else-if="displayType === 'text'" class="show-display show-display--text">

package/src/composables/useEntityItemShowPage.ts

@@ -361,6 +361,7 @@ export function useEntityItemShowPage<T = Record<string, unknown>>(
     notifications.addNotification({ severity: 'info', keep: 'short', ...to, ...entry })
   }, {
     id: () => entityId.value,
+    screen: 'show',
     // The update has arrived: say so on the badge at once — before the reload is
     // coalesced, let alone finished (#2679).
     onEvent: () => notifications.flash(),

package/src/composables/useListPage.ts

@@ -1227,7 +1227,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
         keptKeys.has((item as Record<string, unknown>)[resolvedDataKey])
       ) as T[]
     }
-  })
+  }, { screen: 'list' })
 
   // ============ UTILITIES ============
   // Browser-locale by default (unified policy — see utils/formatters).

package/src/composables/useLiveEntity.ts

@@ -10,7 +10,9 @@
  * 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).
+ * What the entity does about it is its own policy (`live` on the manager) —
+ * which may differ per screen and per change kind (#2971); the page builders
+ * only say which screen they are.
  *
  * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
  */
@@ -33,10 +35,17 @@ export interface UseLiveEntityOptions {
    * notification badge's flash.
    */
   onEvent?: () => void
+  /**
+   * Which screen this is, to pick its rule when the entity's `live.refresh`
+   * is set per screen (#2971). Without it, a per-screen policy means `'mounted'`.
+   */
+  screen?: 'list' | 'show'
 }
 
+type RefreshRule = 'mounted' | false | string[]
+
 interface LivePolicy {
-  refresh?: 'mounted' | false
+  refresh?: RefreshRule | { list?: RefreshRule; show?: RefreshRule }
   coalesceMs?: number
 }
 
@@ -62,9 +71,15 @@ export function useLiveEntity(
   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 refresh = policy.refresh
+  const rule: RefreshRule = refresh !== null && typeof refresh === 'object' && !Array.isArray(refresh)
+    ? (options.screen ? refresh[options.screen] : undefined) ?? 'mounted'
+    : refresh ?? 'mounted'
+  // `false` — invalidation still happened upstream, the screen just does not
+  // chase it. Subscribing would only burn a listener.
+  if (rule === false) return () => {}
+  // An array names the change kinds worth a reload (#2971).
+  const kinds = Array.isArray(rule) ? new Set(rule) : null
 
   const coalesceMs = policy.coalesceMs ?? 300
   let timer: ReturnType<typeof setTimeout> | null = null
@@ -114,6 +129,7 @@ export function useLiveEntity(
     const payload = (event.data || {}) as {
       entity?: string
       id?: string | number
+      action?: string
       source?: string
     }
 
@@ -135,6 +151,10 @@ export function useLiveEntity(
       }
     }
 
+    // A kind this screen ignores is not news to it: no cue, no reload. An event
+    // carrying no kind is an update, as the live router reports it by default.
+    if (kinds && !kinds.has(payload.action ?? 'updated')) return
+
     options.onEvent?.()
 
     // Coalesce: a backend replaying fifty rows must cost one reload, not fifty.

package/src/entity/EntityManager.types.ts

@@ -18,6 +18,7 @@ import type { HookRegistry } from '../hooks/HookRegistry'
 import type { EntityManager } from './EntityManager'
 import type { RouteStatePersister } from '../routeState'
 import type { NewNotification } from '../notifications/NotificationStore'
+import type { LiveEntityAction } from '../kernel/LiveEntityRouter'
 
 // ============ INTERNAL TYPES ============
 
@@ -224,8 +225,13 @@ export interface LiveEntityPolicy {
   /**
    * `'mounted'` (default) — a screen currently showing this entity reloads.
    * `false` — invalidate the cache only; the screen updates next time it asks.
+   * An array of change kinds — reload only for those (`['created', 'deleted']`:
+   * rows came or went). An event carrying no kind counts as `'updated'`.
+   *
+   * One rule applies to every screen; `{ list, show }` sets it per screen
+   * (#2971), a screen left out keeping `'mounted'`.
    */
-  refresh?: 'mounted' | false
+  refresh?: LiveRefreshRule | LiveRefreshPolicy
   /**
    * Window (ms) over which a burst of events collapses into a single reload.
    * Default 300. `0` reloads on every event — rarely what you want.
@@ -246,6 +252,15 @@ export interface LiveEntityPolicy {
   describeUpdate?: (before: EntityRecord, after: EntityRecord) => LiveUpdateEntry | null | undefined
 }
 
+/** What a screen does about a change made elsewhere (#2971). */
+export type LiveRefreshRule = 'mounted' | false | LiveEntityAction[]
+
+/** `LiveEntityPolicy.refresh` per screen (#2971): the list pages and the detail pages. */
+export interface LiveRefreshPolicy {
+  list?: LiveRefreshRule
+  show?: LiveRefreshRule
+}
+
 /** The notification entry `LiveEntityPolicy.describeUpdate` asks for (#2685). */
 export type LiveUpdateEntry = Omit<NewNotification, 'severity'> & Partial<Pick<NewNotification, 'severity'>>
 

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, LiveUpdateEntry } from './entity/EntityManager.types'
+export type { LiveEntityPolicy, LiveUpdateEntry, LiveRefreshRule, LiveRefreshPolicy } from './entity/EntityManager.types'
 export { LiveEntityRouter, createLiveEntityRouter } from './kernel/LiveEntityRouter'
 export type {
   LiveEntityRouterOptions,

package/src/kernel/Kernel.registries.ts

@@ -375,7 +375,7 @@ export function applyRegistryMethods(KernelClass: { prototype: Kernel }): void {
    */
   const KNOWN_KERNEL_OPTIONS = new Set([
     'apiClient', 'app', 'authAdapter', 'authTypes', 'basePath', 'coreRoutes',
-    'debug', 'debugBar', 'defaultEntityCacheTtlMs', 'entityAuthAdapter',
+    'debug', 'debugBar', 'defaultEntityCacheTtlMs', 'display', 'entityAuthAdapter',
     'eventRouter', 'existingApp', 'existingRouter', 'existingSignals',
     'features', 'hashMode', 'homeRoute', 'i18n', 'layouts', 'managerRegistry',
     'managerResolver', 'managers', 'moduleDefs', 'modules', 'modulesOptions',

package/src/kernel/Kernel.ts

@@ -81,6 +81,7 @@ import { applyApiMethods } from './Kernel.api'
 import { applyI18nMethods } from './Kernel.i18n'
 import type { I18n } from '../i18n/I18n'
 import type { SseSubscriptions } from './sseSubscriptions'
+import { setEmptyPlaceholder } from '../utils/formatters'
 
 export class Kernel {
   options: KernelOptions
@@ -133,6 +134,8 @@ export class Kernel {
   _authImpersonationCleanup: (() => void) | null = null
 
   constructor(options: KernelOptions) {
+    // Module-level, like the formatters that read it: one app per page (#2772).
+    if (options.display?.emptyPlaceholder !== undefined) setEmptyPlaceholder(options.display.emptyPlaceholder)
     // Auto-inject DebugModule if debugBar.module is provided
     if (options.debugBar?.module) {
       const DebugModuleClass = options.debugBar.module

package/src/kernel/Kernel.types.ts

@@ -268,6 +268,11 @@ export interface KernelOptions {
   routeState?: string | RouteStatePersister
   debugBar?: DebugBarConfig
   notifications?: NotificationsConfig
+  /** App-wide display defaults (#2772). */
+  display?: {
+    /** What a missing value shows, in detail pages and formatters. Default `'-'`. */
+    emptyPlaceholder?: string
+  }
   toast?: Record<string, unknown>
   debug?: boolean
   onAuthExpired?: (payload: unknown) => void

package/src/types/index.ts

@@ -109,6 +109,8 @@ export interface FieldConfig {
   filterable?: boolean
   searchable?: boolean
   validator?: (value: unknown) => boolean | string
+  /** Shown in displays for an empty value; defaults to the kernel's `display.emptyPlaceholder` (#2772). */
+  emptyText?: string
   [key: string]: unknown
 }
 

package/src/utils/formatters.ts

@@ -8,6 +8,25 @@
  *   {{ formatDateTime(item.updated_at) }}
  */
 
+// =============================================================================
+// EMPTY PLACEHOLDER
+// =============================================================================
+
+let emptyPlaceholder = '-'
+
+/**
+ * What qdadm shows for a missing value (#2772): the formatters and detail
+ * pages. Set once by the kernel from `display.emptyPlaceholder`.
+ */
+export function setEmptyPlaceholder(value: string): void {
+  emptyPlaceholder = value
+}
+
+/** The current empty placeholder, `'-'` unless configured. */
+export function getEmptyPlaceholder(): string {
+  return emptyPlaceholder
+}
+
 // =============================================================================
 // DATE/TIME FORMATTING
 // =============================================================================
@@ -22,16 +41,16 @@
  * @param dateStr - ISO date string or Date object
  * @param options - Intl.DateTimeFormat options
  * @param locale - Explicit locale override (default: browser locale)
- * @returns Formatted date string or '-' if empty
+ * @returns Formatted date string or the empty placeholder if empty
  */
 export function formatDate(
   dateStr: string | Date | null | undefined,
   options: Intl.DateTimeFormatOptions = {},
   locale?: string
 ): string {
-  if (!dateStr) return '-'
+  if (!dateStr) return emptyPlaceholder
   const date = new Date(dateStr)
-  if (isNaN(date.getTime())) return '-'
+  if (isNaN(date.getTime())) return emptyPlaceholder
 
   if (Object.keys(options).length === 0) {
     return date.toLocaleString(locale)
@@ -75,9 +94,9 @@ export function formatDateOnly(
   options: Intl.DateTimeFormatOptions = {},
   locale?: string
 ): string {
-  if (!dateStr) return '-'
+  if (!dateStr) return emptyPlaceholder
   const date = new Date(dateStr)
-  if (isNaN(date.getTime())) return '-'
+  if (isNaN(date.getTime())) return emptyPlaceholder
   return date.toLocaleDateString(locale, {
     year: 'numeric',
     month: '2-digit',
@@ -90,9 +109,9 @@ export function formatDateOnly(
  * Format to time only (14:30:00)
  */
 export function formatTimeOnly(dateStr: string | Date | null | undefined): string {
-  if (!dateStr) return '-'
+  if (!dateStr) return emptyPlaceholder
   const date = new Date(dateStr)
-  if (isNaN(date.getTime())) return '-'
+  if (isNaN(date.getTime())) return emptyPlaceholder
   return date.toLocaleTimeString()
 }
 
@@ -115,7 +134,7 @@ export function formatDateOrNever(dateStr: string | Date | null | undefined): st
  * @returns Human-readable duration (e.g., "2h 30m 15s" or "45.2s")
  */
 export function formatDuration(ms: number | null | undefined): string {
-  if (ms === null || ms === undefined) return '-'
+  if (ms === null || ms === undefined) return emptyPlaceholder
   if (ms < 1000) return `${ms}ms`
 
   const seconds = Math.floor(ms / 1000)
@@ -142,10 +161,10 @@ export function formatDurationBetween(
   startDate: string | Date | null | undefined,
   endDate: string | Date | null | undefined
 ): string {
-  if (!startDate || !endDate) return '-'
+  if (!startDate || !endDate) return emptyPlaceholder
   const start = new Date(startDate)
   const end = new Date(endDate)
-  if (isNaN(start.getTime()) || isNaN(end.getTime())) return '-'
+  if (isNaN(start.getTime()) || isNaN(end.getTime())) return emptyPlaceholder
   return formatDuration(end.getTime() - start.getTime())
 }
 
@@ -163,7 +182,7 @@ export function formatNumber(
   options: Intl.NumberFormatOptions = {},
   locale?: string
 ): string {
-  if (value === null || value === undefined) return '-'
+  if (value === null || value === undefined) return emptyPlaceholder
   return value.toLocaleString(locale, options)
 }
 
@@ -178,7 +197,7 @@ export function formatCurrency(
   currencyCode = 'USD',
   locale?: string
 ): string {
-  if (value === null || value === undefined) return '-'
+  if (value === null || value === undefined) return emptyPlaceholder
   return new Intl.NumberFormat(locale, { style: 'currency', currency: currencyCode }).format(value)
 }
 
@@ -186,7 +205,7 @@ export function formatCurrency(
  * Format bytes to human-readable size
  */
 export function formatBytes(bytes: number | null | undefined): string {
-  if (bytes === null || bytes === undefined) return '-'
+  if (bytes === null || bytes === undefined) return emptyPlaceholder
   if (bytes === 0) return '0 B'
 
   const units = ['B', 'KB', 'MB', 'GB', 'TB']
@@ -200,7 +219,7 @@ export function formatBytes(bytes: number | null | undefined): string {
  * Format a percentage
  */
 export function formatPercent(value: number | null | undefined, decimals = 1): string {
-  if (value === null || value === undefined) return '-'
+  if (value === null || value === undefined) return emptyPlaceholder
   return `${(value * 100).toFixed(decimals)}%`
 }
 

package/src/utils/index.ts

@@ -16,6 +16,8 @@ export {
   formatCurrency,
   formatBytes,
   formatPercent,
+  setEmptyPlaceholder,
+  getEmptyPlaceholder,
 } from './formatters'
 
 // Error formatting