@quazardous/qdadm 2.5.0 → 2.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -46,8 +46,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@quazardous/qdcore": "^0.2.1",
-    "@quazardous/qddebug": "^0.2.1",
+    "@quazardous/qdcore": "^1.0.0",
+    "@quazardous/qddebug": "^1.0.0",
     "@quazardous/quarkernel": "^2.1.0",
     "pluralize": "^8.0.0",
     "yaml": "^2.8.4"

package/src/composables/useListPage.ts

@@ -261,26 +261,47 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // when the i18n bundle has no translation for the field.
   const columnInlineHeaders = new Map<string, string | undefined>()
 
+  // One-shot per entity+field (#1255): the catalog winning over an explicit
+  // header is by design, but it must never happen silently — the day a key
+  // appears, the page author learns which inline header it shadows.
+  const warnedHeaderShadows = new Set<string>()
+  function warnHeaderShadow(field: string, i18nValue: string, explicit: string | undefined): void {
+    if (explicit === undefined || explicit === i18nValue) return
+    const key = `${entity}.${field}`
+    if (warnedHeaderShadows.has(key)) return
+    warnedHeaderShadows.add(key)
+    console.warn(
+      `[qdadm] column '${field}' (${entity}): i18n key entities.${entity}.fields.${field} ` +
+        `("${i18nValue}") shadows explicit header ("${explicit}") — the catalog wins by design; ` +
+        `drop the inline header or remove the key.`
+    )
+  }
+
   /**
-   * Resolve a column header: i18n hit on entities.{entity}.fields.{field} wins,
+   * Resolve a column header: i18n hit on entities.{entity}.fields.{field} wins
+   * (the inline `header` is the no-key fallback, not an absolute override),
    * otherwise the inline `header` option, otherwise a capitalized field name.
    */
   function resolveColumnHeader(field: string, inline?: string): string {
     if (entity && kernelI18n) {
       const trace = kernelI18n.resolve(`entities.${entity}.fields.${field}`)
-      if (trace.hit) return trace.result
+      if (trace.hit) {
+        warnHeaderShadow(field, trace.result, inline)
+        return trace.result
+      }
     }
     return inline || field.charAt(0).toUpperCase() + field.slice(1)
   }
 
   function addColumn(field: string, columnConfig: Partial<ColumnConfig> = {}): void {
     columnInlineHeaders.set(field, columnConfig.header)
+    // Resolved header LAST so the catalog wins at registration too (#1255) —
+    // previously the inline header survived until the first locale change
+    // flipped it to the i18n value, silently and inconsistently.
     columnsMap.value.set(field, {
       field,
-      header: resolveColumnHeader(field, columnConfig.header),
       ...columnConfig,
-      // Re-apply resolved header after spread so it wins over a stale inline.
-      ...(columnConfig.header ? {} : { header: resolveColumnHeader(field) }),
+      header: resolveColumnHeader(field, columnConfig.header),
     })
   }
 
@@ -308,8 +329,17 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
    *
    * Header resolution: i18n key (`entities.{entity}.fields.{field}`) >
    * `overrides.header` > inline header given to `addColumn` >
