@octanejs/tanstack-router 0.1.2

package/src/router.ts

@@ -0,0 +1,63 @@
+// `createRouter` — the only piece of `RouterCore` setup that's framework-specific.
+// `RouterCore`'s constructor takes `(options, getStoreFactory)`; react-router
+// passes a factory that, on the client, builds REACTIVE atoms (`createAtom`/`batch`
+// from `@tanstack/store`) and, on the server, non-reactive snapshot stores. Those
+// atoms are framework-agnostic — `createAtom` lives in `@tanstack/store`, not in
+// `@tanstack/react-store` — so octane reuses the exact same factory. The reactive
+// atoms expose `.subscribe(cb) → { unsubscribe }` + `.get()`, which `useStore` binds
+// to octane's `useSyncExternalStore`.
+import {
+	RouterCore,
+	createNonReactiveMutableStore,
+	createNonReactiveReadonlyStore,
+} from '@tanstack/router-core';
+import { createAtom, batch } from '@tanstack/store';
+import { startTransition } from 'octane';
+
+const isServerEnv = typeof document === 'undefined';
+
+// Every reactive router commit funnels through the store factory's `batch`:
+// `beforeLoad` (location + pending matches), the resolved `onReady` commit
+// (active matches + search), `setMatches`/`setPending`/`setCached`, and
+// `invalidate`. Wrap it in octane's `startTransition` so the resulting
+// `__store`/per-match notifications schedule TRANSITION-priority renders.
+//
+// Why this is needed: router-core already wraps navigation in
+// `router.startTransition` (Transitioner.tsrx), but the RESOLVED commit is run
+// inside `startViewTransition(fn)`, and a real browser defers `fn` to a later
+// task. By then octane's transition window (TRANSITION_DEPTH / the async
+// `startTransition` window) has closed, so the commit would schedule an URGENT
+// re-render. For a same-route `?page` change that urgent re-render lands on a
+// suspending descendant (the route component reading `useSearch`), and an urgent
+// suspend does NOT hold — the route's pending fallback flashes. Re-asserting the
+// transition AT COMMIT TIME makes that re-render ride the concurrent-navigation
+// transition, so octane keeps the current page on screen until the new one is
+// ready (matching cross-route navigation). `startTransition` is re-entrant, so
+// nesting (router-core's own startTransition → this batch) is a no-op extra
+// level; non-navigation router commits ride a transition too, which is harmless
+// (router stores are only ever mutated by router internals, never by urgent user
+// state). SSR uses the non-reactive factory below and is unaffected.
+const octaneStoreFactory = (opts: { isServer?: boolean }) => {
+	if (opts?.isServer ?? isServerEnv) {
+		return {
+			createMutableStore: createNonReactiveMutableStore,
+			createReadonlyStore: createNonReactiveReadonlyStore,
+			batch: (fn: () => void) => fn(),
+		};
+	}
+	return {
+		createMutableStore: createAtom,
+		createReadonlyStore: createAtom,
+		batch: (fn: () => void) => startTransition(() => batch(fn)),
+	};
+};
+
+export class Router extends (RouterCore as any) {
+	constructor(options: any) {
+		super(options, octaneStoreFactory);
+	}
+}
+
+export function createRouter(options: any): any {
+	return new Router(options);
+}

package/src/useAwaited.ts

@@ -0,0 +1,9 @@
+// Suspend until a deferred promise resolves and return its data. react-router uses
+// `React.use(promise)` when available; octane has the same Suspense-shaped `use`, so
+// this is a one-liner. The promise is typically produced by router-core's `defer()`
+// in a loader and streamed to the client.
+import { use } from 'octane';
+
+export function useAwaited(opts: { promise: any }): any {
+	return use(opts.promise);
+}

package/src/useBlocker.tsrx

