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

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

@@ -1,10 +0,0 @@
-import type { NavigationZone } from './navigation.schemas';
-/**
- * Returns whether a given stack entry is the top (active) entry in its zone.
- *
- * Used by persistent stack rendering to determine visibility — non-top entries
- * are rendered with `display: none` to preserve their React state and avoid
- * re-fetching data on back-navigation.
- */
-export declare function useIsStackEntryActive(entryId: string, zone: NavigationZone): boolean;
-//# sourceMappingURL=useIsStackEntryActive.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"useIsStackEntryActive.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/useIsStackEntryActive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,GAAG,OAAO,CAKpF"}

package/dist/esm/core/navigation/useIsStackEntryActive.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useIsStackEntryActive.js","sourceRoot":"","sources":["../../../../../src/core/navigation/useIsStackEntryActive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAe,EAAE,IAAoB;IACzE,MAAM,EAAE,YAAY,EAAE,GAAG,kBAAkB,EAAE,CAAC;IAC9C,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,QAAQ,GAAG,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC7D,OAAO,QAAQ,EAAE,EAAE,KAAK,OAAO,CAAC;AAClC,CAAC","sourcesContent":["import { useNavigationState } from './useNavigationState';\nimport type { NavigationZone } from './navigation.schemas';\n\n/**\n * Returns whether a given stack entry is the top (active) entry in its zone.\n *\n * Used by persistent stack rendering to determine visibility — non-top entries\n * are rendered with `display: none` to preserve their React state and avoid\n * re-fetching data on back-navigation.\n */\nexport function useIsStackEntryActive(entryId: string, zone: NavigationZone): boolean {\n  const { getZoneState } = useNavigationState();\n  const zoneState = getZoneState(zone);\n  const topEntry = zoneState.stack[zoneState.stack.length - 1];\n  return topEntry?.id === entryId;\n}\n"]}

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

@@ -1,23 +1,26 @@
 /**
- * useNavigationController Hook
+ * The navigation CONTROLLER: what a click does.
  *
- * The main hook for triggering navigation in the application.
- * Components (sidebar, toolbar, list items, etc.) use this to navigate.
+ * `navigate()` resolves a navigation request through `navigationPolicyResolver`, applies the
+ * outcome (clean breaks, in-place hand-off, promote, the cascade) and emits the placement. It is the
+ * click path; the URL path lives in `useNavigationRouterSync.ts`.
  *
- * The controller:
- * 1. Receives navigation requests
- * 2. Resolves the navigation target using NavigationPolicyResolver
- * 3. Emits appropriate navigation events (PUSH, REPLACE, etc.)
- * 4. Optionally updates the browser URL for addressable operations
+ * ## The split, 2026-09-25
  *
- * Also includes URL-to-state synchronization (merged from RouterNavigationSync):
- * - useRouterSync hook syncs external URL changes with navigation state
- * - Uses NavigationSource to track origin and avoid sync loops
+ * This module was 2,322 lines holding click resolution, URL reconciliation, the ancestor cascade,
+ * clean breaks, dismiss and the emit bridge. The seam was measured rather than guessed: the
+ * router-sync half used exactly THREE symbols from the controller half — `logDebug` and the two
+ * cascade functions — so it came out at a cost of two shared modules and no behaviour change.
+ *
+ * | module | answers |
+ * |---|---|
+ * | this one | what a CLICK does |
+ * | `useNavigationRouterSync.ts` | what a URL means — deep links, back/forward, hosted panes |
+ * | `navigation-cascade.ts` | what fills the zones nobody clicked |
+ * | `navigation-controller-internals.ts` | the debug channel and the browser-URL write |
  */
