toiljs 0.0.14 → 0.0.16

package/src/client/navigation/navigation.ts

@@ -9,6 +9,13 @@ import { flushSync } from 'react-dom';
 import { enableManualScrollRestoration, planScroll, rememberScroll } from './scroll.js';
 import type { Href } from '../types.js';
 
+/**
+ * Asserts a runtime-computed string is a valid {@link Href}, the escape hatch for hrefs built from
+ * data (e.g. `` `/${category}/${slug}` ``) that can't be checked against the static route union.
+ * Use at the call site: `<Link href={href(path)} />`, `navigate(href(path))`.
+ */
+export const href = (path: string): Href => path as Href;
+
 const listeners = new Set<() => void>();
 let popstateBound = false;
 
@@ -23,6 +30,16 @@ export function setViewTransitions(enabled: boolean): void {
     viewTransitions = enabled;
 }
 
+// Whether to wrap navigations in a React transition. Off by default: a navigation commits eagerly, so
+// a route's `loading.tsx` shows immediately while its loader runs. On, the current page is kept
+// visible until the next route is ready (smoother, but no loading state). Set from `client.transitions`.
+let navTransitions = false;
+
+/** Enables React-transition (keep-current-page) navigation. Called once by `mount` from `client.transitions`. */
+export function setTransitions(enabled: boolean): void {
+    navTransitions = enabled;
+}
+
 /** Whether the current navigation should animate via the View Transitions API. */
 function shouldViewTransition(): boolean {
     if (!viewTransitions || typeof document === 'undefined' || typeof window === 'undefined') {
@@ -48,18 +65,21 @@ function runListeners(): void {
 }
 
 /**
- * Re-renders subscribers for a location change. Normally wrapped in `startTransition` (smooth: the
- * current page stays while the next route loads). When View Transitions are enabled and supported,
- * the commit runs synchronously inside `document.startViewTransition` so the browser animates the
- * old and new DOM (a crossfade, or shared-element transitions via `view-transition-name`).
+ * Re-renders subscribers for a location change. When View Transitions are enabled and supported, the
+ * commit runs synchronously inside `document.startViewTransition` so the browser animates the old and
+ * new DOM. Otherwise, with `client.transitions` on, it's wrapped in `startTransition` (the current
+ * page stays while the next route loads); by default it commits eagerly, so a route's `loading.tsx`
+ * shows right away instead of holding the previous page.
  */
 function notify(): void {
     if (shouldViewTransition()) {
         (document as ViewTransitionDocument).startViewTransition?.(() => {
             flushSync(runListeners);
         });
-    } else {
+    } else if (navTransitions) {
         startTransition(runListeners);
+    } else {
+        runListeners();
     }
 }
 

package/src/client/navigation/prefetch.ts

@@ -1,130 +1,169 @@
-import { matchRoute } from '../routing/match.js';
-import type { RouteDef } from '../types.js';
-
-declare global {
-    interface Navigator {
-        /** Non-standard but widely shipped; used to skip prefetch on data-saver / slow links. */
-        readonly connection?: {
-            readonly saveData?: boolean;
-            readonly effectiveType?: string;
-        };
-    }
-}
-
-let routeTable: RouteDef[] = [];
-const warmed = new WeakSet<RouteDef>();
-let io: IntersectionObserver | null = null;
-let mo: MutationObserver | null = null;
-
-/** Resolves a same-origin `href` to a registered route, or `null` for external/unknown targets. */
-function routeForHref(href: string): RouteDef | null {
-    let url: URL;
-    try {
-        url = new URL(href, window.location.href);
-    } catch {
-        return null;
-    }
-    if (url.origin !== window.location.origin) return null;
-    for (const route of routeTable) {
-        if (matchRoute(route.pattern, url.pathname)) return route;
-    }
-    return null;
-}
-
-/**
- * Warms a route's lazy chunk by triggering its loader once. Best-effort: each route loads at most
- * once, and a failed load is forgotten (so the real navigation can retry and surface the error).
- */
-function warm(route: RouteDef): void {
-    if (warmed.has(route)) return;
-    warmed.add(route);
-    void route.load().catch(() => {
-        warmed.delete(route);
-    });
-}
-
-/**
- * Prefetches the route chunk for an internal `href` so a later navigation resolves instantly.
- * No-op for external, unknown, or already-prefetched targets, safe to call from anywhere,
- * including before an imperative {@link navigate} (e.g. `prefetch('/dashboard')` on hover/intent).
- */
-export function prefetch(href: string): void {
-    const route = routeForHref(href);
-    if (route) warm(route);
-}
-
-/** Anchors to skip even when internal: new-tab, downloads, or an explicit `data-no-prefetch` opt-out. */
-function isPrefetchable(a: HTMLAnchorElement): boolean {
-    if (a.target && a.target !== '_self') return false;
-    if (a.hasAttribute('download')) return false;
-    if (a.dataset.noPrefetch !== undefined) return false;
-    return true;
-}
-
-/** Observes an anchor for viewport entry if it points at a known internal route. */
-function observeAnchor(a: HTMLAnchorElement): void {
-    if (!io || !isPrefetchable(a) || !routeForHref(a.href)) return;
-    io.observe(a);
-}
-
-/** Finds and observes every `<a href>` under `root`. */
-function scan(root: ParentNode): void {
-    root.querySelectorAll('a[href]').forEach((el) => {
-        if (el instanceof HTMLAnchorElement) observeAnchor(el);
-    });
-}
-
-/** Skip prefetching on data-saver mode or 2g-class connections, where bandwidth is precious. */
-function shouldSkipForConnection(): boolean {
-    const c = navigator.connection;
-    if (!c) return false;
-    return c.saveData === true || c.effectiveType === 'slow-2g' || c.effectiveType === '2g';
-}
-
-/**
- * Starts idle-time prefetching of internal links. As each `<a>` pointing at a known route scrolls
- * into view (or near it, 200px margin) its chunk is warmed once; links added later by client
- * navigation are picked up via a MutationObserver. Called by {@link mount}; runs once per app.
- */
-export function startPrefetcher(routes: RouteDef[]): void {
-    routeTable = routes;
-    if (
-        typeof window === 'undefined' ||
-        typeof IntersectionObserver === 'undefined' ||
-        typeof MutationObserver === 'undefined' ||
-        io
-    ) {
-        return;
-    }
-    if (shouldSkipForConnection()) return;
-
-    io = new IntersectionObserver(
-        (entries) => {
-            for (const entry of entries) {
-                if (!entry.isIntersecting) continue;
-                const a = entry.target;
-                if (a instanceof HTMLAnchorElement) {
-                    io?.unobserve(a);
-                    prefetch(a.href);
-                }
-            }
-        },
-        { rootMargin: '200px' },
-    );
-
-    mo = new MutationObserver((mutations) => {
-        for (const m of mutations) {
-            for (const node of m.addedNodes) {
-                if (node instanceof HTMLAnchorElement) observeAnchor(node);
-                else if (node instanceof Element) scan(node);
-            }
-        }
-    });
-
-    const begin = (): void => {
-        scan(document);
-        mo?.observe(document.body, { childList: true, subtree: true });
-    };
-    if (typeof requestIdleCallback === 'function') requestIdleCallback(begin);
-    else setTimeout(begin, 200);
-}
+import { prefetchRouteData } from '../routing/loader.js';
+import { matchRoute } from '../routing/match.js';
+import type { RouteDef } from '../types.js';
+
+declare global {
+    interface Navigator {
+        /** Non-standard but widely shipped; used to skip prefetch on data-saver / slow links. */
+        readonly connection?: {
+            readonly saveData?: boolean;
+            readonly effectiveType?: string;
+        };
+    }
+}
+
+let routeTable: RouteDef[] = [];
+const warmed = new WeakSet<RouteDef>();
+const dataWarmed = new Set<string>();
+let io: IntersectionObserver | null = null;
+let mo: MutationObserver | null = null;
+
+/** Resolves a same-origin `href` to a registered route, or `null` for external/unknown targets. */
+function routeForHref(href: string): RouteDef | null {
+    let url: URL;
+    try {
+        url = new URL(href, window.location.href);
+    } catch {
+        return null;
+    }
+    if (url.origin !== window.location.origin) return null;
+    for (const route of routeTable) {
+        if (matchRoute(route.pattern, url.pathname)) return route;
+    }
+    return null;
+}
+
+/**
+ * Warms a route's lazy chunk by triggering its loader once. Best-effort: each route loads at most
+ * once, and a failed load is forgotten (so the real navigation can retry and surface the error).
+ */
+function warm(route: RouteDef): void {
+    if (warmed.has(route)) return;
+    warmed.add(route);
+    void route.load().catch(() => {
+        warmed.delete(route);
+    });
+}
+
+/**
+ * Prefetches the route chunk for an internal `href` so a later navigation resolves instantly.
+ * No-op for external, unknown, or already-prefetched targets, safe to call from anywhere,
+ * including before an imperative {@link navigate} (e.g. `prefetch('/dashboard')` on hover/intent).
+ */
+export function prefetch(href: string): void {
+    const route = routeForHref(href);
+    if (route) warm(route);
+}
+
+/**
+ * Prefetches both the chunk and the loader data for an internal `href`, so a later navigation
+ * commits synchronously (no suspense, no held-page wait). Called on link hover / focus intent, where
+ * running the route's loader early is worth it. No-op for external/unknown/already-warmed targets.
+ */
+export function prefetchData(href: string): void {
+    let url: URL;
+    try {
+        url = new URL(href, window.location.href);
+    } catch {
+        return;
+    }
+    if (url.origin !== window.location.origin) return;
+    const key = url.pathname + url.search;
+    if (dataWarmed.has(key)) return;
+    for (const route of routeTable) {
+        const params = matchRoute(route.pattern, url.pathname);
+        if (params) {
+            dataWarmed.add(key);
+            warm(route);
+            prefetchRouteData(route, params, url.pathname, url.search);
+            return;
+        }
+    }
+}
+
+/** Anchors to skip even when internal: new-tab, downloads, or an explicit `data-no-prefetch` opt-out. */
+function isPrefetchable(a: HTMLAnchorElement): boolean {
+    if (a.target && a.target !== '_self') return false;
+    if (a.hasAttribute('download')) return false;
+    if (a.dataset.noPrefetch !== undefined) return false;
+    return true;
+}
+
+/** Observes an anchor for viewport entry if it points at a known internal route. */
+function observeAnchor(a: HTMLAnchorElement): void {
+    if (!io || !isPrefetchable(a) || !routeForHref(a.href)) return;
+    io.observe(a);
+}
+
+/** Finds and observes every `<a href>` under `root`. */
+function scan(root: ParentNode): void {
+    root.querySelectorAll('a[href]').forEach((el) => {
+        if (el instanceof HTMLAnchorElement) observeAnchor(el);
+    });
+}
+
+/** Skip prefetching on data-saver mode or 2g-class connections, where bandwidth is precious. */
+function shouldSkipForConnection(): boolean {
+    const c = navigator.connection;
+    if (!c) return false;
+    return c.saveData === true || c.effectiveType === 'slow-2g' || c.effectiveType === '2g';
+}
+
+/**
+ * Starts idle-time prefetching of internal links. As each `<a>` pointing at a known route scrolls
+ * into view (or near it, 200px margin) its chunk is warmed once; links added later by client
+ * navigation are picked up via a MutationObserver. Called by {@link mount}; runs once per app.
+ */
+export function startPrefetcher(routes: RouteDef[]): void {
+    routeTable = routes;
+    if (
+        typeof window === 'undefined' ||
+        typeof IntersectionObserver === 'undefined' ||
+        typeof MutationObserver === 'undefined' ||
+        io
+    ) {
+        return;
+    }
+    if (shouldSkipForConnection()) return;
+
+    io = new IntersectionObserver(
+        (entries) => {
+            for (const entry of entries) {
+                if (!entry.isIntersecting) continue;
+                const a = entry.target;
+                if (a instanceof HTMLAnchorElement) {
+                    io?.unobserve(a);
+                    prefetch(a.href);
+                }
+            }
+        },
+        { rootMargin: '200px' },
+    );
+
+    mo = new MutationObserver((mutations) => {
+        for (const m of mutations) {
+            for (const node of m.addedNodes) {
+                if (node instanceof HTMLAnchorElement) observeAnchor(node);
+                else if (node instanceof Element) scan(node);
+            }
+        }
+    });
+
+    // Hover / focus intent: warm the chunk *and* run the loader for the target so the click commits
+    // synchronously. Delegated on the document so links added later are covered automatically.
+    const onIntent = (event: Event): void => {
+        const target = event.target;
+        if (!(target instanceof Element)) return;
+        const a = target.closest('a[href]');
+        if (a instanceof HTMLAnchorElement && isPrefetchable(a) && a.href) prefetchData(a.href);
+    };
+    document.addEventListener('pointerover', onIntent, { passive: true });
+    document.addEventListener('focusin', onIntent);
+
+    const begin = (): void => {
+        scan(document);
+        mo?.observe(document.body, { childList: true, subtree: true });
+    };
+    if (typeof requestIdleCallback === 'function') requestIdleCallback(begin);
+    else setTimeout(begin, 200);
+}

package/src/client/navigation/scroll.ts

@@ -1,53 +1,53 @@
-/**
- * Manual scroll management for client navigation: scroll to top on push navigations, restore the
- * saved position on back/forward, and honor in-page `#hash` targets. Positions are keyed by
- * history entry; {@link applyScroll} runs once after the navigation commits.
- */
-const positions = new Map<string, number>();
-
-interface ScrollPlan {
-    readonly restore: number | null;
-    readonly hash: string;
-    readonly toTop: boolean;
-}
-let plan: ScrollPlan | null = null;
-
-/** Switches off the browser's automatic scroll restoration so the router can manage it. */
-export function enableManualScrollRestoration(): void {
-    if (typeof window !== 'undefined' && 'scrollRestoration' in window.history) {
-        window.history.scrollRestoration = 'manual';
-    }
-}
-
-/** Saves the current scroll position for a history key (called before leaving an entry). */
-export function rememberScroll(key: string): void {
-    positions.set(key, window.scrollY);
-}
-
-/** Plans what {@link applyScroll} should do after the next navigation commits. */
-export function planScroll(opts: { restoreKey?: string; hash: string; toTop: boolean }): void {
-    plan = {
-        restore: opts.restoreKey !== undefined ? (positions.get(opts.restoreKey) ?? 0) : null,
-        hash: opts.hash,
-        toTop: opts.toTop,
-    };
-}
-
-/** Applies the pending scroll plan once: hash target, else restored position, else top. */
-export function applyScroll(): void {
-    const current = plan;
-    plan = null;
-    if (!current) return;
-    if (current.hash) {
-        const el = document.getElementById(decodeURIComponent(current.hash.slice(1)));
-        if (el) {
-            el.scrollIntoView();
-            return;
-        }
-    }
-    if (current.restore !== null) {
-        window.scrollTo(0, current.restore);
-        return;
-    }
-    if (current.toTop) window.scrollTo(0, 0);
-}
+/**
+ * Manual scroll management for client navigation: scroll to top on push navigations, restore the
+ * saved position on back/forward, and honor in-page `#hash` targets. Positions are keyed by
+ * history entry; {@link applyScroll} runs once after the navigation commits.
+ */
+const positions = new Map<string, number>();
+
+interface ScrollPlan {
+    readonly restore: number | null;
+    readonly hash: string;
+    readonly toTop: boolean;
+}
+let plan: ScrollPlan | null = null;
+
+/** Switches off the browser's automatic scroll restoration so the router can manage it. */
+export function enableManualScrollRestoration(): void {
+    if (typeof window !== 'undefined' && 'scrollRestoration' in window.history) {
+        window.history.scrollRestoration = 'manual';
+    }
+}
+
+/** Saves the current scroll position for a history key (called before leaving an entry). */
+export function rememberScroll(key: string): void {
+    positions.set(key, window.scrollY);
+}
+
+/** Plans what {@link applyScroll} should do after the next navigation commits. */
+export function planScroll(opts: { restoreKey?: string; hash: string; toTop: boolean }): void {
+    plan = {
+        restore: opts.restoreKey !== undefined ? (positions.get(opts.restoreKey) ?? 0) : null,
+        hash: opts.hash,
+        toTop: opts.toTop,
+    };
+}
+
+/** Applies the pending scroll plan once: hash target, else restored position, else top. */
+export function applyScroll(): void {
+    const current = plan;
+    plan = null;
+    if (!current) return;
+    if (current.hash) {
+        const el = document.getElementById(decodeURIComponent(current.hash.slice(1)));
+        if (el) {
+            el.scrollIntoView();
+            return;
+        }
+    }
+    if (current.restore !== null) {
+        window.scrollTo(0, current.restore);
+        return;
+    }
+    if (current.toTop) window.scrollTo(0, 0);
+}

package/src/client/routing/Router.tsx

@@ -68,13 +68,19 @@ function renderMatched(
 
     // A route with a `loading.tsx` keys its boundary per URL *and* navigation epoch, so its fallback
     // shows even inside the transition, on first nav and on an in-place revalidate of the same URL
-    // (the epoch bumps). A route without one keeps a stable boundary so the transition holds the old
-    // page. The loader cache key stays the bare URL, so the boundary remount still reuses cached data.
+    // (the epoch bumps). A route without one keeps a STABLE boundary (key `undefined`): the Suspense
+    // must NOT be remounted on navigation, or it becomes a freshly-mounted boundary with no committed
+    // content and React shows its (null) fallback during the next route's chunk/loader load, i.e. a
+    // blank flash, even inside the transition. With a stable boundary the transition holds the old
+    // page until the next one is ready. The loader cache key stays the bare URL, so reused data hits.
+    // The page itself is keyed by URL so each route mounts fresh (no state bleed between routes); it
+    // lives INSIDE the boundary so that re-mount doesn't tear down the boundary above it.
     let content: ReactNode = (
         <Suspense
             key={matched.loading ? `${dataKey}:${String(epoch)}` : undefined}
             fallback={fallback}>
             <RoutePage
+                key={dataKey}
                 route={matched}
                 params={params}
                 dataKey={dataKey}