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

package/dist/esm/core/navigation/NavigationContext.d.ts

@@ -14,6 +14,7 @@
 import React from 'react';
 import { NavigationZoneName } from '@wildo-ai/saas-models';
 import { NavigationState, NavigationZoneState, NavigationStackEntry, NavigationZone, NavigationContent } from './navigation.schemas';
+import type { CollapsibleZoneSituation } from './zone-collapse-migration';
 export interface NavigationContextType {
     state: NavigationState;
     getZoneState: (zone: NavigationZone) => NavigationZoneState;
@@ -84,6 +85,13 @@ export interface NavigationContextType {
      */
     contentAreaWidth: number | undefined;
     setContentAreaWidth: (width: number | undefined) => void;
+    /**
+     * Enforce "a collapsed zone holds nothing" for every collapsible zone in ONE state update — see
+     * `zone-collapse-migration.ts`. Applied against the latest state rather than the last render's, so
+     * two zones collapsing or returning together are one decision, and entries move as objects so no
+     * field is lost on the way. A no-op (no re-render) when nothing has to move.
+     */
+    reconcileCollapsedZones: (situations: CollapsibleZoneSituation[]) => void;
 }
 export declare const NavigationContext: React.Context<NavigationContextType | undefined>;
 interface NavigationProviderProps {

package/dist/esm/core/navigation/NavigationContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NavigationContext.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/NavigationContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAA2E,MAAM,OAAO,CAAC;AAIhG,OAAO,EAAwB,kBAAkB,EAAwB,MAAM,uBAAuB,CAAC;AAWvG,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EAEpB,cAAc,EACd,iBAAiB,EAGlB,MAAM,sBAAsB,CAAC;AAgB9B,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,eAAe,CAAC;IAEvB,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,mBAAmB,CAAC;IAC5D,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,MAAM,CAAC;IAC/C,aAAa,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACvE,WAAW,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,oBAAoB,GAAG,SAAS,CAAC;IACxE,aAAa,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;IAEjD,yBAAyB,EAAE,MAAM,CAAC;IAClC,sBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAErD;;;;OAIG;IACH,WAAW,EAAE,kBAAkB,CAAC;IAChC,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAEnD;;;;;;;;;;OAUG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,iBAAiB,EAAE,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,CAAC;IAE7D;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAA+D,CAAC;AAM/I,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CAq1B5F"}
+{"version":3,"file":"NavigationContext.d.ts","sourceRoot":"","sources":["../../../../src/core/navigation/NavigationContext.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAA2E,MAAM,OAAO,CAAC;AAIhG,OAAO,EAAwB,kBAAkB,EAAwB,MAAM,uBAAuB,CAAC;AAYvG,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EAEpB,cAAc,EACd,iBAAiB,EAGlB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAgB1E,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,eAAe,CAAC;IAEvB,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,mBAAmB,CAAC;IAC5D,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,MAAM,CAAC;IAC/C,aAAa,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,iBAAiB,GAAG,SAAS,CAAC;IACvE,WAAW,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,oBAAoB,GAAG,SAAS,CAAC;IACxE,aAAa,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;IAEjD,yBAAyB,EAAE,MAAM,CAAC;IAClC,sBAAsB,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAErD;;;;OAIG;IACH,WAAW,EAAE,kBAAkB,CAAC;IAChC,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAEnD;;;;;;;;;;OAUG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAElE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,cAAc,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC1C,iBAAiB,EAAE,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,KAAK,IAAI,CAAC;IAE7D;;;;;;;;;;OAUG;IACH,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,KAAK,IAAI,CAAC;IAEzD;;;;;OAKG;IACH,uBAAuB,EAAE,CAAC,UAAU,EAAE,wBAAwB,EAAE,KAAK,IAAI,CAAC;CAC3E;AAED,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAA+D,CAAC;AAM/I,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,EAAE,uBAAuB,GAAG,KAAK,CAAC,YAAY,CA07B5F"}

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

@@ -16,9 +16,11 @@ import { createContext, useState, useEffect, useCallback, useMemo, useRef } from
 import { useLocation, useNavigate } from 'react-router-dom';
 import { useEventBus } from '../../core/events/useEventBus.js';
 import { ResourcePrimaryScope, NavigationZoneName, NavigationTransition } from '@wildo-ai/saas-models';
+import { zoneMutationTargetIndex } from './zone-visible-entry.js';
 import { NavigationUtils } from './navigation.utils.js';
 import { FrontendEvents, } from '../../core/events/events.frontend.schemas.js';
 import { NavigationSource, NavigationZone, NavigationContentType, NAVIGATION_STRUCTURAL_ZONES, } from './navigation.schemas.js';
+import { reconcileCollapsedZones } from './zone-collapse-migration.js';
 import { useResourceRegistry } from '../../core/resources/useResourceRegistry.js';
 import { frontendResourceUtils } from '../../core/resources/frontend-resource.utils.js';
 import { useAppScopeSafe } from '../../core/scope/useAppScope.js';
@@ -58,21 +60,54 @@ export function NavigationProvider({ children }) {
                     ...prev.zones[zone],
                     stack: [...prev.zones[zone].stack, entry],
                     isVisible: true,
+                    /*
+                     * A pushed entry in a TABBED zone becomes the active tab. `activeTabId` is only ever written
+                     * for a tabbed zone, so its presence is the reducer's signal, as in `zoneMutationTargetIndex`.
+                     * Until 2026-09-25 a push left it alone: once a reader had clicked any tab, every record
+                     * they opened afterwards landed as a tab that was not shown — the tab bar grew and the
+                     * screen did not change. Absent, the renderer already shows the top, which is the new entry.
+                     */
+                    activeTabId: prev.zones[zone].activeTabId !== undefined ? entry.id : undefined,
                 },
             },
         }));
     }, []);