@@ -0,0 +1,136 @@
+// useBlocker / Block — port of react-router's useBlocker.tsx. Registers a
+// history blocker (`history.block`) whose composed blockerFn resolves the
+// current/next locations to matched-route shapes, asks `shouldBlockFn`, and —
+// with `withResolver` — parks the navigation in a promise the caller settles
+// via the returned resolver's `proceed()` / `reset()`. Also supports the legacy
+// `(blockerFn, condition)` and `{ blockerFn, condition }` signatures. Authored
+// in .tsrx so the compiler slots the internal useState/useEffect and callers'
+// withSlot wrapping keeps per-call-site state independent.
+import { useState, useEffect, isChildrenBlock } from 'octane';
+import { useRouter } from './context.ts';
+
+const IDLE_RESOLVER = {
+	status: 'idle',
+	current: undefined,
+	next: undefined,
+	action: undefined,
+	proceed: undefined,
+	reset: undefined,
+};
+
+function _resolveBlockerOpts(opts, condition) {
+	if (opts === undefined) {
+		return { shouldBlockFn: () => true, withResolver: false };
+	}
+	if ('shouldBlockFn' in opts) return opts;
+	if (typeof opts === 'function') {
+		const shouldBlock = Boolean(condition ?? true);
+		const _customBlockerFn = async () => {
+			if (shouldBlock) return await opts();
+			return false;
+		};
+		return {
+			shouldBlockFn: _customBlockerFn,
+			enableBeforeUnload: shouldBlock,
+			withResolver: false,
+		};
+	}
+	const shouldBlock = Boolean(opts.condition ?? true);
+	const fn = opts.blockerFn;
+	const _customBlockerFn = async () => {
+		if (shouldBlock && fn !== undefined) return await fn();
+		return shouldBlock;
+	};
+	return {
+		shouldBlockFn: _customBlockerFn,
+		enableBeforeUnload: shouldBlock,
+		withResolver: fn === undefined,
+	};
+}
+
+export function useBlocker(opts, condition) {
+	const { shouldBlockFn, enableBeforeUnload = true, disabled = false, withResolver = false } =
+		_resolveBlockerOpts(opts, condition);
+
+	const router = useRouter();
+	const { history } = router;
+
+	const [resolver, setResolver] = useState(IDLE_RESOLVER);
+
+	useEffect(() => {
+		const blockerFnComposed = async (blockerFnArgs) => {
+			function getLocation(location) {
+				const parsedLocation = router.parseLocation(location);
+				const matchedRoutes = router.getMatchedRoutes(parsedLocation.pathname);
+				if (matchedRoutes.foundRoute === undefined) {
+					return {
+						routeId: '__notFound__',
+						fullPath: parsedLocation.pathname,
+						pathname: parsedLocation.pathname,
+						params: matchedRoutes.routeParams,
+						search: router.options.parseSearch(location.search),
+					};
+				}
+				return {
+					routeId: matchedRoutes.foundRoute.id,
+					fullPath: matchedRoutes.foundRoute.fullPath,
+					pathname: parsedLocation.pathname,
+					params: matchedRoutes.routeParams,
+					search: router.options.parseSearch(location.search),
+				};
+			}
+
+			const current = getLocation(blockerFnArgs.currentLocation);
+			const next = getLocation(blockerFnArgs.nextLocation);
+
+			if (current.routeId === '__notFound__' && next.routeId !== '__notFound__') {
+				return false;
+			}
+
+			const shouldBlock = await shouldBlockFn({
+				action: blockerFnArgs.action,
+				current,
+				next,
+			});
+			if (!withResolver) return shouldBlock;
+			if (!shouldBlock) return false;
+
+			const promise = new Promise((resolve) => {
+				setResolver({
+					status: 'blocked',
+					current,
+					next,
+					action: blockerFnArgs.action,
+					proceed: () => resolve(false),
+					reset: () => resolve(true),
+				});
+			});
+
+			const canNavigateAsync = await promise;
+			setResolver(IDLE_RESOLVER);
+			return canNavigateAsync;
+		};
+
+		return disabled
+			? undefined
+			: history.block({ blockerFn: blockerFnComposed, enableBeforeUnload });
+	}, [shouldBlockFn, enableBeforeUnload, disabled, withResolver, history, router]);
+
+	return resolver;
+}
+
+// Declarative blocker: registers useBlocker and renders children (optionally a
+// render prop receiving the resolver).
+export function Block(props) @{
+	const { children, ...rest } = props;
+	const resolver = useBlocker(rest);
+	const out =
+		children
+			? typeof children === 'function' && !isChildrenBlock(children)
+				? children(resolver)
+				: children
+			: null;
+	<>
+		{out}
+	</>
+}

package/src/useBlocker.tsrx.d.ts

@@ -0,0 +1,3 @@
+// Type declaration for the .tsrx module (resolved by relative path).
+export declare const useBlocker: (opts?: unknown, condition?: unknown) => unknown;
+export declare const Block: (props: Record<string, unknown>) => unknown;

package/src/useElementScrollRestoration.ts

