qdadm 0.51.4 → 0.51.5

package/package.json

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

package/src/components/SeverityTag.vue

@@ -46,7 +46,7 @@ const props = defineProps({
 })
 
 const orchestrator = inject('qdadmOrchestrator')
-// Auto-discover entity from page context (provided by useListPageBuilder, useBareForm, etc.)
+// Auto-discover entity from page context (provided by useListPage, useBareForm, etc.)
 const mainEntity = inject('mainEntity', null)
 
 const resolvedEntity = computed(() => props.entity || mainEntity)

package/src/components/lists/ListPage.vue

@@ -8,7 +8,7 @@
  * - FilterBar with search and custom filters
  * - DataTable with actions column
  *
- * Props come from useListPageBuilder composable
+ * Props come from useListPage composable
  *
  * Filter types:
  * - 'select' (default): Standard dropdown

package/src/components/pages/LoginPage.vue

@@ -203,7 +203,7 @@ async function handleLogin() {
             <label for="qdadm-password">{{ passwordLabel }}</label>
             <Password
               v-model="password"
-              id="qdadm-password"
+              inputId="qdadm-password"
               class="w-full"
               :feedback="false"
               toggleMask

package/src/composables/index.js

@@ -9,7 +9,7 @@ export { useDirtyState } from './useDirtyState'
 export { useForm } from './useForm'
 export { useEntityItemFormPage, useEntityItemFormPage as useFormPageBuilder } from './useEntityItemFormPage'
 export * from './useJsonSyntax'
-export { useListPageBuilder, PAGE_SIZE_OPTIONS } from './useListPageBuilder'
+export { useListPage, PAGE_SIZE_OPTIONS } from './useListPage'
 export { usePageTitle } from './usePageTitle'
 export { useApp } from './useApp'
 export { useAuth } from './useAuth'

package/src/composables/{useListPageBuilder.js → useListPage.js}

@@ -3,6 +3,7 @@ import { useRouter, useRoute } from 'vue-router'
 import { useToast } from 'primevue/usetoast'
 import { useConfirm } from 'primevue/useconfirm'
 import { useHooks } from './useHooks.js'
+import { useEntityItemPage } from './useEntityItemPage.js'
 import { FilterQuery } from '../query/FilterQuery.js'
 
 // Cookie utilities for pagination persistence
@@ -58,7 +59,7 @@ function setSessionFilters(key, filters) {
 }
 
 /**
- * useListPageBuilder - Unified procedural builder for CRUD list pages
+ * useListPage - Unified procedural builder for CRUD list pages
  *
  * Provides a declarative/procedural API to build list pages with:
  * - Cards zone (stats, custom content)
@@ -102,14 +103,14 @@ function setSessionFilters(key, filters) {
  * ## Basic Usage
  *
  * ```js
- * const list = useListPageBuilder({ entity: 'domains' })
+ * const list = useListPage({ entity: 'domains' })
  * list.addFilter('status', { options: [...] })
  * list.setSearch({ fields: ['name', 'email'] })
  * list.addCreateAction()
  * list.addEditAction()
  * ```
  */
-export function useListPageBuilder(config = {}) {
+export function useListPage(config = {}) {
   const {
     entity,
     dataKey,
@@ -156,6 +157,35 @@ export function useListPageBuilder(config = {}) {
   // Provide entity context for child components (e.g., SeverityTag auto-discovery)
   provide('mainEntity', entity)
 
+  // ============ PARENT CHAIN SUPPORT ============
+  // When list is a child of a parent entity (e.g., /bots/:id/commands),
+  // we use useEntityItemPage for the PARENT to:
+  // - Load parent entity data
+  // - Set breadcrumbs for parent
+  // - Provide parent context to the list
+
+  const parentConfig = computed(() => route.meta?.parent || null)
+
+  // Create useEntityItemPage for PARENT entity (not for list's own entity)
+  // Only when parentConfig exists
+  let parentPage = null
+  if (route.meta?.parent) {
+    const parentMeta = route.meta.parent
+    parentPage = useEntityItemPage({
+      entity: parentMeta.entity,
+      loadOnMount: true,  // Auto-load parent on mount
+      breadcrumb: true,   // Parent sets its breadcrumb
+      idParam: parentMeta.param,  // Use parent's param (e.g., 'id' for /bots/:id)
+      autoLoadParent: true  // Support grandparent chain
+    })
+  }
+
+  // Parent data and loading state (null if no parent)
+  const parentData = computed(() => parentPage?.data.value || null)
+  const parentId = computed(() => parentPage?.entityId.value || null)
+  const parentLoading = computed(() => parentPage?.loading.value || false)
+  const parentChain = computed(() => parentPage?.parentChain.value || new Map())
+
   // Read config from manager with option overrides
   const entityName = config.entityName ?? manager.label
   const entityNamePlural = config.entityNamePlural ?? manager.labelPlural
@@ -1079,13 +1109,9 @@ export function useListPageBuilder(config = {}) {
         }
       }
 
-      // Auto-add parent filter from route config
-      const parentConfig = route.meta?.parent
-      if (parentConfig?.foreignKey && parentConfig?.param) {
-        const parentId = route.params[parentConfig.param]
-        if (parentId) {
-          filters[parentConfig.foreignKey] = parentId
-        }
+      // Auto-add parent filter from route config (uses parentPage from useEntityItemPage)
+      if (parentConfig.value?.foreignKey && parentId.value) {
+        filters[parentConfig.value.foreignKey] = parentId.value
       }
 
       if (Object.keys(filters).length > 0) {
@@ -1645,6 +1671,14 @@ export function useListPageBuilder(config = {}) {
     // Manager access
     manager,
 
+    // Parent chain (when list is child of parent entity)
+    parentConfig,
+    parentId,
+    parentData,
+    parentLoading,
+    parentChain,
+    parentPage,  // Full useEntityItemPage instance for parent (or null)
+
     // State
     items,
     displayItems,  // Use this for rendering (handles local/API filtering)

package/src/debug/EntitiesCollector.js

@@ -231,9 +231,14 @@ export class EntitiesCollector extends Collector {
       storage: {
         type: storage?.constructor?.storageName || storage?.constructor?.name || 'None',
         endpoint: storage?.endpoint || storage?._endpoint || null,
-        capabilities: storage?.capabilities || storage?.constructor?.capabilities || {}
+        capabilities: storage?.capabilities || storage?.constructor?.capabilities || {},
+        hasNormalize: !!(storage?._normalize),
+        hasDenormalize: !!(storage?._denormalize)
       },
 
+      // Multi-storage info
+      multiStorage: this._detectMultiStorage(manager),
+
       // Cache info
       cache: {
         enabled: cache.enabled ?? false,
@@ -311,6 +316,72 @@ export class EntitiesCollector extends Collector {
     }
   }
 
+  /**
+   * Detect if a manager uses multi-storage pattern
+   * @param {EntityManager} manager - Manager instance
+   * @returns {object|null} Multi-storage info or null
+   * @private
+   */
+  _detectMultiStorage(manager) {
+    // Check if resolveStorage is overridden (not the base implementation)
+    const hasCustomResolve = manager.resolveStorage &&
+      manager.resolveStorage.toString() !== 'resolveStorage(method, context) {\n    return { storage: this.storage };\n  }'
+
+    if (!hasCustomResolve) {
+      // Also check by looking for additional storage properties
+      const additionalStorages = this._findAdditionalStorages(manager)
+      if (additionalStorages.length === 0) {
+        return null
+      }
+    }
+
+    // Find all storage properties on the manager
+    const storages = this._findAdditionalStorages(manager)
+
+    return {
+      enabled: true,
+      storages: storages.map(s => ({
+        name: s.name,
+        type: s.storage?.constructor?.storageName || s.storage?.constructor?.name || 'Unknown',
+        endpoint: s.storage?.endpoint || null,
+        hasNormalize: !!(s.storage?._normalize),
+        hasDenormalize: !!(s.storage?._denormalize)
+      }))
+    }
+  }
+
+  /**
+   * Find additional storage instances on a manager
+   * @param {EntityManager} manager - Manager instance
+   * @returns {Array<{name: string, storage: object}>}
+   * @private
+   */
+  _findAdditionalStorages(manager) {
+    const storages = []
+    const mainStorage = manager.storage
+
+    // Look for properties that look like storages
+    for (const key of Object.keys(manager)) {
+      // Skip private and known non-storage properties
+      if (key.startsWith('_') || key === 'storage') continue
+
+      const value = manager[key]
+      if (!value || typeof value !== 'object') continue
+
+      // Check if it looks like a storage (has list, get, create methods or endpoint)
+      const isStorage = (
+        (typeof value.list === 'function' && typeof value.get === 'function') ||
+        (value.endpoint && typeof value.fetch === 'function')
+      )
+
+      if (isStorage && value !== mainStorage) {
+        storages.push({ name: key, storage: value })
+      }
+    }
+
+    return storages
+  }
+
   /**
    * Get cached items from a manager
    * @param {EntityManager} manager - Manager instance

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

@@ -168,6 +168,24 @@ function getCapabilityLabel(cap) {
           <span class="entity-key">Storage:</span>
           <span class="entity-value">{{ entity.storage.type }}</span>
           <span v-if="entity.storage.endpoint" class="entity-endpoint">{{ entity.storage.endpoint }}</span>
+          <span v-if="entity.storage.hasNormalize || entity.storage.hasDenormalize" class="entity-normalize-badge" title="Has normalize/denormalize">
+            <i class="pi pi-arrows-h" />
+          </span>
+          <span v-if="entity.multiStorage?.enabled" class="entity-multi-badge" title="Multi-storage routing">
+            <i class="pi pi-sitemap" />
+            +{{ entity.multiStorage.storages.length }}
+          </span>
+        </div>
+        <!-- Multi-storage details -->
+        <div v-if="entity.multiStorage?.enabled && entity.multiStorage.storages.length > 0" class="entity-multi-storages">
+          <div v-for="s in entity.multiStorage.storages" :key="s.name" class="entity-multi-storage">
+            <span class="entity-storage-name">{{ s.name }}</span>
+            <span class="entity-storage-type">{{ s.type }}</span>
+            <span v-if="s.endpoint" class="entity-endpoint">{{ s.endpoint }}</span>
+            <span v-if="s.hasNormalize || s.hasDenormalize" class="entity-normalize-badge" title="Has normalize/denormalize">
+              <i class="pi pi-arrows-h" />
+            </span>
+          </div>
         </div>
         <div v-if="entity.storage.capabilities && Object.keys(entity.storage.capabilities).length > 0" class="entity-row">
           <span class="entity-key">Caps:</span>
@@ -580,6 +598,50 @@ function getCapabilityLabel(cap) {
   background: #3f3f46;
   border-radius: 2px;
 }
+.entity-normalize-badge {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  background: rgba(139, 92, 246, 0.2);
+  color: #a78bfa;
+  border-radius: 3px;
+  font-size: 10px;
+}
+.entity-multi-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  padding: 2px 6px;
+  background: rgba(59, 130, 246, 0.2);
+  color: #60a5fa;
+  border-radius: 3px;
+  font-size: 10px;
+  font-weight: 600;
+}
+.entity-multi-storages {
+  margin-left: 66px;
+  margin-top: 4px;
+  margin-bottom: 6px;
+  padding-left: 8px;
+  border-left: 2px solid #3b82f6;
+}
+.entity-multi-storage {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 3px 0;
+  font-size: 10px;
+}
+.entity-storage-name {
+  color: #60a5fa;
+  font-weight: 500;
+  min-width: 80px;
+}
+.entity-storage-type {
+  color: #a1a1aa;
+}
 .entity-capabilities {
   display: flex;
   gap: 4px;

package/src/entity/EntityManager.js

@@ -304,6 +304,61 @@ export class EntityManager {
     }
   }
 
+  // ============ STORAGE RESOLUTION ============
+
+  /**
+   * Resolve which storage to use for an operation
+   *
+   * Override in subclass to route to different storages based on context.
+   * This enables multi-endpoint patterns like:
+   * - /api/commands (global)
+   * - /api/bots/:id/commands (scoped to bot)
+   *
+   * The default implementation returns the single configured storage.
+   *
+   * @param {string} method - Operation: 'list', 'get', 'create', 'update', 'delete'
+   * @param {object} [context] - Routing context
+   * @param {Array<{entity: string, id: string|number}>} [context.parentChain] - Parent chain from root to direct parent
+   * @returns {{ storage: IStorage, path?: string, mappingKey?: string }}
+   *
+   * @example
+   * // Single storage (default, no change needed)
+   * manager.resolveStorage('list') // { storage: this.storage }
+   *
+   * @example
+   * // Access direct parent (last in chain)
+   * const parent = context?.parentChain?.at(-1)
+   *
+   * @example
+   * // Multi-storage routing in subclass
+   * resolveStorage(method, context) {
+   *   const parent = context?.parentChain?.at(-1)
+   *   if (parent?.entity === 'bots') {
+   *     return {
+   *       storage: this.botStorage,
+   *       path: `/${parent.id}/commands`
+   *     }
+   *   }
+   *   return { storage: this.storage }
+   * }
+   *
+   * @example
+   * // Nested parents: /users/:userId/posts/:postId/comments
+   * resolveStorage(method, context) {
+   *   const chain = context?.parentChain || []
+   *   if (chain.length === 2 && chain[0].entity === 'users' && chain[1].entity === 'posts') {
+   *     return {
+   *       storage: this.nestedStorage,
+   *       path: `/${chain[0].id}/posts/${chain[1].id}/comments`
+   *     }
+   *   }
+   *   return { storage: this.storage }
+   * }
+   */
+  resolveStorage(method, context) {
+    return { storage: this.storage }
+  }
+
   // ============ METADATA ACCESSORS ============
 
   /**
@@ -857,10 +912,12 @@ export class EntityManager {
    * @param {string} [params.sort_by] - Sort field
    * @param {string} [params.sort_order] - 'asc' or 'desc'
    * @param {boolean} [params.cacheSafe] - If true, allow caching even with filters
+   * @param {object} [context] - Routing context for multi-storage
    * @returns {Promise<{ items: Array, total: number, fromCache: boolean }>}
    */
-  async list(params = {}) {
-    if (!this.storage) {
+  async list(params = {}, context) {
+    const { storage } = this.resolveStorage('list', context)
+    if (!storage) {
       throw new Error(`[EntityManager:${this.name}] list() not implemented`)
     }
 
@@ -893,7 +950,7 @@ export class EntityManager {
     if (!_internal) this._stats.cacheMisses++
 
     // 2. Fetch from API (storage normalizes response to { items, total })
-    const response = await this.storage.list(queryParams)
+    const response = await storage.list(queryParams)
     const items = response.items || []
     const total = response.total ?? items.length
 
@@ -937,9 +994,11 @@ export class EntityManager {
    * Otherwise fetches from storage.
    *
    * @param {string|number} id
+   * @param {object} [context] - Routing context for multi-storage
    * @returns {Promise<object>}
    */
-  async get(id) {
+  async get(id, context) {
+    const { storage } = this.resolveStorage('get', context)
     this._stats.get++
 
     // Try cache first if valid and complete
@@ -954,8 +1013,8 @@ export class EntityManager {
 
     // Fallback to storage
     this._stats.cacheMisses++
-    if (this.storage) {
-      return this.storage.get(id)
+    if (storage) {
+      return storage.get(id)
     }
     throw new Error(`[EntityManager:${this.name}] get() not implemented`)
   }
@@ -1006,17 +1065,19 @@ export class EntityManager {
    * - postsave: After successful storage.create(), for side effects
    *
    * @param {object} data
+   * @param {object} [context] - Routing context for multi-storage
    * @returns {Promise<object>} - The created entity
    */
-  async create(data) {
+  async create(data, context) {
+    const { storage } = this.resolveStorage('create', context)
     this._stats.create++
-    if (this.storage) {
+    if (storage) {
       // Invoke presave hooks (can modify data or throw to abort)
       const presaveContext = this._buildPresaveContext(data, true)
       await this._invokeHook('presave', presaveContext)
 
       // Use potentially modified data from context
-      const result = await this.storage.create(presaveContext.record)
+      const result = await storage.create(presaveContext.record)
       this.invalidateCache()
 
       // Invoke postsave hooks (for side effects)
@@ -1043,17 +1104,19 @@ export class EntityManager {
    *
    * @param {string|number} id
    * @param {object} data
+   * @param {object} [context] - Routing context for multi-storage
    * @returns {Promise<object>}
    */
-  async update(id, data) {
+  async update(id, data, context) {
+    const { storage } = this.resolveStorage('update', context)
     this._stats.update++
-    if (this.storage) {
+    if (storage) {
       // Invoke presave hooks (can modify data or throw to abort)
       const presaveContext = this._buildPresaveContext(data, false, id)
       await this._invokeHook('presave', presaveContext)
 
       // Use potentially modified data from context
-      const result = await this.storage.update(id, presaveContext.record)
+      const result = await storage.update(id, presaveContext.record)
       this.invalidateCache()
 
       // Invoke postsave hooks (for side effects)
@@ -1115,16 +1178,18 @@ export class EntityManager {
    * - predelete: Before storage.delete(), can throw to abort (for cascade checks)
    *
    * @param {string|number} id
+   * @param {object} [context] - Routing context for multi-storage
    * @returns {Promise<void>}
    */
-  async delete(id) {
+  async delete(id, context) {
+    const { storage } = this.resolveStorage('delete', context)
     this._stats.delete++
-    if (this.storage) {
+    if (storage) {
       // Invoke predelete hooks (can throw to abort, e.g., for cascade checks)
       const predeleteContext = this._buildPredeleteContext(id)
       await this._invokeHook('predelete', predeleteContext)
 
-      const result = await this.storage.delete(id)
+      const result = await storage.delete(id)
       this.invalidateCache()
       this._emitSignal('deleted', {
         manager: this.name,

package/src/entity/storage/ApiStorage.js

@@ -20,6 +20,34 @@ import { IStorage } from './IStorage.js'
  *   endpoint: '/users',
  *   getClient: () => inject('apiClient')
  * })
+ *
+ * // With parameter mapping (transform filter names for API)
+ * const storage = new ApiStorage({
+ *   endpoint: '/commands',
+ *   client: apiClient,
+ *   paramMapping: {
+ *     bot_uuid: 'botUuid',  // filters.bot_uuid → ?botUuid=xxx
+ *     page_size: 'limit'    // page_size → ?limit=xxx
+ *   }
+ * })
+ *
+ * // With data normalization (different API format)
+ * const storage = new ApiStorage({
+ *   endpoint: '/api/projects/:id/tasks',
+ *   client: apiClient,
+ *   // API → internal format
+ *   normalize: (apiData) => ({
+ *     id: apiData.task_id,
+ *     title: apiData.name,
+ *     status: apiData.state
+ *   }),
+ *   // Internal → API format
+ *   denormalize: (data) => ({
+ *     task_id: data.id,
+ *     name: data.title,
+ *     state: data.status
+ *   })
+ * })
  * ```
  */
 export class ApiStorage extends IStorage {
@@ -55,7 +83,15 @@ export class ApiStorage extends IStorage {
       getClient = null,
       // Response format configuration
       responseItemsKey = 'items',
-      responseTotalKey = 'total'
+      responseTotalKey = 'total',
+      // Parameter mapping: { clientName: apiName }
+      // Transforms filter and query param names before sending to API
+      paramMapping = {},
+      // Data normalization
+      // normalize: (apiData) => internalData - transform API response
+      // denormalize: (internalData) => apiData - transform before sending
+      normalize = null,
+      denormalize = null
     } = options
 
     this.endpoint = endpoint
@@ -63,6 +99,50 @@ export class ApiStorage extends IStorage {
     this._getClient = getClient
     this.responseItemsKey = responseItemsKey
     this.responseTotalKey = responseTotalKey
+    this.paramMapping = paramMapping
+    this._normalize = normalize
+    this._denormalize = denormalize
+  }
+
+  /**
+   * Normalize API response data to internal format
+   * @param {object|Array} data - API response data
+   * @returns {object|Array} - Normalized data
+   */
+  _normalizeData(data) {
+    if (!this._normalize) return data
+    if (Array.isArray(data)) {
+      return data.map(item => this._normalize(item))
+    }
+    return this._normalize(data)
+  }
+
+  /**
+   * Denormalize internal data to API format
+   * @param {object} data - Internal data
+   * @returns {object} - API format data
+   */
+  _denormalizeData(data) {
+    if (!this._denormalize) return data
+    return this._denormalize(data)
+  }
+
+  /**
+   * Apply parameter mapping to transform names
+   * @param {object} params - Original params
+   * @returns {object} - Params with mapped names
+   */
+  _applyParamMapping(params) {
+    if (!this.paramMapping || Object.keys(this.paramMapping).length === 0) {
+      return params
+    }
+
+    const mapped = {}
+    for (const [key, value] of Object.entries(params)) {
+      const mappedKey = this.paramMapping[key] || key
+      mapped[mappedKey] = value
+    }
+    return mapped
   }
 
   get client() {
@@ -88,13 +168,18 @@ export class ApiStorage extends IStorage {
    */
   async list(params = {}) {
     const { page = 1, page_size = 20, sort_by, sort_order, filters = {} } = params
+
+    // Apply param mapping to filters
+    const mappedFilters = this._applyParamMapping(filters)
+
     const response = await this.client.get(this.endpoint, {
-      params: { page, page_size, sort_by, sort_order, ...filters }
+      params: { page, page_size, sort_by, sort_order, ...mappedFilters }
     })
 
     const data = response.data
+    const items = data[this.responseItemsKey] || data.items || data
     return {
-      items: data[this.responseItemsKey] || data.items || data,
+      items: this._normalizeData(items),
       total: data[this.responseTotalKey] || data.total || (Array.isArray(data) ? data.length : 0)
     }
   }
@@ -106,7 +191,7 @@ export class ApiStorage extends IStorage {
    */
   async get(id) {
     const response = await this.client.get(`${this.endpoint}/${id}`)
-    return response.data
+    return this._normalizeData(response.data)
   }
 
   /**
@@ -115,8 +200,9 @@ export class ApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async create(data) {
-    const response = await this.client.post(this.endpoint, data)
-    return response.data
+    const apiData = this._denormalizeData(data)
+    const response = await this.client.post(this.endpoint, apiData)
+    return this._normalizeData(response.data)
   }
 
   /**
@@ -126,8 +212,9 @@ export class ApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async update(id, data) {
-    const response = await this.client.put(`${this.endpoint}/${id}`, data)
-    return response.data
+    const apiData = this._denormalizeData(data)
+    const response = await this.client.put(`${this.endpoint}/${id}`, apiData)
+    return this._normalizeData(response.data)
   }
 
   /**
@@ -137,8 +224,9 @@ export class ApiStorage extends IStorage {
    * @returns {Promise<object>}
    */
   async patch(id, data) {
-    const response = await this.client.patch(`${this.endpoint}/${id}`, data)
-    return response.data
+    const apiData = this._denormalizeData(data)
+    const response = await this.client.patch(`${this.endpoint}/${id}`, apiData)
+    return this._normalizeData(response.data)
   }
 
   /**

package/src/query/FilterQuery.js

@@ -102,7 +102,7 @@ export class FilterQuery {
   }
 
   /**
-   * Set the parent manager (called by useListPageBuilder for field source)
+   * Set the parent manager (called by useListPage for field source)
    *
    * @param {EntityManager} manager
    * @returns {FilterQuery} this for chaining

package/src/security/pages/RoleList.vue

@@ -3,14 +3,14 @@
  * RoleList - Role listing page (standard ListPage pattern)
  */
 
-import { useListPageBuilder, ListPage, useOrchestrator } from '../../index.js'
+import { useListPage, ListPage, useOrchestrator } from '../../index.js'
 import Column from 'primevue/column'
 import Tag from 'primevue/tag'
 import Chip from 'primevue/chip'
 import Message from 'primevue/message'
 
 // ============ LIST BUILDER ============
-const list = useListPageBuilder({ entity: 'roles' })
+const list = useListPage({ entity: 'roles' })
 
 // ============ SEARCH ============
 list.setSearch({