@quazardous/qdadm 2.6.1 → 2.7.1

package/package.json

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

package/src/components/editors/JsonStructuredField.vue

@@ -28,7 +28,8 @@
  * - mode: Optional v-model for view mode ('structured' or 'json')
  * - label: Optional label for the field
  * - jsonHeight: Height of JSON editor (default: 400px)
- * - jsonMode: Mode for JSON editor - 'tree' or 'text' (default: 'text')
+ * - jsonMode: Mode for JSON editor - 'tree', 'text' or 'table' (default: 'text');
+ *   string literals accepted so consumers don't need the vanilla-jsoneditor Mode enum (#1280)
  * - defaultMode: Initial mode if not using v-model:mode (default: 'structured')
  * - showToggle: Whether to show the toggle (default: true, useful to hide in nested usage)
  * - guardInvalidJson: Block switching to structured view while JSON is invalid (default: true)
@@ -60,7 +61,7 @@ interface Props {
   mode?: ViewMode | null
   label?: string | null
   jsonHeight?: string
-  jsonMode?: Mode
+  jsonMode?: Mode | 'tree' | 'text' | 'table'
   defaultMode?: ViewMode
   showToggle?: boolean
   guardInvalidJson?: boolean
@@ -73,7 +74,7 @@ const props = withDefaults(defineProps<Props>(), {
   mode: null,
   label: null,
   jsonHeight: '400px',
-  jsonMode: 'text' as Mode,
+  jsonMode: 'text',
   defaultMode: 'structured',
   showToggle: true,
   guardInvalidJson: true,

package/src/components/layout/AppLayout.vue

@@ -31,6 +31,8 @@ import { version as qdadmVersion } from '../../../package.json'
 interface FeaturesConfig {
   poweredBy?: boolean
   breadcrumb?: boolean
+  /** Opt-in (#1332/#1341): View↔Edit toggle next to the terminal crumb */
+  breadcrumbModeToggle?: boolean
   [key: string]: unknown
 }
 
@@ -239,7 +241,7 @@ watch(() => route.fullPath, () => {
 
 // Navigation context (breadcrumb + navlinks from route config)
 // Entity data comes from activeStack (populated by useEntityItemPage/useEntityItemFormPage)
-const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks } = useNavContext()
+const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks, modeToggle } = useNavContext()
 
 // Allow child pages to override breadcrumb/navlinks via provide/inject
 const breadcrumbOverride = ref<BreadcrumbItem[] | null>(null)
@@ -258,6 +260,12 @@ const showBreadcrumb = computed<boolean>(() => {
   if (route.name === 'dashboard') return false
   return true
 })
+
+// View↔Edit toggle on the terminal crumb (#1332/#1341) — same opt-in contract
+// as DefaultBreadcrumb; this inline breadcrumb must honor the flag too
+const shownModeToggle = computed(() =>
+  features.breadcrumbModeToggle === true ? modeToggle.value : null
+)
 </script>
 
 <template>
@@ -382,6 +390,17 @@ const showBreadcrumb = computed<boolean>(() => {
           </template>
         </Breadcrumb>
 
+        <!-- View↔Edit mode toggle (#1332/#1341) — plain navigation; the form
+             page's own route-leave guard covers unsaved changes on edit→show -->
+        <RouterLink
+          v-if="shownModeToggle"
+          :to="shownModeToggle.to"
+          class="breadcrumb-mode-toggle"
+        >
+          <i :class="shownModeToggle.target === 'edit' ? 'pi pi-pencil' : 'pi pi-eye'"></i>
+          <span>{{ shownModeToggle.label }}</span>
+        </RouterLink>
+
         <!-- Navlinks (provided by PageNav for child routes) -->
         <div v-if="navlinks.length > 0" class="layout-navlinks">
           <template v-for="(link, index) in navlinks" :key="link.to?.name || index">
@@ -702,6 +721,24 @@ const showBreadcrumb = computed<boolean>(() => {
   padding-bottom: 0;
 }
 
+/* Mode toggle sits right after the crumbs; auto margin keeps navlinks pinned right */
+.breadcrumb-mode-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  margin-left: 0.75rem;
+  margin-right: auto;
+  font-size: 0.875rem;
+  color: var(--p-primary-500, #3b82f6);
+  text-decoration: none;
+  transition: color var(--fad-transition-fast);
+}
+
+.breadcrumb-mode-toggle:hover {
+  color: var(--p-primary-600, #2563eb);
+  text-decoration: underline;
+}
+
 .layout-navlinks {
   display: flex;
   align-items: center;

package/src/components/layout/defaults/DefaultBreadcrumb.vue

@@ -15,6 +15,8 @@ import Breadcrumb from 'primevue/breadcrumb'
 
 interface FeaturesConfig {
   breadcrumb?: boolean
+  /** Opt-in (#1332): render a View↔Edit toggle next to the terminal crumb */
+  breadcrumbModeToggle?: boolean
   [key: string]: unknown
 }
 
@@ -22,7 +24,7 @@ const route = useRoute()
 const features = inject<FeaturesConfig>('qdadmFeatures', { breadcrumb: true })
 
 // Navigation context (breadcrumb + navlinks from route config)
-const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks } = useNavContext()
+const { breadcrumb: defaultBreadcrumb, navlinks: defaultNavlinks, modeToggle } = useNavContext()
 
 // Allow child pages to override breadcrumb/navlinks via provide/inject
 const breadcrumbOverride = inject<Ref<BreadcrumbItem[] | null>>('qdadmBreadcrumbOverride', ref(null))
@@ -39,6 +41,12 @@ const showBreadcrumb = computed<boolean>(() => {
   if (route.name === 'dashboard') return false
   return true
 })
+
+// View↔Edit toggle on the terminal crumb (#1332) — opt-in, and only when
+// useNavContext resolved a reachable, permitted twin-mode route
+const shownModeToggle = computed(() =>
+  features.breadcrumbModeToggle === true ? modeToggle.value : null
+)
 </script>
 
 <template>
@@ -56,6 +64,17 @@ const showBreadcrumb = computed<boolean>(() => {
       </template>
     </Breadcrumb>
 
+    <!-- View↔Edit mode toggle (#1332) — plain navigation; the form page's
+         own route-leave guard covers unsaved changes on edit→show -->
+    <RouterLink
+      v-if="shownModeToggle"
+      :to="shownModeToggle.to"
+      class="breadcrumb-mode-toggle"
+    >
+      <i :class="shownModeToggle.target === 'edit' ? 'pi pi-pencil' : 'pi pi-eye'"></i>
+      <span>{{ shownModeToggle.label }}</span>
+    </RouterLink>
+
     <!-- Navlinks (provided by PageNav for child routes) -->
     <div v-if="navlinks.length > 0" class="breadcrumb-navlinks">
       <template v-for="(link, index) in navlinks" :key="link.to?.name || index">
@@ -92,6 +111,24 @@ const showBreadcrumb = computed<boolean>(() => {
   font-size: 0.875rem;
 }
 
+/* Mode toggle sits right after the crumbs; auto margin keeps navlinks pinned right */
+.breadcrumb-mode-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  margin-left: 0.75rem;
+  margin-right: auto;
+  font-size: 0.875rem;
+  color: var(--p-primary-500, #3b82f6);
+  text-decoration: none;
+  transition: color 0.15s;
+}
+
+.breadcrumb-mode-toggle:hover {
+  color: var(--p-primary-700, #1d4ed8);
+  text-decoration: underline;
+}
+
 .navlinks-separator {
   color: var(--p-surface-400, #94a3b8);
 }

package/src/components/show/ShowPage.vue

@@ -46,6 +46,9 @@ import Message from 'primevue/message'
 import FieldGroups from '../item/FieldGroups.vue'
 import ShowField from './ShowField.vue'
 import type { ButtonSeverity } from '../../types'
+// Single source of truth (#1281): the props must accept exactly what the
+// composable emits — a local redeclaration is where the two drifted apart.
+import type { ResolvedAction } from '../../composables/useEntityItemShowPage'
 
 /**
  * Page title parts for PageHeader
@@ -56,19 +59,6 @@ interface PageTitleParts {
   entityLabel: string | undefined
 }
 
-/**
- * Action configuration
- */
-interface ResolvedAction {
-  name: string
-  label: string
-  icon?: string
-  severity?: ButtonSeverity
-  isLoading: boolean
-  isDisabled: boolean
-  onClick: () => void | Promise<void>
-}
-
 /**
  * Resolved field config
  */

package/src/composables/createShowFieldResolver.ts

@@ -39,7 +39,8 @@ export interface ShowFieldDefinition {
   type?: string
   schemaType?: string
   label?: string
-  reference?: string
+  /** Canonical FieldConfig object form, or the entity name as a bare string */
+  reference?: string | { entity: string; labelField?: string; valueField?: string }
   referenceRoute?: string | ((value: unknown) => { name: string; params: Record<string, unknown> })
   referenceLabel?: string | ((value: unknown, option?: unknown) => string)
   options?: unknown[]
@@ -73,6 +74,8 @@ export interface ShowResolvedFieldConfig extends ShowFieldDefinition {
  */
 export interface ShowResolverOrchestrator {
   get: (entityName: string) => ShowResolverManager | undefined
+  /** Real Orchestrator.get THROWS on unknown entities — probe first when available */
+  has?: (entityName: string) => boolean
 }
 
 /**
@@ -133,13 +136,20 @@ export function createShowFieldResolver(
     let resolvedDisplayType = SHOW_TYPE_MAPPINGS[type] || SHOW_TYPE_MAPPINGS[schemaType] || 'text'
     const resolvedLabel = label || snakeCaseToTitle(name)
 
-    // Auto-set reference route if reference entity is specified
+    // Auto-set reference route if reference entity is specified.
+    // FieldConfig.reference is canonically { entity, ... }; the bare-string
+    // form stays accepted. Passing the object to orchestrator.get produced
+    // '[object Object]' lookups that THREW during generateFields (#1341).
     let referenceRoute = rest.referenceRoute
     if (reference && !referenceRoute) {
-      const refManager = orchestrator.get(reference)
+      const refEntity = typeof reference === 'string' ? reference : reference.entity
+      const refManager =
+        refEntity && (!orchestrator.has || orchestrator.has(refEntity))
+          ? orchestrator.get(refEntity)
+          : undefined
       if (refManager) {
         referenceRoute = (value: unknown) => ({
-          name: `${refManager.routePrefix || reference}-show`,
+          name: `${refManager.routePrefix || refEntity}-show`,
           params: { [refManager.idField]: value },
         })
       }

package/src/composables/index.ts

@@ -73,6 +73,7 @@ export {
   type NavChainType,
   type BreadcrumbItem,
   type NavLinkItem,
+  type BreadcrumbModeToggle,
 } from './useNavContext'
 export { useNavigation, type UseNavigationReturn, type NavItem, type NavSection } from './useNavigation'
 export {

package/src/composables/useEntityItemShowPage.ts

@@ -55,6 +55,7 @@ import {
   type ShowResolvedFieldConfig,
 } from './createShowFieldResolver'
 import type { OrchestratorLike } from '../entity/EntityManager.interface'
+import type { ButtonSeverity } from '../types'
 import { useActionRegistry } from './useActionRegistry'
 
 // #1191 — shared structural view (manager tier from useEntityItemPage)
@@ -81,7 +82,8 @@ export interface ActionConfig {
   name: string
   label: string
   icon?: string
-  severity?: string
+  /** PrimeVue Button severity — the shared union, not bare string (#1281) */
+  severity?: ButtonSeverity
   onClick: () => void | Promise<void>
   visible?: (ctx: { canEdit: boolean; canDelete: boolean }) => boolean
   disabled?: (ctx: { loading: boolean }) => boolean
@@ -99,7 +101,8 @@ export interface LazyActionConfig {
   name: string
   label: string
   icon?: string
-  severity?: string
+  /** PrimeVue Button severity — the shared union, not bare string (#1281) */
+  severity?: ButtonSeverity
   onClick: () => void | Promise<void>
   resolve: (data: unknown) => Promise<{ visible?: boolean; disabled?: boolean }>
   loading?: () => boolean
@@ -129,7 +132,7 @@ export interface ShowPageProps {
   loading: boolean
   title: string
   titleParts: PageTitleParts
-  badges: Array<{ label: string; severity?: string }>
+  badges: Array<{ label: string; severity?: ButtonSeverity }>
   fields: ResolvedFieldConfig[]
   groups: FieldGroup<ResolvedFieldConfig>[]
   data: Record<string, unknown> | null

package/src/composables/useNavContext.ts

@@ -21,6 +21,7 @@ import { useRoute, useRouter, type RouteParamsRawGeneric } from 'vue-router'
 import { getSiblingRoutes } from '../module/moduleRegistry'
 import { useSemanticBreadcrumb, type SemanticBreadcrumbItem } from './useSemanticBreadcrumb'
 import { useStackHydrator, type HydratedLevel } from '../chain/useStackHydrator'
+import { useI18n } from '../i18n/useI18n'
 import type { EntityManagerLike, OrchestratorLike } from '../entity/EntityManager.interface'
 
 // #1191 — shared minimal structural views (was: local redeclarations)
@@ -64,6 +65,29 @@ export interface BreadcrumbItem {
   icon?: string
 }
 
+/**
+ * View↔Edit toggle for the breadcrumb terminal (#1332)
+ *
+ * Non-null only when the current route is an entity item mode
+ * (`entity-show` / `entity-edit`), the twin-mode route exists
+ * (`${routePrefix}-edit` / `-show` + `router.hasRoute`), and — for the
+ * Edit affordance — `manager.canUpdate()` allows it. The permission check
+ * passes the hydrated entity when available, so ownership-conditional
+ * permissions are honored once the item is loaded.
+ */
+export interface BreadcrumbModeToggle {
+  /** Mode of the current route */
+  current: 'show' | 'edit'
+  /** Mode the toggle navigates to */
+  target: 'show' | 'edit'
+  /** Twin-route location — a plain router.push; any dirty-form protection
+   *  comes from the form page's own onBeforeRouteLeave guard */
+  to: { name: string; params: RouteParamsRawGeneric }
+  /** Locale-reactive label: i18n `breadcrumb.view` / `breadcrumb.edit`,
+   *  falling back to "View" / "Edit" */
+  label: string
+}
+
 /**
  * Nav link item
  */
@@ -105,6 +129,7 @@ export interface UseNavContextReturn {
   // Navigation
   breadcrumb: ComputedRef<BreadcrumbItem[]>
   navlinks: ComputedRef<NavLinkItem[]>
+  modeToggle: ComputedRef<BreadcrumbModeToggle | null>
 
   // Helpers
   parentConfig: ComputedRef<ParentConfig | undefined>
@@ -125,6 +150,9 @@ export function useNavContext(_options: UseNavContextOptions = {}): UseNavContex
   // Stack hydrator for entity data (has async-loaded data and labels)
   const hydrator = useStackHydrator()
 
+  // i18n for the mode-toggle labels (no-op shim outside a kernel)
+  const { i18n: kernelI18n, locale: i18nLocale } = useI18n()
+
   function getManager(entityName: string): EntityManager | null {
     return orchestrator?.get(entityName) ?? null
   }
@@ -414,6 +442,44 @@ export function useNavContext(_options: UseNavContextOptions = {}): UseNavContex
     return null
   })
 
+  // ============================================================================
+  // MODE TOGGLE (#1332)
+  // ============================================================================
+
+  function toggleLabel(target: 'show' | 'edit'): string {
+    const trace = kernelI18n?.resolve(target === 'edit' ? 'breadcrumb.edit' : 'breadcrumb.view')
+    if (trace?.hit) return trace.result
+    return target === 'edit' ? 'Edit' : 'View'
+  }
+
+  const modeToggle = computed<BreadcrumbModeToggle | null>(() => {
+    void i18nLocale.value // label re-resolves on locale change
+
+    const semantic = semanticBreadcrumb.value
+    const terminal = semantic[semantic.length - 1]
+    if (!terminal?.entity || !terminal.id) return null
+    if (terminal.kind !== 'entity-show' && terminal.kind !== 'entity-edit') return null
+
+    const manager = getManager(terminal.entity)
+    if (!manager?.routePrefix) return null
+
+    const current = terminal.kind === 'entity-edit' ? 'edit' : 'show'
+    // Target is the OPPOSITE of the current mode — getDefaultItemRoute's
+    // edit-preference is a landing default, not a toggle.
+    const target = current === 'edit' ? 'show' : 'edit'
+    const twinRoute = `${manager.routePrefix}-${target}`
+    if (!router.hasRoute(twinRoute)) return null
+
+    if (target === 'edit' && !manager.canUpdate(entityData.value ?? undefined)) return null
+
+    return {
+      current,
+      target,
+      to: { name: twinRoute, params: { [manager.idField || 'id']: terminal.id } },
+      label: toggleLabel(target),
+    }
+  })
+
   return {
     // Analysis
     navChain,
@@ -427,6 +493,7 @@ export function useNavContext(_options: UseNavContextOptions = {}): UseNavContex
     // Navigation
     breadcrumb,
     navlinks,
+    modeToggle,
 
     // Helpers
     parentConfig,

package/src/entity/EntityManager.interface.ts

@@ -44,7 +44,7 @@ export interface EntityManagerBase<T = unknown> {
   // 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 }>
+  getEntityBadges?: (data: T) => EntityBadge[]
 }
 
 // ─── Permissions ─────────────────────────────────────────────────────────────

package/src/index.ts

@@ -128,6 +128,9 @@ export type {
   RelationConfig,
   NavConfig,
   StorageCapabilities,
+  // PrimeVue severity union (#1281) — type ActionConfig/badge literals against
+  // this instead of bare strings.
+  ButtonSeverity,
 } from './types'
 
 // Manager Factory
@@ -266,6 +269,7 @@ export {
   type NavChainType,
   type BreadcrumbItem,
   type NavLinkItem,
+  type BreadcrumbModeToggle,
 } from './composables/useNavContext'
 export {
   useNavigation,

package/src/kernel/KernelContext.entities.ts

@@ -6,6 +6,7 @@
 
 import { managerFactory, type ManagerFactoryContext } from '../entity/factory.js'
 import type { EntityManager } from '../entity/EntityManager'
+import type { EntityRecord } from '../types'
 import { UsersManager } from '../security/UsersManager'
 import type { UserEntityOptions } from './KernelContext.types'
 import type { KernelContext } from './KernelContext'
@@ -22,10 +23,10 @@ export function applyEntityMethods(KernelContextClass: { prototype: KernelContex
    * Uses managerFactory to resolve config into a manager instance.
    * Registers with Orchestrator for CRUD operations.
    */
-  proto.entity = function (
+  proto.entity = function <T extends EntityRecord>(
     this: Self,
     name: string,
-    config: string | Record<string, unknown> | EntityManager
+    config: string | Record<string, unknown> | EntityManager<T>
   ): Self {
     const factoryContext = {
       storageResolver: this._kernel.options.storageResolver,

package/src/kernel/KernelContext.ts

@@ -46,6 +46,7 @@ import type { DeferredRegistry } from '../deferred/DeferredRegistry.js'
 import type { SecurityChecker } from '../entity/auth/SecurityChecker'
 import type { PermissionRegistry } from '../security/PermissionRegistry'
 import type { EntityManager } from '../entity/EntityManager'
+import type { EntityRecord } from '../types'
 import type { I18n } from '../i18n/I18n'
 import type { AliasPattern, MessagesBundle, TranslationProvider } from '../i18n/types'
 
@@ -195,7 +196,9 @@ export class KernelContext {
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface KernelContext {
   // Entities (KernelContext.entities.ts)
-  entity(name: string, config: string | Record<string, unknown> | EntityManager): this
+  // Generic so narrowed managers pass: EntityManager<T> is invariant in T,
+  // so EntityManager<EntityRecord> would reject every typed subclass (#1281).
+  entity<T extends EntityRecord>(name: string, config: string | Record<string, unknown> | EntityManager<T>): this
   userEntity(options: UserEntityOptions): this
 
   // Routing (KernelContext.routing.ts)

package/src/plugin.ts

@@ -63,6 +63,8 @@ export interface FeaturesConfig {
   auth?: boolean
   poweredBy?: boolean
   breadcrumb?: boolean
+  /** Opt-in (#1332): View↔Edit toggle on the breadcrumb terminal crumb */
+  breadcrumbModeToggle?: boolean
   [key: string]: boolean | undefined
 }