@octanejs/tanstack-router 0.1.9 → 0.1.11

package/src/fileRoute.ts

@@ -0,0 +1,277 @@
+import { createRoute } from './route';
+import {
+	useLoaderData,
+	useLoaderDeps,
+	useMatch,
+	useNavigate,
+	useParams,
+	useRouteContext,
+	useSearch,
+} from './hooks';
+import { useRouter } from './context';
+import { splitSlot, subSlot } from './internal';
+import type {
+	AnyContext,
+	AnyRoute,
+	AnyRouter,
+	Constrain,
+	ConstrainLiteral,
+	FileBaseRouteOptions,
+	FileRoutesByPath,
+	LazyRouteOptions,
+	Register,
+	RegisteredRouter,
+	ResolveParams,
+	Route,
+	RouteById,
+	RouteConstraints,
+	RouteIds,
+	RouteLoaderEntry,
+	UpdatableRouteOptions,
+	UseNavigateResult,
+} from '@tanstack/router-core';
+import type {
+	UseLoaderDataRoute,
+	UseLoaderDepsRoute,
+	UseMatchRoute,
+	UseParamsRoute,
+	UseRouteContextRoute,
+	UseSearchRoute,
+} from './routeHookTypes';
+
+declare const process: {
+	env: {
+		NODE_ENV?: string;
+	};
+};
+
+export function createFileRoute<
+	TFilePath extends keyof FileRoutesByPath,
+	TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'],
+	TId extends RouteConstraints['TId'] = FileRoutesByPath[TFilePath]['id'],
+	TPath extends RouteConstraints['TPath'] = FileRoutesByPath[TFilePath]['path'],
+	TFullPath extends RouteConstraints['TFullPath'] = FileRoutesByPath[TFilePath]['fullPath'],
+>(path?: TFilePath): FileRoute<TFilePath, TParentRoute, TId, TPath, TFullPath>['createRoute'] {
+	return new FileRoute<TFilePath, TParentRoute, TId, TPath, TFullPath>(path, {
+		silent: true,
+	}).createRoute;
+}
+
+/** @deprecated Use `createFileRoute(path)(options)` instead. */
+export class FileRoute<
+	TFilePath extends keyof FileRoutesByPath,
+	TParentRoute extends AnyRoute = FileRoutesByPath[TFilePath]['parentRoute'],
+	TId extends RouteConstraints['TId'] = FileRoutesByPath[TFilePath]['id'],
+	TPath extends RouteConstraints['TPath'] = FileRoutesByPath[TFilePath]['path'],
+	TFullPath extends RouteConstraints['TFullPath'] = FileRoutesByPath[TFilePath]['fullPath'],
+> {
+	silent?: boolean;
+
+	constructor(
+		public path?: TFilePath,
+		_opts?: { silent: boolean },
+	) {
+		this.silent = _opts?.silent;
+	}
+
+	createRoute = <
+		TRegister = Register,
+		TSearchValidator = undefined,
+		TParams = ResolveParams<TPath>,
+		TRouteContextFn = AnyContext,
+		TBeforeLoadFn = AnyContext,
+		TLoaderDeps extends Record<string, any> = {},
+		TLoaderFn = undefined,
+		TChildren = unknown,
+		TSSR = unknown,
+		const TMiddlewares = unknown,
+		THandlers = undefined,
+	>(
+		options?: FileBaseRouteOptions<
+			TRegister,
+			TParentRoute,
+			TId,
+			TPath,
+			TSearchValidator,
+			TParams,
+			TLoaderDeps,
+			TLoaderFn,
+			AnyContext,
+			TRouteContextFn,
+			TBeforeLoadFn,
+			AnyContext,
+			TSSR,
+			TMiddlewares,
+			THandlers
+		> &
+			UpdatableRouteOptions<
+				TParentRoute,
+				TId,
+				TFullPath,
+				TParams,
+				TSearchValidator,
+				TLoaderFn,
+				TLoaderDeps,
+				AnyContext,
+				TRouteContextFn,
+				TBeforeLoadFn
+			>,
+	): Route<
+		TRegister,
+		TParentRoute,
+		TPath,
+		TFullPath,
+		TFilePath,
+		TId,
+		TSearchValidator,
+		TParams,
+		AnyContext,
+		TRouteContextFn,
+		TBeforeLoadFn,
+		TLoaderDeps,
+		TLoaderFn,
+		TChildren,
+		unknown,
+		TSSR,
+		TMiddlewares,
+		THandlers
+	> => {
+		if (process.env.NODE_ENV !== 'production' && !this.silent) {
+			console.warn('Warning: FileRoute is deprecated. Use createFileRoute(path)(options) instead.');
+		}
+		const route = createRoute(options as any);
+		(route as any).isRoot = false;
+		return route as any;
+	};
+}
+
+/** @deprecated Place the loader in the main `createFileRoute` options. */
+export function FileRouteLoader<
+	TFilePath extends keyof FileRoutesByPath,
+	TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],
+>(
+	_path: TFilePath,
+): <TLoaderFn>(
+	loaderFn: Constrain<
+		TLoaderFn,
+		RouteLoaderEntry<
+			Register,
+			TRoute['parentRoute'],
+			TRoute['types']['id'],
+			TRoute['types']['params'],
+			TRoute['types']['loaderDeps'],
+			TRoute['types']['routerContext'],
+			TRoute['types']['routeContextFn'],
+			TRoute['types']['beforeLoadFn']
+		>
+	>,
+) => TLoaderFn {
+	if (process.env.NODE_ENV !== 'production') {
+		console.warn(
+			'Warning: FileRouteLoader is deprecated. Place the loader in createFileRoute options.',
+		);
+	}
+	return (loaderFn) => loaderFn as never;
+}
+
+declare module '@tanstack/router-core' {
+	export interface LazyRoute<in out TRoute extends AnyRoute> {
+		useMatch: UseMatchRoute<TRoute['id']>;
+		useRouteContext: UseRouteContextRoute<TRoute['id']>;
+		useSearch: UseSearchRoute<TRoute['id']>;
+		useParams: UseParamsRoute<TRoute['id']>;
+		useLoaderDeps: UseLoaderDepsRoute<TRoute['id']>;
+		useLoaderData: UseLoaderDataRoute<TRoute['id']>;
+		useNavigate: () => UseNavigateResult<TRoute['fullPath']>;
+	}
+}
+
+export class LazyRoute<TRoute extends AnyRoute> {
+	options: { id: string } & LazyRouteOptions;
+	declare useMatch: UseMatchRoute<TRoute['id']>;
+	declare useRouteContext: UseRouteContextRoute<TRoute['id']>;
+	declare useSearch: UseSearchRoute<TRoute['id']>;
+	declare useParams: UseParamsRoute<TRoute['id']>;
+	declare useLoaderDeps: UseLoaderDepsRoute<TRoute['id']>;
+	declare useLoaderData: UseLoaderDataRoute<TRoute['id']>;
+	declare useNavigate: () => UseNavigateResult<TRoute['fullPath']>;
+
+	constructor(opts: { id: string } & LazyRouteOptions) {
+		this.options = opts;
+		const id = this.options.id;
+		this.useMatch = ((...args: Array<any>) => {
+			const [user, slot] = splitSlot(args);
+			const options = user[0] ?? {};
+			return useMatch(
+				{
+					select: options.select,
+					from: id,
+					structuralSharing: options.structuralSharing,
+				},
+				subSlot(slot, 'lr:m'),
+			);
+		}) as typeof this.useMatch;
+		this.useRouteContext = ((...args: Array<any>) => {
+			const [user, slot] = splitSlot(args);
+			return useRouteContext({ ...(user[0] ?? {}), from: id }, subSlot(slot, 'lr:c'));
+		}) as typeof this.useRouteContext;
+		this.useSearch = ((...args: Array<any>) => {
+			const [user, slot] = splitSlot(args);
+			const options = user[0] ?? {};
+			return useSearch(
+				{
+					select: options.select,
+					from: id,
+					structuralSharing: options.structuralSharing,
+				},
+				subSlot(slot, 'lr:s'),
+			);
+		}) as typeof this.useSearch;
+		this.useParams = ((...args: Array<any>) => {
+			const [user, slot] = splitSlot(args);
+			const options = user[0] ?? {};
+			return useParams(
+				{
+					select: options.select,
+					from: id,
+					structuralSharing: options.structuralSharing,
+				},
+				subSlot(slot, 'lr:p'),
+			);
+		}) as typeof this.useParams;
+		this.useLoaderDeps = ((...args: Array<any>) => {
+			const [user, slot] = splitSlot(args);
+			return useLoaderDeps({ ...(user[0] ?? {}), from: id }, subSlot(slot, 'lr:d'));
+		}) as typeof this.useLoaderDeps;
+		this.useLoaderData = ((...args: Array<any>) => {
+			const [user, slot] = splitSlot(args);
+			return useLoaderData({ ...(user[0] ?? {}), from: id }, subSlot(slot, 'lr:l'));
+		}) as typeof this.useLoaderData;
+		this.useNavigate = ((...args: Array<any>) => {
+			const [, slot] = splitSlot(args);
+			const router = useRouter();
+			return useNavigate(
+				{ from: (router.routesById as Record<string, any>)[id].fullPath },
+				subSlot(slot, 'lr:n'),
+			);
+		}) as typeof this.useNavigate;
+	}
+}
+
+export function createLazyRoute<
+	TRouter extends AnyRouter = RegisteredRouter,
+	TId extends string = string,
+	TRoute extends AnyRoute = RouteById<TRouter['routeTree'], TId>,
+>(id: ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>) {
+	return (opts: LazyRouteOptions) => new LazyRoute<TRoute>({ id, ...opts });
+}
+
+export function createLazyFileRoute<
+	TFilePath extends keyof FileRoutesByPath,
+	TRoute extends FileRoutesByPath[TFilePath]['preLoaderRoute'],
+>(id: TFilePath): (opts: LazyRouteOptions) => LazyRoute<TRoute> {
+	if (typeof id === 'object') {
+		return new LazyRoute<TRoute>(id) as any;
+	}
+	return (opts: LazyRouteOptions) => new LazyRoute<TRoute>({ id, ...opts });
+}