-import type { EnginePageRef } from '../../core/config/launcher-items.frontend.schemas';
-import { NavigationZone, NavigationContent, NavigationContentType, NavigationInitiatorContext } from './navigation.schemas';
-import { NavigationZoneName, ResourceConfiguration_Operation_UrlParameterInfo, type TransitionConfig } from '@wildo-ai/saas-models';
-import type { FrontendResourceConfiguration_Operation } from '../../core/resources/resources.frontend.schemas';
+import { NavigationZone, NavigationContent, NavigationInitiatorContext } from './navigation.schemas';
+import { NavigationZoneName, type TransitionConfig } from '@wildo-ai/saas-models';
 import { FrontendResourceOperationContext } from '../../core/resources/resources.frontend.schemas';
 /**
  * Navigation request options
@@ -73,6 +76,16 @@ export interface NavigationController {
      */
     navigateToResource: (resourceContext: FrontendResourceOperationContext, initiator: NavigationInitiatorContext, urlPath?: string, transitionOverride?: TransitionConfig) => void;
     goBack: (zone?: NavigationZone) => void;
+    /**
+     * Close the TOP overlay — the dialog the reader is dismissing — and reveal whatever it was opened
+     * over, including another overlay.
+     *
+     * It used to clear the whole overlay stack. Overlays do stack (an Edit opened from a Read shown as
+     * an overlay), so Cancel, Escape, the close button or a click outside discarded both layers where
+     * the reader had dismissed one. Every caller — the dialog chrome, the create and update surfaces,
+     * the SAML wizard — means "close this dialog". Clearing every overlay is a reset, not a dismissal,
+     * and the one path that wants it (switching organization) clears the stack directly.
+     */
     closeOverlay: () => void;
     /** Close an adjacent structural pane outright — see the implementation for why this is not `goBack`. */
     dismissZone: (zone: NavigationZoneName) => void;
@@ -104,146 +117,4 @@ export declare const ScopedNavigationControllerContext: import("react").Context<
  */
 export declare function useGlobalNavigationController(): NavigationController;
 export declare function useNavigationController(): NavigationController;
