@octanejs/remix-router 0.1.0

package/src/lib/dom/routers.tsrx

@@ -0,0 +1,104 @@
+// BrowserRouter / HashRouter / HistoryRouter — transcribed from
+// react-router@7.18.1 lib/dom/lib.tsx. Declarative routers over browser /
+// hash / caller-provided history (upstream repeats the subscribe body in each;
+// so does this transcription).
+import { startTransition, useCallback, useLayoutEffect, useRef, useState } from 'octane';
+import { createBrowserHistory, createHashHistory } from '../router/history';
+import { Router } from '../components/Router.tsrx';
+
+export function BrowserRouter(props) @{
+	const { basename, children, useTransitions, window } = props;
+
+	const historyRef = useRef(null);
+	if (historyRef.current == null) {
+		historyRef.current = createBrowserHistory({ window, v5Compat: true });
+	}
+
+	const history = historyRef.current;
+	const [state, setStateImpl] = useState({
+		action: history.action,
+		location: history.location,
+	});
+	const setState = useCallback((newState) => {
+		if (useTransitions === false) {
+			setStateImpl(newState);
+		} else {
+			startTransition(() => setStateImpl(newState));
+		}
+	}, [useTransitions]);
+
+	useLayoutEffect(() => history.listen(setState), [history, setState]);
+
+	<Router
+		basename={basename}
+		location={state.location}
+		navigationType={state.action}
+		navigator={history}
+		useTransitions={useTransitions}
+		children={children}
+	/>
+}
+
+export function HashRouter(props) @{
+	const { basename, children, useTransitions, window } = props;
+
+	const historyRef = useRef(null);
+	if (historyRef.current == null) {
+		historyRef.current = createHashHistory({ window, v5Compat: true });
+	}
+
+	const history = historyRef.current;
+	const [state, setStateImpl] = useState({
+		action: history.action,
+		location: history.location,
+	});
+	const setState = useCallback((newState) => {
+		if (useTransitions === false) {
+			setStateImpl(newState);
+		} else {
+			startTransition(() => setStateImpl(newState));
+		}
+	}, [useTransitions]);
+
+	useLayoutEffect(() => history.listen(setState), [history, setState]);
+
+	<Router
+		basename={basename}
+		location={state.location}
+		navigationType={state.action}
+		navigator={history}
+		useTransitions={useTransitions}
+		children={children}
+	/>
+}
+
+/**
+ * A declarative router that accepts a pre-instantiated `history` object.
+ * Exported as `unstable_HistoryRouter`, as upstream.
+ */
+export function HistoryRouter(props) @{
+	const { basename, children, history, useTransitions } = props;
+
+	const [state, setStateImpl] = useState({
+		action: history.action,
+		location: history.location,
+	});
+	const setState = useCallback((newState) => {
+		if (useTransitions === false) {
+			setStateImpl(newState);
+		} else {
+			startTransition(() => setStateImpl(newState));
+		}
+	}, [useTransitions]);
+
+	useLayoutEffect(() => history.listen(setState), [history, setState]);
+
+	<Router
+		basename={basename}
+		location={state.location}
+		navigationType={state.action}
+		navigator={history}
+		useTransitions={useTransitions}
+		children={children}
+	/>
+}

package/src/lib/dom/routers.tsrx.d.ts

@@ -0,0 +1,23 @@
+// Type declaration for the .tsrx components (resolved by relative path).
+import type { History } from '../router/history';
+
+export declare const BrowserRouter: (props: {
+	basename?: string;
+	children?: unknown;
+	useTransitions?: boolean;
+	window?: Window;
+}) => unknown;
+
+export declare const HashRouter: (props: {
+	basename?: string;
+	children?: unknown;
+	useTransitions?: boolean;
+	window?: Window;
+}) => unknown;
+
+export declare const HistoryRouter: (props: {
+	basename?: string;
+	children?: unknown;
+	history: History;
+	useTransitions?: boolean;
+}) => unknown;

package/src/lib/dom/server.tsrx