package/src/frameworkTypes.ts

@@ -0,0 +1,42 @@
+import type { MetaDescriptor, UseNavigateResult } from '@tanstack/router-core';
+import type { LinkComponentRoute } from './linkTypes';
+import type {
+	UseLoaderDataRoute,
+	UseLoaderDepsRoute,
+	UseMatchRoute,
+	UseParamsRoute,
+	UseRouteContextRoute,
+	UseSearchRoute,
+} from './routeHookTypes';
+
+export type OctaneElementAttributes = Record<string, string | number | boolean | null | undefined>;
+
+export type OctaneScriptAttributes = OctaneElementAttributes & {
+	children?: string;
+};
+
+declare module '@tanstack/router-core' {
+	interface RouteMatchExtensions {
+		// router-core 1.171.15's source RouteMatch carries this field, and its SSR
+		// declarations index it while the published Matches.d.ts accidentally omits
+		// it. Keep the binding's public SSR entry type-checkable without asking
+		// consumers to enable skipLibCheck.
+		__beforeLoadContext?: Record<string, unknown>;
+		meta?: Array<MetaDescriptor | undefined>;
+		links?: Array<OctaneElementAttributes | undefined>;
+		scripts?: Array<OctaneScriptAttributes | undefined>;
+		styles?: Array<OctaneScriptAttributes | undefined>;
+		headScripts?: Array<OctaneScriptAttributes | undefined>;
+	}
+
+	interface RouteExtensions<in out TId extends string, in out TFullPath extends string> {
+		useMatch: UseMatchRoute<TId>;
+		useRouteContext: UseRouteContextRoute<TId>;
+		useSearch: UseSearchRoute<TId>;
+		useParams: UseParamsRoute<TId>;
+		useLoaderDeps: UseLoaderDepsRoute<TId>;
+		useLoaderData: UseLoaderDataRoute<TId>;
+		useNavigate: () => UseNavigateResult<TFullPath>;
+		Link: LinkComponentRoute<TFullPath>;
+	}
+}

