qdadm 0.46.1 → 0.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.46.1",
+  "version": "0.48.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -39,7 +39,8 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@quazardous/quarkernel": "^2.1.0"
+    "@quazardous/quarkernel": "^2.1.0",
+    "pluralize": "^8.0.0"
   },
   "peerDependencies": {
     "pinia": "^2.0.0",

package/src/components/forms/FormField.vue

@@ -7,7 +7,7 @@
  *   <InputText v-model="form.username" />
  * </FormField>
  *
- * The parent form (useFormPageBuilder) provides:
+ * The parent form (useEntityItemFormPage) provides:
  * - isFieldDirty: function to check if field is dirty
  * - getFieldError: function to get field error message
  * - handleFieldBlur: function to trigger validation on blur
@@ -44,7 +44,7 @@ const props = defineProps({
   }
 })
 
-// Inject from parent form (provided by useFormPageBuilder)
+// Inject from parent form (provided by useEntityItemFormPage)
 const isFieldDirty = inject('isFieldDirty', () => false)
 const getFieldError = inject('getFieldError', () => null)
 const handleFieldBlur = inject('handleFieldBlur', () => {})

package/src/components/forms/FormPage.vue

@@ -9,10 +9,10 @@
  * - FormActions footer
  * - UnsavedChangesDialog integration
  *
- * Props come from useFormPageBuilder composable:
+ * Props come from useEntityItemFormPage composable:
  *
  * ```vue
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.generateFields()
  * form.addSaveAction()
  *

package/src/components/layout/PageNav.vue

@@ -110,7 +110,8 @@ const breadcrumbItems = computed(() => {
     const parentLabel = parentData.value
       ? parentManager.getEntityLabel(parentData.value)
       : '...'
-    const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+    const defaultSuffix = parentManager.readOnly ? '-show' : '-edit'
+    const parentRouteName = itemRoute || `${parentManager.routePrefix}${defaultSuffix}`
 
     items.push({
       label: parentLabel,
@@ -157,10 +158,11 @@ const allNavlinks = computed(() => {
 
   if (!parentManager) return navlinks.value
 
-  const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+  const defaultSuffix = parentManager.readOnly ? '-show' : '-edit'
+  const parentRouteName = itemRoute || `${parentManager.routePrefix}${defaultSuffix}`
   const isOnParentRoute = route.name === parentRouteName
 
-  // Details link to parent edit form
+  // Details link to parent item page
   const detailsLink = {
     label: 'Details',
     to: { name: parentRouteName, params: { id: parentId } },

package/src/composables/index.js

@@ -7,13 +7,14 @@ export { useBreadcrumb } from './useBreadcrumb'
 export { useSemanticBreadcrumb, computeSemanticBreadcrumb } from './useSemanticBreadcrumb'
 export { useDirtyState } from './useDirtyState'
 export { useForm } from './useForm'
-export { useFormPageBuilder } from './useFormPageBuilder'
+export { useEntityItemFormPage, useEntityItemFormPage as useFormPageBuilder } from './useEntityItemFormPage'
 export * from './useJsonSyntax'
 export { useListPageBuilder, PAGE_SIZE_OPTIONS } from './useListPageBuilder'
 export { usePageTitle } from './usePageTitle'
 export { useApp } from './useApp'
 export { useAuth } from './useAuth'
 export { useCurrentEntity } from './useCurrentEntity'
+export { useEntityItemPage } from './useEntityItemPage'
 export { useNavContext } from './useNavContext'
 export { useNavigation } from './useNavigation'
 export { useUnsavedChangesGuard } from './useUnsavedChangesGuard'

package/src/composables/{useFormPageBuilder.js → useEntityItemFormPage.js}

@@ -1,5 +1,5 @@
 /**
- * useFormPageBuilder - Unified procedural builder for CRUD form pages
+ * useEntityItemFormPage - Unified procedural builder for CRUD form pages
  *
  * Provides a declarative/procedural API to build form pages with:
  * - Mode detection (create vs edit from route params)
@@ -13,7 +13,7 @@
  * ## Basic Usage
  *
  * ```js
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.addSaveAction()
  * form.addDeleteAction()
  *
@@ -27,7 +27,7 @@
  * ## Auto-generated Fields
  *
  * ```js
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.generateFields()  // Auto-generate from manager.fields
  * form.excludeField('internal_id')  // Exclude specific fields
  * form.addField('custom', { type: 'text', label: 'Custom' })  // Manual override
@@ -40,7 +40,7 @@
  * ## Validation
  *
  * ```js
