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

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

@@ -0,0 +1,174 @@
+/**
+ * URL RECONCILIATION: what a browser URL means for the zone state.
+ *
+ * Six hooks, one invariant — **the URL names exactly one zone's content, and the zones around it are
+ * reconstructed from that**. They cover the deep link and refresh (`useRouterSync`,
+ * `useViewRouterSync`, `useEnginePageRouterSync`), the browser's own back and forward across
+ * structural zones (`useStructuralZoneBackForwardSync`), the `?pane=` hosted pane
+ * (`useHostedPaneRouteSync`) and the settings-hub overlay (`useSettingsHubOverlaySync`).
+ *
+ * Split out of `useNavigationController.ts` on 2026-09-25. That module held the click path and this
+ * one in 2,322 lines, and reasoning about either in isolation meant holding both; the seam was
+ * measured rather than guessed — this half used exactly THREE symbols from the other (`logDebug` and
+ * the two cascade functions), which is what made the split worth doing.
+ *
+ * Nothing here decides a PLACEMENT POLICY. Where content goes is `navigationPolicyResolver`'s
+ * answer, read through `NavigationUtils.resolveResourceTargetZone`; these hooks decide only which
+ * content the URL is currently naming and what has to be rebuilt around it.
+ */
+import type { EnginePageRef } from '../../core/config/launcher-items.frontend.schemas';
+import { NavigationContentType } from './navigation.schemas';
+import { ResourceConfiguration_Operation_UrlParameterInfo } from '@wildo-ai/saas-models';
+import type { FrontendResourceConfiguration_Operation } from '../../core/resources/resources.frontend.schemas';
+/**
+ * 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.
+ *
+ * Placed into SECONDARY even when SECONDARY is collapsed at this width. This hook read the layout
+ * and the breakpoint and used them only as effect dependencies, which looked like collapse handling
+ * and was none: a narrow reload put the pane where nothing draws it. Collapse is now enforced for
+ * EVERY path by `useResponsiveZoneMigration` ("a collapsed zone holds nothing"), which moves the
+ * pane into PRIMARY the same way a click at that width would be placed — so this hook no longer
+ * needs to know the width, and does not pretend to. What it must know is case 2's extension: a pane
+ * held in PRIMARY on the collapsed secondary's behalf is still the pane, or every later URL change
+ * would place it again and the migration would stack a duplicate.
+ *
+ * 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=useNavigationRouterSync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useNavigationRouterSync.d.ts","sourceRoot":"","sources":["../../../../../src/core/navigation/useNavigationRouterSync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iEAAiE,CAAC;AAerG,OAAO,EAGL,qBAAqB,EAGtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAIL,gDAAgD,EAEjD,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,uCAAuC,EACxC,MAAM,+DAA+D,CAAC;AAsBvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,SAAS,EAAE,uCAAuC,GAAG,SAAS,EAC9D,mBAAmB,CAAC,EAAE,gDAAgD,EAAE,GACvE,IAAI,CAqWN;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAyI7C;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CA8EhD"}