package/src/generator-plugin.d.ts

@@ -0,0 +1,20 @@
+export interface TransformRouteSourceOptions {
+	source: string;
+	filename: string;
+	node: unknown;
+}
+
+export interface FormatRouteOptions {
+	source: string;
+	node: unknown;
+}
+
+export interface OctaneRouteGeneratorPlugin {
+	name: string;
+	transformRouteSource: (options: TransformRouteSourceOptions) => string;
+	formatRoute: (options: FormatRouteOptions) => string;
+}
+
+export declare function maskOctaneRouteSource(source: string, filename?: string): string;
+
+export declare function octaneRouteGeneratorPlugin(): OctaneRouteGeneratorPlugin;

package/src/generator-plugin.js

@@ -0,0 +1,100 @@
+import { compileToVolarMappings } from 'octane/compiler/volar';
+
+/**
+ * @typedef {object} AstNode
+ * @property {AstNode | Array<AstNode>} [body]
+ * @property {number} [start]
+ * @property {number} [end]
+ * @property {{ native_tsrx_body?: boolean }} [metadata]
+ */
+
+/**
+ * Makes TSRX route modules parseable by the router generator without changing
+ * source offsets. The generator applies edits to the original source, so the
+ * authored Octane template bodies remain byte-for-byte intact.
+ *
+ * @param {string} source
+ * @param {string} [filename]
+ * @returns {string}
+ */
+export function maskOctaneRouteSource(source, filename = 'route.tsrx') {
+	const { sourceAst } = compileToVolarMappings(source, filename);
+	const output = source.split('');
+
+	for (const body of findNativeTemplateBodies(/** @type {AstNode} */ (sourceAst))) {
+		const { start, end } = body;
+		output[start] = ' ';
+		output[start + 1] = '{';
+		for (let index = start + 2; index < end - 1; index++) {
+			if (source[index] !== '\n' && source[index] !== '\r') {
+				output[index] = ' ';
+			}
+		}
+		output[end - 1] = '}';
+	}
+
+	return output.join('');
+}
+
+/**
+ * @returns {{
+ *   name: string
+ *   transformRouteSource: (options: { source: string, filename: string }) => string
+ *   formatRoute: (options: { source: string }) => string
+ * }}
+ */
+export function octaneRouteGeneratorPlugin() {
+	return {
+		name: 'octane-route-source',
+		transformRouteSource: ({ source, filename }) => maskOctaneRouteSource(source, filename),
+		// Router scaffolds are already formatted. Returning them unchanged avoids
+		// passing TSRX's `@{}` syntax through a TypeScript-only formatter.
+		formatRoute: ({ source }) => source,
+	};
+}
+
+/**
+ * @param {AstNode} root
+ * @returns {Array<{ start: number, end: number }>}
+ */
+function findNativeTemplateBodies(root) {
+	/** @type {Array<{ start: number, end: number }>} */
+	const bodies = [];
+	const visited = new WeakSet();
+
+	/** @param {unknown} value */
+	const visit = (value) => {
+		if (!value || typeof value !== 'object' || visited.has(value)) {
+			return;
+		}
+		visited.add(value);
+
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				visit(item);
+			}
+			return;
+		}
+
+		const node = /** @type {AstNode} */ (value);
+		if (
+			node.metadata?.native_tsrx_body === true &&
+			node.body &&
+			!Array.isArray(node.body) &&
+			typeof node.body.start === 'number' &&
+			typeof node.body.end === 'number'
+		) {
+			bodies.push({ start: node.body.start, end: node.body.end });
+			return;
+		}
+
+		for (const [key, child] of Object.entries(node)) {
+			if (key !== 'metadata' && key !== 'loc') {
+				visit(child);
+			}
+		}
+	};
+
+	visit(root);
+	return bodies;
+}