@@ -0,0 +1,350 @@
+// Static SSR — transcribed from react-router@7.18.1 lib/dom/server.tsx onto
+// octane: StaticRouter (a Router that may not navigate), StaticRouterProvider
+// (renders a static data router + the __staticRouterHydrationData script),
+// createStaticHandler (the dom wrapper adding mapRouteProperties), and
+// createStaticRouter (a stateless DataRouter over a StaticHandlerContext).
+// Render through `octane/server` (renderToString / renderToPipeableStream).
+import type { Location, Path, To } from '../router/history.ts';
+import { Action as NavigationType, createPath, invariant, parsePath } from '../router/history.ts';
+import {
+	IDLE_BLOCKER,
+	IDLE_FETCHER,
+	IDLE_NAVIGATION,
+	createStaticHandler as routerCreateStaticHandler,
+} from '../router/router.ts';
+import { convertRoutesToDataRoutes, isRouteErrorResponse } from '../router/utils.ts';
+import { ABSOLUTE_URL_REGEX } from '../router/url.ts';
+import { Router } from '../components/Router.tsrx';
+import { DataRoutes } from '../components/RouterProvider.tsrx';
+import { mapRouteProperties } from '../components/utils.ts';
+import {
+	DataRouterContext,
+	DataRouterStateContext,
+	FetchersContext,
+	ViewTransitionContext,
+} from '../context.ts';
+
+/**
+ * A Router that may not navigate to any other location. This is useful on the
+ * server where there is no stateful UI.
+ */
+export function StaticRouter(props) @{
+	const { basename, children, location: locationPropIn = '/' } = props;
+
+	let locationProp = locationPropIn;
+	if (typeof locationProp === 'string') {
+		locationProp = parsePath(locationProp);
+	}
+
+	const action = NavigationType.Pop;
+	const location = {
+		pathname: locationProp.pathname || '/',
+		search: locationProp.search || '',
+		hash: locationProp.hash || '',
+		state: locationProp.state != null ? locationProp.state : null,
+		key: locationProp.key || 'default',
+		mask: undefined,
+	};
+
+	const staticNavigator = getStatelessNavigator();
+	<Router
+		basename={basename}
+		location={location}
+		navigationType={action}
+		navigator={staticNavigator}
+		static={true}
+		useTransitions={false}
+		children={children}
+	/>
+}
+
+/**
+ * A DataRouter that may not navigate to any other location. This is useful on
+ * the server where there is no stateful UI.
+ */
+export function StaticRouterProvider(props) @{
+	const { context, router, hydrate = true, nonce } = props;
+
+	invariant(router && context, 'You must provide `router` and `context` to <StaticRouterProvider>');
+
+	const dataRouterContext = {
+		router,
+		navigator: getStatelessNavigator(),
+		static: true,
+		staticContext: context,
+		basename: context.basename || '/',
+	};
+
+	const fetchersContext = new Map();
+
+	let hydrateScript = '';
+
+	if (hydrate !== false) {
+		const data = {
+			loaderData: context.loaderData,
+			actionData: context.actionData,
+			errors: serializeErrors(context.errors),
+		};
+		// Use JSON.parse here instead of embedding a raw JS object here to speed
+		// up parsing on the client.  Dual-stringify is needed to ensure all quotes
+		// are properly escaped in the resulting string.  See:
+		//   https://v8.dev/blog/cost-of-javascript-2019#json
+		const json = escapeHtml(JSON.stringify(JSON.stringify(data)));
+		hydrateScript = `window.__staticRouterHydrationData = JSON.parse(${json});`;
+	}
+
+	const { state } = dataRouterContext.router;
+
+	<>
+		<DataRouterContext.Provider value={dataRouterContext}>
+			<DataRouterStateContext.Provider value={state}>
+				<FetchersContext.Provider value={fetchersContext}>
+					<ViewTransitionContext.Provider value={{ isTransitioning: false }}>
+						<Router
+							basename={dataRouterContext.basename}
+							location={state.location}
+							navigationType={state.historyAction}
+							navigator={dataRouterContext.navigator}
+							static={dataRouterContext.static}
+							useTransitions={false}
+						>
+							<DataRoutes
+								manifest={router.manifest}
+								routes={router.routes}
+								future={router.future}
+								state={state}
+								isStatic={true}
+							/>
+						</Router>
+					</ViewTransitionContext.Provider>
+				</FetchersContext.Provider>
+			</DataRouterStateContext.Provider>
+		</DataRouterContext.Provider>
+		@if (hydrateScript !== '') {
+			<script
+				suppressHydrationWarning
+				nonce={nonce}
+				dangerouslySetInnerHTML={{ __html: hydrateScript }}
+			/>
+		}
+	</>
+}
+
+function serializeErrors(errors) {
+	if (!errors) return null;
+	const entries = Object.entries(errors);
+	const serialized = {};
+	for (const [key, val] of entries) {
+		// Hey you!  If you change this, please change the corresponding logic in
+		// deserializeErrors in react-router-dom/index.tsx :)
+		if (isRouteErrorResponse(val)) {
+			serialized[key] = { ...val, __type: 'RouteErrorResponse' };
+		} else if (val instanceof Error) {
+			// Do not serialize stack traces from SSR for security reasons
+			serialized[key] = {
+				message: val.message,
+				__type: 'Error',
+				// If this is a subclass (i.e., ReferenceError), send up the type so we
+				// can re-create the same type during hydration.
+				...(val.name !== 'Error'
+					? {
+							__subType: val.name,
+						}
+					: {}),
+			};
+		} else {
+			serialized[key] = val;
+		}
+	}
+	return serialized;
+}
+
+function getStatelessNavigator() {
+	return {
+		createHref,
+		encodeLocation,
+		push(to) {
+			throw new Error(`You cannot use navigator.push() on the server because it is a stateless ` +
+				`environment. This error was probably triggered when you did a ` +
+				`\`navigate(${JSON.stringify(to)})\` somewhere in your app.`);
+		},
+		replace(to) {
+			throw new Error(`You cannot use navigator.replace() on the server because it is a stateless ` +
+				`environment. This error was probably triggered when you did a ` +
+				`\`navigate(${JSON.stringify(to)}, { replace: true })\` somewhere ` +
+				`in your app.`);
+		},
+		go(delta) {
+			throw new Error(`You cannot use navigator.go() on the server because it is a stateless ` +
+				`environment. This error was probably triggered when you did a ` +
+				`\`navigate(${delta})\` somewhere in your app.`);
+		},
+		back() {
+			throw new Error(`You cannot use navigator.back() on the server because it is a stateless ` +
+				`environment.`);
+		},
+		forward() {
+			throw new Error(`You cannot use navigator.forward() on the server because it is a stateless ` +
+				`environment.`);
+		},
+	};
+}
+
+/**
+ * Create a static handler to perform server-side data loading.
+ */
+export function createStaticHandler(routes, opts) {
+	return routerCreateStaticHandler(routes, {
+		...opts,
+		mapRouteProperties,
+	});
+}
+
+/**
+ * Create a static DataRouter for server-side rendering.
+ */
+export function createStaticRouter(routes, context, opts = {}) {
+	const manifest = {};
+	const dataRoutes = convertRoutesToDataRoutes(routes, mapRouteProperties, undefined, manifest);
+
+	// Because our context matches may be from a set of routes passed to
+	// createStaticHandler(), we update them here with our newly created/enhanced
+	// data routes
+	const matches = context.matches.map((match) => {
+		const route = manifest[match.route.id] || match.route;
+		return {
+			...match,
+			route,
+		};
+	});
+
+	const msg = (method) =>
+		`You cannot use router.${method}() on the server because it is a stateless environment`;
+
+	return {
+		get basename() {
+			return context.basename;
+		},
+		get future() {
+			return {
+				v8_middleware: false,
+				v8_passThroughRequests: false,
+				v8_trailingSlashAwareDataRequests: false,
+				...opts?.future,
+			};
+		},
+		get state() {
+			return {
+				historyAction: NavigationType.Pop,
+				location: context.location,
+				matches,
+				loaderData: context.loaderData,
+				actionData: context.actionData,
+				errors: context.errors,
+				initialized: true,
+				renderFallback: false,
+				navigation: IDLE_NAVIGATION,
+				restoreScrollPosition: null,
+				preventScrollReset: false,
+				revalidation: 'idle',
+				fetchers: new Map(),
+				blockers: new Map(),
+			};
+		},
+		get routes() {
+			return dataRoutes;
+		},
+		get branches() {
+			return opts.branches;
+		},
+		get manifest() {
+			return manifest;
+		},
+		get window() {
+			return undefined;
+		},
+		initialize() {
+			throw msg('initialize');
+		},
+		subscribe() {
+			throw msg('subscribe');
+		},
+		enableScrollRestoration() {
+			throw msg('enableScrollRestoration');
+		},
+		navigate() {
+			throw msg('navigate');
+		},
+		fetch() {
+			throw msg('fetch');
+		},
+		revalidate() {
+			throw msg('revalidate');
+		},
+		createHref,
+		encodeLocation,
+		getFetcher() {
+			return IDLE_FETCHER;
+		},
+		deleteFetcher() {
+			throw msg('deleteFetcher');
+		},
+		resetFetcher() {
+			throw msg('resetFetcher');
+		},
+		dispose() {
+			throw msg('dispose');
+		},
+		getBlocker() {
+			return IDLE_BLOCKER;
+		},
+		deleteBlocker() {
+			throw msg('deleteBlocker');
+		},
+		patchRoutes() {
+			throw msg('patchRoutes');
+		},
+		_internalFetchControllers: new Map(),
+		_internalSetRoutes() {
+			throw msg('_internalSetRoutes');
+		},
+		_internalSetStateDoNotUseOrYouWillBreakYourApp() {
+			throw msg('_internalSetStateDoNotUseOrYouWillBreakYourApp');
+		},
+	};
+}
+
+function createHref(to) {
+	return typeof to === 'string' ? to : createPath(to);
+}
+
+function encodeLocation(to) {
+	let href =
+		typeof to === 'string' ? to : createPath(to);
+	// Treating this as a full URL will strip any trailing spaces so we need to
+	// pre-encode them since they might be part of a matching splat param from
+	// an ancestor route
+	href = href.replace(/ $/, '%20');
+	const encoded = ABSOLUTE_URL_REGEX.test(href) ? new URL(href) : new URL(href, 'http://localhost');
+	return {
+		pathname: encoded.pathname,
+		search: encoded.search,
+		hash: encoded.hash,
+	};
+}
+
+// Upstream imports escapeHtml from lib/dom/ssr/markup.ts (framework dir, not
+// vendored) — the implementation is this table escape, transcribed verbatim.
+const ESCAPE_LOOKUP: { [match: string]: string } = {
+	'&': '\\u0026',
+	'>': '\\u003e',
+	'<': '\\u003c',
+	'
': '\\u2028',
+	'
': '\\u2029',
+};
+
+const ESCAPE_REGEX = /[&><\u2028\u2029]/g;
+
+function escapeHtml(html: string): string {
+	return html.replace(ESCAPE_REGEX, (match) => ESCAPE_LOOKUP[match]);
+}

