@timber-js/app 0.1.29 → 0.1.31

package/dist/client/index.js

@@ -67,53 +67,55 @@ function useLinkStatus() {
 	return useContext(LinkStatusContext);
 }
 //#endregion
-//#region src/client/router-ref.ts
+//#region src/client/pending-navigation-context.ts
 /**
-* Set the global router instance. Called once during bootstrap.
-*/
-function setGlobalRouter(router) {
-	_setGlobalRouter(router);
-}
-/**
-* Get the global router instance. Throws if called before bootstrap.
-* Used by client-side hooks (useNavigationPending, etc.)
+* PendingNavigationContext — React context for the in-flight navigation URL.
+*
+* Provided by TransitionRoot. The value is the URL being navigated to,
+* or null when idle. Used by:
+* - LinkStatusProvider to show per-link pending spinners
+* - useNavigationPending to return a global pending boolean
+*
+* The pending URL is set as an URGENT update (shows immediately) and
+* cleared inside startTransition (commits atomically with the new tree).
+* This ensures pending state appears instantly on navigation start and
+* disappears in the same React commit as the new params/tree.
+*
+* Separate from NavigationContext (which holds params + pathname) because
+* the pending URL is managed as React state in TransitionRoot, while
+* params/pathname are set via module-level state read by renderRoot.
+* Both contexts commit together in the same transition.
+*
+* See design/19-client-navigation.md §"NavigationContext"
 */
