@quazardous/qdadm 2.0.0 → 2.2.0

package/package.json

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

package/src/api/apiClient.ts

@@ -0,0 +1,34 @@
+/**
+ * Kernel-level default API client (qdadm #1198)
+ *
+ * Apps already build an axios-compatible HttpClient (base URL + auth
+ * interceptors) for their ApiStorages. Registering it once on the kernel
+ * makes it available to composables/widgets that need ad-hoc API calls
+ * (useOptionsLookup endpoint mode, ScopeEditor), so relative endpoints
+ * get base URL + auth applied without per-call wiring:
+ *
+ *   new Kernel({ apiClient: myAxios })
+ */
+import { inject } from 'vue'
+import type { HttpClient } from '../entity/storage/ApiStorage'
+
+/** Injection key under which the kernel provides the default API client. */
+export const API_CLIENT_INJECTION_KEY = 'qdadmApiClient'
+
+/** Accepted forms of the kernel `apiClient` option. */
+export type ApiClientSource = HttpClient | (() => HttpClient)
+
+/** Resolve an ApiClientSource (direct instance or factory) to a client. */
+export function resolveApiClient(source: ApiClientSource | null | undefined): HttpClient | null {
+  if (!source) return null
+  return typeof source === 'function' ? source() : source
+}
+
+/**
+ * Inject the kernel-registered default API client, or null when none is
+ * registered. Must be called from a setup context (like any inject).
+ */
+export function useApiClient(): HttpClient | null {
+  const source = inject<ApiClientSource | null>(API_CLIENT_INJECTION_KEY, null)
+  return resolveApiClient(source)
+}

package/src/components/editors/ScopeEditor.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { ref, computed, onMounted, watch, inject } from 'vue'
+import type { HttpClient } from '../../entity/storage/ApiStorage'
 import AutoComplete from 'primevue/autocomplete'
 import Select from 'primevue/select'
 import Button from 'primevue/button'
@@ -43,8 +44,10 @@ const props = withDefaults(defineProps<Props>(), {
   defaultActions: null
 })
 
-// Get API adapter (optional)
+// Get API adapter (optional); the kernel default client (Kernel({ apiClient }))
+// serves as fallback so scope endpoints get base URL + auth without app wiring.
 const api = inject<ApiAdapter | null>('apiAdapter', null)
+const kernelApiClient = inject<HttpClient | (() => HttpClient) | null>('qdadmApiClient', null)
 
 // Get global scope config (optional) - allows app-level configuration
 const globalScopeConfig = inject<ScopeConfig>('scopeConfig', {})