+    /**
+     * Replace what the zone is SHOWING.
+     *
+     * In a `SINGLE` zone that is the top of the stack. In a `TABBED` zone it is the ACTIVE TAB, which
+     * is not the same entry — and until 2026-09-25 this always replaced the top, so with three tabs
+     * open and tab 0 on screen a REPLACE silently overwrote tab 2 and the visible tab did not change.
+     * The enum's own contract says "`replace` replaces the ACTIVE TAB's content".
+     *
+     * The reducer does not read the layout, so it does not ask for the content model — it reads
+     * `activeTabId`, which is written for a TABBED zone and for nothing else. Absent, the visible entry
+     * is the top of the stack, which is the SINGLE contract exactly.
+     */
     const replaceEntry = useCallback((zone, entry) => {
         logDebug('replaceEntry', { zone, entryId: entry.id, contentType: entry.content.contentType, urlPath: entry.urlPath, source: entry.navigationSource });
         setState(prev => {
             const zoneState = prev.zones[zone];
             logDebug('replaceEntry: previous stack depth', { zone, previousStackDepth: zoneState.stack.length });
-            const newStack = zoneState.stack.length > 0
-                ? [...zoneState.stack.slice(0, -1), entry]
-                : [entry];
+            if (zoneState.stack.length === 0) {
+                return { ...prev, zones: { ...prev.zones, [zone]: { ...zoneState, stack: [entry], isVisible: true } } };
+            }
+            const visibleIndex = zoneMutationTargetIndex(zoneState.stack, zoneState.activeTabId);
+            const replacedTheActiveTab = zoneState.activeTabId !== undefined
+                && zoneState.stack[visibleIndex]?.id === zoneState.activeTabId;
+            const newStack = zoneState.stack.map((existing, index) => (index === visibleIndex ? entry : existing));
             return {
                 ...prev,
-                zones: { ...prev.zones, [zone]: { ...zoneState, stack: newStack, isVisible: true } },
+                zones: {
+                    ...prev.zones,
+                    [zone]: {
+                        ...zoneState,
+                        stack: newStack,
+                        isVisible: true,
+                        // The replacement becomes the active tab; otherwise the zone shows an entry that is gone.
+                        activeTabId: replacedTheActiveTab ? entry.id : zoneState.activeTabId,
+                    },
+                },
             };
         });
     }, []);
