@wildo-ai/saas-frontend-lib 1.1.4 → 1.1.5

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

@@ -33,8 +33,9 @@ import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js
 import { navigationPolicyResolver, resolveViewportDiscriminated } from './navigation-policy-resolver.service.js';
 import { NavigationSource } from './navigation.schemas.js';
 import { NavigationUtils } from './navigation.utils.js';
-import { emitFreshStartNavigationCleanup } from './navigation-clean-break.frontend.utils.js';
+import { emitFreshStartNavigationCleanup, emitOverlayBreakoutCleanup } from './navigation-clean-break.frontend.utils.js';
 import { useTransactionAwareSyncRetry } from './useTransactionAwareSyncRetry.js';
+import { useRouterLocationAheadOfCommit, useSynchronousBrowserLocation } from './useSynchronousBrowserLocation.js';
 import { CommonRoutePaths } from '../../core/runtime/routes.frontend.definitions.js';
 import { FrontendResourceUtils, frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
 import { isOperationAddressable } from '../../core/resources/resources.frontend.schemas.js';
@@ -311,7 +312,7 @@ export const ScopedNavigationControllerContext = createContext(null);
  */
 export function useGlobalNavigationController() {
     const { emit } = useEventBus();
-    const { resourceRelationshipDepth: currentResourceRelationshipDepth, getZoneDepth, getZoneState } = useNavigationState();
+    const { resourceRelationshipDepth: currentResourceRelationshipDepth, getZoneDepth, getZoneState, contentAreaWidth } = useNavigationState();
     const { navigationLayout, currentBreakpoint, compositeViews, fullCustomViews, flowsActorsViews } = useUI();
     const { user } = useUserOrgs();
     const appScope = useAppScopeSafe();
@@ -611,6 +612,8 @@ export function useGlobalNavigationController() {
                     relationshipTransition,
                     relationshipMaxDepth,
                     viewport: currentBreakpoint,
+                    // The space the panes must actually fit in — see `NavigationResolutionContext.contentAreaWidth`.
+                    contentAreaWidth,
                     zoneOccupancy,
                     zoneDepth,
                     focusedZone,
@@ -662,6 +665,22 @@ export function useGlobalNavigationController() {
                     emitFreshStartNavigationCleanup(emit, 'promote_navigation');
                     logDebug('PROMOTE clean break: cleared SECONDARY + COMPANION + OVERLAY');
                 }
+                // ─── OVERLAY Breakout ─────────────────────────────────────
+                // Content launched from INSIDE the overlay that resolves to a structural zone has left the
+                // overlay behind — so the overlay must not stay open over it. Only the overlay closes; the
+                // zones underneath are the context the person is returning to. See #1511 and
+                // `emitOverlayBreakoutCleanup` for the measurement.
+                //
+                // PROMOTE is excluded: it has already performed the stronger reset above.
+                if (initiator.sourceZone === NavigationZone.OVERLAY
+                    && resolution.targetZone !== NavigationZone.OVERLAY
+                    && resolution.transition !== NavigationTransition.PROMOTE) {
+                    emitOverlayBreakoutCleanup(emit, 'overlay_breakout_navigation');
+                    logDebug('OVERLAY breakout: closed the overlay it was launched from', {
+                        targetZone: resolution.targetZone,
+                        transition: resolution.transition,
+                    });
+                }
                 // ─── Cascading Orchestrator ───────────────────────────────
                 // When the resolved zone is SECONDARY or COMPANION, auto-populate ancestor
                 // zones that are currently empty so the user sees proper context.
@@ -795,6 +814,7 @@ export function useGlobalNavigationController() {
         getOperationContextNeeds,
         routerNavigate,
         getZoneState,
+        contentAreaWidth,
         inPlaceHost,
     ]);
     const navigateToResource = useCallback((resourceContext, initiator, urlPath, transitionOverride) => {
@@ -843,13 +863,52 @@ export function useGlobalNavigationController() {
     const closeOverlay = useCallback(() => {
         emit(FrontendEvents.NAVIGATION_CLOSE, { zone: NavigationZone.OVERLAY });
     }, [emit]);
+    /**
+     * DISMISS an adjacent structural zone — close the pane, not one step of it.
+     *
+     * ## Why this is not `goBack`
+     *
+     * `goBack` pops ONE entry. A reader who drilled three records deep into a pane and wants their
+     * width back would have to press it three times, and the first two presses look like the control
+     * doing nothing. Dismiss clears the zone's whole stack in one gesture, which is what "close this
+     * pane" means everywhere else it exists.
+     *
+     * ## Why the URL is written, and why it is the SAME url `goBack` writes
+     *
+     * A pane that leaves the layout must leave the address too, or a reload reopens it — measured on
+     * the workbench (2026-09-22) when a pop wrote nothing and `?pane=` survived. Both gestures leave
+     * the same layout behind, so `resolveZoneDismissUrl` owns the answer for both; a second copy of
+     * that walk is how one of them comes to write a pane's bare address, which the reconciler cannot
+     * claim and therefore rebuilds into primary.
+     *
+     * The URL is resolved BEFORE the zone is cleared, because the answer is read off the zone states
+     * as they stand while the pane is still there.
+     *
+     * OVERLAY is not dismissable this way — it has `closeOverlay`, its own stack semantics and its own
+     * URL rules — and PRIMARY is not dismissable at all: there is no layout left after it.
+     */
+    const dismissZone = useCallback((zone) => {
+        if (zone === NavigationZoneName.PRIMARY)
+            return;
+        if (getZoneState(zone).stack.length === 0)
+            return;
+        const browserUrl = NavigationUtils.resolveZoneDismissUrl({
+            zone,
+            currentBrowserUrl: currentBrowserUrlRef.current,
+            getZoneState,
+        });
+        emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone });
+        if (browserUrl) {
+            updateBrowserUrl(routerNavigate, browserUrl, true);
+        }
+    }, [emit, getZoneState, routerNavigate]);
     /**
      * Check if a zone's stack has entries to go back to.
      */
     const canGoBack = useCallback((zone) => {
         return getZoneDepth(zone) > 1;
     }, [getZoneDepth]);
-    return useMemo(() => ({ navigate, navigateToResource, goBack, closeOverlay, canGoBack, resourceRelationshipDepth: currentResourceRelationshipDepth }), [navigate, navigateToResource, goBack, closeOverlay, canGoBack, currentResourceRelationshipDepth]);
+    return useMemo(() => ({ navigate, navigateToResource, goBack, closeOverlay, dismissZone, canGoBack, resourceRelationshipDepth: currentResourceRelationshipDepth }), [navigate, navigateToResource, goBack, closeOverlay, dismissZone, canGoBack, currentResourceRelationshipDepth]);
 }
 /**
  * Hook to control navigation in the application.
@@ -909,12 +968,13 @@ export function useNavigationController() {
  */
 export function useRouterSync(resourceType, operation, routePathParameters) {
     const location = useLocation();
+    const routerLocationAhead = useRouterLocationAheadOfCommit(location);
     const urlParameters = useParams();
     const { registry } = useResourceRegistry();
     const { emit } = useEventBus();
     const { getZoneState } = useNavigationState();
     const appScope = useAppScopeSafe();
-    const { navigationLayout: resolvedNavigationLayout } = useUI();
+    const { navigationLayout: resolvedNavigationLayout, currentBreakpoint } = useUI();
     const currentBrowserUrl = useMemo(() => NavigationUtils.buildBrowserUrl(location.pathname, location.search), [location.pathname, location.search]);
     const liveAppScopeContextIdentifiers = useMemo(() => appScope?.buildContextResourceIdentifiers?.() ?? {}, [appScope]);
     const liveAppScopeContextIdentifiersKey = useMemo(() => FrontendResourceUtils.buildContextResourceIdentifiersKey(liveAppScopeContextIdentifiers), [liveAppScopeContextIdentifiers]);
@@ -953,6 +1013,15 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
             return;
         }
         clearTransactionRetry();
+        // Guard: the router already left the URL this route committed with. The transaction above ends on
+        // `setTimeout(0)`, but a location transition can still be pending after it — so the committed URL here
+        // names the page the browser LEFT. Rebuilding from it re-pushes that page, and the always-mounted
+        // reconciler (reading the router) clears it again: the ping-pong measured on an organization switch.
+        // The effect re-runs when the committed location catches up. See `useRouterLocationAheadOfCommit`.
+        if (routerLocationAhead) {
+            logDebug('useRouterSync: SKIP — the router is ahead of the committed location', { committedUrl: currentBrowserUrl });
+            return;
+        }
         // Skip if we've already synced this path
         if (lastSyncedPath.current === currentBrowserUrl) {
             logDebug('useRouterSync: SKIP — already synced this path', { currentBrowserUrl });
@@ -990,7 +1059,10 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
         const prefersAdjacentZoneForDetail = depth === 0
             && hasSecondary
             && operation !== undefined
-            && NavigationUtils.layoutSplitsOperationFromPrimary(resolvedNavigationLayout, operation);
+            // The viewport goes in so a VIEWPORT-scoped override is reconstructed the way the click
+            // resolved it. `undefined` until the first measurement, which matches only the unconditional
+            // overrides — an unknown viewport is not a particular one.
+            && NavigationUtils.layoutSplitsOperationFromPrimary(resolvedNavigationLayout, operation, currentBreakpoint);
         const targetZone = NavigationUtils.resolveResourceTargetZone(depth, {
             hasSecondary,
             hasCompanion,
@@ -1014,6 +1086,45 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
             lastSyncedPath.current = currentBrowserUrl;
             return;
         }
+        /*
+         * ─── ANOTHER structural zone may already be showing this destination ────────────────────────
+         *
+         * The ownership question above is asked of the zone THIS HOOK computed, and that zone is
+         * derived from the URL alone — depth, plus whether the layout splits this operation out of
+         * primary. It cannot see where the content actually IS, so a record placed in a pane BY A CLICK
+         * and addressed by a bare URL is invisible to it: the hook computes PRIMARY, asks PRIMARY, is
+         * told no, and rebuilds the record there. Primary's top entry then changes, which makes the
+         * zone-dependency cleanup clear SECONDARY — so the pane the reader was using disappears and the
+         * record they opened in it is on the left instead.
+         *
+         * Measured on Wonder CRM (2026-09-24), and it is the defect reported as "click a linked
+         * resource inside the pane and it goes on the left, not on the right": a `contact` opened from
+         * inside a deal's pane lands in SECONDARY correctly (the pane's own `transitions.read` is
+         * `PUSH`, so `getStructuralSourceZone` keeps it there) and writes `/contact/:id` as the browser
+         * URL, because primary holds a deals LIST and is therefore URL-derivable — no hosted pane, no
+         * `?pane=`. That bare URL is what this hook then reconstructs from.
+         *
+         * `findStructuralRouteOwner` is the question worth asking instead — "which structural zone's
+         * VISIBLE entry does this URL address?" — and it already exists, scanning COMPANION → SECONDARY
+         * → PRIMARY by destination. If any zone owns the URL, the application is already showing what
+         * the URL names and there is nothing to reconstruct. A view-state-only difference
+         * (`searchDiffers`) is likewise not a rebuild: the always-mounted reconciler refreshes the
+         * entry's `urlPath` in place.
+         *
+         * This does NOT subsume the check above — that one is what lets the target zone REBUILD when it
+         * holds a different destination — it is the missing half: the other zones get a veto they never
+         * had.
+         */
+        const structuralOwner = NavigationUtils.findStructuralRouteOwner(currentBrowserUrl, getZoneState);
+        if (structuralOwner && structuralOwner.zone !== targetZone) {
+            logDebug('useRouterSync: SKIP — another structural zone already shows this destination', {
+                owningZone: structuralOwner.zone,
+                targetZone,
+                currentBrowserUrl,
+            });
+            lastSyncedPath.current = currentBrowserUrl;
+            return;
+        }
         // Build resource context from URL params
         // Pass routePathParameters for accurate FK field mapping (e.g., assignedToUserId → USERS)
         const urlContextIdentifiers = frontendResourceUtils.extractResourceIdentifiersFromUrlParams(urlParameters, registry, routePathParameters);
@@ -1086,6 +1197,7 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
     }, [
         location.pathname,
         location.search,
+        routerLocationAhead,
         urlParameters,
         resourceType,
         operation,
@@ -1100,6 +1212,7 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
         routePathParameters,
         resourceRoutePatterns,
         resolvedNavigationLayout,
+        currentBreakpoint,
         currentBrowserUrl,
         retryTick,
         scheduleTransactionRetry,
@@ -1127,6 +1240,7 @@ export function useRouterSync(resourceType, operation, routePathParameters) {
  */
 export function useViewRouterSync(viewRef, contentType) {
     const location = useLocation();
+    const routerLocationAhead = useRouterLocationAheadOfCommit(location);
     const { emit } = useEventBus();
     const { getZoneState } = useNavigationState();
     const { registry } = useResourceRegistry();
@@ -1143,6 +1257,10 @@ export function useViewRouterSync(viewRef, contentType) {
             return;
         }
         clearTransactionRetry();
+        // Guard: the router already left the URL this route committed with (a pending location transition).
+        // Rebuilding from it would restore the page the browser left. See `useRouterLocationAheadOfCommit`.
+        if (routerLocationAhead)
+            return;
         // Skip if already synced
         if (lastSyncedPath.current === currentUrl)
             return;
@@ -1250,7 +1368,7 @@ export function useViewRouterSync(viewRef, contentType) {
             transition: NavigationTransition.REPLACE,
         });
         lastSyncedPath.current = currentUrl;
-    }, [viewRef, contentType, emit, getZoneState, fullCustomViews, flowsActorsViews, registry, currentUrl, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
+    }, [viewRef, contentType, emit, getZoneState, fullCustomViews, flowsActorsViews, registry, currentUrl, routerLocationAhead, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
 }
 /**
  * Router sync for typed engine pages.
@@ -1261,6 +1379,7 @@ export function useViewRouterSync(viewRef, contentType) {
  */
 export function useEnginePageRouterSync(pageRef) {
     const location = useLocation();
+    const routerLocationAhead = useRouterLocationAheadOfCommit(location);
     const { emit } = useEventBus();
     const { getZoneState } = useNavigationState();
     const lastSyncedPath = useRef(null);
@@ -1274,6 +1393,10 @@ export function useEnginePageRouterSync(pageRef) {
             return;
         }
         clearTransactionRetry();
+        // Guard: the router already left the URL this route committed with (a pending location transition).
+        // Rebuilding from it would restore the page the browser left. See `useRouterLocationAheadOfCommit`.
+        if (routerLocationAhead)
+            return;
         if (lastSyncedPath.current === currentUrl)
             return;
         // Same per-zone, destination-based ownership as the view sync above.
@@ -1295,7 +1418,7 @@ export function useEnginePageRouterSync(pageRef) {
             transition: NavigationTransition.REPLACE,
         });
         lastSyncedPath.current = currentUrl;
-    }, [pageRef, emit, getZoneState, currentUrl, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
+    }, [pageRef, emit, getZoneState, currentUrl, routerLocationAhead, retryTick, scheduleTransactionRetry, clearTransactionRetry]);
 }
 /**
  * Persistent, always-mounted reconciler that maps browser **back/forward**
@@ -1318,8 +1441,9 @@ export function useEnginePageRouterSync(pageRef) {
  * mounted the same way: exactly once, at the navigation-runtime level.
  *
  * ── Contract ───────────────────────────────────────────────────────────────
- * On every `location` change (deferred while a navigation transaction is
- * mid-flight, so controller-driven URL updates are not double-handled):
+ * On every `location` change — read from the data router synchronously, so a URL the
+ * transition-committed location context coalesced away is still observed — (deferred while
+ * a navigation transaction is mid-flight, so controller-driven URL updates are not double-handled):
  *  1. Settings-hub URLs (`/settings*`) are owned by {@link useSettingsHubOverlaySync}
  *     (overlay layer) — skip them entirely so we never clobber the structural
  *     content sitting beneath the hub.
@@ -1345,7 +1469,9 @@ export function useEnginePageRouterSync(pageRef) {
  * hook only brings zone state up to match it, so there is no URL-write loop.
  */
 export function useStructuralZoneBackForwardSync() {
-    const location = useLocation();
+    // The router's own location, not the transition-committed one: a coalesced intermediate URL is what
+    // left `lastSyncedPath` behind and turned browser back into a no-op. See `useSynchronousBrowserLocation`.
+    const location = useSynchronousBrowserLocation();
     const { emit } = useEventBus();
     const { getZoneState } = useNavigationState();
     const lastSyncedPath = useRef(null);
@@ -1429,8 +1555,10 @@ export function useStructuralZoneBackForwardSync() {
             for (const zone of NAVIGATION_STRUCTURAL_ZONES) {
                 emit(FrontendEvents.NAVIGATION_CLEAR_ZONE, { zone });
             }
-            // Transaction auto-commits (setTimeout(0)); the route-mounted sync hooks
-            // skip while it is active and reconstruct on their transaction-aware retry.
+            // Transaction auto-commits (setTimeout(0)); the route-mounted sync hooks skip while it is
+            // active, and also while the router is ahead of their committed location
+            // (`useRouterLocationAheadOfCommit`). They rebuild when both have cleared: the transaction
+            // epoch or the committed location changing re-runs their effects.
         }
         lastSyncedPath.current = currentUrl;
     }, [currentUrl, location.pathname, emit, getZoneState, retryTick, scheduleRetry, clearRetry]);