@@ -0,0 +1,12 @@
+// useElementScrollRestoration — restore scroll for a specific element (e.g. a
+// virtualized list) by id or getter. Port of react-router's
+// ScrollRestoration.tsx helper: ensures the router's scroll restoration is set
+// up, then reads the element's stored entry from the scroll-restoration cache.
+import { setupScrollRestoration, getElementScrollRestorationEntry } from '@tanstack/router-core';
+import { useRouter } from './context';
+
+export function useElementScrollRestoration(options: any): any {
+	const router = useRouter();
+	setupScrollRestoration(router, true);
+	return getElementScrollRestorationEntry(router, options);
+}

package/src/useRouterState.ts

@@ -0,0 +1,17 @@
+// The reactive base every router hook reads through: subscribe to the router's
+// canonical snapshot store (`router.stores.__store`) and select a slice.
+import { useStore } from './useStore';
+import { useRouter } from './context';
+import { splitSlot, subSlot } from './internal';
+
+export function useRouterState(...args: any[]): any {
+	const [user, slot] = splitSlot(args);
+	const opts = (user[0] ?? {}) as { select?: (s: any) => any; router?: any };
+	const router = useRouter(opts.router ? { router: opts.router } : undefined);
+	return useStore(
+		router.stores.__store,
+		opts.select ?? ((s: any) => s),
+		undefined,
+		subSlot(slot, 'rs'),
+	);
+}

package/src/useStore.ts

@@ -0,0 +1,46 @@
+// The keystone adapter. Everything reactive in the router funnels through
+// `@tanstack/react-store`'s `useStore(atom, selector)`, which is
+// `useSyncExternalStoreWithSelector(atom.subscribe→unsubscribe, atom.get, …,
+// selector, compare)`. Octane has no `…WithSelector`, so we fold the selector +
+// compare into a memoized snapshot getter on top of octane's native
+// `useSyncExternalStore`. The atoms come from router-core's client store factory
+// (`createAtom` from `@tanstack/store`): `.subscribe(cb) → { unsubscribe }` + `.get()`.
+import { useSyncExternalStore, useCallback, useRef } from 'octane';
+import { subSlot, splitSlot } from './internal';
+
+interface Atom<T> {
+	subscribe: (cb: () => void) => { unsubscribe: () => void };
+	get: () => T;
+}
+
+export function useStore<T, S = T>(...args: any[]): S {
+	const [user, slot] = splitSlot(args);
+	const atom = user[0] as Atom<T>;
+	const selector = (user[1] ?? ((s: T) => s as unknown as S)) as (s: T) => S;
+	const compare = (user[2] ?? Object.is) as (a: S, b: S) => boolean;
+
+	// Re-subscribe only when the atom identity changes (it's stable across renders).
+	const subscribe = useCallback(
+		(onChange: () => void) => atom.subscribe(onChange).unsubscribe,
+		[atom],
+		subSlot(slot, 'us:cb'),
+	);
+
+	// Memoize selector output: same store input → same output; structurally-equal
+	// output keeps its previous reference (so useSyncExternalStore doesn't loop).
+	const cache = useRef<{ in: T; out: S } | null>(null, subSlot(slot, 'us:cache'));
+	const getSnapshot = (): S => {
+		const input = atom.get();
+		const prev = cache.current;
+		if (prev && Object.is(prev.in, input)) return prev.out;
+		const next = selector(input);
+		if (prev && compare(prev.out, next)) {
+			cache.current = { in: input, out: prev.out };
+			return prev.out;
+		}
+		cache.current = { in: input, out: next };
+		return next;
+	};
+
+	return useSyncExternalStore(subscribe, getSnapshot, getSnapshot, subSlot(slot, 'us:uses'));
+}

package/src/utils.ts

@@ -0,0 +1,18 @@
+// Small hook utilities ported from react-router's utils.tsx. Plain-`.ts` hooks
+// forward the caller's compiler-injected slot (see internal.ts).
+import { useRef } from 'octane';
+import { splitSlot, subSlot } from './internal';
+
+// Returns the value from the previous render (null on first render). Ported from
+// react-router's usePrevious — the previous/current pair lives in one ref cell and
+// rolls forward during render when the incoming value changes.
+export function usePrevious(...args: any[]): any {
+	const [user, slot] = splitSlot(args);
+	const value = user[0];
+	const ref = useRef({ value, prev: null }, subSlot(slot, 'prev'));
+	const current = ref.current.value;
+	if (value !== current) {
+		ref.current = { value, prev: current };
+	}
+	return ref.current.prev;
+}