@timber-js/app 0.2.0-alpha.67 → 0.2.0-alpha.69

package/src/server/ssr-wrappers.tsx

@@ -8,7 +8,7 @@
  * Radix UI that rely on useId() internally.
  *
  * The client tree (browser-entry.ts) wraps the RSC element with:
- *   TransitionRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
+ *   NavigationRoot → PendingNavigationProvider → Fragment(TopLoader, ...) →
  *     TimberNuqsAdapter → NuqsAdapterProvider → NavigationProvider → element
  *
  * The SSR tree must produce the same component boundaries. These wrappers
@@ -23,15 +23,15 @@ import { createElement, Fragment, type ReactNode } from 'react';
 import { withNuqsSsrAdapter } from './nuqs-ssr-provider.js';
 
 /**
- * SSR equivalent of TransitionRoot.
+ * SSR equivalent of NavigationRoot.
  *
- * On the client, TransitionRoot uses useState + useTransition and renders:
+ * On the client, NavigationRoot uses useState and standalone startTransition, rendering:
  *   PendingNavigationProvider(Fragment(TopLoader, element))
  *
  * This SSR version matches the component boundary depth without client
  * hooks. It renders SsrPendingProvider → Fragment(SsrTopLoader, children).
  */
-function SsrTransitionRoot({
+function SsrNavigationRoot({
   children,
   hasTopLoader,
 }: {
@@ -97,7 +97,7 @@ function SsrNuqsWrapper({
  * on both sides.
  *
  * Client tree (browser-entry.ts):
- *   TransitionRoot
+ *   NavigationRoot
  *     → PendingNavigationProvider
  *       → Fragment(TopLoader, element)
  *         → TimberNuqsAdapter
@@ -106,7 +106,7 @@ function SsrNuqsWrapper({
  *               → [RSC element]
  *
  * SSR tree (this function):
- *   SsrTransitionRoot
+ *   SsrNavigationRoot
  *     → SsrPendingProvider
  *       → Fragment(SsrTopLoader, element)
  *         → SsrNuqsWrapper
@@ -125,8 +125,8 @@ export function wrapSsrElement(
 ): ReactNode {
   // Build inside-out to match the client's createElement chain:
   //   NavigationProvider(TimberNuqsAdapter(element))
-  //   → passed as initial to TransitionRoot
-  //   → TransitionRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
+  //   → passed as initial to NavigationRoot
+  //   → NavigationRoot renders PendingNavigationProvider(Fragment(TopLoader, initial))
 
   // 1. Innermost: NavigationProvider equivalent
   const withNav = createElement(SsrNavigationProvider, null, element);
@@ -134,6 +134,6 @@ export function wrapSsrElement(
   // 2. TimberNuqsAdapter equivalent (wraps withNuqsSsrAdapter for the actual nuqs provider)
   const withNuqs = createElement(SsrNuqsWrapper, { searchParams, children: withNav });
 
-  // 3. Outermost: TransitionRoot equivalent (PendingNavigationProvider + TopLoader)
-  return createElement(SsrTransitionRoot, { hasTopLoader, children: withNuqs });
+  // 3. Outermost: NavigationRoot equivalent (PendingNavigationProvider + TopLoader)
+  return createElement(SsrNavigationRoot, { hasTopLoader, children: withNuqs });
 }

package/dist/client/transition-root.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transition-root.d.ts","sourceRoot":"","sources":["../../src/client/transition-root.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAoD,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzF,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsBlE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,SAAS,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC,GAAG,SAAS,CA2DZ;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAIzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,CAAC,GAChC,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,cAAc,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI,CAc5F"}

package/src/client/transition-root.tsx

@@ -1,205 +0,0 @@
-/**
- * TransitionRoot — Wrapper component for transition-based rendering.
- *
- * Solves the "new boundary has no old content" problem for client-side
- * navigation. When React renders a completely new Suspense boundary via
- * root.render(), it shows the fallback immediately — root.render() is
- * always an urgent update regardless of startTransition.
- *
- * TransitionRoot holds the current element in React state. Navigation
- * updates call startTransition(() => setState(newElement)), which IS
- * a transition update. React keeps the old committed tree visible while
- * any new Suspense boundaries in the transition resolve.
- *
- * Also manages `pendingUrl` as React state with an urgent/transition split:
- * - Navigation START: `setPendingUrl(url)` is an urgent update — React
- *   commits it before the next paint, showing the spinner immediately.
- * - Navigation END: `setPendingUrl(null)` is inside `startTransition`
- *   alongside `setElement(newTree)` — both commit atomically, so the
- *   spinner disappears in the same frame as the new content appears.
- *
- * See design/05-streaming.md §"deferSuspenseFor"
- * See design/19-client-navigation.md §"NavigationContext"
- */
-
-import { useState, useTransition, createElement, Fragment, type ReactNode } from 'react';
-import { PendingNavigationProvider } from './navigation-context.js';
-import { TopLoader, type TopLoaderConfig } from './top-loader.js';
-import { getCurrentNavId, resetLinkPending } from './link-pending-store.js';
-
-// ─── Module-level functions ──────────────────────────────────────
-
-/**
- * Module-level reference to the state setter wrapped in startTransition.
- * Used for non-navigation renders (applyRevalidation, popstate replay).
- */
-let _transitionRender: ((element: ReactNode) => void) | null = null;
-
-/**
- * Module-level reference to the navigation transition function.
- * Wraps a full navigation (fetch + render) in a single startTransition
- * with useOptimistic for the pending URL.
- */
-let _navigateTransition:
-  | ((pendingUrl: string, perform: () => Promise<ReactNode>) => Promise<void>)
-  | null = null;
-
-// ─── Component ───────────────────────────────────────────────────
-
-/**
- * Root wrapper component that enables transition-based rendering.
- *
- * Renders PendingNavigationProvider around children for the pending URL
- * context. The DOM tree matches the server-rendered HTML during hydration
- * (the provider renders no extra DOM elements).
- *
- * Usage in browser-entry.ts:
- *   const rootEl = createElement(TransitionRoot, { initial: wrapped });
- *   reactRoot = hydrateRoot(document, rootEl);
- *
- * Subsequent navigations:
- *   navigateTransition(url, async () => { fetch; return wrappedElement; });
- *
- * Non-navigation renders:
- *   transitionRender(newWrappedElement);
- */
-export function TransitionRoot({
-  initial,
-  topLoaderConfig,
-}: {
-  initial: ReactNode;
-  topLoaderConfig?: TopLoaderConfig;
-}): ReactNode {
-  const [element, setElement] = useState<ReactNode>(initial);
-  const [pendingUrl, setPendingUrl] = useState<string | null>(null);
-  const [, startTransition] = useTransition();
-
-  // Non-navigation render (revalidation, popstate cached replay).
-  _transitionRender = (newElement: ReactNode) => {
-    startTransition(() => {
-      setElement(newElement);
-    });
-  };
-
-  // Full navigation transition.
-  // setPendingUrl(url) is an URGENT update — React commits it before the next
-  // paint, so the pending spinner appears immediately when navigation starts.
-  // Inside startTransition: the async fetch + setElement + setPendingUrl(null)
-  // are deferred. When the transition commits, the new tree and pendingUrl=null
-  // both apply in the same React commit — making the pending→active transition
-  // atomic (no frame where pending is false but the old tree is still visible).
-  _navigateTransition = (url: string, perform: () => Promise<ReactNode>) => {
-    // Urgent: show pending state immediately (for TopLoader / useNavigationPending)
-    setPendingUrl(url);
-
-    return new Promise<void>((resolve, reject) => {
-      startTransition(async () => {
-        // Capture the current nav ID before async work begins.
-        // Used to guard against stale clears when a newer navigation
-        // supersedes this one.
-        const navId = getCurrentNavId();
-        try {
-          const newElement = await perform();
-          setElement(newElement);
-          // Clear pending inside the transition — commits atomically with new tree
-          setPendingUrl(null);
-          // Reset per-link pending state. The navId guard ensures a stale
-          // transition (T1) doesn't clear a newer navigation's (T2) link.
-          // The setter call is a transition update — batched with setElement
-          // and setPendingUrl, so pending clears atomically with new tree.
-          // See design/19-client-navigation.md §"Per-Link Pending State"
-          resetLinkPending(navId);
-          resolve();
-        } catch (err) {
-          // Clear pending on error too
-          setPendingUrl(null);
-          resetLinkPending(navId);
-          reject(err);
-        }
-      });
-    });
-  };
-
-  // Inject TopLoader alongside the element tree inside PendingNavigationProvider.
-  // The TopLoader reads pendingUrl from context to show/hide the progress bar.
-  // It is rendered only when not explicitly disabled via config.
-  const showTopLoader = topLoaderConfig?.enabled !== false;
-  const children = showTopLoader
-    ? createElement(Fragment, null, createElement(TopLoader, { config: topLoaderConfig }), element)
-    : element;
-  return createElement(PendingNavigationProvider, { value: pendingUrl }, children);
-}
-
-// ─── Public API ──────────────────────────────────────────────────
-
-/**
- * Trigger a transition render for non-navigation updates.
- * React keeps the old committed tree visible while any new Suspense
- * boundaries in the update resolve.
- *
- * Used for: applyRevalidation, popstate replay with cached payload.
- */
-export function transitionRender(element: ReactNode): void {
-  if (_transitionRender) {
-    _transitionRender(element);
-  }
-}
-
-/**
- * Run a full navigation inside a React transition with optimistic pending URL.
- *
- * The `perform` callback runs inside `startTransition` — it should fetch the
- * RSC payload, update router state, and return the wrapped React element.
- * The pending URL shows immediately (useOptimistic urgent update) and reverts
- * to null when the transition commits (atomic with the new tree).
- *
- * Returns a Promise that resolves when the async work completes (note: the
- * React transition may not have committed yet, but all state updates are done).
- *
- * Used for: navigate(), refresh(), popstate with fetch.
- */
-export function navigateTransition(
-  pendingUrl: string,
-  perform: () => Promise<ReactNode>
-): Promise<void> {
-  if (_navigateTransition) {
-    return _navigateTransition(pendingUrl, perform);
-  }
-  // Fallback: no TransitionRoot mounted (shouldn't happen in production)
-  return perform().then(() => {});
-}
-
-/**
- * Check if the TransitionRoot is mounted and ready for renders.
- * Used by browser-entry.ts to guard against renders before hydration.
- */
-export function isTransitionRootReady(): boolean {
-  return _transitionRender !== null;
-}
-
-/**
- * Install one-shot deferred callbacks for the no-RSC bootstrap path (TIM-600).
- *
- * When there's no RSC payload, we can't create a React root immediately —
- * `createRoot(document).render(...)` would blank the SSR HTML. Instead,
- * this sets up `_transitionRender` and `_navigateTransition` so that the
- * first client navigation triggers root creation via `createAndMount`.
- *
- * After `createAndMount` runs, TransitionRoot renders and overwrites these
- * callbacks with its real `startTransition`-based implementations.
- */
-export function installDeferredNavigation(createAndMount: (initial: ReactNode) => void): void {
-  let mounted = false;
-  const mountOnce = (element: ReactNode) => {
-    if (mounted) return;
-    mounted = true;
-    createAndMount(element);
-  };
-  _transitionRender = (element: ReactNode) => {
-    mountOnce(element);
-  };
-  _navigateTransition = async (_pendingUrl: string, perform: () => Promise<ReactNode>) => {
-    const element = await perform();
-    mountOnce(element);
-  };
-}