@@ -178,8 +181,17 @@ function isRowComplete(row: ScopeRow): boolean {
 async function loadScopeDefinition(): Promise<void> {
   loading.value = true
   try {
-    if (!api) {
-      // No API adapter, use defaults
+    let data: ScopeDefinition | null = null
+    if (api) {
+      data = await api.request('GET', config.value.endpoint)
+    } else if (kernelApiClient) {
+      // Fallback: kernel default API client (base URL + auth applied)
+      const client = typeof kernelApiClient === 'function' ? kernelApiClient() : kernelApiClient
+      data = (await client.get<ScopeDefinition>(config.value.endpoint)).data
+    }
+
+    if (!data) {
+      // No API layer available, use defaults
       scopeDefinition.value = {
         resources: [...config.value.resources],
         actions: [...config.value.actions],
@@ -187,7 +199,6 @@ async function loadScopeDefinition(): Promise<void> {
       return
     }
 
-    const data = await api.request('GET', config.value.endpoint)
     scopeDefinition.value = {
       resources: data.resources || [...config.value.resources],
       actions: data.actions || [...config.value.actions],

package/src/composables/useOptionsLookup.ts

@@ -42,6 +42,7 @@
  */
 import { ref, onMounted, type Ref } from 'vue'
 import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
+import { useApiClient } from '../api/apiClient'
 
 export interface OptionsLookupItem {
   label: string
@@ -66,11 +67,27 @@ export interface UseOptionsLookupConfig {
   entity?: string
   /** Extract distinct values from a specific field (entity mode only) */
   field?: string
-  /** Fetch options from a raw API endpoint */
+  /**
+   * Fetch options from an API endpoint.
+   *
+   * Routing (#1198): a **relative** endpoint goes through the kernel's
+   * default API client when one is registered (`Kernel({ apiClient })`) —
+   * base URL + auth applied, no per-call wiring. An **absolute** URL is
+   * fetched raw (escape hatch for third-party APIs, combine with `headers`).
+   * A relative endpoint with no registered client falls back to a raw fetch
+   * (legacy) with a console warning.
+   */
   endpoint?: string
+  /**
+   * Route the endpoint request through the named entity's storage
+   * (`storage.request('GET', endpoint)`) instead of the kernel client —
+   * explicit refinement for multi-API apps. Takes precedence over the
+   * kernel client.
+   */
+  via?: string
   /** When using endpoint: pick a sub-key from the response data */
   pick?: string
-  /** Extra headers for endpoint fetch (e.g. Authorization) */
+  /** Extra headers for the raw-fetch paths (e.g. Authorization) */
   headers?: Record<string, string> | (() => Record<string, string>)
   /** Static options (no fetch needed) */
   static?: unknown[]
@@ -164,10 +181,16 @@ export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLook
       : defaultDecode
   )
 
-  // Resolve orchestrator lazily (only if entity mode)
-  let getManager: ((name: string) => { list: (params?: Record<string, unknown>) => Promise<{ items: unknown[] }> }) | null = null
+  // Resolve orchestrator lazily (entity mode, or via:'entityName' routing)
+  type LookupManager = {
+    list: (params?: Record<string, unknown>) => Promise<{ items: unknown[] }>
+    storage?: {
+      request?: (method: string, path: string, options?: Record<string, unknown>) => Promise<unknown>
+    }
+  }
+  let getManager: ((name: string) => LookupManager) | null = null
 
-  if (config.entity) {
+  if (config.entity || config.via) {
     try {
       const orc = useOrchestrator()
       // Generic-vs-non-generic: getManager is parameterised by an
@@ -180,6 +203,105 @@ export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLook
     }
   }
 
+  // Kernel default API client (Kernel({ apiClient })) — used for relative
+  // endpoints so base URL + auth apply without per-call wiring (#1198).
+  let apiClient: ReturnType<typeof useApiClient> = null
+  if (config.endpoint) {
+    try {
+      apiClient = useApiClient()
+    } catch {
+      // Outside a setup/injection context
+    }
+  }
+
+  // Bare-relative warning: once per composable instance, not per load
+  let warnedBareRelative = false
+
+  function warnLookup(msg: string): void {
+    console.warn(`[qdadm] useOptionsLookup(endpoint: '${config.endpoint}'): ${msg}`)
+  }
+
+  /** Shared normalization for every endpoint path: unwrap data, pick, array-check. */
+  function normalizeEndpointPayload(json: unknown): unknown[] {
+    let data: unknown = (json as { data?: unknown })?.data ?? json
+    if (config.pick && typeof data === 'object' && data !== null && !Array.isArray(data)) {
+      data = (data as Record<string, unknown>)[config.pick]
+    }
+    if (!Array.isArray(data)) {
+      warnLookup('response contained no usable array (after data/pick unwrap) — check the endpoint payload shape')
+      return []
+    }
+    return data
+  }
+
+  /** Endpoint routing (#1198): via storage > relative→kernel client > raw fetch. */
+  async function loadFromEndpoint(): Promise<unknown[]> {
+    const endpoint = config.endpoint!
+    const isAbsolute = /^https?:\/\//i.test(endpoint)
+
+    // 1. via:'entityName' → that entity's storage (explicit refinement)
+    if (config.via && getManager) {
+      const storage = getManager(config.via)?.storage
+      if (storage?.request) {
+        try {
+          const json = await storage.request('GET', endpoint)
+          return normalizeEndpointPayload(json)
+        } catch (err) {
+          warnLookup(`request via '${config.via}' storage failed: ${err instanceof Error ? err.message : err}`)
+          throw err
+        }
+      }
+      warnLookup(`via: '${config.via}' has no storage.request() — falling back to the default routing`)
+    }
+
+    // 2. relative endpoint → kernel default API client (base URL + auth)
+    if (!isAbsolute && apiClient) {
+      try {
+        const { data } = await apiClient.get(endpoint)
+        return normalizeEndpointPayload(data)
+      } catch (err) {
+        warnLookup(`request through the kernel apiClient failed: ${err instanceof Error ? err.message : err}`)
+        throw err
+      }
+    }
+
+    // 3. raw fetch — absolute URL (escape hatch) or legacy relative call
+    if (!isAbsolute && !warnedBareRelative) {
+      warnedBareRelative = true
+      warnLookup(
+        'relative endpoint fetched bare — no API base URL or auth header applied. ' +
+        'Register Kernel({ apiClient }) (recommended), use via: \'entityName\', or pass an absolute URL + headers.'
+      )
+    }
+    const extraHeaders = typeof config.headers === 'function' ? config.headers() : config.headers
+    const response = await fetch(endpoint, {
+      credentials: 'include',
+      headers: { 'Accept': 'application/json', ...extraHeaders },
+    })
+    if (!response.ok) {
+      const authHint = response.status === 401 || response.status === 403
+        ? ' — missing auth? register Kernel({ apiClient }) or pass headers'
+        : ''
+      warnLookup(`HTTP ${response.status}${authHint}`)
+      throw new Error(`HTTP ${response.status}`)
+    }
+    const contentType = response.headers.get('content-type') || ''
+    if (!contentType.includes('json')) {
+      warnLookup(
+        `response is not JSON (content-type: '${contentType || 'unknown'}') — the relative URL likely resolved ` +
+        'to the app origin (HTML page). Register Kernel({ apiClient }) or use an absolute URL.'
+      )
+    }
+    let json: unknown
+    try {
+      json = await response.json()
+    } catch (err) {
+      warnLookup(`response body is not parseable JSON: ${err instanceof Error ? err.message : err}`)
+      throw err
+    }
+    return normalizeEndpointPayload(json)
+  }
+
   // Encoded strings cache for mapped mode (rebuilt on processItems)
   let encodedStrings: string[] = []
 
@@ -255,21 +377,7 @@ export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLook
           items = rawItems
         }
       } else if (config.endpoint) {
-        const extraHeaders = typeof config.headers === 'function' ? config.headers() : config.headers
-        const response = await fetch(config.endpoint, {
-          credentials: 'include',
-          headers: { 'Accept': 'application/json', ...extraHeaders },
-        })
-        if (!response.ok) throw new Error(`HTTP ${response.status}`)
-        const json = await response.json()
-
-        let data = json.data ?? json
-
-        if (config.pick && typeof data === 'object' && !Array.isArray(data)) {
-          data = (data as Record<string, unknown>)[config.pick]
-        }
-
-        items = Array.isArray(data) ? data : []
+        items = await loadFromEndpoint()
       }
 
       processItems(items)

package/src/index.ts

@@ -293,6 +293,12 @@ export {
   type OptionsLookupItem,
   type OptionsDisplayMode,
 } from './composables/useOptionsLookup'
+export {
+  useApiClient,
+  resolveApiClient,
+  API_CLIENT_INJECTION_KEY,
+  type ApiClientSource,
+} from './api/apiClient'
 export { useChildPage, type UseChildPageReturn } from './composables/useChildPage'
 export { useSidebarState, SIDEBAR_COLLAPSED_KEY } from './composables/useSidebarState'
 

package/src/kernel/Kernel.types.ts

@@ -11,6 +11,7 @@ import type { EntityManager } from '../entity/EntityManager'
 import type { EntityAuthAdapter } from '../entity/auth/EntityAuthAdapter'
 import type { RoleProvider } from '../security/RolesProvider'
 import type { I18nOptions } from '../i18n/types'
+import type { ApiClientSource } from '../api/apiClient'
 
 /**
  * Auth adapter interface (app-level authentication)
@@ -183,6 +184,34 @@ export interface KernelOptions {
   debug?: boolean
   onAuthExpired?: (payload: unknown) => void
   i18n?: I18nOptions
+  /**
+   * Default API HTTP client (axios-compatible `HttpClient`, or a factory),
+   * provided to composables/widgets as `qdadmApiClient`. Relative-endpoint
+   * lookups (`useOptionsLookup` endpoint mode, `ScopeEditor` fallback) route
+   * through it so the app's base URL + auth headers apply without per-call
+   * wiring. Typically the same client your ApiStorages use.
+   */
+  apiClient?: ApiClientSource
+  /**
+   * Naming policy for the URL param carrying the parent id in child route
+   * families (#1201). `auto` (default): list-only families keep the bare
+   * `idField` param; families with show/edit routes namespace the parent
+   * (`jobs/:jobId/tasks/:id`) so the principal (child) id stays `:id`.
+   * `always`: namespaced everywhere. `bare`: legacy `idField` param, with
+   * an explicit registration error on collision.
+   */
+  parentParamMode?: 'auto' | 'always' | 'bare'
+  /**
+   * Global mapping service for parent URL param names (#1201). Consulted
+   * before `parentParamMode`; a per-call `parentParam` still wins. Return
+   * undefined to fall through to the mode-based default.
+   */
+  routeParamResolver?: (ctx: {
+    parentEntity: string
+    parentRouteName: string
+    childEntity: string | null
+    parentIdField: string
+  }) => string | undefined
   /**
    * Existing Vue app to install qdadm onto. When provided, the Kernel
    * skips its own `createApp(WrappedRoot)` and reuses the supplied

package/src/kernel/Kernel.vue.ts

@@ -205,6 +205,12 @@ export function applyVueMethods(KernelClass: { prototype: any }): void {
     app.provide('qdadmActiveStack', this.activeStack)
     app.provide('qdadmStackHydrator', this.stackHydrator)
 
+    if (this.options.apiClient) {
+      // Default API client for composables/widgets (useOptionsLookup,
+      // ScopeEditor) — relative endpoints get base URL + auth (#1198).
+      app.provide('qdadmApiClient', this.options.apiClient)
+    }
+
     if (this.options.debug && typeof window !== 'undefined') {
       const self = this
       // Single namespaced surface for browser-console & agent introspection.

package/src/kernel/KernelContext.routing.ts

@@ -45,6 +45,89 @@ function capitalize(str: string): string {
   return str.charAt(0).toUpperCase() + str.slice(1)
 }
 
+/** Context handed to a kernel-level routeParamResolver (#1201). */
+export interface RouteParamResolverContext {
+  parentEntity: string
+  parentRouteName: string
+  /** Child entity name, or null for a non-entity childPage. */
+  childEntity: string | null
+  parentIdField: string
+}
+
+/**
+ * Resolve the URL param name carrying the parent id in a child route
+ * family (#1201). Precedence: per-call `parentParam` > kernel
+ * `routeParamResolver` > `parentParamMode`:
+ *
+ * - `auto` (default): families whose routes never carry the child's own
+ *   id (list-only, childPage) keep the bare parent `idField` param —
+ *   unchanged URLs. Families with show/edit routes namespace the parent
+ *   (`:jobId`) so the principal (child) id stays `:id`.
+ * - `always`: namespaced parent param everywhere.
+ * - `bare`: legacy `idField` param everywhere; a would-be collision
+ *   throws at registration instead of silently shadowing the parent.
+ */
+function resolveParentParam(opts: {
+  kernelOptions?: {
+    parentParamMode?: 'auto' | 'always' | 'bare'
+    routeParamResolver?: (ctx: RouteParamResolverContext) => string | undefined
+  }
+  explicit?: string
+  parentEntity: string
+  parentRouteName: string
+  childEntity: string | null
+  parentIdField: string
+  childIdParam: string
+  hasOwnIdParam: boolean
+}): string {
+  const {
+    kernelOptions,
+    explicit,
+    parentEntity,
+    parentRouteName,
+    childEntity,
+    parentIdField,
+    childIdParam,
+    hasOwnIdParam,
+  } = opts
+
+  if (explicit) return explicit
+
+  const resolved = kernelOptions?.routeParamResolver?.({
+    parentEntity,
+    parentRouteName,
+    childEntity,
+    parentIdField,
+  })
+  if (resolved) return resolved
+
+  const mode = kernelOptions?.parentParamMode || 'auto'
+  const namespaced = `${singularize(parentEntity)}Id`
+
+  if (mode === 'always') return namespaced
+
+  if (mode === 'bare') {
+    if (hasOwnIdParam && parentIdField === childIdParam) {
+      throw new Error(
+        `[qdadm] crud('${childEntity}', { parentRoute: '${parentRouteName}' }): parent and child ` +
+        `both use the URL param ':${childIdParam}' — the child id would shadow the parent id. ` +
+        `Switch parentParamMode to 'auto', or set an explicit parentParam.`
+      )
+    }
+    return parentIdField
+  }
+
+  // mode === 'auto'
+  if (!hasOwnIdParam) return parentIdField
+  if (namespaced === childIdParam) {
+    throw new Error(
+      `[qdadm] crud('${childEntity}', { parentRoute: '${parentRouteName}' }): the namespaced ` +
+      `parent param ':${namespaced}' collides with the child idField — set an explicit parentParam.`
+    )
+  }
+  return namespaced
+}
+
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function applyRoutingMethods(KernelContextClass: { prototype: any }): void {
   const proto = KernelContextClass.prototype as Self
@@ -103,7 +186,20 @@ export function applyRoutingMethods(KernelContextClass: { prototype: any }): voi
         const parentManager = parentEntityName
           ? this._kernel.orchestrator?.get(parentEntityName)
           : null
-        const parentIdParam = parentManager?.idField || 'id'
+        const parentIdField = parentManager?.idField || 'id'
+        // Families with show/edit routes carry the child's own :id — the
+        // parent param must not collide with it (#1201).
+        const hasOwnIdParam = !!(pages.show || pages.form || pages.edit)
+        const parentIdParam = resolveParentParam({
+          kernelOptions: this._kernel.options,
+          explicit: options.parentParam,
+          parentEntity: parentEntityName || parentRouteName,
+          parentRouteName,
+          childEntity: entity,
+          parentIdField,
+          childIdParam: idParam,
+          hasOwnIdParam,
+        })
 
         // Build base path: parentPath/:parentId/entity (e.g., books/:bookId/loans)
         const parentBasePath =
@@ -238,7 +334,19 @@ export function applyRoutingMethods(KernelContextClass: { prototype: any }): voi
     const parentManager = parentEntityName
       ? this._kernel.orchestrator?.get(parentEntityName)
       : null
-    const parentIdParam = parentManager?.idField || 'id'
+    const parentIdField = parentManager?.idField || 'id'
+    // childPage has no own :id (single-id family) — auto mode keeps the
+    // bare param; explicit parentParam / resolver / 'always' still apply.
+    const parentIdParam = resolveParentParam({
+      kernelOptions: this._kernel.options,
+      explicit: options.parentParam,
+      parentEntity: parentEntityName || parentRouteName,
+      parentRouteName,
+      childEntity: null,
+      parentIdField,
+      childIdParam: 'id',
+      hasOwnIdParam: false,
+    })
 
     const parentBasePath =
       parentRoute.path.replace(/\/(create|:.*)?$/, '') || parentEntityName

package/src/kernel/KernelContext.types.ts

@@ -148,6 +148,12 @@ export interface CrudOptions {
   parentRoute?: string
   foreignKey?: string
   label?: string
+  /**
+   * Explicit URL param name carrying the parent id in child routes
+   * (e.g. 'jobUuid' → `jobs/:jobUuid/tasks/:id`). Overrides the kernel
+   * `routeParamResolver` and `parentParamMode` (#1201).
+   */
+  parentParam?: string
 }
 
 /** Child page options for non-entity child routes */
@@ -156,6 +162,8 @@ export interface ChildPageOptions {
   label?: string
   icon?: string
   meta?: Record<string, unknown>
+  /** Explicit URL param name for the parent id (see CrudOptions.parentParam). */
+  parentParam?: string
 }
 
 /** User entity options */