- * const form = useFormPageBuilder({ entity: 'books' })
+ * const form = useEntityItemFormPage({ entity: 'books' })
  * form.generateFields()
  *
  * // Add custom validator
@@ -77,19 +77,18 @@
  * - Unsaved changes guard modal
  * - Permission-aware save/delete actions via EntityManager.canUpdate/canDelete
  */
-import { ref, computed, watch, onMounted, inject, provide } from 'vue'
+import { ref, computed, watch, onMounted, onUnmounted, provide } from 'vue'
 import { useRouter, useRoute } from 'vue-router'
 import { useToast } from 'primevue/usetoast'
 import { useConfirm } from 'primevue/useconfirm'
 import { useDirtyState } from './useDirtyState'
 import { useUnsavedChangesGuard } from './useUnsavedChangesGuard'
 import { useBreadcrumb } from './useBreadcrumb'
-import { useCurrentEntity } from './useCurrentEntity'
+import { useEntityItemPage } from './useEntityItemPage'
 import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
 import { deepClone } from '../utils/transformers'
-import { onUnmounted } from 'vue'
 
-export function useFormPageBuilder(config = {}) {
+export function useEntityItemFormPage(config = {}) {
   const {
     entity,
     // Mode detection
@@ -118,41 +117,22 @@ export function useFormPageBuilder(config = {}) {
   const toast = useToast()
   const confirm = useConfirm()
 
-  // Get EntityManager via orchestrator
-  const orchestrator = inject('qdadmOrchestrator')
-  if (!orchestrator) {
-    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)
-
-  // Provide entity context for child components (e.g., SeverityTag auto-discovery)
-  provide('mainEntity', entity)
+  // Use useEntityItemPage for common infrastructure
+  // (orchestrator, manager, entityId, provide('mainEntity'), breadcrumb)
+  const itemPage = useEntityItemPage({
+    entity,
+    loadOnMount: false,  // Form controls its own loading
+    breadcrumb: false,   // Form calls setBreadcrumbEntity manually after transform
+    getId
+  })
 
-  // Share entity data with navigation context (for breadcrumb)
-  const { setCurrentEntity } = useCurrentEntity()
+  const { manager, orchestrator, entityId, setBreadcrumbEntity } = itemPage
 
   // Read config from manager with option overrides
   const entityName = config.entityName ?? manager.label
   const routePrefix = config.routePrefix ?? manager.routePrefix
   const initialData = config.initialData ?? manager.getInitialData()
 
-  // ============ MODE DETECTION ============
-
-  /**
-   * Extract entity ID from route params
-   * Supports: /books/:id/edit, /books/:id, /books/new
-   */
-  const entityId = computed(() => {
-    if (getId) return getId()
-    return route.params.id || route.params.key || null
-  })
-
   /**
    * Detect form mode: 'create' or 'edit'
    * Based on route name or presence of ID
@@ -263,7 +243,7 @@ export function useFormPageBuilder(config = {}) {
       takeSnapshot()
 
       // Share with navigation context for breadcrumb
-      setCurrentEntity(transformed)
+      setBreadcrumbEntity(transformed)
 
       if (onLoadSuccess) {
         await onLoadSuccess(transformed)
@@ -520,7 +500,7 @@ export function useFormPageBuilder(config = {}) {
         const updatedConfig = { ...config, options }
         fieldsMap.value.set(name, updatedConfig)
       } catch (error) {
-        console.warn(`[useFormPageBuilder] Failed to resolve options for field '${name}':`, error)
+        console.warn(`[useEntityItemFormPage] Failed to resolve options for field '${name}':`, error)
       }
     }
   }

package/src/composables/useEntityItemPage.js

@@ -0,0 +1,201 @@
+/**
+ * useEntityItemPage - Base composable for single entity item pages
+ *
+ * Provides common functionality for pages that display a single entity:
+ * - Entity loading by ID from route params
+ * - Loading/error state management
+ * - Breadcrumb integration (auto-calls setBreadcrumbEntity)
+ * - Manager access for child composables
+ *
+ * Used as base for:
+ * - Show pages (read-only detail pages)
+ * - useEntityItemFormPage (create/edit forms)
+ *
+ * ## Basic Usage (standalone)
+ *
+ * ```js
+ * const { data, loading, error, reload } = useEntityItemPage({ entity: 'posts' })
+ *
+ * // data.value contains the loaded entity
+ * // loading.value is true while fetching
+ * // error.value contains error message if failed
+ * ```
+ *
+ * ## Usage in parent composables
+ *
+ * ```js
+ * function useEntityItemFormPage(config) {
+ *   const itemPage = useEntityItemPage({
+ *     entity: config.entity,
+ *     loadOnMount: false,  // Form controls its own loading
+ *     transformLoad: config.transformLoad
+ *   })
+ *
+ *   // Use itemPage.load(), itemPage.data, etc.
+ * }
+ * ```
+ */
+import { ref, computed, onMounted, inject, provide } from 'vue'
+import { useRoute } from 'vue-router'
+import { useCurrentEntity } from './useCurrentEntity.js'
+
+export function useEntityItemPage(config = {}) {
+  const {
+    entity,
+    // Loading options
+    loadOnMount = true,
+    breadcrumb = true,
+    // ID extraction
+    getId = null,
+    idParam = 'id',
+    // Transform hook
+    transformLoad = (data) => data,
+    // Callbacks
+    onLoadSuccess = null,
+    onLoadError = null
+  } = config
+
+  const route = useRoute()
+
+  // Get EntityManager via orchestrator
+  const orchestrator = inject('qdadmOrchestrator')
+  if (!orchestrator) {
+    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)
+
+  // Provide entity context for child components
+  provide('mainEntity', entity)
+
+  // Breadcrumb integration
+  const { setBreadcrumbEntity } = useCurrentEntity()
+
+  // ============ STATE ============
+
+  const data = ref(null)
+  const loading = ref(false)
+  const error = ref(null)
+
+  // ============ ID EXTRACTION ============
+
+  /**
+   * Extract entity ID from route params
+   * Supports custom getId function or param name
+   */
+  const entityId = computed(() => {
+    if (getId) return getId()
+    return route.params[idParam] || route.params.id || route.params.key || null
+  })
+
+  // ============ LOADING ============
+
+  /**
+   * Load entity by ID
+   * @param {string|number} [id] - Optional ID override (defaults to route param)
+   * @returns {Promise<object|null>} Loaded entity data or null on error
+   */
+  async function load(id = entityId.value) {
+    if (!id) {
+      error.value = 'No entity ID provided'
+      return null
+    }
+
+    loading.value = true
+    error.value = null
+
+    try {
+      const responseData = await manager.get(id)
+
+      if (!responseData) {
+        error.value = `${manager.label || entity} not found`
+        return null
+      }
+
+      const transformed = transformLoad(responseData)
+      data.value = transformed
+
+      // Share with navigation context for breadcrumb
+      if (breadcrumb) {
+        setBreadcrumbEntity(transformed)
+      }
+
+      if (onLoadSuccess) {
+        await onLoadSuccess(transformed)
+      }
+
+      return transformed
+    } catch (err) {
+      console.error(`[useEntityItemPage] Failed to load ${entity}:`, err)
+      error.value = err.response?.data?.detail || err.message || `Failed to load ${manager.label || entity}`
+
+      if (onLoadError) {
+        await onLoadError(err)
+      }
+
+      return null
+    } finally {
+      loading.value = false
+    }
+  }
+
+  /**
+   * Reload current entity
+   */
+  async function reload() {
+    return load(entityId.value)
+  }
+
+  // ============ COMPUTED ============
+
+  /**
+   * Entity label (uses manager.getEntityLabel)
+   */
+  const entityLabel = computed(() => {
+    if (!data.value) return null
+    return manager.getEntityLabel(data.value)
+  })
+
+  /**
+   * Check if entity is loaded
+   */
+  const isLoaded = computed(() => data.value !== null)
+
+  // ============ LIFECYCLE ============
+
+  if (loadOnMount) {
+    onMounted(() => {
+      if (entityId.value) {
+        load()
+      }
+    })
+  }
+
+  // ============ RETURN ============
+
+  return {
+    // State
+    data,
+    loading,
+    error,
+
+    // Computed
+    entityId,
+    entityLabel,
+    isLoaded,
+
+    // Actions
+    load,
+    reload,
+
+    // References (for parent composables)
+    manager,
+    orchestrator,
+    setBreadcrumbEntity
+  }
+}

package/src/composables/useNavContext.js

@@ -46,6 +46,19 @@ export function useNavContext(options = {}) {
     return router.getRoutes().some(r => r.name === name)
   }
 
+  /**
+   * Get default item route for an entity manager
+   * - Read-only entities: use -show suffix
+   * - Editable entities: use -edit suffix
+   * @param {EntityManager} manager
+   * @returns {string} Route name
+   */
+  function getDefaultItemRoute(manager) {
+    if (!manager) return null
+    const suffix = manager.readOnly ? '-show' : '-edit'
+    return `${manager.routePrefix}${suffix}`
+  }
+
   /**
    * Convert semantic breadcrumb to navigation chain format
    * Maps semantic kinds to chain types for compatibility
@@ -71,7 +84,7 @@ export function useNavContext(options = {}) {
           entity: item.entity,
           manager,
           id: item.id,
-          routeName: manager ? `${manager.routePrefix}-edit` : null
+          routeName: getDefaultItemRoute(manager)
         })
       } else if (item.kind === 'entity-create') {
         // Create page - treat as special list
@@ -246,7 +259,7 @@ export function useNavContext(options = {}) {
     const parentManager = getManager(parentEntity)
     if (!parentManager) return []
 
-    const parentRouteName = itemRoute || `${parentManager.routePrefix}-edit`
+    const parentRouteName = itemRoute || getDefaultItemRoute(parentManager)
     const isOnParent = route.name === parentRouteName
 
     // Details link

package/src/entity/EntityManager.js

@@ -1,6 +1,7 @@
 import { PermissiveAuthAdapter } from './auth/PermissiveAdapter.js'
 import { AuthActions } from './auth/EntityAuthAdapter.js'
 import { QueryExecutor } from '../query/QueryExecutor.js'
+import pluralize from 'pluralize'
 
 /**
  * EntityManager - Base class for entity CRUD operations
@@ -307,36 +308,34 @@ export class EntityManager {
 
   /**
    * Get entity label (singular)
-   * Default: capitalize name (e.g., 'users' → 'User')
+   * Default: capitalize name (e.g., 'users' → 'User', 'countries' → 'Country')
    */
   get label() {
     if (this._label) return this._label
     if (!this.name) return 'Item'
-    // users → User, book → Book
-    const singular = this.name.endsWith('s') ? this.name.slice(0, -1) : this.name
+    const singular = pluralize.singular(this.name)
     return singular.charAt(0).toUpperCase() + singular.slice(1)
   }
 
   /**
    * Get entity label (plural)
-   * Default: capitalize name or add 's' (e.g., 'user' → 'Users')
+   * Default: capitalize name (e.g., 'user' → 'Users', 'country' → 'Countries')
    */
   get labelPlural() {
     if (this._labelPlural) return this._labelPlural
     if (!this.name) return 'Items'
-    // users → Users, book → Books
-    const plural = this.name.endsWith('s') ? this.name : this.name + 's'
+    const plural = pluralize.plural(this.name)
     return plural.charAt(0).toUpperCase() + plural.slice(1)
   }
 
   /**
    * Get route prefix for this entity
-   * Default: singular form of name (e.g., 'books' → 'book')
+   * Default: singular form of name (e.g., 'books' → 'book', 'countries' → 'country')
    */
   get routePrefix() {
     if (this._routePrefix) return this._routePrefix
     if (!this.name) return 'item'
-    return this.name.endsWith('s') ? this.name.slice(0, -1) : this.name
+    return pluralize.singular(this.name)
   }
 
   /**

package/src/entity/storage/MockApiStorage.js

@@ -1,4 +1,5 @@
 import { IStorage } from './IStorage.js'
+import { QueryExecutor } from '../../query/index.js'
 
 /**
  * MockApiStorage - In-memory storage with localStorage persistence
@@ -191,16 +192,9 @@ export class MockApiStorage extends IStorage {
 
     let items = this._getAll()
 
-    // Apply filters (substring match for strings, exact match for others)
-    for (const [key, value] of Object.entries(filters)) {
-      if (value === null || value === undefined || value === '') continue
-      items = items.filter(item => {
-        const itemValue = item[key]
-        if (typeof value === 'string' && typeof itemValue === 'string') {
-          return itemValue.toLowerCase().includes(value.toLowerCase())
-        }
-        return itemValue === value
-      })
+    // Apply filters using QueryExecutor (supports MongoDB-like operators)
+    if (Object.keys(filters).length > 0) {
+      items = QueryExecutor.execute(items, filters).items
     }
 
     // Apply search (substring match on all string fields)

package/src/security/pages/RoleForm.vue

@@ -4,13 +4,13 @@
  */
 
 import { ref, computed, inject } from 'vue'
-import { useFormPageBuilder, FormPage, useOrchestrator, PermissionEditor } from '../../index.js'
+import { useEntityItemFormPage, FormPage, useOrchestrator, PermissionEditor } from '../../index.js'
 import InputText from 'primevue/inputtext'
 import AutoComplete from 'primevue/autocomplete'
 import Chip from 'primevue/chip'
 
 // ============ FORM BUILDER ============
-const form = useFormPageBuilder({ entity: 'roles' })
+const form = useEntityItemFormPage({ entity: 'roles' })
 
 // ============ HELPERS ============
 const { getManager } = useOrchestrator()