@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/navigation/navigation.utils.js

@@ -0,0 +1,993 @@
+/**
+ * Navigation Utilities
+ *
+ * Shared utility functions for the navigation system.
+ * Centralized to avoid duplication across navigation modules.
+ */
+import { CascadeDirection, CoreResourceOperation, coreResourceShared_FieldIdentifier, NavigationZoneName, ParentDisplay, ResourcesConfigOperationsUrlsBuilderUtils, ResourceRelationshipCardinality, Resources_SharedUtils, } from '@wildo-ai/saas-models';
+import { frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
+import { pickPreferredOperationForCoreSemantic, resolveEffectiveCoreOperationFromOperation, } from '../../core/resources/operation-semantics.frontend.utils.js';
+import { NavigationZone, APP_LEVEL_NAVIGATION_SOURCE, NavigationContentType, isCustomComponentNavigationItem, isViewNavigationItem, } from './navigation.schemas.js';
+import { LoggerFrontendService } from '../../core/monitoring/logger.frontend.service.js';
+const logger = LoggerFrontendService.getLogger();
+const logDebug = logger.debugByType('NavigationUtils');
+logger.setDebugTypeLogging('NavigationUtils', false);
+/**
+ * Navigation utility class with static methods for navigation operations
+ */
+export class NavigationUtils {
+    static resolveContextIdentifierValue(resourceContext, contextKey) {
+        const rawValue = resourceContext.contextResourceIdentifiers?.[contextKey];
+        if (typeof rawValue === 'string') {
+            return rawValue;
+        }
+        if (rawValue && typeof rawValue === 'object') {
+            const nestedId = rawValue.resourceId;
+            return typeof nestedId === 'string' ? nestedId : undefined;
+        }
+        return undefined;
+    }
+    // ================================
+    // Navigation Transaction
+    // ================================
+    //
+    // A navigation transaction wraps multi-step operations (e.g., home click,
+    // org switch, cascading) that must be treated as atomic.  While a transaction
+    // is active, useRouterSync is suppressed to prevent the Outlet from
+    // re-populating the PRIMARY stack with stale content during React Router's
+    // startTransition-based route change.
+    //
+    // Usage:
+    //   NavigationUtils.beginTransaction('home_navigation');
+    //   emit(NAVIGATION_CLEAR_ZONE, { zone: PRIMARY });
+    //   routerNavigate('/');
+    //   NavigationUtils.commitTransaction();   // or let it auto-commit
+    //
+    // Auto-commit: If commitTransaction() is not called explicitly, the
+    // transaction auto-commits after the current event loop iteration via
+    // setTimeout(0).  This ensures the transaction covers all synchronous code
+    // AND React's batched state updates and effects, but doesn't leak into
+    // future render cycles.
+    //
+    // Safety net: A hard timeout (5s) auto-commits with a warning if the
+    // caller forgets.  This prevents permanent router sync suppression.
+    //
+    // Lives on NavigationUtils (static) to avoid circular dependencies between
+    // NavigationContext and useNavigationController.
+    static _transactionActive = false;
+    static _transactionSource = null;
+    static _transactionAutoCommitTimer = null;
+    static _transactionSafetyTimer = null;
+    /**
+     * Begin a navigation transaction.
+     *
+     * While active, useRouterSync skips synchronization to prevent stale content
+     * from being pushed to the navigation stack during multi-step operations.
+     *
+     * Transactions auto-commit after the current event loop iteration (setTimeout(0))
+     * to handle the common case where explicit commitTransaction() is omitted.
+     * A safety timeout (5s) prevents permanent suppression if something goes wrong.
+     *
+     * @param source - Descriptive label for debugging (e.g., 'home_navigation', 'org_switch')
+     */
+    static beginTransaction(source) {
+        // If a transaction is already active, just update the source (nested call)
+        if (NavigationUtils._transactionActive) {
+            logDebug('beginTransaction: NESTED (already active)', { existingSource: NavigationUtils._transactionSource, newSource: source });
+            NavigationUtils._transactionSource = source;
+            return;
+        }
+        NavigationUtils._transactionActive = true;
+        NavigationUtils._transactionSource = source;
+        logDebug('beginTransaction: STARTED', { source });
+        // Auto-commit after current event loop iteration.
+        // setTimeout(0) fires after all synchronous code, microtasks, and React's
+        // batched rendering + effects, but before the next macrotask.
+        NavigationUtils._transactionAutoCommitTimer = setTimeout(() => {
+            if (NavigationUtils._transactionActive) {
+                logDebug('beginTransaction: AUTO-COMMIT (setTimeout(0))', { source: NavigationUtils._transactionSource });
+                NavigationUtils._transactionActive = false;
+                NavigationUtils._transactionSource = null;
+            }
+            NavigationUtils._transactionAutoCommitTimer = null;
+        }, 0);
+        // Safety net: hard timeout to prevent permanent suppression
+        NavigationUtils._transactionSafetyTimer = setTimeout(() => {
+            if (NavigationUtils._transactionActive) {
+                console.warn('[NavigationUtils] Transaction safety timeout — force committing after 5s', { source: NavigationUtils._transactionSource });
+                NavigationUtils._transactionActive = false;
+                NavigationUtils._transactionSource = null;
+            }
+            NavigationUtils._transactionSafetyTimer = null;
+        }, 5000);
+    }
+    /**
+     * Explicitly commit (end) the current navigation transaction.
+     *
+     * This is optional — transactions auto-commit after the current event loop
+     * iteration.  Call this explicitly when you want deterministic timing, e.g.,
+     * inside a requestAnimationFrame callback after a route change.
+     */
+    static commitTransaction() {
+        if (!NavigationUtils._transactionActive) {
+            return;
+        }
+        logDebug('commitTransaction: COMMITTED', { source: NavigationUtils._transactionSource });
+        NavigationUtils._transactionActive = false;
+        NavigationUtils._transactionSource = null;
+        // Clear pending timers
+        if (NavigationUtils._transactionAutoCommitTimer) {
+            clearTimeout(NavigationUtils._transactionAutoCommitTimer);
+            NavigationUtils._transactionAutoCommitTimer = null;
+        }
+        if (NavigationUtils._transactionSafetyTimer) {
+            clearTimeout(NavigationUtils._transactionSafetyTimer);
+            NavigationUtils._transactionSafetyTimer = null;
+        }
+    }
+    /**
+     * Check if a navigation transaction is currently active.
+     *
+     * Used by useRouterSync to decide whether to skip synchronization.
+     * Unlike the old consumeRouterSyncSuppression(), this does NOT consume
+     * the flag — the transaction remains active until committed.
+     */
+    static isInTransaction() {
+        return NavigationUtils._transactionActive;
+    }
+    /**
+     * Get the current transaction source label (for debugging).
+     */
+    static getTransactionSource() {
+        return NavigationUtils._transactionSource;
+    }
+    /**
+     * Build the canonical browser URL string used by navigation ownership checks.
+     *
+     * We compare full addressable URLs (`pathname + search`) rather than mixing
+     * pathname-only and query-bearing variants across different runtime entry
+     * points. This keeps URL-first reconstruction truthful for views that encode
+     * meaningful state in query params.
+     */
+    static buildBrowserUrl(pathname, search = '') {
+        return search ? `${pathname}${search}` : pathname;
+    }
+    /**
+     * Normalize a stored URL before route-owner comparisons.
+     *
+     * We intentionally preserve query parameters because they participate in
+     * addressable navigation state, but drop hash fragments because the runtime
+     * does not model them as navigation ownership signals.
+     */
+    static normalizeComparableUrl(urlPath) {
+        if (!urlPath) {
+            return undefined;
+        }
+        const [withoutHash] = urlPath.split('#');
+        return withoutHash || undefined;
+    }
+    /**
+     * Resolve which structural zone currently owns a URL.
+     *
+     * URL-first reconstruction must only trust the visible top entry of a zone,
+     * never a stale entry buried deeper in a backstack. We therefore scan the
+     * structural zones from deepest to shallowest and only match against each
+     * zone's current top entry.
+     */
+    static findStructuralRouteOwner(urlPath, getZoneState) {
+        const comparableTargetUrl = NavigationUtils.normalizeComparableUrl(urlPath);
+        if (!comparableTargetUrl) {
+            return null;
+        }
+        const zonePriority = [
+            NavigationZoneName.COMPANION,
+            NavigationZoneName.SECONDARY,
+            NavigationZoneName.PRIMARY,
+        ];
+        for (const zone of zonePriority) {
+            const topEntry = NavigationUtils.getTopEntry(getZoneState(zone));
+            if (NavigationUtils.normalizeComparableUrl(topEntry?.urlPath) === comparableTargetUrl) {
+                return { zone, entry: topEntry };
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a URL pattern matches a pathname (exact match).
+     * Patterns use :paramName format (e.g., /organizations/:organizationId/api-keys)
+     * and pathnames have actual values (e.g., /organizations/abc123/api-keys).
+     *
+     * @param pattern - URL pattern with :paramName placeholders
+     * @param pathname - Actual URL pathname with resolved values
+     * @returns true if the pattern matches the pathname
+     */
+    static matchUrlPattern(pattern, pathname) {
+        // First replace :paramName with a placeholder that won't be escaped
+        // Then escape special regex chars, then restore the placeholder as regex group
+        const PLACEHOLDER = '___PARAM___';
+        const paramNames = [];
+        // Extract :paramName patterns and replace with placeholder
+        const withPlaceholders = pattern.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_match, paramName) => {
+            paramNames.push(paramName);
+            return PLACEHOLDER;
+        });
+        // Escape special regex characters
+        const escaped = withPlaceholders.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        // Replace placeholders with regex capture groups
+        const regexPattern = escaped.replace(new RegExp(PLACEHOLDER, 'g'), '([^/]+)');
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(pathname);
+    }
+    /**
+     * Check if pathname matches pattern or is a child of it.
+     * Used to determine if a navigation item should be marked as active.
+     *
+     * @param pattern - URL pattern with :paramName placeholders
+     * @param pathname - Actual URL pathname
+     * @returns true if the pathname matches the pattern or is a child route
+     */
+    static isActiveRoute(pattern, pathname) {
+        const normalizedPattern = pattern.split('?')[0]?.split('#')[0] ?? pattern;
+        const normalizedPathname = pathname.split('?')[0]?.split('#')[0] ?? pathname;
+        // Exact match
+        if (NavigationUtils.matchUrlPattern(normalizedPattern, normalizedPathname)) {
+            return true;
+        }
+        // Check if pathname starts with pattern (for child routes)
+        // We need to check each segment to handle dynamic params correctly
+        const patternSegments = normalizedPattern.split('/').filter(Boolean);
+        const pathSegments = normalizedPathname.split('/').filter(Boolean);
+        // If pattern has more segments than path, it can't match
+        if (patternSegments.length > pathSegments.length) {
+            return false;
+        }
+        // Check if all pattern segments match path segments
+        for (let i = 0; i < patternSegments.length; i++) {
+            const patternSeg = patternSegments[i];
+            const pathSeg = pathSegments[i];
+            if (patternSeg.startsWith(':')) {
+                // Dynamic segment - any non-empty value matches
+                if (!pathSeg)
+                    return false;
+            }
+            else {
+                // Static segment - must match exactly
+                if (patternSeg !== pathSeg)
+                    return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Convert resourceType-keyed identifiers to fieldIdentifier-keyed identifiers for URL substitution.
+     *
+     * Frontend URLs use :fieldIdentifier format (e.g., :organizationId), but contextResourceIdentifiers
+     * use resourceType as keys (e.g., 'organizations'). This function converts between the two.
+     *
+     * @param resourceTypeIdentifiers - Map with resourceType keys (e.g., { organizations: 'org-123' })
+     * @param allResourceFieldIdentifiers - Registry mapping from resourceType to fieldIdentifier
+     * @returns Map with fieldIdentifier keys (e.g., { organizationId: 'org-123' })
+     */
+    static convertToFieldIdentifierKeys(resourceTypeIdentifiers, allResourceFieldIdentifiers) {
+        const result = {};
+        for (const [resourceType, value] of Object.entries(resourceTypeIdentifiers)) {
+            if (value) {
+                // Look up fieldIdentifier for this resourceType
+                const fieldIdentifier = allResourceFieldIdentifiers[resourceType];
+                if (fieldIdentifier) {
+                    result[fieldIdentifier] = value;
+                }
+                else {
+                    // Fallback: check if it's already a fieldIdentifier or if it's in coreResourceShared_FieldIdentifier
+                    const coreFieldId = coreResourceShared_FieldIdentifier[resourceType];
+                    if (coreFieldId) {
+                        result[coreFieldId] = value;
+                    }
+                    else {
+                        // Last resort: use the key as-is (might be a custom field)
+                        result[resourceType] = value;
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Resolve URL path placeholders with actual values from context identifiers.
+     *
+     * Frontend URLs use :fieldIdentifier format (React Router style, e.g., /organizations/:organizationId/api-keys).
+     * This function replaces these placeholders with actual values.
+     *
+     * @param urlPath - URL path with :paramName placeholders
+     * @param fieldIdentifiers - Map with fieldIdentifier keys (e.g., { organizationId: 'org-123' })
+     * @returns Resolved URL path with placeholders replaced
+     */
+    static resolveUrlPath(urlPath, fieldIdentifiers) {
+        if (!urlPath)
+            return undefined;
+        let resolvedPath = urlPath;
+        for (const [fieldIdentifier, value] of Object.entries(fieldIdentifiers)) {
+            if (value !== undefined && value !== null && value !== '') {
+                const resolvedValue = String(value);
+                // Replace :fieldIdentifier format (React Router style - primary format for frontend)
+                // Use word boundary to avoid partial matches (e.g., :organizationId vs :organizationIdExtra)
+                const colonRegex = new RegExp(`:${fieldIdentifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[/\\?]|$)`, 'g');
+                resolvedPath = resolvedPath.replace(colonRegex, resolvedValue);
+                // Also handle {fieldIdentifier} format for backwards compatibility with backend-style URLs
+                const curlyBraceRegex = new RegExp(`\\{${fieldIdentifier.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\}`, 'g');
+                resolvedPath = resolvedPath.replace(curlyBraceRegex, resolvedValue);
+            }
+        }
+        return resolvedPath;
+    }
+    /**
+     * Check if a URL path still contains unresolved :paramName or {paramName} placeholders.
+     * Used as a sending-side guard to prevent writing malformed URLs to the browser or API calls.
+     *
+     * @param urlPath - Resolved URL path to check
+     * @returns true if unresolved placeholders remain
+     */
+    static hasUnresolvedPlaceholders(urlPath) {
+        // Match :paramName (React Router style) — word char sequences after colon, not preceded by //
+        // Also match {paramName} (backend style)
+        return /:[a-zA-Z_]\w*(?=[/\\?]|$)/.test(urlPath) || /\{[a-zA-Z_]\w*\}/.test(urlPath);
+    }
+    /**
+     * Helper to create initiator context for app-level launchers
+     *
+     * @param launcher - The app-level action launcher
+     * @returns Navigation initiator context for app-level navigation
+     */
+    static createAppLevelInitiator(launcher) {
+        return {
+            sourceZone: APP_LEVEL_NAVIGATION_SOURCE,
+            launcher,
+        };
+    }
+    /**
+     * Dispatch navigation for an AnyNavigationItem — DRY helper shared
+     * across all behavior hooks that convert a nav item click into a
+     * `navigate()` call.
+     */
+    static dispatchNavigationForItem(navigate, item, launcher) {
+        if (isCustomComponentNavigationItem(item)) {
+            navigate({
+                content: {
+                    contentType: NavigationContentType.CUSTOM_COMPONENT,
+                    componentRef: item.componentRef,
+                    contextResourceIdentifiers: item.contextResourceIdentifiers,
+                },
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: item.urlPath,
+            });
+        }
+        else if (isViewNavigationItem(item)) {
+            navigate({
+                content: NavigationUtils.buildNavigationContentForViewItem(item),
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: item.urlPath,
+            });
+        }
+        else {
+            navigate({
+                content: {
+                    contentType: NavigationContentType.RESOURCE_OPERATION,
+                    resourceContext: item.resourceContext,
+                },
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: item.urlPath,
+            });
+        }
+    }
+    /**
+     * Dispatch navigation for a resolved target (from the new per-launcher resolution layer).
+     *
+     * Builds `NavigationContent` from the resolved target's fields, dispatching
+     * on presence of `resourceContext` (resource items) vs `viewRef`+`contentType` (view items).
+     */
+    static dispatchNavigationForResolvedTarget(navigate, target, launcher) {
+        if (target.resourceContext) {
+            navigate({
+                content: {
+                    contentType: NavigationContentType.RESOURCE_OPERATION,
+                    resourceContext: target.resourceContext,
+                },
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: target.urlPath,
+            });
+        }
+        else if (target.viewRef && target.contentType) {
+            const content = NavigationUtils.buildNavigationContentForResolvedView(target.viewRef, target.contentType, target.fullCustomComponentRef, target.flowsActorsSystemRefs, target.contextResourceIdentifiers, target.urlParamValues, target.requiredFeatures);
+            navigate({
+                content,
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: target.urlPath,
+            });
+        }
+        else if (target.contentType === NavigationContentType.ENGINE_PAGE && target.pageRef) {
+            navigate({
+                content: {
+                    contentType: NavigationContentType.ENGINE_PAGE,
+                    pageRef: target.pageRef,
+                },
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: target.urlPath,
+            });
+        }
+        else if (target.componentRef) {
+            navigate({
+                content: {
+                    contentType: NavigationContentType.CUSTOM_COMPONENT,
+                    componentRef: target.componentRef,
+                    contextResourceIdentifiers: target.contextResourceIdentifiers,
+                },
+                initiator: NavigationUtils.createAppLevelInitiator(launcher),
+                urlPath: target.urlPath,
+            });
+        }
+        else {
+            logDebug('Cannot dispatch navigation for resolved target — no resolved resource/view/page payload', { target });
+        }
+    }
+    /**
+     * Build navigation content from resolved view fields.
+     * Mirrors `buildNavigationContentForViewItem` but operates on loose fields
+     * from `ResolvedNavigationTarget` instead of `ViewNavigationItem`.
+     */
+    static buildNavigationContentForResolvedView(viewRef, contentType, fullCustomComponentRef, flowsActorsSystemRefs, contextResourceIdentifiers, urlParamValues, requiredFeatures) {
+        switch (contentType) {
+            case NavigationContentType.COMPOSITE_VIEW:
+                return {
+                    contentType: NavigationContentType.COMPOSITE_VIEW,
+                    viewRef,
+                    contextResourceIdentifiers,
+                };
+            case NavigationContentType.CHART_VIEW:
+                return {
+                    contentType: NavigationContentType.CHART_VIEW,
+                    viewRef,
+                    contextResourceIdentifiers,
+                    urlParamValues,
+                    requiredFeatures,
+                };
+            case NavigationContentType.EXECUTION_VIEW:
+                return {
+                    contentType: NavigationContentType.EXECUTION_VIEW,
+                    viewRef,
+                    contextResourceIdentifiers,
+                };
+            case NavigationContentType.FULL_CUSTOM_VIEW:
+                return {
+                    contentType: NavigationContentType.FULL_CUSTOM_VIEW,
+                    viewRef,
+                    fullCustomComponentRef: fullCustomComponentRef ?? '',
+                    contextResourceIdentifiers,
+                };
+            case NavigationContentType.FLOWS_ACTORS_VIEW:
+                return {
+                    contentType: NavigationContentType.FLOWS_ACTORS_VIEW,
+                    viewRef,
+                    flowsActorsSystemRefs: flowsActorsSystemRefs ?? [],
+                    contextResourceIdentifiers,
+                };
+            default:
+                throw new Error(`Unknown view content type: ${contentType}`);
+        }
+    }
+    /**
+     * Create initiator context for operation-related navigation (from within a structural zone).
+     */
+    static createOperationInitiator(sourceZone, sourceOperation) {
+        return {
+            sourceZone: sourceZone ?? NavigationZone.PRIMARY,
+            ...(sourceOperation ? { sourceOperation: sourceOperation } : {}),
+        };
+    }
+    /**
+     * Create initial empty zone state
+     */
+    static createEmptyZoneState(zone) {
+        return {
+            zone,
+            stack: [],
+            isVisible: zone === NavigationZoneName.PRIMARY,
+        };
+    }
+    /**
+     * Create initial navigation state.
+     *
+     * v3 shape: `{ zones: { primary, secondary, companion }, overlay: [] }`
+     * — DIALOG and SHEET merged into a single `overlay` stack.
+     * — Former THIRD zone is now COMPANION.
+     */
+    static createInitialNavigationState() {
+        return {
+            zones: {
+                [NavigationZoneName.PRIMARY]: NavigationUtils.createEmptyZoneState(NavigationZoneName.PRIMARY),
+                [NavigationZoneName.SECONDARY]: NavigationUtils.createEmptyZoneState(NavigationZoneName.SECONDARY),
+                [NavigationZoneName.COMPANION]: NavigationUtils.createEmptyZoneState(NavigationZoneName.COMPANION),
+            },
+            overlay: [],
+        };
+    }
+    /**
+     * Get the current depth of a zone's stack
+     */
+    static getZoneDepth(state) {
+        return state?.stack.length ?? 0;
+    }
+    /**
+     * Get the top entry of a zone's stack (current content)
+     */
+    static getTopEntry(state) {
+        return state.stack[state.stack.length - 1];
+    }
+    /**
+     * Calculate the resource relationship depth from parentResourcesRequirements.
+     *
+     * This is the correct depth metric for navigation policy resolution:
+     * - Root resource (no parents) → depth 0
+     * - First-level child (1 parent) → depth 1
+     * - Grandchild (2 parents) → depth 2
+     *
+     * Unlike viewDepth (stack-based), this reflects the actual resource hierarchy
+     * depth, which is what the navigation policy's depth matrix cares about.
+     *
+     * @param parentResourcesRequirements - Array of parent resource requirements
+     * @returns The resource relationship depth (0 = root, 1 = child, 2 = grandchild, etc.)
+     */
+    static calculateResourceRelationshipDepth(parentResourcesRequirements) {
+        return parentResourcesRequirements?.length ?? 0;
+    }
+    /**
+     * Resolve the structural zone that should own a routed resource entry based on
+     * its relationship depth and the zones available in the current layout.
+     *
+     * This is shared by URL-sync restoration and AppRouter's routed page wrapper so
+     * the page props and the live navigation stack cannot disagree about whether a
+     * deep-linked resource belongs to PRIMARY, SECONDARY, or COMPANION.
+     */
+    static resolveResourceTargetZone(depth, options) {
+        const hasSecondary = !!options?.hasSecondary;
+        const hasCompanion = !!options?.hasCompanion;
+        let targetZone = depth >= 2
+            ? NavigationZoneName.COMPANION
+            : depth === 1
+                ? NavigationZoneName.SECONDARY
+                : NavigationZoneName.PRIMARY;
+        if (!hasCompanion && targetZone === NavigationZoneName.COMPANION) {
+            targetZone = hasSecondary ? NavigationZoneName.SECONDARY : NavigationZoneName.PRIMARY;
+        }
+        else if (!hasSecondary && targetZone === NavigationZoneName.SECONDARY) {
+            targetZone = NavigationZoneName.PRIMARY;
+        }
+        return targetZone;
+    }
+    /**
+     * Generate a unique stack entry ID
+     */
+    static generateStackEntryId() {
+        return `nav-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * Check if content is a resource operation
+     */
+    static isResourceOperationContent(content) {
+        return content.contentType === NavigationContentType.RESOURCE_OPERATION;
+    }
+    /**
+     * Resolve the URL for a resource operation given candidate context identifiers.
+     *
+     * This is the unified URL resolution pipeline, centralizing the logic that was
+     * previously duplicated across useNavigationController, NavigationContext, and useRouterSync.
+     *
+     * Steps:
+     * 1. Build all possible route paths for the operation
+     * 2. Select the best matching route path based on available context
+     * 3. Convert resourceType keys to fieldIdentifier keys
+     * 4. Ensure FK-prefixed placeholders resolve correctly
+     * 5. Resolve :placeholder patterns with actual values
+     *
+     * @param resourceConfig - The frontend resource configuration
+     * @param operation - The operation configuration
+     * @param candidateContextIdentifiers - Normalized context identifiers (resourceType → id)
+     * @param allResourceFieldIdentifiers - Registry mapping resourceType → fieldIdentifier
+     * @param parentResourcesRequirements - Optional parent resource requirements for route selection
+     * @returns Resolved URL info, or undefined if resolution fails
+     */
+    static resolveResourceUrl(resourceConfig, operation, candidateContextIdentifiers, allResourceFieldIdentifiers, parentResourcesRequirements) {
+        try {
+            logDebug('resolveResourceUrl()', { resourceIdentifier: resourceConfig.resourceIdentifier, operationIdentifier: operation.operationIdentifier, candidateKeys: Object.keys(candidateContextIdentifiers) });
+            const routePaths = ResourcesConfigOperationsUrlsBuilderUtils.buildOperationFrontendRoutePaths(resourceConfig, operation, allResourceFieldIdentifiers);
+            if (!routePaths || routePaths.length === 0) {
+                return undefined;
+            }
+            const selected = frontendResourceUtils.selectMatchingRoutePath(routePaths, candidateContextIdentifiers, resourceConfig.resourceIdentifier, resourceConfig.resourceFieldIdentifier, parentResourcesRequirements);
+            const templateUrl = selected.url;
+            const routePathParameters = (selected.parameters ?? []);
+            // Convert resourceType keys to fieldIdentifier keys for URL substitution
+            const urlParameters = NavigationUtils.convertToFieldIdentifierKeys(candidateContextIdentifiers, allResourceFieldIdentifiers);
+            // Ensure FK-prefixed placeholders (e.g. :assignedToUserId) resolve correctly:
+            // routePathParameters provide the exact placeholder fieldIdentifier to use.
+            // Prefer exact FK-keyed context entries when available (self-ref / multi-parent
+            // routes), then fall back to the broader resourceType key.
+            for (const p of routePathParameters) {
+                const v = candidateContextIdentifiers[p.fieldIdentifier] ?? candidateContextIdentifiers[p.resourceType];
+                if (v) {
+                    urlParameters[p.fieldIdentifier] = v;
+                }
+            }
+            let resolvedUrl = NavigationUtils.resolveUrlPath(templateUrl, urlParameters);
+            // Guard: if unresolved placeholders remain, log warning and nullify the resolved URL
+            // The caller will fall back to not updating the browser URL (navigation) or aborting (forms)
+            if (resolvedUrl && NavigationUtils.hasUnresolvedPlaceholders(resolvedUrl)) {
+                logDebug('resolveResourceUrl() WARNING: unresolved placeholders in URL', { templateUrl, resolvedUrl });
+                resolvedUrl = undefined;
+            }
+            else {
+                logDebug('resolveResourceUrl() resolved', { templateUrl, resolvedUrl });
+            }
+            return { resolvedUrl, templateUrl, routePathParameters };
+        }
+        catch (err) {
+            logDebug('resolveResourceUrl() failed', { error: String(err) });
+            return undefined;
+        }
+    }
+    /**
+     * Resolve an operationRef string (e.g., "TASKS.LIST.default") into a full
+     * NavigationContent_ResourceOperation by looking up the operation in the registry.
+     *
+     * This is the resolution step for **unresolved operation refs** — a lightweight
+     * navigation input format where the emitter only knows a ref string, not a full
+     * NavigationContent payload.
+     *
+     * **Consumers:**
+     * - NAVIGATION_REQUEST event listener (in useNavigationController): resolves
+     *   `payload.operationRef` before entering the navigation pipeline. Used by
+     *   emitters that sit above ResourceRegistryProvider (e.g., NotificationProvider).
+     * - RouterErrorBoundary: calls this directly to resolve error guidance nextAction
+     *   refs, since NavigationProvider is destroyed in the error boundary context.
+     *
+     * @param operationRef   Dot-separated ref, e.g., "TASKS.LIST.default" or "TASKS.LIST"
+     * @param additionalIdentifiers  Optional context identifiers (orgId, resourceId, etc.)
+     * @param registry       The frontend resource registry for operation lookup
+     * @returns Resolved NavigationContent_ResourceOperation, or undefined if lookup fails
+     */
+    static resolveOperationRef(operationRef, additionalIdentifiers, registry) {
+        const parts = operationRef.split('.');
+        if (parts.length < 2) {
+            logDebug('resolveOperationRef() failed: invalid ref format', { operationRef });
+            return undefined;
+        }
+        const [resourceType, operationId, operationVariantRef] = parts;
+        const resourceConfig = registry.resourceConfigurations[resourceType];
+        if (!resourceConfig) {
+            logDebug('resolveOperationRef() failed: resource not found', { resourceType });
+            return undefined;
+        }
+        const matchingOperations = resourceConfig.operations.filter((op) => String(op.operationIdentifier) === operationId);
+        const defaultOperations = matchingOperations.filter((op) => op.isOperationDefault);
+        const operation = operationVariantRef === 'default'
+            ? defaultOperations.length === 1
+                ? defaultOperations[0]
+                : undefined
+            : operationVariantRef
+                ? matchingOperations.find((op) => op.variantKey === operationVariantRef)
+                : defaultOperations.length === 1
+                    ? defaultOperations[0]
+                    : matchingOperations.length === 1
+                        ? matchingOperations[0]
+                        : undefined;
+        if (!operation) {
+            logDebug('resolveOperationRef() failed: operation not found', { resourceType, operationId, operationVariantRef });
+            return undefined;
+        }
+        logDebug('resolveOperationRef() resolved', { operationRef, resourceType, operationId, operationVariantRef });
+        const parentResourcesRequirements = additionalIdentifiers
+            ? frontendResourceUtils.buildParentResourcesRequirements(resourceType, additionalIdentifiers, registry)
+            : [];
+        return {
+            contentType: NavigationContentType.RESOURCE_OPERATION,
+            resourceContext: frontendResourceUtils.createFrontendResourceOperationContextFromOperation({
+                resourceType: resourceType,
+                operation,
+                contextResourceIdentifiers: additionalIdentifiers ?? {},
+                parentResourcesRequirements,
+            }),
+        };
+    }
+    /**
+     * Build NavigationContent from a ViewNavigationItem.
+     *
+     * Centralizes the viewType → NavigationContent conversion that was previously
+     * duplicated across every preset component's click handler.
+     */
+    static buildNavigationContentForViewItem(item) {
+        const contentType = item.contentType;
+        switch (contentType) {
+            case NavigationContentType.COMPOSITE_VIEW:
+                return {
+                    contentType: NavigationContentType.COMPOSITE_VIEW,
+                    viewRef: item.viewRef,
+                    contextResourceIdentifiers: item.contextResourceIdentifiers,
+                };
+            case NavigationContentType.CHART_VIEW:
+                return {
+                    contentType: NavigationContentType.CHART_VIEW,
+                    viewRef: item.viewRef,
+                    contextResourceIdentifiers: item.contextResourceIdentifiers,
+                    urlParamValues: item.urlParamValues,
+                    requiredFeatures: item.requiredFeatures,
+                };
+            case NavigationContentType.EXECUTION_VIEW:
+                return {
+                    contentType: NavigationContentType.EXECUTION_VIEW,
+                    viewRef: item.viewRef,
+                    contextResourceIdentifiers: item.contextResourceIdentifiers,
+                };
+            case NavigationContentType.FULL_CUSTOM_VIEW:
+                return {
+                    contentType: NavigationContentType.FULL_CUSTOM_VIEW,
+                    viewRef: item.viewRef,
+                    fullCustomComponentRef: item.fullCustomComponentRef ?? '',
+                    contextResourceIdentifiers: item.contextResourceIdentifiers,
+                };
+            case NavigationContentType.FLOWS_ACTORS_VIEW:
+                return {
+                    contentType: NavigationContentType.FLOWS_ACTORS_VIEW,
+                    viewRef: item.viewRef,
+                    flowsActorsSystemRefs: item.flowsActorsSystemRefs ?? [],
+                    contextResourceIdentifiers: item.contextResourceIdentifiers,
+                };
+            default:
+                throw new Error(`Unknown view content type: ${contentType}`);
+        }
+    }
+    // ================================
+    // Cascading Utilities
+    // ================================
+    /**
+     * Find the relationship between two resource types in the registry.
+     *
+     * Searches the global `resourceRelationships` array for a match where:
+     * - resourceType1 = parentType, resourceType2 = childType
+     * - Optionally filtered by foreignKeyField for disambiguation
+     *
+     * @param parentType - The parent resource type (resourceType1 side)
+     * @param childType - The child resource type (resourceType2 side)
+     * @param registry - The frontend resources registry
+     * @param foreignKeyField - Optional FK field for disambiguation when multiple relationships exist
+     * @returns The matching ResourceRelationship, or undefined
+     */
+    static findRelationshipBetween(parentType, childType, registry, foreignKeyField) {
+        return registry.resourceRelationships.find(rel => rel.resourceType1 === parentType &&
+            rel.resourceType2 === childType &&
+            !rel.isDisabled &&
+            (foreignKeyField === undefined ||
+                Resources_SharedUtils.tryResolveRelationshipForeignKeyIdentity(rel, registry.allResourceFieldIdentifiers)?.fieldIdentifier === foreignKeyField));
+    }
+    /**
+     * Determine the default ancestor operation based on relationship cardinality.
+     *
+     * Cardinality semantics:
+     * - 1:N (parent ONE → child MANY): ancestor shows LIST (list of children / siblings)
+     * - 1:1 (parent ONE → child ONE): ancestor shows READ (parent detail)
+     * - N:1 (reversed perspective): ancestor shows READ (parent detail)
+     * - M:N (junction): ancestor shows LIST (related items)
+     *
+     * @param relationship - The resource relationship
+     * @returns The default CoreResourceOperation for the ancestor zone
+     */
+    static deriveDefaultAncestorOperation(relationship) {
+        const { cardinality1, cardinality2 } = relationship;
+        const isParentOne = cardinality1 === ResourceRelationshipCardinality.ONE
+            || cardinality1 === ResourceRelationshipCardinality.ZERO_OR_ONE;
+        const isChildOne = cardinality2 === ResourceRelationshipCardinality.ONE
+            || cardinality2 === ResourceRelationshipCardinality.ZERO_OR_ONE;
+        // Self-referencing: use the relationship-owned navigation direction to disambiguate
+        // which side is "parent" vs "child" for the ancestor zone operation.
+        // Without this, the engine can't distinguish forward (parent→child = LIST)
+        // from backward (child→parent = READ) since both types are the same.
+        if (relationship.resourceType1 === relationship.resourceType2) {
+            const navigationConfig = relationship.display?.inParentNavigation;
+            if (navigationConfig?.direction === CascadeDirection.BACKWARD)
+                return CoreResourceOperation.READ;
+            return CoreResourceOperation.LIST;
+        }
+        // 1:1 → READ parent detail
+        if (isParentOne && isChildOne) {
+            return CoreResourceOperation.READ;
+        }
+        // 1:N (parent=ONE, child=MANY) → LIST (show siblings in parent context)
+        if (isParentOne) {
+            return CoreResourceOperation.LIST;
+        }
+        // N:1 reversed → READ parent
+        if (isChildOne) {
+            return CoreResourceOperation.READ;
+        }
+        // M:N → LIST
+        return CoreResourceOperation.LIST;
+    }
+    /**
+     * Resolve the ancestor operation for a given relationship.
+     *
+     * Resolution order:
+     * 1. Explicit `ancestorOperation` override from display.inParentNavigation → use directly
+     * 2. Cardinality-based default (deriveDefaultAncestorOperation)
+     * 3. Fallback: swap LIST ↔ READ if default is not available
+     * 4. null if no suitable operation exists
+     *
+     * @param relationship - The resource relationship between ancestor and descendant
+     * @param ancestorConfig - The ancestor resource's frontend configuration
+     * @returns The resolved CoreResourceOperation, or null if no suitable operation
+     */
+    static resolveAncestorOperation(relationship, ancestorConfig) {
+        const operation = NavigationUtils.resolveAncestorOperationConfig(relationship, ancestorConfig);
+        return operation
+            ? (resolveEffectiveCoreOperationFromOperation(operation) ?? null)
+            : null;
+    }
+    static resolveAncestorOperationConfig(relationship, ancestorConfig) {
+        const directOperations = (ancestorConfig.operations ?? []);
+        const legacyOperations = !ancestorConfig.operations && ancestorConfig.operationsConfiguration
+            ? Object.entries(ancestorConfig.operationsConfiguration).map(([operationIdentifier, operation]) => ({
+                ...operation,
+                operationIdentifier,
+            }))
+            : [];
+        const operations = directOperations.length > 0 ? directOperations : legacyOperations;
+        if (operations.length === 0)
+            return null;
+        const findOp = (op) => pickPreferredOperationForCoreSemantic(operations, op, { requireAddressable: true });
+        // 1. Explicit override from display.inParentNavigation.ancestorOperation.
+        // This allows relationship config to force a specific operation (LIST or READ)
+        // for the ancestor zone, overriding the cardinality-based default.
+        if (relationship) {
+            const navigationConfig = relationship.display?.inParentNavigation;
+            const ancestorOp = navigationConfig?.ancestorOperation;
+            if (ancestorOp) {
+                const explicitOperation = findOp(ancestorOp);
+                if (explicitOperation) {
+                    return explicitOperation;
+                }
+            }
+        }
+        // 2. Cardinality-based default
+        const defaultOp = relationship
+            ? NavigationUtils.deriveDefaultAncestorOperation(relationship)
+            : CoreResourceOperation.LIST;
+        const defaultOperation = findOp(defaultOp);
+        if (defaultOperation)
+            return defaultOperation;
+        // 3. Fallback: swap LIST ↔ READ
+        const fallbackOp = defaultOp === CoreResourceOperation.LIST
+            ? CoreResourceOperation.READ
+            : CoreResourceOperation.LIST;
+        const fallbackOperation = findOp(fallbackOp);
+        if (fallbackOperation)
+            return fallbackOperation;
+        // 4. No suitable operation
+        return null;
+    }
+    /**
+     * Check if secondary/companion zone content is relevant to the current PRIMARY top entry.
+     *
+     * Content is considered "stale" (irrelevant) when:
+     * - It's a resource operation whose parentResourcesRequirements no longer match
+     *   the PRIMARY zone's parent resource type and id
+     * - It's a view (composite/chart) — always stale on PRIMARY change
+     *
+     * @param dependentContent - Content in SECONDARY or COMPANION zone
+     * @param primaryContent - Current top content in PRIMARY zone
+     * @returns true if the dependent content is still relevant to the primary
+     */
+    static isContentRelevantToParent(dependentContent, primaryContent) {
+        // Views are not relationship-aware → always stale on PRIMARY change
+        if (dependentContent.contentType !== NavigationContentType.RESOURCE_OPERATION) {
+            return false;
+        }
+        // Primary is not a resource operation → dependent is stale
+        if (primaryContent.contentType !== NavigationContentType.RESOURCE_OPERATION) {
+            return false;
+        }
+        const primaryResourceType = primaryContent.resourceContext.resourceType;
+        const primaryResourceId = frontendResourceUtils.getPrimaryResourceIdentifier(primaryContent.resourceContext);
+        const parentReqs = dependentContent.resourceContext.parentResourcesRequirements;
+        // If dependent has no parent requirements → it's a root resource, not dependent on PRIMARY
+        if (!parentReqs || parentReqs.length === 0) {
+            return false;
+        }
+        return parentReqs.some((requirement) => {
+            if (requirement.resourceType !== primaryResourceType) {
+                return false;
+            }
+            if (!primaryResourceId) {
+                return false;
+            }
+            const requirementContextKey = requirement.foreignKeyField ?? requirement.resourceType;
+            const expectedParentId = NavigationUtils.resolveContextIdentifierValue(dependentContent.resourceContext, requirementContextKey) ?? NavigationUtils.resolveContextIdentifierValue(dependentContent.resourceContext, requirement.resourceType);
+            if (!expectedParentId) {
+                return false;
+            }
+            return expectedParentId === primaryResourceId;
+        });
+    }
+    // =========================================================================
+    // RELATIONSHIP DISPLAY UTILITIES
+    // =========================================================================
+    /**
+     * Determine whether a parent reference should be shown in a child resource view.
+     *
+     * Uses navigation context, inline rendering state, and relationship config
+     * to decide if showing a parent link/badge is appropriate or redundant.
+     *
+     * @param inlineParentContext - Set by ContainerNested when rendering inline children
+     * @param navigationZone - Which zone the child is rendered in
+     * @param navigationInitiator - How the child was navigated to (source, relationship info)
+     * @param getZoneState - Function to check another zone's current state (for staleness detection)
+     *
+     */
+    static shouldShowParentReference(inlineParentContext, navigationZone, navigationInitiator, getZoneState) {
+        // 1. Inline rendering — parent is visible above, never show
+        if (inlineParentContext)
+            return false;
+        // 2. Overlay — parent is visible behind overlay, never show
+        if (navigationZone === NavigationZone.OVERLAY)
+            return false;
+        // 3. Check explicit inChildView config from relationship
+        const inChildView = navigationInitiator?.sourceRelationship?.inChildView;
+        if (inChildView?.parentDisplay === ParentDisplay.NONE)
+            return false;
+        // 4. Multi-zone — if source zone is different, check if parent is STILL visible there
+        const sourceZone = navigationInitiator?.sourceZone;
+        if (sourceZone && sourceZone !== navigationZone && getZoneState) {
+            const sourceZoneState = getZoneState(sourceZone);
+            const topEntry = sourceZoneState?.stack?.[sourceZoneState.stack.length - 1];
+            if (topEntry?.content && 'resourceContext' in topEntry.content) {
+                const topResourceContext = topEntry.content.resourceContext;
+                const topResourceType = topResourceContext?.resourceType;
+                const topResourceId = topResourceContext
+                    ? frontendResourceUtils.getPrimaryResourceIdentifier(topResourceContext)
+                    : undefined;
+                const sourceRelationship = navigationInitiator?.sourceRelationship;
+                if (topResourceType === sourceRelationship?.parentResourceType &&
+                    (!sourceRelationship.parentResourceId ||
+                        sourceRelationship.parentResourceId === topResourceId)) {
+                    return false;
+                }
+            }
+        }
+        // 5. No initiator (direct URL), same-zone PUSH/REPLACE, or stale source zone — show reference
+        return true;
+    }
+    /**
+     * Resolve the default `showParentLink` value for a relationship when
+     * `display.inChildView.showParentLink` is not explicitly configured.
+     *
+     * Rule: `true` for required FK fields (the parent is integral to the child),
+     *        `false` for optional FK fields (the parent is an optional association).
+     *
+     * @param schema - The child resource schema
+     * @param fkFieldName - The foreign key field name on the child
+     */
+    static resolveDefaultShowParentLink(schema, fkFieldName) {
+        try {
+            // Check if the schema is an object type with the FK field
+            const shape = schema?._def?.shape?.();
+            if (!shape || !shape[fkFieldName])
+                return true; // Default to showing
+            const fieldSchema = shape[fkFieldName];
+            // Check if the field is optional (has ZodOptional wrapper)
+            const isOptional = fieldSchema?._def?.typeName === 'ZodOptional'
+                || fieldSchema?.isOptional?.() === true;
+            return !isOptional;
+        }
+        catch {
+            // If schema introspection fails, default to showing
+            return true;
+        }
+    }
+}
+//# sourceMappingURL=navigation.utils.js.map