@@ -82,11 +117,33 @@ export function NavigationProvider({ children }) {
             if (zoneState.stack.length === 0)
                 return prev;
             let newStack;
+            let nextActiveTabId = zoneState.activeTabId;
             if (toEntryId) {
                 const targetIndex = zoneState.stack.findIndex(e => e.id === toEntryId);
                 newStack = targetIndex >= 0
                     ? zoneState.stack.slice(0, targetIndex + 1)
                     : zoneState.stack.slice(0, -1);
+                nextActiveTabId = zoneState.activeTabId !== undefined
+                    ? newStack[newStack.length - 1]?.id
+                    : zoneState.activeTabId;
+            }
+            else if (zoneState.activeTabId !== undefined) {
+                /*
+                 * ─── In a TABBED zone, back leaves the ACTIVE tab ───────────────────────────────────────
+                 *
+                 * `NavigationTransition.PUSH` documents this as "back navigation pops the stack OR switches
+                 * to the previous tab", and until 2026-09-25 it always sliced the LAST entry — so with tab 0
+                 * on screen, back removed tab 2 and the reader saw nothing change. Removing the active tab
+                 * and showing its neighbour is what "switches to the previous tab" means.
+                 */
+                const activeIndex = zoneMutationTargetIndex(zoneState.stack, zoneState.activeTabId);
+                if (zoneState.stack[activeIndex]?.id !== zoneState.activeTabId) {
+                    newStack = zoneState.stack.slice(0, -1);
+                }
+                else {
+                    newStack = zoneState.stack.filter((_, index) => index !== activeIndex);
+                    nextActiveTabId = newStack[Math.max(0, activeIndex - 1)]?.id;
+                }
             }
             else {
                 newStack = zoneState.stack.slice(0, -1);
@@ -98,32 +155,30 @@ export function NavigationProvider({ children }) {
                     [zone]: {
                         ...zoneState,
                         stack: newStack,
+                        activeTabId: newStack.length > 0 ? nextActiveTabId : undefined,
                         isVisible: newStack.length > 0 || zone === NavigationZoneName.PRIMARY,
                     },
                 },
             };
         });
     }, []);
