@quazardous/qdadm 2.1.0 → 2.2.0

package/package.json

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

package/src/kernel/Kernel.types.ts

@@ -192,6 +192,26 @@ export interface KernelOptions {
    * 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/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 */