@quazardous/qdadm 2.4.1 → 2.4.3

package/package.json

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

package/src/components/edit/FormPage.vue

@@ -36,7 +36,8 @@ import { computed, type PropType } from 'vue'
 import PageHeader from '../layout/PageHeader.vue'
 import FormActions from './FormActions.vue'
 import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
-import Card from 'primevue/card'
+import CardShell from '../layout/CardShell.vue'
+import { formatFetchError } from '../../utils/errors'
 import Button from 'primevue/button'
 import Message from 'primevue/message'
 import type { ResolvedAction, ResolvedFieldConfig } from '../../composables/useEntityItemFormPage'
@@ -119,11 +120,7 @@ const headerActions = computed<ResolvedAction[]>(() =>
 )
 
 // Get error message from fetchError
-const fetchErrorMessage = computed<string | null>(() => {
-  if (!props.fetchError) return null
-  if (typeof props.fetchError === 'string') return props.fetchError
-  return props.fetchError.message || props.fetchError.detail || 'Failed to load entity'
-})
+const fetchErrorMessage = computed<string | null>(() => formatFetchError(props.fetchError))
 
 // Guard dialog handlers
 function onGuardSaveAndLeave(): void {
@@ -205,29 +202,8 @@ function onGuardStay(): void {
         </ul>
       </Message>
 
-      <!-- Card wrapper or direct content -->
-      <Card v-if="cardWrapper">
-        <template #content>
-          <slot name="fields" />
-
-          <!-- Form Actions (in footer) -->
-          <template v-if="showFormActions">
-            <slot name="footer">
-              <FormActions
-                :isEdit="isEdit"
-                :saving="saving"
-                :dirty="dirty"
-                :showSaveAndClose="showSaveAndClose"
-                @save="emit('save')"
-                @saveAndClose="emit('saveAndClose')"
-                @cancel="emit('cancel')"
-              />
-            </slot>
-          </template>
-        </template>
-      </Card>
-
-      <template v-else>
+      <!-- Single content body; Card wrapper is conditional (#1193) -->
+      <CardShell :card="cardWrapper">
         <slot name="fields" />
 
         <!-- Form Actions (in footer) -->
@@ -244,7 +220,7 @@ function onGuardStay(): void {
             />
           </slot>
         </template>
-      </template>
+      </CardShell>
     </template>
 
     <!-- Unsaved Changes Dialog -->

package/src/components/layout/CardShell.vue

@@ -0,0 +1,26 @@
+<script setup lang="ts">
+/**
+ * CardShell — conditional Card wrapper (#1193).
+ *
+ * ShowPage and FormPage duplicated their entire content body twice (once
+ * inside <Card><template #content>, once bare). Wrapping the single body
+ * in this shell keeps the slots in the host component (no forwarding).
+ */
+import Card from 'primevue/card'
+
+defineProps<{
+  /** Wrap the default slot in a PrimeVue Card (#content). */
+  card?: boolean
+}>()
+</script>
+
+<template>
+  <Card v-if="card">
+    <template #content>
+      <slot />
+    </template>
+  </Card>
+  <template v-else>
+    <slot />
+  </template>
+</template>

package/src/components/lists/ListPage.vue

@@ -180,7 +180,7 @@ const emit = defineEmits<{
   (e: 'update:searchQuery', value: string): void
   (e: 'update:filterValues', values: Record<string, unknown>): void
   (e: 'page', event: { page: number; rows: number }): void
-  (e: 'sort', event: { sortField: string; sortOrder: number }): void
+  (e: 'sort', event: { sortField: string | null; sortOrder: number | null }): void
   (e: 'row-click', data: unknown, originalEvent: MouseEvent): void
 }>()
 
@@ -293,7 +293,9 @@ function onPage(event: { page: number; rows: number }): void {
 
 function onSort(event: unknown): void {
   const e = event as { sortField?: string | null; sortOrder?: number | null }
-  emit('sort', { sortField: String(e.sortField ?? ''), sortOrder: e.sortOrder ?? 1 })
+  // Pass removableSort's "sort removed" state through honestly (#1222):
+  // null stays null — the composable decides the fallback (defaultSort).
+  emit('sort', { sortField: e.sortField ?? null, sortOrder: e.sortOrder ?? null })
 }
 
 function onRowClick(event: { data: unknown; originalEvent: Event }): void {

package/src/components/show/ShowPage.vue

@@ -39,7 +39,8 @@
  */
 import { computed, type PropType } from 'vue'
 import PageHeader from '../layout/PageHeader.vue'
-import Card from 'primevue/card'
+import CardShell from '../layout/CardShell.vue'
+import { formatFetchError } from '../../utils/errors'
 import Button from 'primevue/button'
 import Message from 'primevue/message'
 import FieldGroups from '../item/FieldGroups.vue'
@@ -163,7 +164,7 @@ const useGroupLayout = computed(() => {
   return hasRealGroups && props.layout !== 'flat'
 })
 
-const emit = defineEmits<{
+defineEmits<{
   (e: 'edit'): void
   (e: 'delete'): void
   (e: 'back'): void
@@ -180,11 +181,11 @@ const footerActions = computed<ResolvedAction[]>(() =>
 )
 
 // Get error message from fetchError
-const fetchErrorMessage = computed<string | null>(() => {
-  if (!props.fetchError) return null
-  if (typeof props.fetchError === 'string') return props.fetchError
-  return props.fetchError.message || props.fetchError.detail || 'Failed to load entity'
-})
+const fetchErrorMessage = computed<string | null>(() => formatFetchError(props.fetchError))
+
+/** Value union accepted by ShowField — aliased so the template cast has no
+ * `|` (the eslint vue/no-deprecated-filter rule misreads it as a filter). */
+type ShowFieldValue = string | number | boolean | Date | Record<string, unknown> | unknown[]
 </script>
 
 <template>
@@ -232,70 +233,8 @@ const fetchErrorMessage = computed<string | null>(() => {
 
     <!-- Content -->
     <template v-else>
-      <!-- Card wrapper or direct content -->
-      <Card v-if="cardWrapper">
-        <template #content>
-          <!-- Grid layout with optional media zone -->
-          <div
-            class="show-content"
-            :class="{ 'show-content--with-media': slots.media }"
-            :style="slots.media ? { '--media-width': mediaWidth } : {}"
-          >
-            <!-- Media zone (optional) -->
-            <div v-if="slots.media" class="show-media">
-              <slot name="media" />
-            </div>
-
-            <!-- Fields/Groups zone -->
-            <div class="show-fields" :class="{ 'show-fields--horizontal': horizontalFields && !useGroupLayout }">
-              <!-- Group layout mode -->
-              <template v-if="useGroupLayout">
-                <slot name="groups">
-                  <FieldGroups
-                    :groups="groups"
-                    :data="data"
-                    :layout="layout"
-                    :child-layout="childLayout"
-                  >
-                    <template #field="{ field, value }">
-                      <ShowField
-                        :field="field"
-                        :value="value as string | number | boolean | Date | Record<string, unknown> | unknown[]"
-                        :horizontal="horizontalFields"
-                        :label-width="labelWidth"
-                      />
-                    </template>
-                  </FieldGroups>
-                </slot>
-              </template>
-              <!-- Flat fields mode (default) -->
-              <template v-else>
-                <slot name="fields" />
-              </template>
-            </div>
-          </div>
-
-          <!-- Footer Actions -->
-          <template v-if="showActions && footerActions.length > 0">
-            <slot name="footer">
-              <div class="show-actions">
-                <Button
-                  v-for="action in footerActions"
-                  :key="action.name"
-                  :label="action.label"
-                  :icon="action.icon"
-                  :severity="action.severity"
-                  :loading="action.isLoading"
-                  :disabled="action.isDisabled"
-                  @click="action.onClick"
-                />
-              </div>
-            </slot>
-          </template>
-        </template>
-      </Card>
-
-      <template v-else>
+      <!-- Single content body; Card wrapper is conditional (#1193) -->
+      <CardShell :card="cardWrapper">
         <!-- Grid layout with optional media zone -->
         <div
           class="show-content"
@@ -321,7 +260,7 @@ const fetchErrorMessage = computed<string | null>(() => {
                   <template #field="{ field, value }">
                     <ShowField
                       :field="field"
-                      :value="value as string | number | boolean | Date | Record<string, unknown> | unknown[]"
+                      :value="value as ShowFieldValue"
                       :horizontal="horizontalFields"
                       :label-width="labelWidth"
                     />
@@ -353,7 +292,7 @@ const fetchErrorMessage = computed<string | null>(() => {
             </div>
           </slot>
         </template>
-      </template>
+      </CardShell>
     </template>
   </div>
 </template>

package/src/composables/useActionRegistry.ts

@@ -0,0 +1,82 @@
+/**
+ * Generic action registry (#1193) — the map + ordered add/remove/resolve
+ * skeleton was rebuilt in useListPage, useEntityItemFormPage and
+ * useEntityItemShowPage; only the resolution context differs, so the
+ * consumer supplies `resolve(action, ctx)` and calls `resolveAll(ctx)`.
+ */
+import { ref, type Ref } from 'vue'
+
+export interface UseActionRegistryOptions<A extends { name: string }, Ctx, R> {
+  /** Defaults merged under every added action (e.g. { severity: 'secondary' }). */
+  defaults?: Partial<A>
+  /**
+   * Resolve one action against the consumer's context. Return null to
+   * filter it out (visibility check lives here).
+   */
+  resolve: (action: A, ctx: Ctx) => R | null
+}
+
+export interface UseActionRegistryReturn<A extends { name: string }, Ctx, R> {
+  /** Raw registered actions, insertion-ordered (exposed for advanced consumers). */
+  actionsMap: Ref<Map<string, A>>
+  /** Registration order — kept explicit so external entries (e.g. lazy actions) can share it. */
+  order: Ref<string[]>
+  add(action: A): void
+  remove(name: string): void
+  has(name: string): boolean
+  /** Drop every registered action (order included). */
+  clear(): void
+  /** Resolve every registered action in order, dropping nulls. */
+  resolveAll(ctx: Ctx): R[]
+  /** Resolve a single registered action by name (null if absent or filtered). */
+  resolveOne(name: string, ctx: Ctx): R | null
+}
+
+export function useActionRegistry<A extends { name: string }, Ctx = void, R = A>(
+  options: UseActionRegistryOptions<A, Ctx, R>
+): UseActionRegistryReturn<A, Ctx, R> {
+  const { defaults, resolve } = options
+  const actionsMap = ref(new Map()) as Ref<Map<string, A>>
+  const order = ref<string[]>([])
+
+  function add(action: A): void {
+    actionsMap.value.set(action.name, { ...defaults, ...action })
+    if (!order.value.includes(action.name)) {
+      order.value.push(action.name)
+    }
+  }
+
+  function remove(name: string): void {
+    actionsMap.value.delete(name)
+    const idx = order.value.indexOf(name)
+    if (idx !== -1) order.value.splice(idx, 1)
+  }
+
+  function has(name: string): boolean {
+    return actionsMap.value.has(name)
+  }
+
+  function clear(): void {
+    actionsMap.value.clear()
+    order.value = []
+  }
+
+  function resolveAll(ctx: Ctx): R[] {
+    const resolved: R[] = []
+    for (const name of order.value) {
+      const action = actionsMap.value.get(name)
+      if (!action) continue
+      const r = resolve(action, ctx)
+      if (r !== null) resolved.push(r)
+    }
+    return resolved
+  }
+
+  function resolveOne(name: string, ctx: Ctx): R | null {
+    const action = actionsMap.value.get(name)
+    if (!action) return null
+    return resolve(action, ctx)
+  }
+
+  return { actionsMap, order, add, remove, has, clear, resolveAll, resolveOne }
+}

package/src/composables/useBareForm.ts

@@ -36,6 +36,7 @@ import { useUnsavedChangesGuard, type GuardDialogState } from './useUnsavedChang
 import { useBreadcrumb, type BreadcrumbDisplayItem } from './useBreadcrumb'
 import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
 import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
+import { createOrchestratorToast } from './useOrchestratorToast'
 
 // #1191 — shared minimal structural views (was: local redeclarations)
 type EntityManager = EntityManagerLike
@@ -169,12 +170,8 @@ export function useBareForm(options: UseBareFormOptions): UseBareFormReturn {
   const route = useRoute()
   const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
 
-  // Toast helper - wraps orchestrator.toast for legacy compatibility
-  const toast: ToastHelper = {
-    add({ severity, summary, detail, emitter }) {
-      orchestrator?.toast[severity]?.(summary, detail, emitter)
-    },
-  }
+  // Toast helper (#1193 — shared facade)
+  const toast: ToastHelper = createOrchestratorToast(orchestrator)
 
   // Common state
   const loading = ref(false)

package/src/composables/useEntityItemFormPage.ts

@@ -50,6 +50,8 @@ import type {
   ErrorSummaryItem,
   PageTitleParts,
 } from './useEntityItemFormPage.types'
+import { createOrchestratorToast } from './useOrchestratorToast'
+import { useActionRegistry } from './useActionRegistry'
 import { TYPE_MAPPINGS, TYPE_VALIDATORS, snakeCaseToTitle, isEmpty } from './useEntityItemFormPage.types'
 
 // Re-export public types
@@ -100,7 +102,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
     // Mode detection
     getId = null,
     createRouteSuffix = 'create',
-    editRouteSuffix: _editRouteSuffix = 'edit', // eslint-disable-line @typescript-eslint/no-unused-vars
+    editRouteSuffix = 'edit',
     // Form options
     loadOnMount = true,
     enableGuard = true,
@@ -143,12 +145,8 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
     hydrator,
   } = itemPage
 
-  // Toast helper - wraps orchestrator.toast for legacy compatibility
-  const toast: ToastHelper = {
-    add({ severity, summary, detail, emitter }) {
-      ;(orchestrator as Orchestrator)?.toast?.[severity]?.(summary, detail, emitter)
-    },
-  }
+  // Toast helper (#1193 — shared facade)
+  const toast: ToastHelper = createOrchestratorToast(orchestrator as Orchestrator | null)
 
   // Read config from manager with option overrides
   const entityName = config.entityName ?? manager.label
@@ -331,7 +329,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
         const createdId = (responseData as Record<string, unknown>)?.[manager.idField]
         if (createdId) {
           const currentRouteName = (route.name as string) || ''
-          const editRouteName = currentRouteName.replace(/(-create|-new)$/, '-edit')
+          const editRouteName = currentRouteName.replace(/(-create|-new)$/, `-${editRouteSuffix}`)
           router.push({
             name: editRouteName,
             params: { ...route.params, [manager.idField]: String(createdId) },
@@ -505,7 +503,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
   })
 
   // Expose refs for validation (which needs direct access)
-  const { fieldsMap, fieldOrder, excludedFields, fields, groups } = fieldManager
+  const { fieldsMap, fieldOrder, fields, groups } = fieldManager
 
   /**
    * Generate fields from manager schema
@@ -572,36 +570,43 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
 
   // ============ VALIDATION ============
 
-  function validateField(name: string): string | null {
-    const fieldConfig = fieldsMap.value.get(name)
-    if (!fieldConfig) return null
-
-    const value = data.value[name]
-
+  /**
+   * Shared validator pipeline (#1193): required → type validator → custom
+   * validate. Pure — returns the error message or null; callers own the
+   * errors ref bookkeeping.
+   */
+  function runFieldValidators(fieldConfig: ResolvedFieldConfig, value: unknown): string | null {
     if (fieldConfig.required && isEmpty(value)) {
-      const error = `${fieldConfig.label} is required`
-      errors.value = { ...errors.value, [name]: error }
-      return error
+      return `${fieldConfig.label} is required`
     }
 
     const typeValidator = TYPE_VALIDATORS[fieldConfig.schemaType]
     if (typeValidator) {
       const result = typeValidator(value)
-      if (result !== true) {
-        errors.value = { ...errors.value, [name]: result as string }
-        return result as string
-      }
+      if (result !== true) return result as string
     }
 
     if (fieldConfig.validate && typeof fieldConfig.validate === 'function') {
       const result = fieldConfig.validate(value, data.value)
       if (result !== true && result !== undefined && result !== null) {
-        const error = typeof result === 'string' ? result : `${fieldConfig.label} is invalid`
-        errors.value = { ...errors.value, [name]: error }
-        return error
+        return typeof result === 'string' ? result : `${fieldConfig.label} is invalid`
       }
     }
 
+    return null
+  }
+
+  function validateField(name: string): string | null {
+    const fieldConfig = fieldsMap.value.get(name)
+    if (!fieldConfig) return null
+
+    const error = runFieldValidators(fieldConfig, data.value[name])
+
+    if (error) {
+      errors.value = { ...errors.value, [name]: error }
+      return error
+    }
+
     if (errors.value[name]) {
       const { [name]: _removed, ...rest } = errors.value
       void _removed // Intentionally unused - destructuring to omit
@@ -618,29 +623,8 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
       const fieldConfig = fieldsMap.value.get(fieldName)
       if (!fieldConfig) continue
 
-      const value = data.value[fieldName]
-
-      if (fieldConfig.required && isEmpty(value)) {
-        newErrors[fieldName] = `${fieldConfig.label} is required`
-        continue
-      }
-
-      const typeValidator = TYPE_VALIDATORS[fieldConfig.schemaType]
-      if (typeValidator) {
-        const result = typeValidator(value)
-        if (result !== true) {
-          newErrors[fieldName] = result as string
-          continue
-        }
-      }
-
-      if (fieldConfig.validate && typeof fieldConfig.validate === 'function') {
-        const result = fieldConfig.validate(value, data.value)
-        if (result !== true && result !== undefined && result !== null) {
-          newErrors[fieldName] =
-            typeof result === 'string' ? result : `${fieldConfig.label} is invalid`
-        }
-      }
+      const error = runFieldValidators(fieldConfig, data.value[fieldName])
+      if (error) newErrors[fieldName] = error
     }
 
     errors.value = newErrors
@@ -684,29 +668,30 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
 
   // ============ ACTIONS ============
 
-  const actionsMap = ref<Map<string, ActionConfig>>(new Map())
+  // #1193 — shared registry skeleton; form-state resolution stays here
+  const actionRegistry = useActionRegistry<ActionConfig, void, ResolvedAction>({
+    resolve: (action) => {
+      if (action.visible && !action.visible({ isEdit: isEdit.value, dirty: dirty.value })) return null
+      return {
+        ...action,
+        isLoading: action.loading ? action.loading() : false,
+        isDisabled: action.disabled
+          ? action.disabled({ dirty: dirty.value, saving: saving.value })
+          : false,
+      }
+    },
+  })
 
   function addAction(name: string, actionConfig: Omit<ActionConfig, 'name'>): void {
-    actionsMap.value.set(name, { name, ...actionConfig })
+    actionRegistry.add({ name, ...actionConfig } as ActionConfig)
   }
 
   function removeAction(name: string): void {
-    actionsMap.value.delete(name)
+    actionRegistry.remove(name)
   }
 
   function getActions(): ResolvedAction[] {
-    const actions: ResolvedAction[] = []
-    for (const [, action] of actionsMap.value) {
-      if (action.visible && !action.visible({ isEdit: isEdit.value, dirty: dirty.value })) continue
-      actions.push({
-        ...action,
-        isLoading: action.loading ? action.loading() : false,
-        isDisabled: action.disabled
-          ? action.disabled({ dirty: dirty.value, saving: saving.value })
-          : false,
-      })
-    }
-    return actions
+    return actionRegistry.resolveAll(undefined)
   }
 
   const actions = computed(() => getActions())

package/src/composables/useEntityItemPage.ts

@@ -12,11 +12,12 @@
  * - Show pages (read-only detail pages)
  * - useEntityItemFormPage (create/edit forms)
  */
-import { ref, computed, onMounted, inject, provide, type Ref, type ComputedRef } from 'vue'
+import { ref, computed, onMounted, provide, type Ref, type ComputedRef } from 'vue'
 import { useRoute } from 'vue-router'
 import { useStackHydrator, type StackHydratorReturn } from '../chain/useStackHydrator'
 import type { EntityManagerCrud } from '../entity/EntityManager.interface'
 import type { OrchestratorLike } from '../entity/EntityManager.interface'
+import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
 
 /**
  * Parent configuration from route.meta.parent
@@ -142,7 +143,8 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
   const route = useRoute()
 
   // Get EntityManager via orchestrator
-  const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator')
+  // #1193 — canonical injection (single error-message source), erased to the CRUD-tier view
+  const orchestrator = useOrchestrator().orchestrator as unknown as Orchestrator
   if (!orchestrator) {
     throw new Error(
       '[qdadm] Orchestrator not provided.\n' +
@@ -232,7 +234,6 @@ export function useEntityItemPage<T = unknown>(config: UseEntityItemPageOptions<
       // Calculate total depth to set correct breadcrumb levels
       // If chain is: grandparent -> parent -> current
       // grandparent = level 1, parent = level 2, current = level 3
-      // const totalDepth = getChainDepth()
 
       // Load chain from immediate parent up to root
       let currentConfig: ParentConfig | undefined = parentConfig.value

package/src/composables/useEntityItemShowPage.ts

@@ -55,6 +55,7 @@ import {
   type ShowResolvedFieldConfig,
 } from './createShowFieldResolver'
 import type { OrchestratorLike } from '../entity/EntityManager.interface'
+import { useActionRegistry } from './useActionRegistry'
 
 // #1191 — shared structural view (manager tier from useEntityItemPage)
 type Orchestrator = OrchestratorLike<EntityManager>
@@ -344,17 +345,27 @@ export function useEntityItemShowPage<T = unknown>(
 
   // ============ ACTION MANAGEMENT ============
 
-  const actionsMap = ref<Map<string, ActionConfig>>(new Map())
-  const actionOrder = ref<string[]>([])
-
   const canEdit = computed(() => manager.canUpdate?.(data.value) ?? true)
   const canDelete = computed(() => manager.canDelete?.(data.value) ?? true)
 
+  // #1193 — shared registry skeleton; the order list is shared with lazy
+  // actions so declaration order survives the regular/lazy interleave.
+  type ShowActionCtx = { canEdit: boolean; canDelete: boolean; loading: boolean }
+  const actionRegistry = useActionRegistry<ActionConfig, ShowActionCtx, ResolvedAction>({
+    resolve: (action, ctx) => {
+      if (action.visible && !action.visible(ctx)) return null
+      return {
+        ...action,
+        isLoading: action.loading ? action.loading() : false,
+        isDisabled: action.disabled ? action.disabled(ctx) : false,
+      }
+    },
+  })
+  const actionsMap = actionRegistry.actionsMap
+  const actionOrder = actionRegistry.order
+
   function addAction(action: ActionConfig): UseEntityItemShowPageReturn<T> {
-    actionsMap.value.set(action.name, action)
-    if (!actionOrder.value.includes(action.name)) {
-      actionOrder.value.push(action.name)
-    }
+    actionRegistry.add(action)
     return returnValue
   }
 
@@ -445,20 +456,16 @@ export function useEntityItemShowPage<T = unknown>(
         return null
       })
       .filter((entry): entry is NonNullable<typeof entry> => entry !== null)
-      .filter((entry) => {
-        if (entry.type === 'regular') return !entry.action.visible || entry.action.visible(ctx)
-        const state = resolved.get(entry.action.name)
-        return state?.visible === true
-      })
       .map((entry) => {
-        const a = entry.action
-        if (entry.type === 'lazy') {
-          const state = resolved.get(a.name)
-          return { ...a, isLoading: a.loading ? a.loading() : false, isDisabled: state?.disabled ?? false }
+        if (entry.type === 'regular') {
+          return actionRegistry.resolveOne(entry.action.name, ctx)
         }
-        const regular = a as ActionConfig
-        return { ...regular, isLoading: regular.loading ? regular.loading() : false, isDisabled: regular.disabled ? regular.disabled(ctx) : false }
+        const state = resolved.get(entry.action.name)
+        if (state?.visible !== true) return null
+        const a = entry.action
+        return { ...a, isLoading: a.loading ? a.loading() : false, isDisabled: state?.disabled ?? false }
       })
+      .filter((a): a is ResolvedAction => a !== null)
   })
 
   // ============ PAGE TITLE ============

package/src/composables/useListPage.ts

@@ -95,6 +95,9 @@ import {
   setSessionFilters,
   snakeToTitle,
 } from './useListPage.utils'
+import { useActionRegistry } from './useActionRegistry'
+import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
+import { createOrchestratorToast } from './useOrchestratorToast'
 
 // Re-export PAGE_SIZE_OPTIONS so existing consumers (qdadm/index.ts,
 // composables/index.ts) keep their import path.
@@ -134,15 +137,10 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   // i18n integration — column headers resolve via entities.{entity}.fields.{field}
   const { i18n: kernelI18n, locale: i18nLocale } = useI18n()
 
-  // Get EntityManager via orchestrator
-  const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator')
-
-  // Toast helper - wraps orchestrator.toast for legacy compatibility
-  const toast: ToastHelper = {
-    add({ severity, summary, detail, emitter }) {
-      orchestrator?.toast[severity]?.(summary, detail, emitter)
-    },
-  }
+  // Get EntityManager via orchestrator (#1193 — canonical injection: one
+  // error-message source; erased to this file's Read-tier view)
+  const orchestrator = useOrchestrator().orchestrator as unknown as Orchestrator
+  const toast: ToastHelper = createOrchestratorToast(orchestrator)
 
   if (!orchestrator) {
     throw new Error(
@@ -835,38 +833,37 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
   }
 
   // ============ ACTIONS ============
-  const actionsMap = ref<Map<string, ActionConfig>>(new Map())
-
-  function addAction(name: string, actionConfig: Omit<ActionConfig, 'name'>): void {
-    actionsMap.value.set(name, {
-      name,
-      severity: 'secondary',
-      ...actionConfig,
-    } as ActionConfig)
-  }
-
-  function removeAction(name: string): void {
-    actionsMap.value.delete(name)
-  }
-
   function resolveValue<T>(value: T | ((row: unknown) => T), row: unknown): T {
     return typeof value === 'function' ? (value as (row: unknown) => T)(row) : value
   }
 
-  function getActions(row: unknown): ResolvedAction[] {
-    const actions: ResolvedAction[] = []
-    for (const [, action] of actionsMap.value) {
-      if (action.visible && !action.visible(row)) continue
-      actions.push({
+  // #1193 — shared registry skeleton; row-aware resolution stays here
+  const actionRegistry = useActionRegistry<ActionConfig, unknown, ResolvedAction>({
+    defaults: { severity: 'secondary' },
+    resolve: (action, row) => {
+      if (action.visible && !action.visible(row)) return null
+      return {
         name: action.name,
         icon: action.icon ? resolveValue(action.icon, row) : undefined,
         tooltip: action.tooltip ? resolveValue(action.tooltip, row) : undefined,
         severity: resolveValue(action.severity || 'secondary', row),
         isDisabled: action.disabled ? action.disabled(row) : false,
         handler: () => action.onClick(row),
-      })
-    }
-    return actions
+      }
+    },
+  })
+  const actionsMap = actionRegistry.actionsMap
+
+  function addAction(name: string, actionConfig: Omit<ActionConfig, 'name'>): void {
+    actionRegistry.add({ name, ...actionConfig } as ActionConfig)
+  }
+
+  function removeAction(name: string): void {
+    actionRegistry.remove(name)
+  }
+
+  function getActions(row: unknown): ResolvedAction[] {
+    return actionRegistry.resolveAll(row)
   }
 
   // ============ SEARCH ============
@@ -912,7 +909,15 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
       manager.invalidateCache()
     }
 
-    loading.value = true
+    // Delayed loading indicator (#1222): near-synchronous loads (cache/local
+    // storage, fast APIs) used to flip loading true->false within one frame,
+    // interrupting PrimeVue's overlay-mask enter transition — the leave
+    // transitionend never fired and the invisible mask stayed in the DOM,
+    // swallowing every subsequent click (sort toggles became no-ops). The
+    // spinner only appears when a load actually takes time.
+    const loadingTimer = setTimeout(() => {
+      loading.value = true
+    }, 150)
     try {
       let params: Record<string, unknown> = { ...extraParams }
 
@@ -992,6 +997,7 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
       })
       console.error('Load error:', error)
     } finally {
+      clearTimeout(loadingTimer)
       loading.value = false
     }
   }
@@ -1004,9 +1010,18 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     loadItems()
   }
 
-  function onSort(event: { sortField: string; sortOrder: number }): void {
-    sortField.value = event.sortField
-    sortOrder.value = event.sortOrder as 1 | -1
+  function onSort(event: { sortField: string | null; sortOrder: number | null }): void {
+    // removableSort's third state ("sort removed") reaches us as nulls —
+    // fall back to the list's default sort instead of loading unsorted
+    // (#1222: on the cache path an unsorted load re-served the cache in
+    // whatever order the previous sort left it, a visual no-op).
+    if (!event.sortField || !event.sortOrder) {
+      sortField.value = defaultSort
+      sortOrder.value = defaultSortOrder
+    } else {
+      sortField.value = event.sortField
+      sortOrder.value = event.sortOrder as 1 | -1
+    }
     if (persistSort) {
       setSessionSort(filterSessionKey, {
         field: sortField.value,
@@ -1276,9 +1291,10 @@ export function useListPage<T = unknown>(config: UseListPageOptions<T>): UseList
     }
 
     if (alteredConfig.actions) {
-      actionsMap.value.clear()
+      // Route through the registry so the order list stays in sync (#1193)
+      actionRegistry.clear()
       for (const action of alteredConfig.actions) {
-        actionsMap.value.set(action.name, action)
+        actionRegistry.add(action)
       }
     }
 

package/src/composables/useListPage.utils.ts

@@ -106,7 +106,7 @@ export function getSessionSort(key: string): SessionSort | null {
     const stored = sessionStorage.getItem(SORT_SESSION_PREFIX + key)
     if (!stored) return null
     const parsed = JSON.parse(stored) as SessionSort
-    if (parsed && (parsed.order === 1 || parsed.order === -1)) return parsed
+    if (parsed && (parsed.order === 1 || parsed.order === -1) && parsed.field !== '') return parsed
     return null
   } catch {
     return null

package/src/composables/useOrchestratorToast.ts

@@ -0,0 +1,26 @@
+/**
+ * Orchestrator toast facade (#1193) — was copy-pasted verbatim in
+ * useListPage, useEntityItemFormPage and useBareForm.
+ */
+import type { OrchestratorLike } from '../entity/EntityManager.interface'
+
+/** Legacy-compatible toast surface used across the page composables. */
+export interface ToastHelper {
+  add(options: {
+    severity: 'success' | 'error' | 'warn' | 'info'
+    summary: string
+    detail?: string
+    emitter?: unknown
+  }): void
+}
+
+/** Build the facade over any orchestrator-shaped object (null-tolerant). */
+export function createOrchestratorToast(
+  orchestrator: Pick<OrchestratorLike, 'toast'> | null | undefined
+): ToastHelper {
+  return {
+    add({ severity, summary, detail, emitter }) {
+      orchestrator?.toast?.[severity]?.(summary, detail, emitter)
+    },
+  }
+}

package/src/entity/EntityManager.query.ts

@@ -1,6 +1,7 @@
 import { QueryExecutor, type QueryObject } from '../query/QueryExecutor'
 import type { ListParams, ListResult } from '../types'
 import type { EntityManagerInternal, OperationStats, QueryOptions } from './EntityManager.types'
+import { nullSortRank, type NullSortMode } from '../query/clientFilter'
 
 type Self = EntityManagerInternal<any>
 
@@ -168,18 +169,26 @@ export function applyQueryMethods(EntityManagerClass: { prototype: any }): void
     // Total after filtering (before pagination)
     const total = result.length
 
-    // Apply sort (QueryExecutor does not sort)
+    // Apply sort (QueryExecutor does not sort). Copy first (#1222): result
+    // may still BE cache.items — an in-place sort would mutate the cache,
+    // making later unsorted reads return whatever order the last sort left.
     if (sort_by) {
+      // Resolve null placement: field config > manager option > 'last'
+      const fieldCfg = this.getFieldConfig?.(sort_by) as { nullSort?: NullSortMode } | null
+      const nullMode: NullSortMode = fieldCfg?.nullSort ?? this.nullSort ?? 'last'
+      const nullCmp = nullSortRank(nullMode, sort_order === 'asc' ? 'asc' : 'desc')
+      result = [...result]
       result.sort((a: any, b: any) => {
         const aVal = a[sort_by]
         const bVal = b[sort_by]
 
-        // Nulls always sort LAST, both directions (#1221) — matches the
-        // storage adapters' shared comparator; direction-aware placement
-        // put "never seen" rows on top of every desc date sort.
+        // Null placement is configurable per field/manager (#1222 —
+        // depends on the API and the field semantics). Default 'last'
+        // keeps the #1221 behavior; e.g. nullSort: 'low' makes "Never"
+        // sort beyond the oldest period on a last-seen date column.
         if (aVal == null && bVal == null) return 0
-        if (aVal == null) return 1
-        if (bVal == null) return -1
+        if (aVal == null) return nullCmp
+        if (bVal == null) return -nullCmp
 
         // Compare
         if (typeof aVal === 'string' && typeof bVal === 'string') {

package/src/entity/EntityManager.ts

@@ -30,6 +30,7 @@ import type {
   StorageResolution,
   Orchestrator,
 } from './EntityManager.types'
+import type { NullSortMode } from '../query/clientFilter'
 
 // Re-export public types from types file
 export type {
@@ -83,6 +84,8 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
   protected _fields: Record<string, FieldConfig>
 
   localFilterThreshold: number | null
+  /** Default null placement for local sorts (#1222); field-level nullSort wins. */
+  nullSort?: NullSortMode
   protected _cacheTtlMs: number | null
   protected _asymmetric: boolean
   protected _detailCache: DetailCacheState<T> = { items: new Map() }
@@ -153,6 +156,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
       badges = null,
       fields = {},
       localFilterThreshold = null,
+      nullSort,
       cacheTtlMs = null,
       asymmetric = false,
       detailCacheTtlMs = 0,
@@ -183,6 +187,7 @@ export class EntityManager<T extends EntityRecord = EntityRecord> {
     this._fields = fields
 
     this.localFilterThreshold = localFilterThreshold
+    this.nullSort = nullSort
     this._cacheTtlMs = cacheTtlMs
     this._asymmetric = asymmetric
     this._detailCacheTtlMs = detailCacheTtlMs

package/src/entity/EntityManager.types.ts

@@ -11,6 +11,7 @@ import type {
 } from '../types'
 import type { AuthUser, EntityAuthAdapter as IEntityAuthAdapter } from './auth/EntityAuthAdapter'
 import type { SignalBus } from '../kernel/SignalBus'
+import type { NullSortMode } from '../query/clientFilter'
 import type { HookRegistry } from '../hooks/HookRegistry'
 
 // Circular type import — safe because `import type` is erased at runtime
@@ -214,6 +215,8 @@ export interface EntityManagerOptions<T extends EntityRecord = EntityRecord> {
   badges?: (entity: T) => EntityBadge[]
   fields?: Record<string, FieldConfig>
   localFilterThreshold?: number | null
+  /** Default null placement for local sorts: 'first' | 'last' | 'low' | 'high' (default 'last', #1222). Field-level nullSort wins. */
+  nullSort?: NullSortMode
   /** Cache TTL in milliseconds (0=disabled, -1=infinite, >0=TTL). Overrides global, overridden by storage. */
   cacheTtlMs?: number | null
   /** Asymmetric mode: list() and get() return different structures. get() skips list cache. */

package/src/generated/managers/testManager.ts

@@ -0,0 +1,46 @@
+/**
+ * TestManager - Auto-generated EntityManager
+ *
+ * Generated by qdadm/gen/generateManagers
+ * DO NOT EDIT MANUALLY - Changes will be overwritten
+ *
+ * Entity: test
+ * Endpoint: /test
+ */
+
+import { EntityManager } from '@quazardous/qdadm'
+import type { EntityRecord } from '@quazardous/qdadm'
+import { ApiStorage } from '@quazardous/qdadm'
+
+export interface TestEntity extends EntityRecord {
+}
+
+/**
+ * Schema definition for test
+ */
+export const testSchema = {
+  name: "test",
+  endpoint: "/test",
+  fields: {}
+} as const
+
+/**
+ * Storage options for test
+ */
+const storageOptions = {
+  endpoint: "/test"
+}
+
+/**
+ * TestManager instance
+ *
+ * Provides CRUD operations for test entity.
+ */
+export const testManager = new EntityManager<TestEntity>({
+  ...{
+  name: "test",
+  idField: "id",
+  fields: {}
+},
+  storage: new ApiStorage<TestEntity>(storageOptions)
+})

package/src/index.ts

@@ -299,6 +299,18 @@ export {
   API_CLIENT_INJECTION_KEY,
   type ApiClientSource,
 } from './api/apiClient'
+export {
+  sortItems,
+  filterItems,
+  searchItems,
+  paginate,
+  defaultGenerateId,
+  nullSortRank,
+  type SortOrder,
+  type FilterItemsOptions,
+  type NullSortMode,
+  type SortItemsOptions,
+} from './query/clientFilter'
 export { useChildPage, type UseChildPageReturn } from './composables/useChildPage'
 export { useSidebarState, SIDEBAR_COLLAPSED_KEY } from './composables/useSidebarState'
 

package/src/query/clientFilter.ts

@@ -15,14 +15,55 @@
 
 export type SortOrder = 'asc' | 'desc'
 
-/** Sort by a field, nulls/undefined last — the canonical adapter comparator. */
-export function sortItems<T>(items: T[], sortBy?: string | null, sortOrder: SortOrder = 'asc'): T[] {
+/**
+ * Null placement when sorting (#1222 — configurable, it depends on the
+ * API and the field semantics):
+ * - 'last'  (default): nulls at the end, both directions — the historical
+ *   adapter behavior, keeps empty rows out of the way.
+ * - 'first': nulls at the top, both directions.
+ * - 'low':   null behaves as the lowest value — first in asc, last in
+ *   desc. Right for "last seen" dates ("Never" sorts beyond the oldest
+ *   period); equals PrimeVue nullSortOrder: -1.
+ * - 'high':  null behaves as the highest value — last in asc, first in desc.
+ */
+export type NullSortMode = 'first' | 'last' | 'low' | 'high'
+
+export interface SortItemsOptions {
+  nulls?: NullSortMode
+}
+
+export function nullSortRank(mode: NullSortMode, sortOrder: SortOrder): number {
+  // Return the comparator result for "a is null, b is not"
+  switch (mode) {
+    case 'first':
+      return -1
+    case 'low':
+      return sortOrder === 'asc' ? -1 : 1
+    case 'high':
+      return sortOrder === 'asc' ? 1 : -1
+    case 'last':
+    default:
+      return 1
+  }
+}
+
+/** Sort by a field — the canonical comparator (null placement configurable). */
+export function sortItems<T>(
+  items: T[],
+  sortBy?: string | null,
+  sortOrder: SortOrder = 'asc',
+  options: SortItemsOptions = {}
+): T[] {
   if (!sortBy) return items
+  const { nulls = 'last' } = options
   return items.sort((a, b) => {
     const aVal = a[sortBy as keyof T]
     const bVal = b[sortBy as keyof T]
-    if (aVal === undefined || aVal === null) return 1
-    if (bVal === undefined || bVal === null) return -1
+    const aNull = aVal === undefined || aVal === null
+    const bNull = bVal === undefined || bVal === null
+    if (aNull && bNull) return 0
+    if (aNull) return nullSortRank(nulls, sortOrder)
+    if (bNull) return -nullSortRank(nulls, sortOrder)
     if (aVal < bVal) return sortOrder === 'asc' ? -1 : 1
     if (aVal > bVal) return sortOrder === 'asc' ? 1 : -1
     return 0

package/src/types/index.ts

@@ -79,6 +79,8 @@ export type FieldType =
  * Field configuration
  */
 export interface FieldConfig {
+  /** Null placement when this field is locally sorted: 'first' | 'last' | 'low' | 'high' (#1222). */
+  nullSort?: 'first' | 'last' | 'low' | 'high'
   type: FieldType
   label?: string
   required?: boolean

package/src/utils/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * Error formatting helpers (#1193).
+ */
+
+/** Fetch-error shape accepted by the page components. */
+export interface FetchErrorLike {
+  message?: string
+  detail?: string
+}
+
+/**
+ * Normalize a fetch error (string or axios-ish object) to a display
+ * message — was duplicated byte-identically in ShowPage and FormPage.
+ */
+export function formatFetchError(
+  error: string | FetchErrorLike | null | undefined,
+  fallback = 'Failed to load entity'
+): string | null {
+  if (!error) return null
+  if (typeof error === 'string') return error
+  return error.message || error.detail || fallback
+}

package/src/utils/index.ts

@@ -18,6 +18,9 @@ export {
   formatPercent,
 } from './formatters'
 
+// Error formatting
+export { formatFetchError, type FetchErrorLike } from './errors'
+
 // Transformers
 export {
   toKeyValueArray,