-/**
- * Hook to sync React Router URL changes with navigation state.
- *
- * When a user navigates via URL (bookmark, direct link, refresh),
- * this hook ensures the navigation state is updated accordingly.
- *
- * Uses NavigationSource to detect controller-initiated navigation:
- * - If top entry has source=CONTROLLER and matches current URL, skip sync
- * - Otherwise, this is an external URL change, sync it with source=URL_SYNC
- *
- * @param resourceType - The resource type for the current route
- * @param operation - The operation configuration
- * @param routePathParameters - Route path parameters with relationship info for deterministic URL selection
- */
-export declare function useRouterSync(resourceType: string | undefined, operation: FrontendResourceConfiguration_Operation | undefined, routePathParameters?: ResourceConfiguration_Operation_UrlParameterInfo[]): void;
-/**
- * Hook to sync view routes (composite, chart, custom, flows-actors) with navigation state.
- *
- * Unlike useRouterSync (which handles resource operations), this handles non-resource
- * content types that only need a viewRef and contentType. Views are always depth 0
- * (placed in PRIMARY zone), have no parent chain, and no cascading.
- *
- * On refresh / deep link, this hook populates the PRIMARY zone's navigation stack
- * with the correct view content so that:
- * - ZoneContentRenderer renders the view
- * - Sidebar active state reflects the current view
- * - goBack() works correctly
- *
- * @param viewRef - The view reference from the URL
- * @param contentType - The navigation content type (COMPOSITE_VIEW, CHART_VIEW, etc.)
- */
-export declare function useViewRouterSync(viewRef: string | undefined, contentType: NavigationContentType): void;
-/**
- * Router sync for typed engine pages.
- *
- * Engine pages are app-level routes that should still populate the PRIMARY stack
- * so launcher active-state and back-navigation remain coherent after refresh or
- * direct URL entry.
- */
-export declare function useEnginePageRouterSync(pageRef: EnginePageRef | undefined): void;
-/**
- * Persistent, always-mounted reconciler that maps browser **back/forward**
- * (history popstate) onto the STRUCTURAL zone stacks (PRIMARY / SECONDARY /
- * COMPANION).
- *
- * ── Why this exists (the gap it closes) ────────────────────────────────────
- * Structural-zone content is rendered from the navigation **stack state**, not
- * from the router `<Outlet/>`: `ZoneContentRenderer` renders `routerChildren`
- * (the Outlet, which hosts `useRouterSync` / `useViewRouterSync` /
- * `useEnginePageRouterSync`) ONLY when a zone's stack is empty. In-session the
- * PRIMARY stack is never empty, so the Outlet — and with it the per-route
- * URL→state sync hooks — is unmounted. Controller-driven navigation (sidebar,
- * links, Home) mutates the stack directly via events, so it is unaffected. But
- * a browser back/forward only changes `location`; with no mounted sync hook
- * observing it, the stack was never reconciled — the URL (and the
- * `useLocation`-derived sidebar highlight) moved while the rendered content
- * stayed on the previous entry. This is the structural-zone analogue of what
- * {@link useSettingsHubOverlaySync} already does for the overlay, and it is
- * mounted the same way: exactly once, at the navigation-runtime level.
- *
- * ── Contract ───────────────────────────────────────────────────────────────
- * 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.
- *  2. If the URL addresses the DESTINATION already at the visible top of a
- *     structural zone → no rebuild. When it differs only in VIEW STATE
- *     (`?section=`), the entry's `urlPath` is refreshed in place through
- *     `NAVIGATION_URL_PATH_UPDATED` — same id, same content. Under a composed
- *     URL (`?pane=`, see `useHostedPaneRouteSync`) the host's stamp on PRIMARY
- *     and the pane's on SECONDARY are both refreshed.
- *  3. If the URL matches an entry still sitting LOWER in a zone's backstack →
- *     restore it with a pure `NAVIGATION_POP` to that entry. This is the common
- *     back-button case; popping preserves the revealed entry's live state
- *     (scroll, expanded rows) instead of rebuilding it. A composed URL is
- *     matched against the SECONDARY backstack while PRIMARY addresses the host.
- *  4. Otherwise the URL is not in any structural stack (forward to a
- *     previously-popped entry, or a manual URL edit without reload) → clear the
- *     structural zones inside a transaction so the Outlet fallback remounts and
- *     the existing route-mounted sync hooks reconstruct from the URL. This
- *     reuses the single URL→state derivation rather than duplicating it here,
- *     matching the documented URL-first reconstruction model.
- *
- * We never call `routerNavigate` here — the browser already owns the URL; this
- * hook only brings zone state up to match it, so there is no URL-write loop.
- */
-export declare function useStructuralZoneBackForwardSync(): void;
-/**
- * Persistent, always-mounted reconciler that keeps a HOSTED PANE in step with the URL.
- *
- * A hosted pane is a SECONDARY resource destination opened beside a primary whose own address no
- * resource URL implies — a composite view, a canvas, a chart, an engine page. The browser URL is
- * the host's, carrying the pane as `?pane=` (see `HOSTED_PANE_QUERY_PARAM`), so the pane is never
- * the router's route and no route element ever mounts a sync hook for it. This hook is that sync,
- * mounted once at the navigation-runtime level like the two reconcilers beside it.
- *
- * Contract, on every `location` change (deferred while a transaction is committing; settings-hub
- * URLs are left to the overlay reconciler, the structural zones beneath the hub untouched):
- *  1. No `pane` in the URL and the secondary shows a hosted pane → the pane left the URL (browser
- *     back, the host's `goBack`) → clear SECONDARY.
- *  2. The pane addresses what the secondary already shows → nothing to do (a view-state change
- *     was refreshed by the back/forward reconciler).
- *  3. The pane addresses an entry lower in the secondary backstack → POP to it.
- *  4. Otherwise resolve the pane's URL against the same route table `AppRouter` registers, build
- *     its resource context exactly as `useRouterSync` would from the router's params, and place
- *     it in SECONDARY as a SPLIT flagged `hostedPane`. Placed regardless of whether PRIMARY has
- *     landed yet: the dependency cleanup keeps a hosted pane beside a non-resource primary, so
- *     the two halves of a deep link may arrive in either order.
- *
- * Never writes the URL — the browser owns it; this only brings the zone up to match.
- */
-export declare function useHostedPaneRouteSync(): void;
-/**
- * Persistent, idempotent reconciler that keeps the Settings Hub overlay in sync
- * with the URL. The hub is overlay-rendered but URL-addressable, and the URL is
- * its single source of truth.
- *
- * Mounted ONCE at the navigation-runtime level (NOT per-route, NOT in the
- * `/settings` route element). This is deliberate: a route-mounted sync that
- * pushed on mount and tore down on unmount would, under React StrictMode, have
- * its unmount-teardown double-invoked and close the just-pushed overlay during
- * in-session navigation — the exact "refresh works, in-session click does not"
- * failure mode. A persistent reconciler reads the current URL + overlay state
- * and converges to the correct state on every run, so StrictMode double-invokes
- * and the `state.overlay` dependency re-running are both harmless no-ops.
- *
- * Contract:
- * - On `/settings` / `/settings/:sectionRef`: ensure the overlay top is a
- *   `SETTINGS_HUB` at that section (push when absent, replace on section change,
- *   no-op when already correct).
- * - Off the settings URL: close the hub if it is the top overlay — covers
- *   dismiss-driven navigation, browser back/forward, and app-level navigation
- *   away from settings, all through one URL-driven path.
- *
- * The PRIMARY surface beneath the hub is the route element's render (home as the
- * `routerChildren` fallback on a cold deep-link) or the persisted PRIMARY stack
- * (in-session) — see `NavigationContentAreas`'
- * `ZoneContentRenderer fallback={routerChildren}`.
- */
-export declare function useSettingsHubOverlaySync(): void;
 //# sourceMappingURL=useNavigationController.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useNavigationController.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/useNavigationController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAUH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iEAAiE,CAAC;AAoBrG,OAAO,EACL,cAAc,EAEd,iBAAiB,EACjB,qBAAqB,EACrB,0BAA0B,EAK3B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAEL,kBAAkB,EAIlB,gDAAgD,EAGhD,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAA6B,uCAAuC,EAAE,MAAM,+DAA+D,CAAC;AASxJ,OAAO,EAAE,gCAAgC,EAAE,MAAM,+DAA+D,CAAC;AAsUjH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,0BAA0B,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,kBAAkB,EAAE,CAAE,eAAe,EAAE,gCAAgC,EAAE,SAAS,EAAE,0BAA0B,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,gBAAgB,KAAM,IAAI,CAAC;IAElL,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACxC,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,wGAAwG;IACxG,WAAW,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD,SAAS,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;IAE7C;;OAEG;IACH,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,+CAAmD,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,oBAAoB,CAqsBpE;AA8CD,wBAAgB,uBAAuB,IAAI,oBAAoB,CAI9D;AAQD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,uCAAuC,GAAG,SAAS,EAC9D,mBAAmB,CAAC,EAAE,gDAAgD,EAAE,GACvE,IAAI,CAsTN;AAOD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,qBAAqB,GACjC,IAAI,CAmJN;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,IAAI,CAqDhF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,gCAAgC,IAAI,IAAI,CAwGvD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CA0I7C;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CA8EhD"}
