qdadm 1.13.0 → 1.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "1.13.0",
+  "version": "1.19.2",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -36,7 +36,8 @@
     "./styles": "./src/styles/index.scss",
     "./styles/variables": "./src/styles/_variables.scss",
     "./gen": "./src/gen/index.ts",
-    "./gen/vite-plugin": "./src/gen/vite-plugin.ts"
+    "./gen/vite-plugin": "./src/gen/vite-plugin.ts",
+    "./vite-plugin-debug": "./src/vite/qdadmDebugPlugin.ts"
   },
   "files": [
     "src",
@@ -44,11 +45,14 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@quazardous/qdcore": "^0.2.1",
+    "@quazardous/qddebug": "^0.2.1",
     "@quazardous/quarkernel": "^2.1.0",
-    "pluralize": "^8.0.0"
+    "pluralize": "^8.0.0",
+    "yaml": "^2.8.4"
   },
   "peerDependencies": {
-    "pinia": "^2.0.0",
+    "pinia": "^2.0.0 || ^3.0.0",
     "primevue": "^4.0.0",
     "vue": "^3.3.0",
     "vue-router": "^4.0.0"

package/src/chain/ActiveStack.ts

@@ -1,31 +1,40 @@
 /**
- * ActiveStack - Sync navigation context from route
+ * ActiveStack - Sync navigation context from route (qdadm flavour).
  *
- * Pure vanilla JS container using SignalBus for events.
- * Rebuilt from route.meta on navigation.
+ * Composes a generic `Stack<EntityStackLevel>` from `@quazardous/qdcore` and
+ * adds qdadm-specific lookups (e.g. `getLevelByEntity`). The underlying levels
+ * dual-carry `name` (qdcore-aligned) and `entity` (legacy qdadm field), so all
+ * existing consumers continue to read `level.entity` unchanged.
  *
  * Stack only contains levels WITH IDs (entities with context).
  * - /bots/bot-xyz/commands → stack = [bots(id:bot-xyz)]
  * - /bots/bot-xyz/commands/cmd-123 → stack = [bots(id:bot-xyz), commands(id:cmd-123)]
  *
- * Signals emitted:
- * - stack:change - when stack levels change
+ * Signals emitted (via SignalBus):
+ * - stack:change — when stack levels change
  *
- * For Vue reactivity, use useActiveStack composable.
+ * For Vue reactivity, use the `useActiveStack` composable.
  *
  * @example
  * const stack = new ActiveStack(signalBus)
  * signalBus.on('stack:change', ({ levels }) => console.log('Stack:', levels))
- * stack.set([{ entity: 'bots', param: 'uuid', id: 'bot-123' }])
+ * stack.set([{ entity: 'bots', param: 'uuid', foreignKey: null, id: 'bot-123' }])
  */
 
+import { Stack, type ContentStackLevel } from '@quazardous/qdcore'
 import type { SignalBus } from '../kernel/SignalBus'
 
 /**
- * Stack level definition
+ * qdadm stack level: entity-bound `ContentStackLevel`.
+ *
+ * `name` and `entity` always carry the same value. `name` is the qdcore-canonical
+ * field; `entity` is preserved for backwards compatibility with qdadm callers.
  */
-export interface StackLevel {
-  /** Entity name (e.g., 'bots', 'commands') */
+export interface EntityStackLevel extends ContentStackLevel {
+  type: 'entity'
+  /** qdcore-aligned name (= entity) */
+  name: string
+  /** Entity name (e.g., 'bots', 'commands') — alias of `name` */
   entity: string
   /** Route param name (e.g., 'uuid', 'id') */
   param: string
@@ -35,138 +44,110 @@ export interface StackLevel {
   id: string | null
 }
 
+/**
+ * Legacy alias kept for backwards compatibility. New code should prefer
+ * {@link EntityStackLevel}.
+ */
+export type StackLevel = EntityStackLevel
+
+/**
+ * Input shape accepted by {@link ActiveStack.set} — `name` is optional and
+ * defaults to `entity` so existing callers (`{ entity, param, foreignKey, id }`)
+ * keep working without changes.
+ */
+export type EntityStackLevelInput = Omit<EntityStackLevel, 'type' | 'name'> & {
+  type?: 'entity'
+  name?: string
+}
+
 /**
  * Stack change event payload
  */
 export interface StackChangePayload {
-  levels: StackLevel[]
+  levels: EntityStackLevel[]
+}
+
+/**
+ * Normalize loose input into a fully-typed EntityStackLevel.
+ */
+function normalize(input: EntityStackLevelInput): EntityStackLevel {
+  return {
+    type: 'entity',
+    name: input.name ?? input.entity,
+    entity: input.entity,
+    param: input.param,
+    foreignKey: input.foreignKey,
+    id: input.id,
+  }
 }
 
 export class ActiveStack {
-  private _levels: StackLevel[] = []
-  private _signalBus: SignalBus | null
+  private _stack: Stack<EntityStackLevel>
 
   /**
    * @param signalBus - Optional signal bus for events
    */
   constructor(signalBus: SignalBus | null = null) {
-    this._signalBus = signalBus
+    this._stack = new Stack<EntityStackLevel>(signalBus)
   }
 
-  // ═══════════════════════════════════════════════════════════════════════════
-  // Mutators
-  // ═══════════════════════════════════════════════════════════════════════════
-
-  /**
-   * Replace entire stack (called on route change)
-   * Only emits if levels actually changed (prevents duplicate emissions)
-   *
-   * BUG: Still getting duplicate signals (4 instead of 2) on navigation.
-   * Equality check should prevent this but something is triggering multiple calls
-   * with different levels. Need to investigate router.afterEach timing.
-   */
-  set(levels: StackLevel[]): void {
-    // Quick equality check - same length and same entity+id pairs
-    if (this._levelsEqual(levels)) {
-      return
-    }
-    this._levels = levels
-    this._emit('stack:change', { levels: this._levels })
-  }
+  // ─── Mutators ─────────────────────────────────────────────────────────────
 
   /**
-   * Check if new levels match current levels
-   * @private
+   * Replace entire stack (called on route change).
+   * Only emits if levels actually changed (handled by qdcore Stack).
+   * Accepts either fully-typed `EntityStackLevel` or the legacy
+   * `{ entity, param, foreignKey, id }` shape.
    */
-  private _levelsEqual(newLevels: StackLevel[]): boolean {
-    if (this._levels.length !== newLevels.length) return false
-    for (let i = 0; i < this._levels.length; i++) {
-      const curr = this._levels[i]
-      const next = newLevels[i]
-      // Both are guaranteed to exist because we checked lengths match
-      if (!curr || !next) continue
-      if (curr.entity !== next.entity || curr.id !== next.id) {
-        return false
-      }
-    }
-    return true
+  set(levels: EntityStackLevelInput[]): void {
+    this._stack.set(levels.map(normalize))
   }
 
   /**
-   * Clear the stack
-   * Only emits if not already empty
+   * Clear the stack.
    */
   clear(): void {
-    if (this._levels.length === 0) return
-    this._levels = []
-    this._emit('stack:change', { levels: this._levels })
+    this._stack.clear()
   }
 
-  // ═══════════════════════════════════════════════════════════════════════════
-  // Accessors
-  // ═══════════════════════════════════════════════════════════════════════════
+  // ─── Accessors ────────────────────────────────────────────────────────────
 
-  /**
-   * All stack levels
-   */
-  getLevels(): StackLevel[] {
-    return this._levels
+  getLevels(): EntityStackLevel[] {
+    return this._stack.getLevels()
   }
 
-  /**
-   * Get level by index
-   */
-  getLevel(index: number): StackLevel | null {
-    return this._levels[index] ?? null
+  getLevel(index: number): EntityStackLevel | null {
+    return this._stack.getLevel(index)
   }
 
   /**
-   * Get level by entity name
+   * Get level by entity name (qdadm-specific helper).
    */
-  getLevelByEntity(entity: string): StackLevel | null {
-    return this._levels.find(l => l.entity === entity) ?? null
+  getLevelByEntity(entity: string): EntityStackLevel | null {
+    return this._stack.getLevels().find(l => l.entity === entity) ?? null
   }
 
-  /**
-   * Current (deepest) level
-   */
-  getCurrent(): StackLevel | null {
-    return this._levels.at(-1) ?? null
+  getCurrent(): EntityStackLevel | null {
+    return this._stack.getCurrent()
   }
 
-  /**
-   * Parent level (one above current)
-   */
-  getParent(): StackLevel | null {
-    return this._levels.at(-2) ?? null
+  getParent(): EntityStackLevel | null {
+    return this._stack.getParent()
   }
 
-  /**
-   * Root level (first/topmost)
-   */
-  getRoot(): StackLevel | null {
-    return this._levels[0] ?? null
+  getRoot(): EntityStackLevel | null {
+    return this._stack.getRoot()
   }
 
-  /**
-   * Stack depth
-   */
   getDepth(): number {
-    return this._levels.length
+    return this._stack.getDepth()
   }
 
-  // ═══════════════════════════════════════════════════════════════════════════
-  // Internal
-  // ═══════════════════════════════════════════════════════════════════════════
-
   /**
-   * Emit event via SignalBus
-   * @private
+   * Underlying qdcore Stack instance (escape hatch for advanced use).
    */
-  private _emit(signal: string, payload: StackChangePayload): void {
-    if (this._signalBus) {
-      this._signalBus.emit(signal, payload)
-    }
+  getCoreStack(): Stack<EntityStackLevel> {
+    return this._stack
   }
 }
 

package/src/chain/StackHydrator.ts

@@ -14,7 +14,8 @@
  * signalBus.on('stack:hydrated', (event) => console.log('Hydrated:', event.data.levels))
  */
 
-import type { ActiveStack, StackLevel } from './ActiveStack'
+import type { Hydrator } from '@quazardous/qdcore'
+import type { ActiveStack, EntityStackLevel, StackLevel } from './ActiveStack'
 import type { Orchestrator } from '../orchestrator/Orchestrator'
 import type { SignalBus } from '../kernel/SignalBus'
 import type { EntityRecord } from '../types'
@@ -52,7 +53,7 @@ export interface HydratedPayload {
   levels: HydratedLevel[]
 }
 
-export class StackHydrator {
+export class StackHydrator implements Hydrator<EntityStackLevel, HydratedLevel> {
   private _activeStack: ActiveStack
   private _orchestrator: Orchestrator
   private _signalBus: SignalBus | null

package/src/chain/index.ts

@@ -11,7 +11,13 @@
  */
 
 // Sync stack (context only)
-export { ActiveStack, type StackLevel, type StackChangePayload } from './ActiveStack'
+export {
+  ActiveStack,
+  type StackLevel,
+  type EntityStackLevel,
+  type EntityStackLevelInput,
+  type StackChangePayload,
+} from './ActiveStack'
 export { useActiveStack, type UseActiveStackReturn } from './useActiveStack'
 
 // Async hydration (data + labels)

package/src/components/QdadmRoot.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+/**
+ * QdadmRoot — drop-in helper for hosts that own their own Vue app
+ * and want qdadm's DOM extras (Toast, ToastListener, DebugBar)
+ * rendered alongside.
+ *
+ * Equivalent to the wrapper Kernel produces internally when it owns
+ * `createApp`. When `Kernel({ existingApp })` is used, the host's
+ * App.vue should render `<QdadmRoot />` somewhere visible (typically
+ * at the end of the template) so toasts and the debug bar appear.
+ *
+ * The Toast / DebugBar children are conditional on what the Kernel
+ * was configured with (PrimeVue presence, debugBar option) — render
+ * is a no-op otherwise, so it's always safe to include.
+ */
+
+import { computed, inject, type Component } from 'vue'
+import Toast from 'primevue/toast'
+import ToastListener from '../toast/ToastListener.vue'
+import { getQdadmDebugBarRef } from '../kernel/Kernel.vue'
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * Render the qdadm debug bar inline. Default true preserves the
+     * legacy behaviour. Set false in hosts that already render their
+     * own (shared) `<DebugBar />` to avoid two bars on screen.
+     */
+    debugBar?: boolean
+  }>(),
+  { debugBar: true },
+)
+
+// Read the singleton-on-window debug bar ref. Using a getter (instead
+// of importing the module-level const) makes this resilient to Vite
+// HMR's module fragmentation in dev, where a top-level `const ref`
+// can be torn into separate instances per importer.
+const debugBarRef = getQdadmDebugBarRef()
+const debugBarComp = computed<Component | null>(() =>
+  props.debugBar ? debugBarRef.value : null,
+)
+
+// `qdadmHasPrimeVue` is provided by the Kernel during _installPlugins.
+// True when PrimeVue is wired (so Toast / ToastListener are usable).
+const hasToast = inject<boolean>('qdadmHasPrimeVue', false)
+</script>
+
+<template>
+  <Toast v-if="hasToast" />
+  <ToastListener v-if="hasToast" />
+  <component v-if="debugBarComp" :is="debugBarComp" />
+</template>

package/src/components/edit/FormActions.vue

@@ -14,6 +14,9 @@
  */
 
 import Button from 'primevue/button'
+import { useI18n } from '../../i18n/useI18n'
+
+const { t } = useI18n()
 
 interface Props {
   isEdit?: boolean
@@ -41,31 +44,31 @@ const emit = defineEmits<{
     <div class="form-actions-left">
       <Button
         type="button"
-        :label="isEdit ? 'Update' : 'Create'"
+        :label="isEdit ? t('core.actions.update') : t('core.actions.create')"
         :loading="saving"
         :disabled="!dirty || saving"
         icon="pi pi-check"
         @click="emit('save')"
-        v-tooltip.top="'Save and continue editing'"
+        v-tooltip.top="t('core.tooltips.saveAndContinue')"
       />
       <Button
         v-if="showSaveAndClose"
         type="button"
-        :label="isEdit ? 'Update & Close' : 'Create & Close'"
+        :label="isEdit ? t('core.actions.updateAndClose') : t('core.actions.createAndClose')"
         :loading="saving"
         :disabled="!dirty || saving"
         icon="pi pi-check-circle"
         severity="success"
         @click="emit('saveAndClose')"
-        v-tooltip.top="'Save and return to list'"
+        v-tooltip.top="t('core.tooltips.saveAndReturn')"
       />
-      <span v-if="dirty" class="dirty-indicator" v-tooltip.top="'Unsaved changes'">
+      <span v-if="dirty" class="dirty-indicator" v-tooltip.top="t('core.tooltips.unsavedChanges')">
         <i class="pi pi-circle-fill"></i>
       </span>
     </div>
     <Button
       type="button"
-      label="Cancel"
+      :label="t('core.actions.cancel')"
       severity="secondary"
       icon="pi pi-times"
       @click="emit('cancel')"

package/src/components/edit/LookupPickerDialog.vue

@@ -13,6 +13,9 @@ import DataTable from 'primevue/datatable'
 import Column from 'primevue/column'
 import InputText from 'primevue/inputtext'
 import Button from 'primevue/button'
+import { useI18n } from '../../i18n/useI18n'
+
+const { t } = useI18n()
 
 export interface LookupColumn {
   field: string
@@ -163,7 +166,7 @@ const confirmLabel = computed(() => {
         <i class="pi pi-search" />
         <InputText
           v-model="searchQuery"
-          placeholder="Search..."
+          :placeholder="t('core.placeholders.search')"
           class="w-full"
           autofocus
         />
@@ -199,14 +202,14 @@ const confirmLabel = computed(() => {
       />
       <template #empty>
         <div class="text-center text-color-secondary py-4">
-          {{ searchQuery ? 'No matching items' : 'No items available' }}
+          {{ searchQuery ? t('core.messages.noMatching') : t('core.messages.empty') }}
         </div>
       </template>
     </DataTable>
 
     <template #footer>
       <Button
-        label="Cancel"
+        :label="t('core.actions.cancel')"
         severity="secondary"
         @click="onCancel"
       />

package/src/components/index.ts

@@ -75,3 +75,9 @@ export { default as BannerZone } from './display/BannerZone.vue'
 // Pages
 export { default as LoginPage } from './pages/LoginPage.vue'
 export { default as NotFoundPage } from './pages/NotFoundPage.vue'
+
+// Host integration helper — render in a host App.vue when using
+// `Kernel({ existingApp })` so qdadm's DOM extras (Toast,
+// ToastListener, DebugBar) appear without the Kernel-managed
+// WrappedRoot.
+export { default as QdadmRoot } from './QdadmRoot.vue'

package/src/composables/useEntityItemFormPage.ts

@@ -501,6 +501,7 @@ export function useEntityItemFormPage<T extends Record<string, unknown> = Record
   const fieldManager = useFieldManager<ResolvedFieldConfig>({
     resolveFieldConfig,
     getSchemaFieldConfig: (name) => manager.getFieldConfig(name) || null,
+    entity,
   })
 
   // Expose refs for validation (which needs direct access)

package/src/composables/useEntityItemShowPage.ts

@@ -431,6 +431,7 @@ export function useEntityItemShowPage<T = unknown>(
   const fieldManager = useFieldManager<ResolvedFieldConfig>({
     resolveFieldConfig,
     getSchemaFieldConfig: (name) => manager.getFieldConfig?.(name) || null,
+    entity,
   })
 
   // Direct access to computed values

package/src/composables/useFieldManager.ts

@@ -18,7 +18,8 @@
  * fieldManager.group('info', ['name', 'email'], { label: 'Information' })
  * ```
  */
-import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import { ref, computed, watch, type Ref, type ComputedRef } from 'vue'
+import { useI18n } from '../i18n/useI18n'
 
 /**
  * Base field definition (minimal common interface)
@@ -155,6 +156,15 @@ export interface UseFieldManagerOptions<T extends ResolvedFieldConfig = Resolved
   resolveFieldConfig?: FieldResolver<T>
   /** Get field config from schema (e.g., manager.getFieldConfig) */
   getSchemaFieldConfig?: (name: string) => Partial<BaseFieldDefinition> | null
+  /**
+   * Entity name. When set, field and group labels are resolved through
+   * `entities.{entity}.fields.{name}` / `entities.{entity}.groups.{name}` via
+   * i18n. The result wins over inline `label:` props if found; otherwise the
+   * inline label (then `snakeCaseToTitle`) is used. Required for the i18n
+   * forcing function — modules without an entity context fall back to legacy
+   * behaviour.
+   */
+  entity?: string
 }
 
 /**
@@ -189,6 +199,13 @@ export interface UseFieldManagerReturn<T extends ResolvedFieldConfig = ResolvedF
   hasField: (name: string) => boolean
   hasGroup: (name: string) => boolean
   getUngroupedFields: () => T[]
+
+  /**
+   * Re-resolve labels for all fields and groups against the active locale.
+   * Called automatically when `i18n.locale` changes; exposed for manual
+   * triggering after asynchronous bundle loads.
+   */
+  relabel: () => void
 }
 
 /**
@@ -224,10 +241,41 @@ export function useFieldManager<T extends ResolvedFieldConfig = ResolvedFieldCon
   options: UseFieldManagerOptions<T> = {}
 ): UseFieldManagerReturn<T> {
   const {
-    resolveFieldConfig = defaultResolveFieldConfig as FieldResolver<T>,
+    resolveFieldConfig: userResolveFieldConfig = defaultResolveFieldConfig as FieldResolver<T>,
     getSchemaFieldConfig,
+    entity: entityName,
   } = options
 
+  // i18n integration — looked up from the kernel injection. Returns a no-op
+  // shim if no kernel i18n is available (tests, isolated examples).
+  const { i18n, locale: i18nLocale } = useI18n()
+
+  /**
+   * Wrapped resolver: runs the user's resolver, then overlays the i18n label
+   * if the convention key resolves to a real translation. Tags the resolved
+   * config with `_labelKey` so relabel() can re-resolve on locale change.
+   */
+  function resolveFieldConfig(
+    name: string,
+    fieldConfig: Partial<BaseFieldDefinition>
+  ): T {
+    const resolved = userResolveFieldConfig(name, fieldConfig) as T & {
+      _labelKey?: string
+      _inlineLabel?: string
+    }
+    if (!entityName || !i18n) return resolved
+    const key = `entities.${entityName}.fields.${name}`
+    resolved._labelKey = key
+    // Preserve the inline label (if the user supplied one) so relabel() can
+    // fall back to it when the i18n bundle has no matching key.
+    resolved._inlineLabel = fieldConfig.label as string | undefined
+    const trace = i18n.resolve(key)
+    if (trace.hit) {
+      resolved.label = trace.result
+    }
+    return resolved
+  }
+
   // ============ FIELD STORAGE ============
 
   const fieldsMap = ref<Map<string, T>>(new Map()) as Ref<Map<string, T>>
@@ -405,9 +453,17 @@ export function useFieldManager<T extends ResolvedFieldConfig = ResolvedFieldCon
 
     // Create or update group
     const existing = groupsMap.value.get(name)
+    // Resolve label: i18n hit (entities.X.groups.{name}) wins; fall back to
+    // explicit option, then existing label, then humanized form.
+    let resolvedLabel =
+      groupOptions?.label || existing?.label || snakeCaseToTitle(groupName)
+    if (entityName && i18n) {
+      const trace = i18n.resolve(`entities.${entityName}.groups.${name}`)
+      if (trace.hit) resolvedLabel = trace.result
+    }
     groupsMap.value.set(name, {
       name,
-      label: groupOptions?.label || existing?.label || snakeCaseToTitle(groupName),
+      label: resolvedLabel,
       fields: [...(existing?.fields || []), ...fieldNames],
       parent: parentName,
       // Tab/accordion options (preserve existing if not specified)
@@ -558,6 +614,44 @@ export function useFieldManager<T extends ResolvedFieldConfig = ResolvedFieldCon
     return rootGroups
   })
 
+  // ============ I18N RELABEL ============
+
+  /**
+   * Re-resolve labels for all fields and groups against the active locale.
+   * Iterates the existing maps and replaces each entry's label using the
+   * stored convention key, falling back to the inline label or
+   * snakeCaseToTitle when the key has no translation.
+   */
+  function relabel(): void {
+    if (!entityName || !i18n) return
+
+    for (const [name, field] of fieldsMap.value.entries()) {
+      const meta = field as T & { _labelKey?: string; _inlineLabel?: string }
+      const key = meta._labelKey ?? `entities.${entityName}.fields.${name}`
+      const trace = i18n.resolve(key)
+      const newLabel = trace.hit
+        ? trace.result
+        : meta._inlineLabel || snakeCaseToTitle(name)
+      if (field.label !== newLabel) {
+        fieldsMap.value.set(name, { ...field, label: newLabel } as T)
+      }
+    }
+
+    for (const [name, internal] of groupsMap.value.entries()) {
+      const key = `entities.${entityName}.groups.${name}`
+      const trace = i18n.resolve(key)
+      if (trace.hit && internal.label !== trace.result) {
+        groupsMap.value.set(name, { ...internal, label: trace.result })
+      }
+    }
+  }
+
+  if (entityName && i18n) {
+    // Auto-relabel on locale change. Vue's watcher tracks the ref returned
+    // from useI18n(), so this fires for both immediate and async switches.
+    watch(i18nLocale, () => relabel())
+  }
+
   // ============ RETURN ============
 
   const returnValue: UseFieldManagerReturn<T> = {
@@ -589,6 +683,9 @@ export function useFieldManager<T extends ResolvedFieldConfig = ResolvedFieldCon
     hasField,
     hasGroup,
     getUngroupedFields,
+
+    // i18n
+    relabel,
   }
 
   return returnValue