-    const closeEntry = useCallback((zone, entryId) => {
-        setState(prev => {
-            const zoneState = prev.zones[zone];
-            if (entryId) {
-                const newStack = zoneState.stack.filter(e => e.id !== entryId);
-                return {
-                    ...prev,
-                    zones: { ...prev.zones, [zone]: { ...zoneState, stack: newStack, isVisible: newStack.length > 0 } },
-                };
-            }
-            return {
-                ...prev,
-                zones: { ...prev.zones, [zone]: { ...zoneState, stack: [], isVisible: false } },
-            };
-        });
-    }, []);
-    const clearZoneEntries = useCallback((zone) => {
+    const clearZoneEntries = useCallback((zone, preservePersistent = false) => {
         logDebug('clearZoneEntries called', { zone });
         setState(prev => {
             logDebug('clearZoneEntries: previous stack depth', { zone, previousStackDepth: prev.zones[zone].stack.length });
+            /*
+             * A fresh start asks to keep a PERSISTENT pane — see `emitFreshStartNavigationCleanup`. Read
+             * here because this is the only layer that can see the zone's top entry; the emitter has no
+             * state. The whole stack below a persistent top is dropped: what persists is the reference the
+             * reader is keeping open, not the history of how they got to it.
+             */
+            const persistentTop = prev.zones[zone].stack[prev.zones[zone].stack.length - 1];
+            if (preservePersistent && persistentTop?.persistent) {
+                logDebug('clearZoneEntries: PERSISTENT top kept across the fresh start', { zone });
+                return prev.zones[zone].stack.length === 1
+                    ? prev
+                    : { ...prev, zones: { ...prev.zones, [zone]: { ...prev.zones[zone], stack: [persistentTop] } } };
+            }
             return {
                 ...prev,
                 zones: {
@@ -185,6 +240,7 @@ export function NavigationProvider({ children }) {
                 ephemeral: payload.ephemeral,
                 hostedPane: payload.hostedPane,
                 collapsedFromZone: payload.collapsedFromZone,
+                persistent: payload.persistent,
             };
             if (payload.zone === NavigationZone.OVERLAY) {
                 pushOverlay(entry);
@@ -211,6 +267,7 @@ export function NavigationProvider({ children }) {
                 ephemeral: payload.ephemeral,
                 hostedPane: payload.hostedPane,
                 collapsedFromZone: payload.collapsedFromZone,
+                persistent: payload.persistent,
             };
             if (payload.zone === NavigationZone.OVERLAY) {
                 // Replace the top of the overlay stack
@@ -247,15 +304,23 @@ export function NavigationProvider({ children }) {
                     clearOverlay();
                 }
             }
-            else {
-                closeEntry(payload.zone, payload.stackEntryId);
-            }
+            /*
+             * There is no structural branch, and the type is what says so: `FrontendEvent_NavigationClose`
+             * declares `zone: z.literal(OVERLAY)` and the bus `safeParse`s every payload, so a structural
+             * zone cannot reach here. A branch existed until 2026-09-25 calling a `closeEntry` primitive
+             * that was therefore unreachable — and that primitive was the ONE stack mutator without the
+             * "PRIMARY is always visible" guard its two siblings carry (`popEntry`, `clearZoneEntries`), so
+             * widening the schema would have produced an invisible primary zone. The `as NavigationZoneName`
+             * cast on the way in is what hid it: it widened a type that can only ever be OVERLAY.
+             *
+             * Clearing a structural zone is `NAVIGATION_CLEAR_ZONE`, just below.
+             */
         });
-    }, [on, closeEntry, popOverlay, clearOverlay]);
+    }, [on, popOverlay, clearOverlay]);
     useEffect(() => {
         return on(FrontendEvents.NAVIGATION_CLEAR_ZONE, (payload) => {
-            logDebug('NAVIGATION_CLEAR_ZONE received', { zone: payload.zone });
-            clearZoneEntries(payload.zone);
+            logDebug('NAVIGATION_CLEAR_ZONE received', { zone: payload.zone, preservePersistent: payload.preservePersistent });
+            clearZoneEntries(payload.zone, payload.preservePersistent === true);
         });
     }, [on, clearZoneEntries]);
     /*
@@ -347,6 +412,16 @@ export function NavigationProvider({ children }) {
         // the relationship-aware rule below would clear the hosted pane on every tab click.
         if (prevTopEntry && prevTopEntry.id === currTopEntry.id)
             return;
+        /*
+         * A top that went HOME is not a navigation. When a collapsed pane is given back, the entries
+         * primary was holding for it leave primary's stack, so its top changes — and read as a
+         * navigation, that change would judge the returning panes against the list now on top and could
+         * close the very companion that is coming back. The reader navigated nowhere; the viewport
+         * widened. (`zone-collapse-migration.ts`)
+         */
+        if (prevTopEntry?.collapsedFromZone !== undefined && !currPrimary.stack.some(entry => entry.id === prevTopEntry.id)) {
+            return;
+        }
         // If PRIMARY still points at the exact same resource instance, dependency cleanup
         // can be skipped. Resource type alone is not enough once duplicate edges and
         // same-type parent chains are in play.
@@ -372,14 +447,23 @@ export function NavigationProvider({ children }) {
                  */
                 const isRelevant = (secondaryTop.hostedPane === true
                     && currTopEntry.content.contentType !== NavigationContentType.RESOURCE_OPERATION) || NavigationUtils.isContentRelevantToParent(secondaryTop.content, currTopEntry.content);
-                if (!isRelevant) {
+                if (!isRelevant && secondaryTop.persistent) {
+                    logDebug('Zone dependency cleanup: SECONDARY is PERSISTENT — kept across the primary change', {
+                        paneResourceType: secondaryTop.content.contentType === NavigationContentType.RESOURCE_OPERATION
+                            ? secondaryTop.content.resourceContext.resourceType
+                            : secondaryTop.content.contentType,
+                    });
+                }
+                else if (!isRelevant) {
                     logDebug('Zone dependency cleanup: SECONDARY stale, clearing', {
                         primaryResourceType: currTopEntry.content.contentType === NavigationContentType.RESOURCE_OPERATION
                             ? currTopEntry.content.resourceContext.resourceType
                             : currTopEntry.content.contentType,
                     });
                     clearZoneEntries(NavigationZoneName.SECONDARY);
-                    if (state.zones[NavigationZoneName.COMPANION].stack.length > 0) {
+                    const companionStack = state.zones[NavigationZoneName.COMPANION].stack;
+                    const companionTopEntry = companionStack[companionStack.length - 1];
+                    if (companionStack.length > 0 && !companionTopEntry?.persistent) {
                         companionHandled = true;
                         clearZoneEntries(NavigationZoneName.COMPANION);
                     }
@@ -391,7 +475,25 @@ export function NavigationProvider({ children }) {
             const companionTop = companionState.stack[companionState.stack.length - 1];
             if (companionTop) {
                 const isRelevant = NavigationUtils.isContentRelevantToParent(companionTop.content, currTopEntry.content);
-                if (!isRelevant) {
+                /*
+                 * ─── A PERSISTENT pane is exempt from the DEPENDENCY cleanup ────────────────────────────
+                 *
+                 * That is what `TransitionConfig.persistent` has always promised — "the split zone persists
+                 * when the source zone's content changes" — and until 2026-09-25 the modifier only chose
+                 * COMPANION as the target zone, so the documented reference-panel pattern (a thread, a
+                 * terminal, a doc kept open while you move around) closed on the first unrelated navigation.
+                 *
+                 * Exempt from THIS cleanup only. An explicit dismiss, a clean break and a direct clear all
+                 * still close it: persistence means "do not close because the page beneath changed".
+                 */
+                if (!isRelevant && companionTop.persistent) {
+                    logDebug('Zone dependency cleanup: COMPANION is PERSISTENT — kept across the primary change', {
+                        paneResourceType: companionTop.content.contentType === NavigationContentType.RESOURCE_OPERATION
+                            ? companionTop.content.resourceContext.resourceType
+                            : companionTop.content.contentType,
+                    });
+                }
+                else if (!isRelevant) {
                     logDebug('Zone dependency cleanup: COMPANION stale, clearing', {
                         primaryResourceType: currTopEntry.content.contentType === NavigationContentType.RESOURCE_OPERATION
                             ? currTopEntry.content.resourceContext.resourceType
@@ -759,6 +861,9 @@ export function NavigationProvider({ children }) {
             };
         });
     }, []);
+    const reconcileCollapsedZonesCallback = useCallback((situations) => {
+        setState(prev => reconcileCollapsedZones(prev, situations));
+    }, []);
     const contextValue = useMemo(() => ({
         state,
         getZoneState: getZoneStateCallback,
@@ -775,6 +880,7 @@ export function NavigationProvider({ children }) {
         setEmphasizedZone,
         contentAreaWidth,
         setContentAreaWidth,
+        reconcileCollapsedZones: reconcileCollapsedZonesCallback,
     }), [
         state,
         getZoneStateCallback,
@@ -788,6 +894,7 @@ export function NavigationProvider({ children }) {
         focusedZone,
         emphasizedZone,
         contentAreaWidth,
+        reconcileCollapsedZonesCallback,
     ]);
     return (_jsx(NavigationContext.Provider, { value: contextValue, children: children }));
 }