+{"version":3,"file":"useNavigationController.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/useNavigationController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAkCH,OAAO,EACL,cAAc,EACd,iBAAiB,EAEjB,0BAA0B,EAI3B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,kBAAkB,EAIlB,KAAK,gBAAgB,EACtB,MAAM,uBAAuB,CAAC;AAY/B,OAAO,EAAE,gCAAgC,EAAE,MAAM,+DAA+D,CAAC;AA+BjH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,iBAAiB,CAAC;IAC3B,SAAS,EAAE,0BAA0B,CAAC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0BAA0B,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD;;;;;OAKG;IACH,sBAAsB,CAAC,EAAE,gBAAgB,CAAC;IAC1C;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,kBAAkB,EAAE,CAAE,eAAe,EAAE,gCAAgC,EAAE,SAAS,EAAE,0BAA0B,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,gBAAgB,KAAM,IAAI,CAAC;IAElL,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IACxC;;;;;;;;;OASG;IACH,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,wGAAwG;IACxG,WAAW,EAAE,CAAC,IAAI,EAAE,kBAAkB,KAAK,IAAI,CAAC;IAChD,SAAS,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC;IAE7C;;OAEG;IACH,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,+CAAmD,CAAC;AAElG;;;;;;GAMG;AACH,wBAAgB,6BAA6B,IAAI,oBAAoB,CAm1BpE;AA8CD,wBAAgB,uBAAuB,IAAI,oBAAoB,CAI9D"}