@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/resources/frontend-resource.utils.js

@@ -0,0 +1,1097 @@
+import { CoreResourceOperation, ResourceParentResourceRequirement, ErrorType, ErrorCustomMessageReference, ResourceOperationsUtils, ResourcesConfig_OperationPathUtils, ResourcesConfigOperationsUrlsBuilderUtils, ResourceOperationVariantType, getParentDirectionRelationships, Resources_SharedUtils, RelationshipMutationModel, RelationshipNature, } from "@wildo-ai/saas-models";
+import { ErrorBuilderFrontend } from '../../core/errors/errors-builder.frontend.services.js';
+import { envLoader } from '../../core/runtime/env-variable-loader.frontend.service.js';
+import { pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from './operation-semantics.frontend.utils.js';
+/**
+ * Singleton utility class for frontend resource operations
+ * Provides centralized helper functions for resource context management
+ */
+export class FrontendResourceUtils {
+    static instance;
+    errorBuilder;
+    constructor() {
+        this.errorBuilder = new ErrorBuilderFrontend();
+    }
+    static getInstance() {
+        if (!FrontendResourceUtils.instance) {
+            FrontendResourceUtils.instance = new FrontendResourceUtils();
+        }
+        return FrontendResourceUtils.instance;
+    }
+    // =============================================================================
+    // ERROR BUILDER (STATIC)
+    // =============================================================================
+    /**
+     * Build a proper WildoError_Frontend for resource configuration errors.
+     *
+     * Creates a CONFIGURATION-type error with the WildoError attached, so
+     * React ErrorBoundary can process it through the unified error system.
+     *
+     * @param customMessageReference - The ErrorCustomMessageReference for the specific error
+     * @param context - Additional context for debugging (field names, resource types, etc.)
+     * @returns An Error instance with .wildoError (WildoError_Frontend) attached
+     */
+    static buildConfigurationError(customMessageReference, context) {
+        const instance = FrontendResourceUtils.getInstance();
+        const wildoError = instance.errorBuilder.buildWildoError_Frontend(ErrorType.CONFIGURATION, { customMessageReference, context });
+        const error = new Error(customMessageReference);
+        error.wildoError = wildoError;
+        return error;
+    }
+    // =============================================================================
+    // FOREIGN KEY + LABEL RESOLUTION HELPERS (STATIC)
+    // =============================================================================
+    /**
+     * Resolve the resource type that a foreign key field points to.
+     *
+     * Resolution chain:
+     * 1. Registry map: fieldIdentifierToResourceType (enriched from relationships)
+     * 2. THROW — unresolvable FK is a engine configuration error
+     *
+     * This method NEVER returns null. An unresolvable FK means the resource
+     * configuration is broken and must be fixed. Throwing here surfaces the issue
+     * immediately at the point of use, caught by React ErrorBoundary.
+     *
+     * @param fieldName - The field name in the schema (e.g., "assignedToUserId")
+     * @param fieldSchema - The Zod schema for this field (to read decorator metadata), or undefined
+     * @param registry - The resources registry (with enriched fieldIdentifierToResourceType)
+     */
+    static resolveResourceTypeForForeignKey(fieldName, _fieldSchema, registry) {
+        // 1. Registry lookup (enriched from relationships)
+        const fromRegistry = registry.fieldIdentifierToResourceType?.[fieldName];
+        if (fromRegistry)
+            return fromRegistry;
+        // 2. Not found — throw a proper WildoError. This is a configuration error, not a runtime edge case.
+        throw FrontendResourceUtils.buildConfigurationError(ErrorCustomMessageReference.FRONTEND_FK_RESOLUTION_FAILED, {
+            fieldName,
+            message: `Cannot resolve resource type for FK field "${fieldName}". ` +
+                `Ensure the relationship declares foreignKeyField: "${fieldName}".`,
+        });
+    }
+    /**
+     * Check if field identifier is a plural FK (ends with 'Ids').
+     */
+    static isPluralForeignKeyFieldIdentifier(fieldIdentifier) {
+        return fieldIdentifier.endsWith('Ids');
+    }
+    /**
+     * Get the resource field identifier for a resource type.
+     * Throws if the resource type has no configured field identifier — this is a configuration error.
+     */
+    static getResourceFieldIdentifierForType(resourceType, registry) {
+        const fieldId = registry.resourceConfigurations?.[resourceType]?.resourceFieldIdentifier ||
+            registry.allResourceFieldIdentifiers?.[resourceType];
+        if (!fieldId) {
+            throw FrontendResourceUtils.buildConfigurationError(ErrorCustomMessageReference.FRONTEND_RESOURCE_FIELD_IDENTIFIER_NOT_FOUND, {
+                resourceType,
+                message: `No field identifier for resource type "${resourceType}". ` +
+                    `The resource must be registered with a resourceFieldIdentifier.`,
+            });
+        }
+        return fieldId;
+    }
+    /**
+     * Build a stable parent→child edge identifier for frontend navigation/runtime consumers.
+     *
+     * Resource type alone is not enough when:
+     * - the same parent type appears multiple times in a chain
+     * - multiple edges exist between the same types
+     * - self-references need FK-based disambiguation
+     */
+    static buildRelationshipEdgeKey(params) {
+        return [
+            params.parentResourceType,
+            params.childResourceType,
+            params.foreignKeyField ?? '__default__',
+        ].join('::');
+    }
+    /**
+     * Build the ordered parent-edge chain for a target resource from route/initiator parameters.
+     *
+     * URL parameter arrays may include the target resource's own identifier
+     * (e.g. READ `/tasks/:taskId`). That self parameter is not part of the parent
+     * edge chain and must be excluded before identity comparison.
+     */
+    static buildOrderedRouteParameterEdgeKeys(routePathParameters, targetResourceType, targetDefaultFieldIdentifier) {
+        const parentParameters = routePathParameters.filter((param) => !(param.resourceType === targetResourceType &&
+            param.fieldIdentifier === targetDefaultFieldIdentifier));
+        return parentParameters.map((param, index) => this.buildRelationshipEdgeKey({
+            parentResourceType: param.resourceType,
+            childResourceType: parentParameters[index + 1]?.resourceType ?? targetResourceType,
+            foreignKeyField: param.relationshipField,
+        }));
+    }
+    /**
+     * Build the ordered parent-edge chain carried by `parentResourcesRequirements`.
+     *
+     * Older callers may not populate `childResourceType` / `relationshipEdgeKey`
+     * yet, so this helper derives them from chain order as a compatibility bridge.
+     */
+    static buildOrderedParentRequirementEdgeKeys(parentResourcesRequirements, targetResourceType) {
+        return parentResourcesRequirements.map((requirement, index) => requirement.relationshipEdgeKey ?? this.buildRelationshipEdgeKey({
+            parentResourceType: requirement.resourceType,
+            childResourceType: requirement.childResourceType
+                ?? parentResourcesRequirements[index + 1]?.resourceType
+                ?? targetResourceType,
+            foreignKeyField: requirement.foreignKeyField,
+        }));
+    }
+    /**
+     * Compare the current parent chain against a candidate route/initiator parameter chain.
+     *
+     * This preserves ordered edge identity instead of collapsing the chain to
+     * `resourceType -> foreignKeyField`, which loses meaning for repeated types.
+     */
+    static matchesParentRequirementEdgeChain(parentResourcesRequirements, routePathParameters, targetResourceType, targetDefaultFieldIdentifier) {
+        const requirementEdgeKeys = this.buildOrderedParentRequirementEdgeKeys(parentResourcesRequirements, targetResourceType);
+        const routeEdgeKeys = this.buildOrderedRouteParameterEdgeKeys(routePathParameters, targetResourceType, targetDefaultFieldIdentifier);
+        if (requirementEdgeKeys.length !== routeEdgeKeys.length) {
+            return false;
+        }
+        return requirementEdgeKeys.every((edgeKey, index) => edgeKey === routeEdgeKeys[index]);
+    }
+    /**
+     * Pick the default operation from config for a given operation identifier.
+     * Prefers API_CALL variants, defaults, and non-bulk operations.
+     */
+    static pickDefaultOperationFromConfig(registry, resourceType, operationIdentifier) {
+        const config = registry.resourceConfigurations?.[resourceType];
+        const ops = (config?.operations ?? []);
+        return pickPreferredOperationForCoreSemantic(ops, operationIdentifier) ?? null;
+    }
+    // =============================================================================
+    // CONTEXT BUILDING HELPERS (STATIC)
+    // =============================================================================
+    /**
+     * Convert contextResourceIdentifiers (semantic: ResourceType → id) to
+     * contextualParameters (physical: fieldIdentifier → id) for API calls.
+     *
+     * This is the canonical way to build contextualParameters from a resourceContext.
+     * Used by ResourceAutomatedForm, ResourceAutomaticDisplayer, List, Search, Header.
+     */
+    static buildContextualParameters(contextResourceIdentifiers, registry) {
+        const instance = FrontendResourceUtils.getInstance();
+        const params = {};
+        for (const [resType, value] of Object.entries(contextResourceIdentifiers)) {
+            const resourceId = instance.getResourceId(value);
+            const explicitFieldId = instance.getFieldIdentifier(value);
+            if (explicitFieldId) {
+                params[explicitFieldId] = resourceId;
+            }
+            else {
+                const config = registry.resourceConfigurations?.[resType];
+                if (config) {
+                    params[config.resourceFieldIdentifier] = resourceId;
+                }
+            }
+        }
+        return params;
+    }
+    /**
+     * Build a stable string key from contextResourceIdentifiers for memoization.
+     * Sorted to ensure order-independence.
+     */
+    static buildContextResourceIdentifiersKey(contextResourceIdentifiers) {
+        const instance = FrontendResourceUtils.getInstance();
+        return Object.entries(contextResourceIdentifiers)
+            .map(([resType, value]) => `${resType}:${instance.getResourceId(value)}`)
+            .sort()
+            .join('|');
+    }
+    /**
+     * Resolve parent-owned form fields from matched relationship semantics.
+     *
+     * The old schema-first approach hid any contextual parameter whose field name
+     * happened to exist in the form schema. That couples form affordances to route
+     * shape instead of the declared relationship contract. This helper keeps the
+     * decision on the relationship side:
+     * - match the current parent chain to parent-direction relationships
+     * - resolve the concrete FK identity through the shared helper
+     * - hide/inject only real child-FK fields owned by that relationship
+     *
+     * Association-managed peer edges are excluded on purpose: they should surface
+     * through explicit association/junction UX, not masquerade as child-owned FK
+     * fields in a regular resource form.
+     */
+    static resolveSemanticContextFieldValues(params) {
+        const parentResourcesRequirements = (params.parentResourcesRequirements && params.parentResourcesRequirements.length > 0)
+            ? params.parentResourcesRequirements
+            : (params.contextResourceIdentifiers
+                ? this.getInstance().buildParentResourcesRequirements(params.resourceType, params.contextResourceIdentifiers, params.registry)
+                : []);
+        if (parentResourcesRequirements.length === 0) {
+            return {};
+        }
+        const resourceConfig = params.registry.resourceConfigurations?.[params.resourceType];
+        if (!resourceConfig) {
+            return {};
+        }
+        const urlAddressableParentRelationships = ResourcesConfigOperationsUrlsBuilderUtils.getUrlAddressableParentRelationships(resourceConfig, params.registry.allResourceFieldIdentifiers);
+        if (urlAddressableParentRelationships.length === 0) {
+            return {};
+        }
+        const values = {};
+        for (const requirement of parentResourcesRequirements) {
+            const requirementChildResourceType = requirement.childResourceType ?? params.resourceType;
+            const requirementEdgeKey = requirement.relationshipEdgeKey
+                ?? this.buildRelationshipEdgeKey({
+                    parentResourceType: requirement.resourceType,
+                    childResourceType: requirementChildResourceType,
+                    foreignKeyField: requirement.foreignKeyField,
+                });
+            const relationship = urlAddressableParentRelationships.find((candidate) => {
+                if (candidate.resourceType1 !== requirement.resourceType) {
+                    return false;
+                }
+                const candidateEdgeKey = this.buildRelationshipEdgeKey({
+                    parentResourceType: candidate.resourceType1,
+                    childResourceType: requirementChildResourceType,
+                    foreignKeyField: candidate.foreignKeyField,
+                });
+                return candidateEdgeKey === requirementEdgeKey;
+            });
+            if (!relationship) {
+                continue;
+            }
+            let semantics;
+            try {
+                semantics = Resources_SharedUtils.getResolvedRelationshipSemantics(relationship);
+            }
+            catch (error) {
+                throw this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+                    resourceType: params.resourceType,
+                    parentResourceType: requirement.resourceType,
+                    childResourceType: requirementChildResourceType,
+                    foreignKeyField: relationship.foreignKeyField,
+                    reason: 'Failed to resolve relationship semantics while deriving semantic context field values.',
+                    originalError: error instanceof Error ? error.message : String(error),
+                });
+            }
+            if (semantics.handling.mutationModelMode === RelationshipMutationModel.ASSOCIATION_MANAGED) {
+                continue;
+            }
+            const fkIdentity = Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(relationship, params.registry.allResourceFieldIdentifiers);
+            if (!fkIdentity) {
+                continue;
+            }
+            const contextValue = params.contextualParameters[fkIdentity.fieldIdentifier];
+            if (contextValue !== undefined) {
+                values[fkIdentity.fieldIdentifier] = contextValue;
+            }
+        }
+        return values;
+    }
+    /**
+     * Resolve whether a top-level form field represents a relationship object slot
+     * from the current resource's perspective.
+     *
+     * This is the semantic bridge for generated/custom forms that see only a DTO
+     * field name like `tasks` or `owner`, but need to know whether that field is:
+     * - a plain JSON/object field, or
+     * - a relationship-owned nested object/collection field
+     *
+     * Step 6 currently uses this to fail closed for non-composition nested editing
+     * so `REFERENCE` / `ASSOCIATION` relationships do not regress to generic
+     * nested CRUD UI when a custom DTO accidentally exposes them.
+     */
+    static resolveRelationshipObjectFieldSemantics(params) {
+        const resourceConfig = params.registry.resourceConfigurations?.[params.resourceType];
+        if (!resourceConfig) {
+            return undefined;
+        }
+        const rootFieldName = params.fieldName.split('.')[0];
+        const relationshipBuckets = resourceConfig.resourceRelationships;
+        const candidateRelationships = [
+            ...relationshipBuckets.parentRelationships,
+            ...relationshipBuckets.childRelationships,
+            ...relationshipBuckets.selfRelationships,
+        ];
+        const matches = candidateRelationships.flatMap((relationship) => {
+            if (relationship.resourceType1 !== params.resourceType &&
+                relationship.resourceType2 !== params.resourceType) {
+                return [];
+            }
+            try {
+                const compiledRelationship = Resources_SharedUtils.ensureCompiledRelationship(relationship);
+                const objectIdentity = Resources_SharedUtils.resolveRelationshipObjectIdentityForResource(compiledRelationship, params.resourceType, params.registry.allResourceFieldIdentifiers);
+                if (objectIdentity.objectFieldName !== rootFieldName) {
+                    return [];
+                }
+                const semantics = Resources_SharedUtils.getResolvedRelationshipSemantics(compiledRelationship);
+                const relatedResourceType = compiledRelationship.resourceType1 === params.resourceType
+                    ? compiledRelationship.resourceType2
+                    : compiledRelationship.resourceType1;
+                const nestedMutationOperation = (params.operationType === CoreResourceOperation.CREATE ||
+                    params.operationType === CoreResourceOperation.CREATE_MANY ||
+                    params.operationType === CoreResourceOperation.UPDATE ||
+                    params.operationType === CoreResourceOperation.UPDATE_MANY)
+                    ? params.operationType
+                    : undefined;
+                return [{
+                        rootFieldName,
+                        relationship: compiledRelationship,
+                        semantics,
+                        allowedBulkActions: Resources_SharedUtils.resolveAllowedBulkRelationshipActionsForResource(compiledRelationship, params.resourceType),
+                        relatedResourceType,
+                        foreignKeyIdentity: Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(compiledRelationship, params.registry.allResourceFieldIdentifiers),
+                        nestedMutationConfig: nestedMutationOperation
+                            ? Resources_SharedUtils.resolveRelationshipNestedMutationConfig(compiledRelationship, nestedMutationOperation)
+                            : undefined,
+                    }];
+            }
+            catch (error) {
+                const configurationError = this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+                    resourceType: params.resourceType,
+                    fieldName: params.fieldName,
+                    rootFieldName,
+                    reason: 'Failed to resolve relationship-object field semantics for frontend form rendering.',
+                    originalError: error instanceof Error ? error.message : String(error),
+                });
+                if (envLoader.isDevelopment()) {
+                    throw configurationError;
+                }
+                return [];
+            }
+        });
+        if (matches.length <= 1) {
+            return matches[0];
+        }
+        const compositionMatches = matches.filter((match) => match.semantics.nature === RelationshipNature.COMPOSITION);
+        if (compositionMatches.length === 1) {
+            return compositionMatches[0];
+        }
+        const configurationError = this.buildConfigurationError(ErrorCustomMessageReference.CONFIGURATION, {
+            resourceType: params.resourceType,
+            fieldName: params.fieldName,
+            rootFieldName,
+            reason: 'Multiple relationships resolve to the same relationship-object field identity in frontend form semantics.',
+            candidateCount: matches.length,
+        });
+        if (envLoader.isDevelopment()) {
+            throw configurationError;
+        }
+        return undefined;
+    }
+    /**
+     * Build operation path key for FK READ operation.
+     * Uses ResourcesConfig_OperationPathUtils to create proper operation path keys.
+     */
+    static resolveSingleResourceReadOperation(resourceType, registry, preferredOperation) {
+        if (preferredOperation
+            && !preferredOperation.isBulkOperation
+            && resolveEffectiveCoreOperationFromOperation(preferredOperation) === CoreResourceOperation.READ) {
+            return preferredOperation;
+        }
+        return FrontendResourceUtils.pickDefaultOperationFromConfig(registry, resourceType, CoreResourceOperation.READ);
+    }
+    /**
+     * Build operation path key for FK READ operation.
+     * Uses the preferred mounted read-like operation when one is provided,
+     * otherwise falls back to the resource's preferred read semantic.
+     */
+    static buildForeignKeyReadOperationPath(resourceType, registry, preferredOperation) {
+        const operation = FrontendResourceUtils.resolveSingleResourceReadOperation(resourceType, registry, preferredOperation);
+        if (!operation) {
+            // Last resort: try to build a key anyway (will likely throw downstream).
+            return ResourcesConfig_OperationPathUtils.createOperationPathKey({
+                resourceIdentifier: resourceType,
+                operationIdentifier: CoreResourceOperation.READ,
+                variantType: ResourceOperationVariantType.API_CALL,
+                isOperationDefault: true,
+                isBulkOperation: false,
+            });
+        }
+        return ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation);
+    }
+    /**
+     * Build operation path key for FK SEARCH/LIST operation.
+     * Prefers SEARCH if available, falls back to LIST.
+     */
+    static buildForeignKeySearchOperationPath(resourceType, registry) {
+        const searchOp = FrontendResourceUtils.pickDefaultOperationFromConfig(registry, resourceType, CoreResourceOperation.SEARCH);
+        if (searchOp) {
+            return ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(searchOp);
+        }
+        const listOp = FrontendResourceUtils.pickDefaultOperationFromConfig(registry, resourceType, CoreResourceOperation.LIST);
+        if (listOp) {
+            return ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(listOp);
+        }
+        // Last resort fallback.
+        return ResourcesConfig_OperationPathUtils.createOperationPathKey({
+            resourceIdentifier: resourceType,
+            operationIdentifier: CoreResourceOperation.LIST,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+            isBulkOperation: false,
+        });
+    }
+    /**
+     * Build contextual parameters for fetching a single FK resource.
+     */
+    static buildForeignKeyFetchParams(resourceType, resourceId, registry) {
+        const fieldIdentifier = FrontendResourceUtils.getResourceFieldIdentifierForType(resourceType, registry);
+        return { contextualParameters: { [fieldIdentifier]: resourceId } };
+    }
+    /**
+     * Build query parameters for FK search/list operation.
+     */
+    static buildForeignKeySearchParams(query, limit = 10) {
+        const params = { limit };
+        if (query && query.trim().length > 0) {
+            params.q = query.trim();
+        }
+        return { queryParameters: params };
+    }
+    /**
+     * Compute a resource label using the canonical resource configuration contract:
+     * `resourceConfig.frontendConfiguration.getFrontendResourceLabel`.
+     *
+     * - If config label is a `string[]`, we join non-empty values with a space.
+     * - If config label is a function, we call it with `t` and (optional) context.
+     * - If anything fails, we fall back to common fields (`name`, `title`, `_id`, ...).
+     */
+    static computeFrontendResourceLabel(params) {
+        const { resourceType, registry, currentObject } = params;
+        if (!currentObject || typeof currentObject !== 'object')
+            return null;
+        const obj = currentObject;
+        const config = registry.resourceConfigurations?.[resourceType];
+        const labelDef = config?.frontendConfiguration?.getFrontendResourceLabel;
+        const t = params.t ??
+            ((toTranslate) => toTranslate);
+        try {
+            if (Array.isArray(labelDef)) {
+                const parts = labelDef
+                    .map((field) => obj[field])
+                    .filter((v) => v !== undefined && v !== null)
+                    .map((v) => (typeof v === 'string' ? v.trim() : String(v)))
+                    .filter((v) => v.length > 0);
+                if (parts.length > 0)
+                    return parts.join(' ');
+            }
+            if (typeof labelDef === 'function') {
+                const label = labelDef({
+                    currentObject: currentObject,
+                    objectContext: params.objectContext ?? {},
+                    initiatorUserContext: params.initiatorUserContext,
+                    t,
+                });
+                if (typeof label === 'string' && label.trim().length > 0)
+                    return label;
+            }
+        }
+        catch {
+            // ignore and fall back
+        }
+        // No config-defined label strategy — flag as configuration gap
+        console.error(`[FrontendResourceUtils] No getFrontendResourceLabel configured for "${resourceType}". ` +
+            `Add getFrontendResourceLabel to frontendConfiguration.`);
+        // Minimal fallback: use the resource field identifier to extract a usable label.
+        // Wrapped in try/catch because getResourceFieldIdentifierForType throws for unconfigured
+        // resources, and label computation must not crash the page.
+        try {
+            const fieldId = FrontendResourceUtils.getResourceFieldIdentifierForType(resourceType, registry);
+            const v = obj[fieldId];
+            if (v !== undefined && v !== null)
+                return String(v);
+        }
+        catch {
+            // Resource type not in registry — try common identifier fields as last resort
+            const lastResortId = obj['_id'] ?? obj['id'];
+            if (lastResortId !== undefined && lastResortId !== null)
+                return String(lastResortId);
+        }
+        return null;
+    }
+    /**
+     * Build a WildoError for frontend resource configuration errors (instance method).
+     * Uses ErrorType.CONFIGURATION — missing route paths, missing callbacks, etc.
+     * are configuration errors that should be caught and surfaced clearly.
+     */
+    buildError(customMessageReference, context) {
+        const wildoError = this.errorBuilder.buildWildoError_Frontend(ErrorType.CONFIGURATION, { customMessageReference, context });
+        const error = new Error(customMessageReference);
+        error.wildoError = wildoError;
+        return error;
+    }
+    /**
+     * Helper function to extract the primary resource identifier from contextResourceIdentifiers
+     * The primary resource is the one matching the resourceType
+     */
+    getPrimaryResourceIdentifier(ctx) {
+        const contextValue = ctx.contextResourceIdentifiers[ctx.resourceType];
+        if (typeof contextValue === 'string') {
+            return contextValue;
+        }
+        else if (contextValue && typeof contextValue === 'object' && contextValue.resourceId) {
+            return contextValue.resourceId;
+        }
+        return null;
+    }
+    /**
+     * Helper function to extract resource ID from a contextResourceIdentifiers value
+     * Handles both string and object formats
+     */
+    getResourceId(value) {
+        if (!value) {
+            return '';
+        }
+        if (typeof value === 'string') {
+            return value;
+        }
+        else {
+            return value.resourceId || '';
+        }
+    }
+    /**
+     * Helper function to get field identifier from a contextResourceIdentifiers value
+     * Returns the fieldIdentifier for complex objects, null for simple strings (default field)
+     */
+    getFieldIdentifier(value) {
+        if (!value) {
+            return null;
+        }
+        return typeof value === 'string' ? null : (value.fieldIdentifier || null);
+    }
+    /**
+     * Flatten contextResourceIdentifiers to simple string values.
+     * Handles both string and object formats ({ fieldIdentifier, resourceId }).
+     * Used by notification/celebration nextStep to pass identifiers to the navigation system.
+     */
+    static flattenContextIdentifiers(identifiers) {
+        const instance = FrontendResourceUtils.getInstance();
+        const flat = {};
+        for (const [key, value] of Object.entries(identifiers)) {
+            const id = instance.getResourceId(value);
+            if (id)
+                flat[key] = id;
+        }
+        return flat;
+    }
+    /**
+     * Create a reverse mapping from resourceFieldIdentifier to resourceIdentifier
+     * This allows us to look up which resource type a field identifier belongs to
+     */
+    buildResourceFieldIdentifierToResourceIdentifierMap(registry) {
+        const fieldToResourceMap = {};
+        Object.entries(registry.resourceConfigurations).forEach(([resourceIdentifier, config]) => {
+            const resourceConfig = config;
+            const fieldIdentifier = resourceConfig.resourceFieldIdentifier;
+            fieldToResourceMap[fieldIdentifier] = resourceIdentifier;
+        });
+        return fieldToResourceMap;
+    }
+    /**
+     * Convert URL parameters to the `contextResourceIdentifiers` map consumed by the
+     * rest of the frontend resource system (context building, API calls, breadcrumb, etc.).
+     *
+     * ## Key mapping rules
+     *
+     * | Param type | Map key | Map value |
+     * |------------|---------|-----------|
+     * | Default field (e.g., `unitId`) | Resource type (`ORGANIZATION_UNITS`) | Simple string (`"abc"`) |
+     * | FK field, non-self-ref (e.g., `assignedToUserId`) | Resource type of the FK target (`USERS`) | Complex `{ fieldIdentifier, resourceId }` |
+     * | FK field, self-ref (e.g., `parentUnitId` for ORG_UNITS→ORG_UNITS) | FK field name (`"parentUnitId"`) | Complex `{ fieldIdentifier, resourceId }` |
+     *
+     * ## Self-referencing relationship handling (F-12-A)
+     *
+     * `contextResourceIdentifiers` is `Record<string, ...>` — resource type as key.
+     * For self-referencing trees (e.g., ORGANIZATION_UNITS), both parent and child
+     * share the same resource type, so the second entry would overwrite the first.
+     *
+     * Solution: when a resource type appears multiple times in routePathParameters
+     * (detected via `typeCount`), the **non-default** FK param (e.g., `parentUnitId`)
+     * uses the **FK field name** as the map key instead of the resource type.
+     * `buildContextualParameters` already handles complex values via `fieldIdentifier`,
+     * so the correct URL parameter (`parentUnitId=abc`) is produced without any
+     * changes to downstream callers.
+     *
+     * @param urlParameters - The URL parameters from React Router
+     * @param registry - The resources registry
+     * @param routePathParameters - Route path parameters for accurate FK field mapping
+     */
+    extractResourceIdentifiersFromUrlParams(urlParameters, registry, routePathParameters) {
+        const resourceIdentifiers = {};
+        // If routePathParameters provided, use them for accurate mapping
+        // This handles FK fields like assignedToUserId correctly
+        if (routePathParameters && routePathParameters.length > 0) {
+            // Detect resource types that appear multiple times (self-referencing relationships)
+            const typeCount = new Map();
+            for (const p of routePathParameters) {
+                typeCount.set(p.resourceType, (typeCount.get(p.resourceType) || 0) + 1);
+            }
+            for (const paramInfo of routePathParameters) {
+                const paramValue = urlParameters[paramInfo.fieldIdentifier];
+                if (paramValue !== undefined) {
+                    const resourceConfig = registry.resourceConfigurations[paramInfo.resourceType];
+                    const isDefaultField = resourceConfig &&
+                        resourceConfig.resourceFieldIdentifier === paramInfo.fieldIdentifier;
+                    const isSelfRefType = (typeCount.get(paramInfo.resourceType) || 0) > 1;
+                    if (isDefaultField) {
+                        resourceIdentifiers[paramInfo.resourceType] = paramValue;
+                    }
+                    else if (isSelfRefType) {
+                        // Self-ref FK field (e.g., parentUnitId for ORGANIZATION_UNITS → ORGANIZATION_UNITS).
+                        // Use the FK field name as the map key to avoid overwriting the resource's own entry.
+                        // buildContextualParameters handles this via the complex value's fieldIdentifier.
+                        resourceIdentifiers[paramInfo.fieldIdentifier] = {
+                            fieldIdentifier: paramInfo.fieldIdentifier,
+                            resourceId: paramValue
+                        };
+                    }
+                    else {
+                        resourceIdentifiers[paramInfo.resourceType] = {
+                            fieldIdentifier: paramInfo.fieldIdentifier,
+                            resourceId: paramValue
+                        };
+                    }
+                }
+            }
+            return resourceIdentifiers;
+        }
+        // Fallback: use registry-based mapping for backwards compatibility
+        const fieldToResourceMap = this.buildResourceFieldIdentifierToResourceIdentifierMap(registry);
+        for (const [paramName, paramValue] of Object.entries(urlParameters)) {
+            // Look up the resource identifier using the registry mapping
+            if (fieldToResourceMap[paramName]) {
+                const resourceIdentifier = fieldToResourceMap[paramName];
+                // Check if this is the default field identifier for this resource type
+                const resourceConfig = registry.resourceConfigurations[resourceIdentifier];
+                if (resourceConfig && resourceConfig.resourceFieldIdentifier === paramName) {
+                    // Default field - use simple string format
+                    resourceIdentifiers[resourceIdentifier] = paramValue;
+                }
+                else {
+                    // Custom field - use complex object format
+                    resourceIdentifiers[resourceIdentifier] = {
+                        fieldIdentifier: paramName,
+                        resourceId: paramValue
+                    };
+                }
+            }
+        }
+        return resourceIdentifiers;
+    }
+    /**
+     * Create FrontendResourceOperationContext from resource identifiers and operation
+     * URL parameters should be converted to contextResourceIdentifiers at router level
+     */
+    createFrontendResourceOperationContext(params) {
+        const operationDefaults = params.operation ?? {};
+        return {
+            operationIdentifier: params.operationIdentifier,
+            isOperationDefault: params.isOperationDefault ?? operationDefaults.isOperationDefault ?? false,
+            isBulkOperation: params.isBulkOperation ?? operationDefaults.isBulkOperation ?? false,
+            variantKey: params.variantKey ?? operationDefaults.variantKey,
+            resourceType: params.resourceType,
+            parentResourcesRequirements: params.parentResourcesRequirements ?? [],
+            operation: params.operation,
+            contextResourceIdentifiers: params.contextResourceIdentifiers,
+            additionalContext: params.additionalContext || {}
+        };
+    }
+    /**
+     * Create FrontendResourceOperationPath from parameters
+     */
+    createFrontendResourceOperationPath(params) {
+        let isDefault = false;
+        if (!!params.isOperationDefault) {
+            isDefault = params.isOperationDefault;
+        }
+        else if (!!params.variantKey && params.variantKey !== '') {
+            isDefault = true;
+        }
+        else {
+            isDefault = false;
+        }
+        return {
+            resourceType: params.resourceType,
+            parentResourcesRequirements: params.parentResourcesRequirements ?? [],
+            operationIdentifier: params.operationIdentifier,
+            isOperationDefault: isDefault,
+            isBulkOperation: params.isBulkOperation ?? false,
+            variantKey: params.variantKey ?? undefined
+        };
+    }
+    /**
+     * Create a frontend resource context while preserving the actual configured
+     * operation identifier from the provided operation object.
+     */
+    createFrontendResourceOperationContextFromOperation(params) {
+        return this.createFrontendResourceOperationContext({
+            operationIdentifier: String(params.operation.operationIdentifier),
+            resourceType: params.resourceType,
+            operation: params.operation,
+            contextResourceIdentifiers: params.contextResourceIdentifiers,
+            additionalContext: params.additionalContext,
+            isOperationDefault: params.isOperationDefault ?? params.operation.isOperationDefault,
+            isBulkOperation: params.isBulkOperation ?? params.operation.isBulkOperation,
+            variantKey: params.variantKey ?? params.operation.variantKey,
+            parentResourcesRequirements: params.parentResourcesRequirements,
+        });
+    }
+    /**
+     * Create FrontendResourceOperationContext with path information included
+     */
+    createFrontendResourceOperationContextWithPath(params) {
+        return {
+            ...this.createFrontendResourceOperationPath({
+                resourceType: params.resourceType,
+                operationIdentifier: params.operationIdentifier,
+                isOperationDefault: params.isOperationDefault,
+                isBulkOperation: params.isBulkOperation,
+                variantKey: params.variantKey,
+                parentResourcesRequirements: params.parentResourcesRequirements
+            }),
+            resourceType: params.resourceType,
+            operation: params.operation,
+            contextResourceIdentifiers: params.contextResourceIdentifiers,
+            additionalContext: params.additionalContext || {}
+        };
+    }
+    // ============================================================================
+    // PARENT RESOURCE REQUIREMENTS HELPERS
+    // ============================================================================
+    /**
+     * Build `parentResourcesRequirements` from route path parameters.
+     * Used at route-match time (AppRouter) to determine which parent resources
+     * are required by the current resource and derive their metadata.
+     *
+     * ## Self-referencing relationship handling (F-12-A)
+     *
+     * Uses `getParentDirectionRelationships()` instead of raw `parentRelationships`
+     * so that self-referencing relationships (stored in `selfRelationships` bucket)
+     * are included in the lookup.
+     *
+     * The filter no longer blanket-excludes all same-type params. Instead it only
+     * excludes the resource's **own default field** (e.g., `unitId`). FK params for
+     * the same resource type (e.g., `parentUnitId` for a tree parent) are kept,
+     * producing a proper parent requirement for the self-ref edge.
+     *
+     * @param routePathParameters - Parameters from the matched route path
+     * @param resourceType - The target resource type
+     * @param registry - The frontend resources registry
+     */
+    buildParentResourcesRequirementsFromRouteParams(routePathParameters, resourceType, registry) {
+        const resourceConfig = registry.resourceConfigurations[resourceType];
+        if (!resourceConfig)
+            return [];
+        const parentDirectionRelationships = getParentDirectionRelationships(resourceConfig.resourceRelationships);
+        const defaultFieldIdentifier = resourceConfig.resourceFieldIdentifier;
+        const parentParameters = routePathParameters
+            .filter(param => {
+            // For self-ref: keep FK params (e.g., parentUnitId) but exclude the resource's own field (e.g., unitId)
+            if (param.resourceType === resourceType) {
+                return param.fieldIdentifier !== defaultFieldIdentifier;
+            }
+            return true;
+        });
+        return parentParameters.map((param, index) => {
+            const relationship = parentDirectionRelationships.find(rel => rel.resourceType1 === param.resourceType &&
+                (Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, registry.allResourceFieldIdentifiers)?.fieldIdentifier ?? undefined) === (param.relationshipField ?? undefined));
+            // Route params are already ordered root → leaf, so the "child" side of a
+            // parent edge is simply the next parent param in the chain, or the target
+            // resource when this is the last parent segment.
+            const childResourceType = parentParameters[index + 1]?.resourceType ?? resourceType;
+            return {
+                resourceType: param.resourceType,
+                foreignKeyField: param.relationshipField,
+                childResourceType,
+                relationshipEdgeKey: FrontendResourceUtils.buildRelationshipEdgeKey({
+                    parentResourceType: param.resourceType,
+                    childResourceType,
+                    foreignKeyField: param.relationshipField,
+                }),
+                requirement: relationship?.parentResourceRequirement ?? ResourceParentResourceRequirement.MANDATORY,
+                isPrimaryScope: relationship?.isPrimaryScope ?? false,
+                primaryScope: relationship?.primaryScope,
+            };
+        });
+    }
+    /**
+     * Build `parentResourcesRequirements` from the available context identifiers.
+     * Used by `deriveChildResourceContext` to compute parent requirements for a
+     * child resource based on what parent IDs are currently in context.
+     *
+     * ## Key resolution logic
+     *
+     * Each entry in `contextResourceIdentifiers` has a **key** and a **value**:
+     *
+     * - **Resource-type key** (e.g., `"USERS"`): standard case. The key IS the
+     *   parent resource type. Looked up directly in the URL-addressable parent set.
+     *
+     * - **FK-field key** (e.g., `"parentUnitId"`): self-ref parent case (F-12-A).
+     *   The key is NOT a resource type — it's a FK field name stored by
+     *   `extractResourceIdentifiersFromUrlParams` or `deriveChildResourceContext`
+     *   to avoid key collision with the resource's own entry.
+     *   Resolved via `registry.fieldIdentifierToResourceType` → resource type,
+     *   then matched against the URL-addressable parent set.
+     *
+     * ## Disambiguation
+     *
+     * When multiple relationships exist for the same parent type:
+     * 1. FK field override from self-ref resolution or explicit `relationshipFieldOverrides`
+     * 2. Primary scope relationships first
+     * 3. Default relationships (no foreignKeyField) next
+     * 4. Alphabetical by foreignKeyField as tiebreaker
+     *
+     * @param resourceType - The target resource type
+     * @param contextResourceIdentifiers - Available parent IDs (resource-type or FK-field keyed)
+     * @param registry - The frontend resources registry
+     * @param relationshipFieldOverrides - Optional overrides for FK disambiguation
+     */
+    buildParentResourcesRequirements(resourceType, contextResourceIdentifiers, registry, relationshipFieldOverrides) {
+        const resourceConfig = registry.resourceConfigurations[resourceType];
+        if (!resourceConfig)
+            return [];
+        const parentDirectionRelationships = getParentDirectionRelationships(resourceConfig.resourceRelationships);
+        const urlAddressableParentRelationships = ResourcesConfigOperationsUrlsBuilderUtils.getUrlAddressableParentRelationships(resourceConfig, registry.allResourceFieldIdentifiers);
+        const requirements = [];
+        for (const [key, value] of Object.entries(contextResourceIdentifiers)) {
+            if (key === resourceType)
+                continue;
+            // Resolve the parent resource type: either the key IS a resource type,
+            // or it's a FK field name (self-ref parent) resolvable via the FK map.
+            let parentType;
+            let fkFieldOverride;
+            const explicitFieldId = this.getFieldIdentifier(value);
+            if (registry.resourceConfigurations[key]) {
+                parentType = key;
+                fkFieldOverride = explicitFieldId;
+            }
+            else {
+                if (!explicitFieldId)
+                    continue;
+                const resolved = registry.fieldIdentifierToResourceType?.[explicitFieldId];
+                if (!resolved)
+                    continue;
+                parentType = resolved;
+                fkFieldOverride = explicitFieldId;
+            }
+            const baseRelationshipPool = fkFieldOverride
+                ? urlAddressableParentRelationships
+                : parentDirectionRelationships;
+            const matchingRelationships = baseRelationshipPool.filter(rel => rel.resourceType1 === parentType);
+            if (matchingRelationships.length === 0)
+                continue;
+            const overrideField = fkFieldOverride || relationshipFieldOverrides?.[parentType];
+            let selectedRelationship;
+            if (overrideField) {
+                const overrideMatch = matchingRelationships.find(rel => {
+                    const resolvedIdentity = Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, registry.allResourceFieldIdentifiers);
+                    return resolvedIdentity?.fieldIdentifier === overrideField;
+                });
+                selectedRelationship = overrideMatch ?? matchingRelationships[0];
+            }
+            else if (matchingRelationships.length === 1) {
+                selectedRelationship = matchingRelationships[0];
+            }
+            else {
+                const sorted = [...matchingRelationships].sort((a, b) => {
+                    if (a.isPrimaryScope !== b.isPrimaryScope) {
+                        return a.isPrimaryScope ? -1 : 1;
+                    }
+                    const aHasFK = !!a.foreignKeyField;
+                    const bHasFK = !!b.foreignKeyField;
+                    if (aHasFK !== bHasFK) {
+                        return aHasFK ? 1 : -1;
+                    }
+                    const aField = a.foreignKeyField || '';
+                    const bField = b.foreignKeyField || '';
+                    return aField.localeCompare(bField);
+                });
+                selectedRelationship = sorted[0];
+            }
+            requirements.push({
+                resourceType: parentType,
+                foreignKeyField: selectedRelationship.foreignKeyField,
+                childResourceType: resourceType,
+                relationshipEdgeKey: FrontendResourceUtils.buildRelationshipEdgeKey({
+                    parentResourceType: parentType,
+                    childResourceType: resourceType,
+                    foreignKeyField: selectedRelationship.foreignKeyField,
+                }),
+                requirement: selectedRelationship.parentResourceRequirement,
+                isPrimaryScope: selectedRelationship.isPrimaryScope || false,
+                primaryScope: selectedRelationship.primaryScope,
+            });
+        }
+        return requirements;
+    }
+    /**
+     * Select the matching route path from available paths based on context.
+     * Uses the same deterministic algorithm as the HTTP client URL selection.
+     *
+     * @param routePaths - Available route paths for the operation
+     * @param contextResourceIdentifiers - Available parent IDs
+     * @param currentParentRequirements - Current parent requirements (for FK disambiguation)
+     */
+    selectMatchingRoutePath(routePaths, contextResourceIdentifiers, targetResourceType, targetDefaultFieldIdentifier, currentParentRequirements) {
+        if (routePaths.length === 0) {
+            throw this.buildError(ErrorCustomMessageReference.FRONTEND_RESOURCE_NO_ROUTE_PATHS_AVAILABLE, { reason: 'No route paths available for this operation' });
+        }
+        if (routePaths.length === 1) {
+            return routePaths[0];
+        }
+        // Filter: paths where all parameters can be satisfied
+        const validPaths = routePaths.filter((path) => path.parameters.every((param) => {
+            const exactValue = contextResourceIdentifiers[param.fieldIdentifier];
+            if (this.getResourceId(exactValue) !== '') {
+                return true;
+            }
+            // Only default parent segments may fall back to the broad resource-type
+            // slot. FK-disambiguated segments must be satisfied by their exact field key,
+            // otherwise `/users/:userId/...` and `/users/:assignedToUserId/...` would
+            // collapse back into the same route candidate.
+            if (!param.relationshipField) {
+                const fallbackValue = contextResourceIdentifiers[param.resourceType];
+                return this.getResourceId(fallbackValue) !== '';
+            }
+            return false;
+        }));
+        if (validPaths.length === 0) {
+            // Fallback to first path
+            return routePaths[0];
+        }
+        // Filter by ordered edge identity if requirements are specified.
+        // This keeps route selection aligned with HTTP initiator selection and
+        // avoids collapsing repeated parent types into a resourceType-keyed map.
+        let candidates = validPaths;
+        if (currentParentRequirements && currentParentRequirements.length > 0) {
+            const matchedByEdgeIdentity = validPaths.filter((path) => FrontendResourceUtils.matchesParentRequirementEdgeChain(currentParentRequirements, path.parameters, targetResourceType, targetDefaultFieldIdentifier));
+            if (matchedByEdgeIdentity.length > 0) {
+                candidates = matchedByEdgeIdentity;
+            }
+        }
+        // Sort deterministically (same as HTTP client)
+        candidates.sort((a, b) => {
+            // Most specific first
+            if (b.parameters.length !== a.parameters.length) {
+                return b.parameters.length - a.parameters.length;
+            }
+            // Prefer default relationships
+            const aDefaultCount = a.parameters.filter(p => !p.relationshipField).length;
+            const bDefaultCount = b.parameters.filter(p => !p.relationshipField).length;
+            if (bDefaultCount !== aDefaultCount) {
+                return bDefaultCount - aDefaultCount;
+            }
+            // Alphabetical by URL
+            return a.url.localeCompare(b.url);
+        });
+        return candidates[0];
+    }
+    /**
+     * Extract dataMode from URL query parameters.
+     * Supports both uppercase (RAW, SUMMARY, CONTEXT) and lowercase (raw, summary, context) values.
+     *
+     * @param searchParams - URL search params (from useSearchParams() or URLSearchParams)
+     * @param propDataMode - Optional dataMode from component prop (takes priority)
+     * @param defaultDataMode - Optional default dataMode if not found in query params
+     * @returns DataMode or undefined
+     */
+    extractDataMode(searchParams, propDataMode, defaultDataMode) {
+        const queryValue = searchParams.get('dataMode');
+        return ResourceOperationsUtils.extractDataMode(queryValue, propDataMode, defaultDataMode);
+    }
+    /**
+     * Derive a child resource context from its parent's context.
+     *
+     * Merges the parent's `contextResourceIdentifiers` with the child's own ID,
+     * re-computes `parentResourcesRequirements` for the child, and preserves
+     * FK field overrides from the parent so that deterministic API endpoint
+     * selection works down the hierarchy.
+     *
+     * ## Self-referencing tree handling (F-12-A)
+     *
+     * When the child resource type matches an existing entry in context (tree
+     * navigation, e.g., parent unit → child unit), the parent's ID would be
+     * overwritten by the child. To prevent loss:
+     *
+     * 1. Before overwriting, check if `selfRelationships` declares a FK field
+     *    (e.g., `parentUnitId` for ORGANIZATION_UNITS).
+     * 2. If yes, move the parent's ID to a FK-keyed slot
+     *    (`contextResourceIdentifiers["parentUnitId"] = { fieldIdentifier, resourceId }`).
+     * 3. Then write the child's ID under the resource type key.
+     *
+     * Downstream, `buildContextualParameters` produces both URL parameters
+     * (`unitId=child` + `parentUnitId=parent`) from this structure.
+     *
+     * @param parentContext - The parent resource operation context
+     * @param childConfig - Configuration for the child context
+     * @param registry - The frontend resources registry
+     */
+    deriveChildResourceContext(parentContext, childConfig, registry) {
+        const resourceConfig = registry.resourceConfigurations[childConfig.resourceType];
+        const operation = resourceConfig?.operations?.find((op) => op.operationIdentifier === childConfig.operationIdentifier);
+        // Build new contextResourceIdentifiers
+        const contextResourceIdentifiers = {
+            ...parentContext.contextResourceIdentifiers,
+        };
+        // Self-ref handling: when the child resource type already has an entry (the parent in a tree),
+        // promote the parent ID into a FK-keyed slot so same-type parent chains stay explicit.
+        if (contextResourceIdentifiers[childConfig.resourceType] !== undefined) {
+            const selfRefs = resourceConfig?.resourceRelationships?.selfRelationships;
+            const selfRelationshipOverride = childConfig.relationshipFieldOverrides?.[childConfig.resourceType]
+                ?? [...(parentContext.parentResourcesRequirements ?? [])]
+                    .reverse()
+                    .find((requirement) => requirement.resourceType === childConfig.resourceType &&
+                    requirement.foreignKeyField)?.foreignKeyField;
+            const selfRefRel = selfRelationshipOverride
+                ? selfRefs?.find((rel) => Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, registry.allResourceFieldIdentifiers)?.fieldIdentifier === selfRelationshipOverride)
+                : selfRefs?.find((rel) => Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, registry.allResourceFieldIdentifiers) !== undefined);
+            const selfRefForeignKey = selfRefRel
+                ? Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(selfRefRel, registry.allResourceFieldIdentifiers)?.fieldIdentifier
+                : undefined;
+            if (selfRefForeignKey) {
+                const parentId = this.getResourceId(contextResourceIdentifiers[childConfig.resourceType]);
+                if (parentId) {
+                    // This keeps the existing same-type parent explicit even before the child
+                    // gets its own id. Without this promotion, a tree edge like
+                    // `organizationUnits -> organizationUnits via parentUnitId` would collapse
+                    // into a single `organizationUnits` slot and lose which side is parent.
+                    contextResourceIdentifiers[selfRefForeignKey] = {
+                        fieldIdentifier: selfRefForeignKey,
+                        resourceId: parentId,
+                    };
+                }
+            }
+        }
+        if (childConfig.resourceId) {
+            contextResourceIdentifiers[childConfig.resourceType] = childConfig.resourceId;
+        }
+        // Extract foreign key field overrides from parent context's parentResourcesRequirements
+        // This preserves the specific FK path from the parent (e.g., if parent was accessed
+        // via /assigned-to-users/{assignedToUserId}/..., the child should inherit that relationship)
+        const inheritedOverrides = {};
+        if (parentContext.parentResourcesRequirements) {
+            for (const req of parentContext.parentResourcesRequirements) {
+                if (req.foreignKeyField) {
+                    inheritedOverrides[req.resourceType] = req.foreignKeyField;
+                }
+            }
+        }
+        // Merge inherited overrides with explicit overrides (explicit takes precedence)
+        const mergedOverrides = {
+            ...inheritedOverrides,
+            ...childConfig.relationshipFieldOverrides
+        };
+        // Build parentResourcesRequirements based on context with merged overrides
+        const parentResourcesRequirements = this.buildParentResourcesRequirements(childConfig.resourceType, contextResourceIdentifiers, registry, Object.keys(mergedOverrides).length > 0 ? mergedOverrides : undefined);
+        return {
+            resourceType: childConfig.resourceType,
+            operationIdentifier: String(childConfig.operationIdentifier),
+            operation,
+            isOperationDefault: true,
+            isBulkOperation: false,
+            parentResourcesRequirements,
+            contextResourceIdentifiers,
+            additionalContext: {
+                ...parentContext.additionalContext,
+                ...childConfig.additionalContext
+            }
+        };
+    }
+}
+// Export singleton instance for easy access
+export const frontendResourceUtils = FrontendResourceUtils.getInstance();
+//# sourceMappingURL=frontend-resource.utils.js.map