package/src/lib/dom/server.tsrx.d.ts

@@ -0,0 +1,25 @@
+// Type declaration for the .tsrx module (resolved by relative path).
+import type { Location } from '../router/history';
+import type { Router as DataRouter, StaticHandler, StaticHandlerContext } from '../router/router';
+import type { RouteObject } from '../router/utils';
+
+export declare const StaticRouter: (props: {
+	basename?: string;
+	children?: unknown;
+	location?: Partial<Location> | string;
+}) => unknown;
+
+export declare const StaticRouterProvider: (props: {
+	context: StaticHandlerContext;
+	router: DataRouter;
+	hydrate?: boolean;
+	nonce?: string;
+}) => unknown;
+
+export declare function createStaticHandler(routes: RouteObject[], opts?: any): StaticHandler;
+
+export declare function createStaticRouter(
+	routes: RouteObject[],
+	context: StaticHandlerContext,
+	opts?: { branches?: any[]; future?: any },
+): DataRouter;

package/src/lib/errors.ts

@@ -0,0 +1,84 @@
+// Vendored from react-router@7.18.1 packages/react-router/lib/errors.ts — unmodified.
+// Re-vendor with `node scripts/vendor-remix-router.mjs`; never hand-edit.
+import { isDataWithResponseInit } from './router/router';
+import { ErrorResponseImpl } from './router/utils';
+import type { DataWithResponseInit } from './router/utils';
+
+const ERROR_DIGEST_BASE = 'REACT_ROUTER_ERROR'; // 18
+const ERROR_DIGEST_REDIRECT = 'REDIRECT'; // 8
+const ERROR_DIGEST_ROUTE_ERROR_RESPONSE = 'ROUTE_ERROR_RESPONSE'; // 20
+
+export function createRedirectErrorDigest(response: Response) {
+	return `${ERROR_DIGEST_BASE}:${ERROR_DIGEST_REDIRECT}:${JSON.stringify({
+		status: response.status,
+		statusText: response.statusText,
+		location: response.headers.get('Location'),
+		reloadDocument: response.headers.get('X-Remix-Reload-Document') === 'true',
+		replace: response.headers.get('X-Remix-Replace') === 'true',
+	})}`;
+}
+
+export function decodeRedirectErrorDigest(digest: string):
+	| undefined
+	| {
+			status: number;
+			statusText: string;
+			location: string;
+			reloadDocument: boolean;
+			replace: boolean;
+	  } {
+	if (digest.startsWith(`${ERROR_DIGEST_BASE}:${ERROR_DIGEST_REDIRECT}:{`)) {
+		try {
+			let parsed = JSON.parse(digest.slice(28));
+			if (
+				typeof parsed === 'object' &&
+				parsed &&
+				typeof parsed.status === 'number' &&
+				typeof parsed.statusText === 'string' &&
+				typeof parsed.location === 'string' &&
+				typeof parsed.reloadDocument === 'boolean' &&
+				typeof parsed.replace === 'boolean'
+			) {
+				return parsed;
+			}
+		} catch {}
+	}
+}
+
+export function createRouteErrorResponseDigest(response: DataWithResponseInit<unknown> | Response) {
+	let status = 500;
+	let statusText = '';
+	let data: unknown;
+	if (isDataWithResponseInit(response)) {
+		status = response.init?.status ?? status;
+		statusText = response.init?.statusText ?? statusText;
+		data = response.data;
+	} else {
+		status = response.status;
+		statusText = response.statusText;
+		// We can't do async work here to read the response body.
+		data = undefined;
+	}
+
+	return `${ERROR_DIGEST_BASE}:${ERROR_DIGEST_ROUTE_ERROR_RESPONSE}:${JSON.stringify({
+		status,
+		statusText,
+		data,
+	})}`;
+}
+
+export function decodeRouteErrorResponseDigest(digest: string): undefined | ErrorResponseImpl {
+	if (digest.startsWith(`${ERROR_DIGEST_BASE}:${ERROR_DIGEST_ROUTE_ERROR_RESPONSE}:{`)) {
+		try {
+			let parsed = JSON.parse(digest.slice(40));
+			if (
+				typeof parsed === 'object' &&
+				parsed &&
+				typeof parsed.status === 'number' &&
+				typeof parsed.statusText === 'string'
+			) {
+				return new ErrorResponseImpl(parsed.status, parsed.statusText, parsed.data);
+			}
+		} catch {}
+	}
+}

