qdadm 0.32.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.32.0",
+  "version": "0.35.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -20,6 +20,7 @@
   },
   "exports": {
     ".": "./src/index.js",
+    "./auth": "./src/auth/index.js",
     "./composables": "./src/composables/index.js",
     "./components": "./src/components/index.js",
     "./editors": "./src/editors/index.js",

package/src/auth/SessionAuthAdapter.js

@@ -0,0 +1,254 @@
+/**
+ * SessionAuthAdapter - Base class for user authentication
+ *
+ * Applications extend this class to implement their authentication logic.
+ * The adapter handles user sessions: login, logout, token management.
+ *
+ * This is different from EntityAuthAdapter which handles entity-level permissions.
+ *
+ * @example
+ * ```js
+ * class MyAuthAdapter extends SessionAuthAdapter {
+ *   async login({ username, password }) {
+ *     const response = await api.post('/auth/login', { username, password })
+ *     this.setSession(response.token, response.user)
+ *     return { token: response.token, user: response.user }
+ *   }
+ *
+ *   logout() {
+ *     this.clearSession()
+ *   }
+ * }
+ * ```
+ *
+ * @abstract
+ */
+export class SessionAuthAdapter {
+  /**
+   * Internal session state
+   * @protected
+   */
+  _token = null
+  _user = null
+
+  /**
+   * Authenticate user with credentials
+   *
+   * @param {object} credentials - Login credentials
+   * @param {string} credentials.username - Username or email
+   * @param {string} credentials.password - Password
+   * @returns {Promise<{token: string, user: object}>} Session data
+   * @throws {Error} If authentication fails
+   *
+   * @example
+   * const { token, user } = await adapter.login({ username: 'admin', password: 'secret' })
+   */
+  async login(credentials) {
+    throw new Error('[SessionAuthAdapter] login() must be implemented by subclass')
+  }
+
+  /**
+   * End the current session
+   *
+   * Should clear all session data (tokens, user info).
+   * Called by AppLayout logout button and useAuth().logout()
+   */
+  logout() {
+    throw new Error('[SessionAuthAdapter] logout() must be implemented by subclass')
+  }
+
+  /**
+   * Check if user is currently authenticated
+   *
+   * @returns {boolean} True if user has valid session
+   *
+   * @example
+   * if (adapter.isAuthenticated()) {
+   *   // Show dashboard
+   * } else {
+   *   // Redirect to login
+   * }
+   */
+  isAuthenticated() {
+    throw new Error('[SessionAuthAdapter] isAuthenticated() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current authentication token
+   *
+   * Used by API clients to include in request headers.
+   *
+   * @returns {string|null} JWT token or null if not authenticated
+   *
+   * @example
+   * const token = adapter.getToken()
+   * fetch('/api/data', {
+   *   headers: { Authorization: `Bearer ${token}` }
+   * })
+   */
+  getToken() {
+    throw new Error('[SessionAuthAdapter] getToken() must be implemented by subclass')
+  }
+
+  /**
+   * Get the current user object
+   *
+   * Returns user data from the session. The shape depends on your backend.
+   *
+   * @returns {object|null} User object or null if not authenticated
+   *
+   * @example
+   * const user = adapter.getUser()
+   * console.log(user.username, user.email, user.roles)
+   */
+  getUser() {
+    throw new Error('[SessionAuthAdapter] getUser() must be implemented by subclass')
+  }
+
+  /**
+   * Synchronous user getter (optional)
+   *
+   * Some implementations prefer a property instead of method.
+   * useAuth() supports both patterns.
+   *
+   * @type {object|null}
+   */
+  get user() {
+    return this.getUser()
+  }
+
+  // ─────────────────────────────────────────────────────────────────
+  // Helper methods for subclasses
+  // ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Set session data (helper for subclasses)
+   *
+   * @param {string} token - Authentication token
+   * @param {object} user - User object
+   * @protected
+   */
+  setSession(token, user) {
+    this._token = token
+    this._user = user
+  }
+
+  /**
+   * Clear session data (helper for subclasses)
+   *
+   * @protected
+   */
+  clearSession() {
+    this._token = null
+    this._user = null
+  }
+
+  /**
+   * Validate that the adapter is properly configured
+   *
+   * Called during bootstrap to catch configuration errors early.
+   *
+   * @throws {Error} If required methods are not implemented
+   */
+  static validate(adapter) {
+    const required = ['login', 'logout', 'isAuthenticated', 'getToken', 'getUser']
+    const missing = required.filter(method => typeof adapter[method] !== 'function')
+
+    if (missing.length > 0) {
+      throw new Error(
+        `[SessionAuthAdapter] Missing required methods: ${missing.join(', ')}\n` +
+        'Ensure your authAdapter implements all required methods or extends SessionAuthAdapter.'
+      )
+    }
+  }
+}
+
+/**
+ * LocalStorage-based SessionAuthAdapter implementation
+ *
+ * Ready-to-use adapter that stores session in localStorage.
+ * Extend and override login() to add your API call.
+ *
+ * @example
+ * ```js
+ * class MyAuthAdapter extends LocalStorageSessionAuthAdapter {
+ *   constructor() {
+ *     super('my_app_auth') // localStorage key
+ *   }
+ *
+ *   async login({ username, password }) {
+ *     const res = await fetch('/api/login', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ username, password })
+ *     })
+ *     const data = await res.json()
+ *     this.setSession(data.token, data.user)
+ *     this.persist()
+ *     return data
+ *   }
+ * }
+ * ```
+ */
+export class LocalStorageSessionAuthAdapter extends SessionAuthAdapter {
+  /**
+   * @param {string} storageKey - localStorage key for session data
+   */
+  constructor(storageKey = 'qdadm_auth') {
+    super()
+    this._storageKey = storageKey
+    this._restore()
+  }
+
+  /**
+   * Restore session from localStorage on init
+   * @private
+   */
+  _restore() {
+    try {
+      const stored = localStorage.getItem(this._storageKey)
+      if (stored) {
+        const { token, user } = JSON.parse(stored)
+        this._token = token
+        this._user = user
+      }
+    } catch {
+      // Invalid stored data, ignore
+    }
+  }
+
+  /**
+   * Persist session to localStorage
+   * Call after login() to save session
+   * @protected
+   */
+  persist() {
+    if (this._token && this._user) {
+      localStorage.setItem(this._storageKey, JSON.stringify({
+        token: this._token,
+        user: this._user
+      }))
+    } else {
+      localStorage.removeItem(this._storageKey)
+    }
+  }
+
+  // Arrow functions to preserve `this` when used as callbacks
+  logout = () => {
+    this.clearSession()
+    localStorage.removeItem(this._storageKey)
+  }
+
+  isAuthenticated = () => {
+    return !!this._token
+  }
+
+  getToken = () => {
+    return this._token
+  }
+
+  getUser = () => {
+    return this._user
+  }
+}
+
+export default SessionAuthAdapter

package/src/auth/index.js

@@ -0,0 +1,10 @@
+/**
+ * Auth module - User session authentication
+ *
+ * For entity-level permissions, see entity/auth/EntityAuthAdapter
+ */
+
+export {
+  SessionAuthAdapter,
+  LocalStorageSessionAuthAdapter,
+} from './SessionAuthAdapter.js'

package/src/components/layout/AppLayout.vue

@@ -35,6 +35,7 @@ const route = useRoute()
 const app = useApp()
 const { navSections, isNavActive, sectionHasActiveItem, handleNavClick } = useNavigation()
 const { isAuthenticated, user, logout, authEnabled } = useAuth()
+const signals = inject('qdadmSignals', null)
 
 // LocalStorage key for collapsed sections state (namespaced by app)
 const STORAGE_KEY = computed(() => `${app.shortName.toLowerCase()}_nav_collapsed`)
@@ -150,6 +151,7 @@ const userSubtitle = computed(() => {
 
 function handleLogout() {
   logout()
+  signals?.emit('auth:logout', { reason: 'user' })
   router.push({ name: 'login' })
 }
 

package/src/components/pages/LoginPage.vue

@@ -90,11 +90,12 @@ const props = defineProps({
     default: ''
   },
   /**
-   * Emit business signal on login (requires orchestrator)
+   * Emit auth:login signal on successful login
+   * Required for debug bar auth tracking and other signal listeners
    */
   emitSignal: {
     type: Boolean,
-    default: false
+    default: true
   }
 })
 

package/src/composables/useFormPageBuilder.js

@@ -120,7 +120,13 @@ export function useFormPageBuilder(config = {}) {
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
   const manager = orchestrator.get(entity)
 

package/src/composables/useListPageBuilder.js

@@ -143,7 +143,13 @@ export function useListPageBuilder(config = {}) {
   // Get EntityManager via orchestrator
   const orchestrator = inject('qdadmOrchestrator')
   if (!orchestrator) {
-    throw new Error('[qdadm] Orchestrator not provided. Make sure to use createQdadm() with entityFactory.')
+    throw new Error(
+      '[qdadm] Orchestrator not provided.\n' +
+      'Possible causes:\n' +
+      '1. Kernel not initialized - ensure createKernel().createApp() is called before mounting\n' +
+      '2. Component used outside of qdadm app context\n' +
+      '3. Missing entityFactory in Kernel options'
+    )
   }
   const manager = orchestrator.get(entity)
 

package/src/debug/Collector.js

@@ -179,10 +179,11 @@ export class Collector {
 
   /**
    * Get all entries
+   * Returns a shallow copy to trigger Vue reactivity when used in computed
    * @returns {Array<object>} All recorded entries
    */
   getEntries() {
-    return this.entries
+    return [...this.entries]
   }
 
   /**

package/src/debug/EntitiesCollector.js

@@ -77,12 +77,12 @@ export class EntitiesCollector extends Collector {
     })
     this._signalCleanups.push(entityCleanup)
 
-    // Listen to cache invalidation
-    const cacheCleanup = signals.on('cache:entity:invalidated', () => {
+    // Listen to entity data changes (CRUD operations)
+    const dataCleanup = signals.on('entity:data-invalidate', () => {
       this._lastUpdate = Date.now()
       this.notifyChange()
     })
-    this._signalCleanups.push(cacheCleanup)
+    this._signalCleanups.push(dataCleanup)
   }
 
   /**
@@ -248,6 +248,9 @@ export class EntitiesCollector extends Collector {
         canList: manager.canList?.() ?? true
       },
 
+      // Auth sensitivity (auto-invalidates on auth events)
+      authSensitive: manager._authSensitive ?? false,
+
       // Warmup
       warmup: {
         enabled: manager.warmupEnabled ?? false

package/src/debug/SignalCollector.js

@@ -18,8 +18,8 @@ import { Collector } from './Collector.js'
  * Collector for SignalBus events
  *
  * Records all signals with their name, data, and source for debugging.
- * Uses the `*:*` wildcard pattern to capture all signals following the
- * domain:action naming convention.
+ * Uses the `**` wildcard pattern to capture all signals including
+ * multi-segment names (e.g., entity:data-invalidate, auth:impersonate:start).
  */
 export class SignalCollector extends Collector {
   /**
@@ -43,8 +43,8 @@ export class SignalCollector extends Collector {
 
     // Subscribe to all signals using wildcard pattern
     // QuarKernel supports wildcards with the configured delimiter (:)
-    // '*:*' matches any domain:action signal
-    this._unsubscribe = ctx.signals.on('*:*', (event) => {
+    // '**' matches all signals including multi-segment (entity:data-invalidate)
+    this._unsubscribe = ctx.signals.on('**', (event) => {
       this.record({
         name: event.name,
         data: event.data,

package/src/debug/components/DebugBar.vue

@@ -12,7 +12,7 @@
 import { ref, computed, watch, onMounted, onUnmounted } from 'vue'
 import Badge from 'primevue/badge'
 import Button from 'primevue/button'
-import { ZonesPanel, AuthPanel, EntitiesPanel, ToastsPanel, EntriesPanel } from './panels'
+import { ZonesPanel, AuthPanel, EntitiesPanel, ToastsPanel, EntriesPanel, SignalsPanel } from './panels'
 
 const props = defineProps({
   bridge: { type: Object, required: true },
@@ -658,6 +658,13 @@ function getCollectorColor(name) {
         @update="notifyBridge"
       />
 
+      <!-- Signals collector -->
+      <SignalsPanel
+        v-else-if="currentCollector.name === 'signals' || currentCollector.name === 'SignalCollector'"
+        :collector="currentCollector.collector"
+        :entries="currentCollector.entries"
+      />
+
       <div v-else-if="currentCollector.entries.length === 0" class="debug-empty">
         <i class="pi pi-inbox" />
         <span>No entries</span>

package/src/debug/components/panels/EntitiesPanel.vue

@@ -138,6 +138,11 @@ function getCapabilityLabel(cap) {
             class="pi pi-eye perm-icon-readonly"
             title="Read-only entity"
           />
+          <i
+            v-if="entity.authSensitive"
+            class="pi pi-shield perm-icon-auth-sensitive"
+            title="Auth-sensitive (auto-invalidates on auth events)"
+          />
         </div>
         <span class="entity-label">{{ entity.label }}</span>
         <span v-if="entity.cache.enabled" class="entity-cache" :class="{ 'entity-cache-valid': entity.cache.valid }">
@@ -397,6 +402,10 @@ function getCapabilityLabel(cap) {
   color: #f59e0b;
   margin-left: 2px;
 }
+.perm-icon-auth-sensitive {
+  color: #8b5cf6;
+  margin-left: 2px;
+}
 .entity-label {
   color: #a1a1aa;
   font-size: 11px;

package/src/debug/components/panels/EntriesPanel.vue

@@ -46,6 +46,7 @@ async function copyEntry(entry, idx) {
       :class="{ 'entry-new': entry._isNew }"
     >
       <div class="entry-meta">
+        <span v-if="entry._isNew" class="entry-new-dot" title="New (unseen)" />
         <span class="entry-time">{{ formatTime(entry.timestamp) }}</span>
         <span v-if="entry.name" class="entry-name">{{ entry.name }}</span>
       </div>
@@ -62,6 +63,7 @@ async function copyEntry(entry, idx) {
       :class="{ 'entry-new': entry._isNew }"
     >
       <div class="entry-header">
+        <span v-if="entry._isNew" class="entry-new-dot" title="New (unseen)" />
         <span class="entry-time">{{ formatTime(entry.timestamp) }}</span>
         <span v-if="entry.name" class="entry-name">{{ entry.name }}</span>
         <span v-if="entry.message" class="entry-message">{{ entry.message }}</span>
@@ -98,9 +100,6 @@ async function copyEntry(entry, idx) {
 .entry-h:last-child {
   border-right: none;
 }
-.entry-h.entry-new {
-  border-left: 3px solid #8b5cf6;
-}
 
 /* Vertical entries (right/fullscreen mode) */
 .entries-v {
@@ -118,7 +117,7 @@ async function copyEntry(entry, idx) {
 /* New entry indicator */
 .entry-new {
   position: relative;
-  background: rgba(139, 92, 246, 0.08);
+  background: rgba(245, 158, 11, 0.08);
 }
 .entry-v.entry-new::before {
   content: '';
@@ -127,7 +126,20 @@ async function copyEntry(entry, idx) {
   top: 0;
   bottom: 0;
   width: 3px;
-  background: #8b5cf6;
+  background: #f59e0b;
+}
+.entry-h.entry-new {
+  border-left: 3px solid #f59e0b;
+}
+
+.entry-new-dot {
+  display: inline-block;
+  width: 6px;
+  height: 6px;
+  background: #f59e0b;
+  border-radius: 50%;
+  margin-right: 4px;
+  flex-shrink: 0;
 }
 
 /* Entry parts */