@@ -1460,7 +1588,7 @@ export function useStructuralZoneBackForwardSync() {
  * Never writes the URL — the browser owns it; this only brings the zone up to match.
  */
 export function useHostedPaneRouteSync() {
-    const location = useLocation();
+    const location = useSynchronousBrowserLocation();
     const { emit } = useEventBus();
     const { getZoneState } = useNavigationState();
     const { registry } = useResourceRegistry();
@@ -1578,15 +1706,26 @@ export function useHostedPaneRouteSync() {
 /**
  * Matches the unified Settings Hub URL family.
  * `/settings` → `{ isSettings: true }`; `/settings/:sectionRef` →
- * `{ isSettings: true, sectionRef }`.
+ * `{ isSettings: true, sectionRef }`; `/settings/:sectionRef/:subTabRef` →
+ * `{ isSettings: true, sectionRef, subTabRef }`.
+ *
+ * The remainder is SPLIT rather than taken whole, which it was until 2026-09-17. That mattered
+ * before sub-tabs were addressable: `/settings/a/b` produced the section ref `"a/b"`, which
+ * matches no destination, so the hub silently fell back to its default section — a deep link with
+ * one segment too many opened Profile and said nothing. Splitting makes the second segment mean
+ * what it looks like it means, and anything beyond the second is still ignored.
  */
 function matchSettingsHubPath(pathname) {
     if (pathname === CommonRoutePaths.settings)
         return { isSettings: true };
     const prefix = `${CommonRoutePaths.settings}/`;
     if (pathname.startsWith(prefix)) {
-        const sectionRef = pathname.slice(prefix.length);
-        return { isSettings: true, sectionRef: sectionRef.length > 0 ? sectionRef : undefined };
+        const [sectionRef, subTabRef] = pathname.slice(prefix.length).split('/');
+        return {
+            isSettings: true,
+            sectionRef: sectionRef && sectionRef.length > 0 ? sectionRef : undefined,
+            subTabRef: subTabRef && subTabRef.length > 0 ? subTabRef : undefined,
+        };
     }
     return { isSettings: false };
 }
@@ -1618,7 +1757,7 @@ function matchSettingsHubPath(pathname) {
  * `ZoneContentRenderer fallback={routerChildren}`.
  */
 export function useSettingsHubOverlaySync() {
-    const location = useLocation();
+    const location = useSynchronousBrowserLocation();
     const { emit } = useEventBus();
     const { state } = useNavigationState();
     const { retryTick, scheduleRetry, clearRetry } = useTransactionAwareSyncRetry(location.pathname);
@@ -1640,29 +1779,35 @@ export function useSettingsHubOverlaySync() {
             return;
         }
         clearRetry();
-        const { isSettings, sectionRef } = matchSettingsHubPath(location.pathname);
+        const { isSettings, sectionRef, subTabRef } = matchSettingsHubPath(location.pathname);
         const overlayStack = state.overlay;
         const topEntry = overlayStack.length > 0 ? overlayStack[overlayStack.length - 1] : undefined;
         let topIsHub = false;
         let topSectionRef;
+        let topSubTabRef;
         if (topEntry && topEntry.content.contentType === NavigationContentType.SETTINGS_HUB) {
             topIsHub = true;
             topSectionRef = topEntry.content.sectionRef;
+            topSubTabRef = topEntry.content.subTabRef;
         }
         if (isSettings) {
-            // Already showing the hub at the requested section → converged, nothing to do.
-            if (topIsHub && topSectionRef === sectionRef) {
+            // Already showing the hub at the requested section AND sub-tab → converged, nothing to do.
+            // The sub-tab participates in convergence as well as the section: without it, moving between
+            // two tabs of the same section leaves the reconciler believing it is already correct, so the
+            // URL changes and the panel does not — which is the same class of inertness the section-level
+            // `config`-in-deps bug produced in the hub itself.
+            if (topIsHub && topSectionRef === sectionRef && topSubTabRef === subTabRef) {
                 lastEmitRef.current = null;
                 return;
             }
             const action = topIsHub ? FrontendEvents.NAVIGATION_REPLACE : FrontendEvents.NAVIGATION_PUSH;
-            const emitKey = `${action}|${location.pathname}|${sectionRef ?? ''}|${overlayStack.length}`;
+            const emitKey = `${action}|${location.pathname}|${sectionRef ?? ''}|${subTabRef ?? ''}|${overlayStack.length}`;
             if (lastEmitRef.current === emitKey)
                 return;
             lastEmitRef.current = emitKey;
             emit(action, {
                 zone: NavigationZone.OVERLAY,
-                content: { contentType: NavigationContentType.SETTINGS_HUB, sectionRef },
+                content: { contentType: NavigationContentType.SETTINGS_HUB, sectionRef, subTabRef },
                 urlPath: NavigationUtils.buildBrowserUrl(location.pathname, location.search),
                 stackEntryId: NavigationUtils.generateStackEntryId(),
                 initiator: { sourceZone: NavigationZone.OVERLAY },