-   * `manager.fields[name].label` > humanized field name. Pure read — it
-   * never registers into columnsMap, so calling it during render is safe.
+   * `manager.fields[name].label` > humanized field name.
+   *
+   * NOTE the precedence truth (#1255): an inline `header` is the fallback
+   * used when no i18n key exists — NOT an absolute override. The catalog
+   * wins by design (or a hardcoded header would pin the column to one
+   * language); to pin a header, don't create the key. When a key shadows
+   * an explicit header with a different value, a one-shot dev warning
+   * announces it instead of letting the header change silently.
+   *
+   * Pure read — it never registers into columnsMap, so calling it during
+   * render is safe.
    */
   function column(name: string, overrides: Partial<ColumnConfig> = {}): ColumnConfig {
     // Depend on the locale so headers re-render on locale change.
@@ -318,9 +348,15 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     let header: string | undefined
     if (entity && kernelI18n) {
       const trace = kernelI18n.resolve(`entities.${entity}.fields.${name}`)
-      if (trace.hit) header = trace.result
+      if (trace.hit) {
+        header = trace.result
+        // Both explicit sources are checked: per-call override AND the
+        // inline header registered via addColumn (values compared — a key
+        // that merely copies the header stays silent).
+        warnHeaderShadow(name, trace.result, overrides.header ?? columnInlineHeaders.get(name))
+      }
     }
-    const fieldConfig = manager.getFieldConfig?.(name) as { label?: string } | null | undefined
+    const fieldConfig = manager.getFieldConfig(name) as { label?: string } | null | undefined
     header ??=
       overrides.header ??
       columnInlineHeaders.get(name) ??

package/src/composables/useListPage.types.ts

@@ -61,6 +61,11 @@ export interface ConfirmService {
  */
 export interface ColumnConfig {
   field: string
+  /**
+   * Column header. When an i18n key `entities.{entity}.fields.{field}`
+   * exists, the catalog WINS — an inline header is the no-key fallback,
+   * not an absolute override (#1255). To pin a header, don't create the key.
+   */
   header?: string
   sortable?: boolean
   style?: string

package/src/entity/EntityManager.interface.ts

@@ -13,6 +13,15 @@
  *
  * All interfaces accept an optional generic parameter `T` (default: `unknown`)
  * that flows through to method signatures for typed entity data.
+ *
+ * ## Optionality contract (#1253)
+ *
+ * These views describe the IMPLEMENTER'S MINIMUM, not a mirror of the
+ * EntityManager class. A member is REQUIRED iff qdadm's own composables
+ * call it unguarded (or capability coherence demands it — e.g. the four
+ * can* permission checks travel together). A member stays OPTIONAL only
+ * when it is a genuine capability a minimal manager-like need not carry;
+ * the reason is documented inline. `?` means "conditional", never "lazy".
  */
 
 import type { EntityBadge } from './EntityManager.types'
@@ -32,6 +41,9 @@ export interface EntityManagerBase<T = unknown> {
   labelField?: string | ((entity: T) => string)
   readOnly?: boolean
   getEntityLabel: (data: T) => string
+  // Optional BY DESIGN (#1253): part of the badge/severity presentation
+  // capability; call sites guard (e.g. useEntityItemShowPage checks
+  // `if (!manager.getEntityBadges)`).
   getEntityBadges?: (data: T) => Array<{ label: string; severity?: string }>
 }
 
@@ -41,7 +53,10 @@ export interface EntityManagerBase<T = unknown> {
  * Permission checks — used by guards, list pages, forms.
  */
 export interface EntityManagerPermissions<T = unknown> {
-  canRead?: (entity?: T) => boolean
+  // The four checks are ONE capability — a manager-like answering canUpdate
+  // but not canRead is not a smaller contract, it's an incoherent one. The
+  // `?` on canRead was a #1191 leftover (#1253).
+  canRead: (entity?: T) => boolean
   canCreate: () => boolean
   canUpdate: (entity?: T) => boolean
   canDelete: (entity?: T) => boolean
@@ -55,13 +70,18 @@ export interface EntityManagerPermissions<T = unknown> {
 export interface EntityManagerRead<T = unknown> extends EntityManagerBase<T>, EntityManagerPermissions<T> {
   get: (id: string | number, context?: unknown) => Promise<T>
   list: (params?: unknown, context?: unknown) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
-  query?: (params?: unknown, options?: { routingContext?: unknown }) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
+  // query/invalidateCache/getFieldConfig are required since #1253: they are
+  // unconditionally implemented on the class (prototype-applied) and called
+  // unguarded by list pages — the `?` was a #1191 leftover that forced
+  // consumer-side casts on base methods.
+  query: (params?: unknown, options?: { routingContext?: unknown }) => Promise<{ items: T[]; total?: number; fromCache?: boolean; [key: string]: unknown }>
   delete: (id: string | number, context?: unknown) => Promise<void>
   request: (method: string, path: string, options?: { data?: unknown }) => Promise<unknown>
-  invalidateCache?: () => void
-  localFilterThreshold?: number
+  invalidateCache: () => void
   /** Field config lookup — read-side too since list column binding (#1255) */
-  getFieldConfig?: (name: string) => unknown | null
+  getFieldConfig: (name: string) => unknown | null
+  /** Config-carrying property: always present on the class, VALUE nullable */
+  localFilterThreshold?: number | null
 }
 
 // ─── CRUD ────────────────────────────────────────────────────────────────────
@@ -73,11 +93,14 @@ export interface EntityManagerCrud<T = unknown> extends EntityManagerRead<T> {
   fields?: Record<string, unknown> | unknown[]
   getInitialData: () => Record<string, unknown>
   getFormFields: () => Array<{ name: string; [key: string]: unknown }>
-  getFieldConfig: (name: string) => unknown | null
+  // getFieldConfig inherited (required) from EntityManagerRead since #1253
   resolveReferenceOptions: (fieldName: string) => Promise<unknown[]>
   create: (data: unknown, context?: unknown) => Promise<T>
   update: (id: string | number, data: unknown, context?: unknown) => Promise<T>
   patch: (id: string | number, data: unknown, context?: unknown) => Promise<T>
+  // Optional BY DESIGN (#1253): the severity/badge presentation capability —
+  // a minimal manager-like need not carry it; every qdadm call site guards
+  // (`?.` or truthiness). The canonical class always provides it.
   hasSeverityMap?: (field: string) => boolean
   getSeverity?: (field: string, value: string | number, defaultSeverity?: string) => string
   getSeverityDescriptor?: (field: string, value: string | number, defaultSeverity?: string) => { severity: string; icon?: string; label?: string }

package/src/index.ts

@@ -106,6 +106,17 @@ export {
   type CacheInfo,
 } from './entity/EntityManager'
 
+// Structural manager/orchestrator views (#1253) — the implementer's minimum
+// that composables consume; import these to type manager-likes and test doubles.
+export type {
+  EntityManagerBase,
+  EntityManagerPermissions,
+  EntityManagerRead,
+  EntityManagerCrud,
+  EntityManagerLike,
+  OrchestratorLike,
+} from './entity/EntityManager.interface'
+
 // Re-export core entity types
 export type {
   EntityRecord,