package/src/headContentUtils.ts

@@ -0,0 +1,172 @@
+import {
+	appendUniqueUserTags,
+	deepEqual,
+	escapeHtml,
+	getAssetCrossOrigin,
+	getScriptPreloadAttrs,
+	resolveManifestCssLink,
+} from '@tanstack/router-core';
+import { isServer } from '@tanstack/router-core/isServer';
+import { useRouter } from './context';
+import { splitSlot, subSlot } from './internal';
+import { useStore } from './useStore';
+import type {
+	AnyRouteMatch,
+	AnyRouter,
+	AssetCrossOriginConfig,
+	RouterManagedTag,
+} from '@tanstack/router-core';
+
+function buildTagsFromMatches(
+	router: AnyRouter,
+	nonce: string | undefined,
+	matches: Array<AnyRouteMatch>,
+	assetCrossOrigin?: AssetCrossOriginConfig,
+): Array<RouterManagedTag> {
+	const routeMeta = matches.map((match) => match.meta).filter((meta) => meta !== undefined);
+
+	const resultMeta: Array<RouterManagedTag> = [];
+	const metaByAttribute: Record<string, true> = {};
+	let title: RouterManagedTag | undefined;
+	for (let i = routeMeta.length - 1; i >= 0; i--) {
+		const metas = routeMeta[i]!;
+		for (let j = metas.length - 1; j >= 0; j--) {
+			const meta = metas[j];
+			if (!meta) {
+				continue;
+			}
+
+			if ('title' in meta && typeof meta.title === 'string') {
+				title ??= { tag: 'title', children: meta.title };
+			} else if ('script:ld+json' in meta) {
+				try {
+					resultMeta.push({
+						tag: 'script',
+						attrs: { type: 'application/ld+json' },
+						children: escapeHtml(JSON.stringify(meta['script:ld+json'])),
+					});
+				} catch {
+					// Ignore values that cannot be serialized as JSON-LD.
+				}
+			} else {
+				const attribute =
+					('name' in meta && typeof meta.name === 'string' ? meta.name : undefined) ??
+					('property' in meta && typeof meta.property === 'string' ? meta.property : undefined);
+				if (attribute && metaByAttribute[attribute]) {
+					continue;
+				}
+				if (attribute) {
+					metaByAttribute[attribute] = true;
+				}
+				resultMeta.push({ tag: 'meta', attrs: { ...meta, nonce } });
+			}
+		}
+	}
+
+	if (title) {
+		resultMeta.push(title);
+	}
+	if (nonce) {
+		resultMeta.push({
+			tag: 'meta',
+			attrs: { property: 'csp-nonce', content: nonce },
+		});
+	}
+	resultMeta.reverse();
+
+	const links = matches
+		.flatMap((match) => match.links ?? [])
+		.filter((link) => link !== undefined)
+		.map((link) => ({ tag: 'link', attrs: { ...link, nonce } }) satisfies RouterManagedTag);
+
+	const manifestTags: Array<RouterManagedTag> = [];
+	const preloadTags: Array<RouterManagedTag> = [];
+	const manifest = router.ssr?.manifest;
+	if (manifest) {
+		for (const match of matches) {
+			for (const link of manifest.routes[match.routeId]?.css ?? []) {
+				const resolvedLink = resolveManifestCssLink(link);
+				manifestTags.push({
+					tag: 'link',
+					attrs: {
+						rel: 'stylesheet',
+						...resolvedLink,
+						crossOrigin:
+							getAssetCrossOrigin(assetCrossOrigin, 'stylesheet') ?? resolvedLink.crossOrigin,
+						nonce,
+					},
+				});
+			}
+			for (const preload of manifest.routes[match.routeId]?.preloads ?? []) {
+				preloadTags.push({
+					tag: 'link',
+					attrs: {
+						...getScriptPreloadAttrs(manifest, preload, assetCrossOrigin),
+						nonce,
+					},
+				});
+			}
+		}
+
+		if (manifest.inlineStyle) {
+			manifestTags.push({
+				tag: 'style',
+				attrs: { ...manifest.inlineStyle.attrs, nonce },
+				children: manifest.inlineStyle.children,
+				inlineCss: true,
+			});
+		}
+	}
+
+	const styles = matches
+		.flatMap((match) => match.styles ?? [])
+		.filter((style) => style !== undefined)
+		.map(
+			({ children, ...attrs }) =>
+				({
+					tag: 'style',
+					attrs: { ...attrs, nonce },
+					children: children,
+				}) satisfies RouterManagedTag,
+		);
+
+	const headScripts = matches
+		.flatMap((match) => match.headScripts ?? [])
+		.filter((script) => script !== undefined)
+		.map(
+			({ children, ...attrs }) =>
+				({
+					tag: 'script',
+					attrs: { ...attrs, nonce },
+					children: children,
+				}) satisfies RouterManagedTag,
+		);
+
+	const tags: Array<RouterManagedTag> = [];
+	appendUniqueUserTags(tags, resultMeta);
+	tags.push(...preloadTags);
+	appendUniqueUserTags(tags, links);
+	tags.push(...manifestTags);
+	appendUniqueUserTags(tags, styles);
+	appendUniqueUserTags(tags, headScripts);
+	return tags;
+}
+
+export function useTags(...args: Array<unknown>): Array<RouterManagedTag> {
+	const [userArgs, slot] = splitSlot(args);
+	const assetCrossOrigin = userArgs[0] as AssetCrossOriginConfig | undefined;
+	const router = useRouter();
+	const nonce = router.options.ssr?.nonce;
+
+	if (isServer ?? router.isServer) {
+		return buildTagsFromMatches(router, nonce, router.stores.matches.get(), assetCrossOrigin);
+	}
+
+	return useStore(
+		router.stores.matches,
+		(matches: Array<AnyRouteMatch>) =>
+			buildTagsFromMatches(router, nonce, matches, assetCrossOrigin),
+		deepEqual,
+		subSlot(slot, 'head:tags'),
+	);
+}