-function getRouter() {
-	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
-	return globalRouter;
+var _context$1;
+function getOrCreateContext$1() {
+	if (_context$1 !== void 0) return _context$1;
+	if (typeof React.createContext === "function") _context$1 = React.createContext(null);
+	return _context$1;
 }
 /**
-* Get the global router instance or null if not yet initialized.
-* Used by useRouter() methods to avoid silent failures — callers
-* can log a meaningful warning instead of silently no-oping.
+* Read the pending navigation URL from context.
+* Returns null during SSR (no provider) or in the RSC environment.
+* Internal — used by LinkStatusProvider and useNavigationPending.
 */
-function getRouterOrNull() {
-	return globalRouter;
+function usePendingNavigationUrl() {
+	const ctx = getOrCreateContext$1();
+	if (!ctx) return null;
+	if (typeof React.useContext !== "function") return null;
+	return React.useContext(ctx);
 }
 //#endregion
 //#region src/client/link-status-provider.tsx
 var NOT_PENDING = { pending: false };
 var IS_PENDING = { pending: true };
 /**
-* Client component that subscribes to the router's pending URL and provides
-* a scoped LinkStatusContext to children. Renders no extra DOM — just a
-* context provider around children.
+* Client component that reads the pending URL from PendingNavigationContext
+* and provides a scoped LinkStatusContext to children. Renders no extra DOM —
+* just a context provider around children.
 */
 function LinkStatusProvider({ href, children }) {
-	const status = useSyncExternalStore((callback) => {
-		try {
-			return getRouter().onPendingChange(callback);
-		} catch {
-			return () => {};
-		}
-	}, () => {
-		try {
-			if (getRouter().getPendingUrl() === href) return IS_PENDING;
-			return NOT_PENDING;
-		} catch {
-			return NOT_PENDING;
-		}
-	}, () => NOT_PENDING);
+	const status = usePendingNavigationUrl() === href ? IS_PENDING : NOT_PENDING;
 	return /* @__PURE__ */ jsx(LinkStatusContext.Provider, {
 		value: status,
 		children
@@ -649,6 +651,26 @@ function createRouter(deps) {
 			pathname: url.startsWith("http") ? new URL(url).pathname : url.split("?")[0] || "/"
 		});
 	}
+	/**
+	* Render a payload via navigateTransition (production) or renderRoot (tests).
+	* The perform callback should fetch data, update state, and return the payload.
+	* In production, the entire callback runs inside a React transition with
+	* useOptimistic for the pending URL. In tests, the payload is rendered directly.
+	*/
+	async function renderViaTransition(pendingUrl, perform) {
+		if (deps.navigateTransition) {
+			let headElements = null;
+			await deps.navigateTransition(pendingUrl, async (wrapPayload) => {
+				const result = await perform();
+				headElements = result.headElements;
+				return wrapPayload(result.payload);
+			});
+			return headElements;
+		}
+		const result = await perform();
+		renderPayload(result.payload);
+		return result.headElements;
+	}
 	/** Apply head elements (title, meta tags) to the DOM if available. */
 	function applyHead(elements) {
 		if (elements && deps.applyHead) deps.applyHead(elements);
@@ -658,6 +680,40 @@ function createRouter(deps) {
 		if (deps.afterPaint) deps.afterPaint(callback);
 		else callback();
 	}
+	/**
+	* Core navigation logic shared between the transition and fallback paths.
+	* Fetches the RSC payload, updates all state, and returns the result.
+	*/
+	async function performNavigationFetch(url, options) {
+		const prefetched = prefetchCache.consume(url);
+		let result = prefetched ? {
+			payload: prefetched.payload,
+			headElements: prefetched.headElements,
+			segmentInfo: prefetched.segmentInfo ?? null,
+			params: prefetched.params ?? null
+		} : void 0;
+		if (result === void 0) {
+			const stateTree = segmentCache.serializeStateTree();
+			const rawCurrentUrl = deps.getCurrentUrl();
+			result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
+		}
+		if (options.replace) deps.replaceState({
+			timber: true,
+			scrollY: 0
+		}, "", url);
+		else deps.pushState({
+			timber: true,
+			scrollY: 0
+		}, "", url);
+		historyStack.push(url, {
+			payload: result.payload,
+			headElements: result.headElements,
+			params: result.params
+		});
+		updateSegmentCache(result.segmentInfo);
+		updateNavigationState(result.params, url);
+		return result;
+	}
 	async function navigate(url, options = {}) {
 		const scroll = options.scroll !== false;
 		const replace = options.replace === true;
@@ -668,29 +724,7 @@ function createRouter(deps) {
 		}, "", deps.getCurrentUrl());
 		setPending(true, url);
 		try {
-			let result = prefetchCache.consume(url);
-			if (result === void 0) {
-				const stateTree = segmentCache.serializeStateTree();
-				const rawCurrentUrl = deps.getCurrentUrl();
-				result = await fetchRscPayload(url, deps, stateTree, rawCurrentUrl.startsWith("http") ? new URL(rawCurrentUrl).pathname : new URL(rawCurrentUrl, "http://localhost").pathname);
-			}
-			if (replace) deps.replaceState({
-				timber: true,
-				scrollY: 0
-			}, "", url);
-			else deps.pushState({
-				timber: true,
-				scrollY: 0
-			}, "", url);
-			historyStack.push(url, {
-				payload: result.payload,
-				headElements: result.headElements,
-				params: result.params
-			});
-			updateSegmentCache(result.segmentInfo);
-			updateNavigationState(result.params, url);
-			renderPayload(result.payload);
-			applyHead(result.headElements);
+			applyHead(await renderViaTransition(url, () => performNavigationFetch(url, { replace })));
 			window.dispatchEvent(new Event("timber:navigation-end"));
 			afterPaint(() => {
 				if (scroll) deps.scrollTo(0, 0);
@@ -713,16 +747,17 @@ function createRouter(deps) {
 		const currentUrl = deps.getCurrentUrl();
 		setPending(true, currentUrl);
 		try {
-			const result = await fetchRscPayload(currentUrl, deps);
-			historyStack.push(currentUrl, {
-				payload: result.payload,
-				headElements: result.headElements,
-				params: result.params
-			});
-			updateSegmentCache(result.segmentInfo);
-			updateNavigationState(result.params, currentUrl);
-			renderPayload(result.payload);
-			applyHead(result.headElements);
+			applyHead(await renderViaTransition(currentUrl, async () => {
+				const result = await fetchRscPayload(currentUrl, deps);
+				historyStack.push(currentUrl, {
+					payload: result.payload,
+					headElements: result.headElements,
+					params: result.params
+				});
+				updateSegmentCache(result.segmentInfo);
+				updateNavigationState(result.params, currentUrl);
+				return result;
+			}));
 		} finally {
 			setPending(false);
 		}
@@ -740,16 +775,17 @@ function createRouter(deps) {
 		} else {
 			setPending(true, url);
 			try {
-				const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
-				updateSegmentCache(result.segmentInfo);
-				updateNavigationState(result.params, url);
-				historyStack.push(url, {
-					payload: result.payload,
-					headElements: result.headElements,
-					params: result.params
-				});
-				renderPayload(result.payload);
-				applyHead(result.headElements);
+				applyHead(await renderViaTransition(url, async () => {
+					const result = await fetchRscPayload(url, deps, segmentCache.serializeStateTree());
+					updateSegmentCache(result.segmentInfo);
+					updateNavigationState(result.params, url);
+					historyStack.push(url, {
+						payload: result.payload,
+						headElements: result.headElements,
+						params: result.params
+					});
+					return result;
+				}));
 				afterPaint(() => {
 					deps.scrollTo(0, scrollY);
 					window.dispatchEvent(new Event("timber:scroll-restored"));
@@ -823,15 +859,31 @@ function createRouter(deps) {
 * ```
 */
 function useNavigationPending() {
-	return useSyncExternalStore((callback) => {
-		return getRouter().onPendingChange(callback);
-	}, () => {
-		try {
-			return getRouter().isPending();
-		} catch {
-			return false;
-		}
-	}, () => false);
+	return usePendingNavigationUrl() !== null;
+}
+//#endregion
+//#region src/client/router-ref.ts
+/**
+* Set the global router instance. Called once during bootstrap.
+*/
+function setGlobalRouter(router) {
+	_setGlobalRouter(router);
+}
+/**
+* Get the global router instance. Throws if called before bootstrap.
+* Used by client-side hooks (useNavigationPending, etc.)
+*/
+function getRouter() {
+	if (!globalRouter) throw new Error("[timber] Router not initialized. getRouter() was called before bootstrap().");
+	return globalRouter;
+}
+/**
+* Get the global router instance or null if not yet initialized.
+* Used by useRouter() methods to avoid silent failures — callers
+* can log a meaningful warning instead of silently no-oping.
+*/
+function getRouterOrNull() {
+	return globalRouter;
 }
 //#endregion
 //#region src/client/use-router.ts