package/src/lib/framework-stubs.ts

@@ -0,0 +1,103 @@
+// Framework-mode + RSC surface — THROWING STUBS. react-router's framework
+// mode (Meta/Links/Scripts, createRequestHandler over a @react-router/dev
+// ServerBuild, fog-of-war route discovery, turbo-stream single fetch) and the
+// RSC integration require the framework compiler/runtime, which is
+// permanently out of scope for this port (see docs/remix-router-port-plan.md
+// §1). Each export exists so the export surface reaches full parity honestly:
+// importing is safe; CALLING (or rendering) throws with a pointer to the
+// scope policy instead of failing somewhere deep inside.
+import { createContext } from 'octane';
+
+function frameworkStub(name: string): never {
+	throw new Error(
+		`${name} is part of react-router's FRAMEWORK mode (it requires the ` +
+			`@react-router/dev compiler/runtime), which @octanejs/remix-router does ` +
+			`not support. Library mode (data routers, declarative routers, Form/` +
+			`fetchers, static SSR) is fully supported — see ` +
+			`docs/remix-router-port-plan.md for the scope policy.`,
+	);
+}
+
+function rscStub(name: string): never {
+	throw new Error(
+		`${name} is part of react-router's RSC integration, which ` +
+			`@octanejs/remix-router does not support (octane has no RSC runtime). ` +
+			`See docs/remix-router-port-plan.md for the scope policy.`,
+	);
+}
+
+// ── Framework-mode components (throw on render) ────────────────────────────
+export function Meta(): never {
+	frameworkStub('<Meta>');
+}
+export function Links(): never {
+	frameworkStub('<Links>');
+}
+export function Scripts(): never {
+	frameworkStub('<Scripts>');
+}
+export function PrefetchPageLinks(): never {
+	frameworkStub('<PrefetchPageLinks>');
+}
+export function ServerRouter(): never {
+	frameworkStub('<ServerRouter>');
+}
+
+// ── Framework-mode utilities ────────────────────────────────────────────────
+export function createRoutesStub(): never {
+	frameworkStub('createRoutesStub');
+}
+export function createRequestHandler(): never {
+	frameworkStub('createRequestHandler');
+}
+export function unstable_setDevServerHooks(): never {
+	frameworkStub('unstable_setDevServerHooks');
+}
+
+// ── UNSAFE_ framework internals ─────────────────────────────────────────────
+// FrameworkContext is a real context upstream (consumers null-check it — e.g.
+// ScrollRestoration's SSR-script branch); a real octane context holding null
+// is the honest equivalent of "not in framework mode".
+export const FrameworkContext = createContext<null>(null);
+
+export function RemixErrorBoundary(): never {
+	frameworkStub('UNSAFE_RemixErrorBoundary');
+}
+export function getPatchRoutesOnNavigationFunction(): never {
+	frameworkStub('UNSAFE_getPatchRoutesOnNavigationFunction');
+}
+export function useFogOFWarDiscovery(): never {
+	frameworkStub('UNSAFE_useFogOFWarDiscovery');
+}
+export function getHydrationData(): never {
+	frameworkStub('UNSAFE_getHydrationData');
+}
+export function createClientRoutes(): never {
+	frameworkStub('UNSAFE_createClientRoutes');
+}
+export function createClientRoutesWithHMRRevalidationOptOut(): never {
+	frameworkStub('UNSAFE_createClientRoutesWithHMRRevalidationOptOut');
+}
+export function shouldHydrateRouteLoader(): never {
+	frameworkStub('UNSAFE_shouldHydrateRouteLoader');
+}
+
+// ── Turbo-stream single fetch (framework data protocol) ────────────────────
+export const SingleFetchRedirectSymbol = Symbol('SingleFetchRedirect');
+export function decodeViaTurboStream(): never {
+	frameworkStub('UNSAFE_decodeViaTurboStream');
+}
+export function getTurboStreamSingleFetchDataStrategy(): never {
+	frameworkStub('UNSAFE_getTurboStreamSingleFetchDataStrategy');
+}
+
+// ── RSC ─────────────────────────────────────────────────────────────────────
+export function routeRSCServerRequest(): never {
+	rscStub('unstable_routeRSCServerRequest');
+}
+export function RSCStaticRouter(): never {
+	rscStub('unstable_RSCStaticRouter');
+}
+export function RSCDefaultRootErrorBoundary(): never {
+	rscStub('UNSAFE_RSCDefaultRootErrorBoundary');
+}