@timber-js/app 0.2.0-alpha.90 → 0.2.0-alpha.92

package/dist/_chunks/{interception-DRlhJWbu.js → interception-DSv3A2Zn.js}

@@ -388,6 +388,213 @@ function findPageExtFile(dirPath, name, extSet) {
 	}
 }
 //#endregion
+//#region src/routing/codegen-shared.ts
+/**
+* Shared codegen helpers — import-path computation, codec chain type
+* builder, and searchParams type formatter.
+*
+* Extracted from `codegen.ts` so `link-codegen.ts` can use the same
+* helpers without a cyclic import.
+*/
+/**
+* Compute a relative import specifier for a codec/page file, stripping
+* the .ts/.tsx extension and resolving against the codegen output dir.
+*/
+function codecImportPath(codecFilePath, importBase) {
+	const absPath = codecFilePath.replace(/\.(ts|tsx)$/, "");
+	if (importBase) return "./" + relative(importBase, absPath).replace(/\\/g, "/");
+	return "./" + posix.basename(absPath);
+}
+/** Name of the shared helper type emitted at the top of the .d.ts. */
+var RESOLVE_SEGMENT_FIELD_TYPE_NAME = "_TimberResolveSegmentField";
+/**
+* Helper type emitted once at the top of the generated `.d.ts` and
+* referenced by every codec-chain conditional. Without this shared
+* helper, the inline expansion would duplicate the fallback branch on
+* every step and grow O(2^N) in chain depth (a single deep nested route
+* could blow up the file size and TS performance). With the helper,
+* each step reuses the named type and growth is O(N).
+*
+* The helper is a 2-arg conditional: given a typeof import expression
+* (`Def`), a key (`K`), and a fallback (`F`), it returns `T[K]` if
+* `Def extends ParamsDefinition<T>` and `K extends keyof T`, otherwise
+* `F`. The codec chain composes calls to this helper.
+*/
+function emitResolveSegmentFieldHelper() {
+	return [
+		`type ${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<Def, K extends string, F> =`,
+		`  Def extends import('@timber-js/app/segment-params').ParamsDefinition<infer T>`,
+		`    ? K extends keyof T ? T[K] : F`,
+		`    : F;`
+	].join("\n");
+}
+/**
+* Build a TypeScript type expression that resolves a single param's
+* codec by walking a chain of params.ts files in priority order.
+*
+* Each entry in the chain emits one application of the shared
+* `_TimberResolveSegmentField` helper type. Composing N applications
+* grows linearly with chain depth (O(N) characters), unlike an inline
+* conditional that would duplicate the fallback in each branch and
+* grow O(2^N).
+*
+* The closest match (position 0 in the chain) is checked first; if its
+* `segmentParams` definition declares the key, its inferred type wins.
+* Otherwise we fall through to the next entry, and finally to the
+* provided fallback. See TIM-834.
+*/
+function buildCodecChainType(p, importBase, fallback) {
+	const files = p.codecFilePaths;
+	if (!files || files.length === 0) return fallback;
+	const key = JSON.stringify(p.name);
+	let inner = fallback;
+	for (let i = files.length - 1; i >= 0; i--) inner = `${RESOLVE_SEGMENT_FIELD_TYPE_NAME}<(typeof import('${codecImportPath(files[i], importBase)}'))['segmentParams'], ${key}, ${inner}>`;
+	return inner;
+}
+/**
+* Format the searchParams type for a route entry.
+*
+* When a page.tsx (or params.ts) exports searchParams, we reference its
+* inferred type via an import type. The import path is relative to
+* `importBase` (the directory where the .d.ts will be written). When
+* importBase is undefined, falls back to a bare relative path.
+*/
+function formatSearchParamsType(route, importBase) {
+	if (route.hasSearchParams && route.searchParamsPagePath) return `(typeof import('${codecImportPath(route.searchParamsPagePath, importBase)}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
+	return "{}";
+}
+//#endregion
+//#region src/routing/link-codegen.ts
+/** Shared Link base-props type literal used in every emitted call signature. */
+var LINK_BASE_PROPS_TYPE = "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
+/**
+* Build a TypeScript template literal pattern for a dynamic route.
+* e.g. '/products/[id]'        → '/products/${string}'
+*      '/blog/[...slug]'       → '/blog/${string}'
+*      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
+*      '/[org]/[repo]'         → '/${string}/${string}'
+*/
+function buildResolvedPattern(route) {
+	return route.urlPath.split("/").map((part) => {
+		if (part.startsWith("[[...") && part.endsWith("]]")) return "${string}";
+		if (part.startsWith("[...") && part.endsWith("]")) return "${string}";
+		if (part.startsWith("[") && part.endsWith("]")) return "${string}";
+		return part;
+	}).join("/");
+}
+/**
+* Format the segmentParams type for Link overloads.
+*
+* Link params accept `string | number` for single dynamic segments
+* (convenience — values are stringified at runtime). Catch-all and
+* optional catch-all remain `string[]` / `string[] | undefined`.
+*
+* When the segment's params chain (TIM-834) declares a typed codec, the
+* inferred type from the codec wins via a nested conditional.
+*/
+function formatLinkParamsType(params, importBase) {
+	if (params.length === 0) return "{}";
+	return `{ ${params.map((p) => {
+		const codecType = buildCodecChainType(p, importBase, p.type === "string" ? "string | number" : p.type);
+		return `${p.name}: ${codecType}`;
+	}).join("; ")} }`;
+}
+/**
+* Catch-all call signatures for `<Link>` — external hrefs and computed
+* `string` variables. Emitted from codegen in a SEPARATE
+* `declare module` block (declared AFTER the per-route block) so the TS
+* "later overload set ordered first" rule places these catch-all
+* signatures ahead of per-route in resolution order, leaving per-route
+* as the final overload whose error message is reported on failure.
+*
+* The conditional `string extends H ? ... : never` protection preserves
+* TIM-624's guarantee that unknown internal path literals don't match
+* the catch-all — typos like `<Link href="/typo" />` still error.
+*/
+function formatLinkCatchAllOverloads() {
+	const lines = [];
+	const baseProps = LINK_BASE_PROPS_TYPE;
+	const catchAllSearchParams = "{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>";
+	const externalHref = "`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`";
+	lines.push("  // Typed Link overloads — catch-all (block 2 / emitted second)");
+	lines.push("  interface LinkFunction {");
+	lines.push(`    (props: ${baseProps} & {`);
+	lines.push(`      href: ${externalHref}`);
+	lines.push(`      segmentParams?: never`);
+	lines.push(`      searchParams?: ${catchAllSearchParams}`);
+	lines.push(`    }): import('react').JSX.Element`);
+	lines.push(`    <H extends string>(`);
+	lines.push(`      props: string extends H`);
+	lines.push(`        ? ${baseProps} & {`);
+	lines.push(`            href: H`);
+	lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
+	lines.push(`            searchParams?: ${catchAllSearchParams}`);
+	lines.push(`          }`);
+	lines.push(`        : never`);
+	lines.push(`    ): import('react').JSX.Element`);
+	lines.push("  }");
+	return lines;
+}
+/**
+* Generate typed per-route Link call signatures via LinkFunction
+* interface merging.
+*
+* TIM-835: This emits a SINGLE call signature whose props is a
+* discriminated union keyed on `href`. TypeScript narrows the union by
+* the literal `href` at the call site, then checks the rest of the
+* props against the matched variant. When `segmentParams` or
+* `searchParams` is wrong, TS reports the error against the matched
+* variant — naming the user's actual `href` and the offending field.
+*
+* Before TIM-835, this function emitted N separate per-route overloads
+* (one per route, sometimes two for dynamic routes). When ALL overloads
+* failed, TS would pick an arbitrary failed overload (heuristically the
+* "last tried") to render the diagnostic, often pointing at a route
+* completely unrelated to the one the user wrote. The discriminated
+* union sidesteps overload-resolution heuristics entirely.
+*
+* Open property shapes (`Record<string, unknown>` instead of `never`)
+* for `segmentParams` on routes that don't declare them keep generic
+* `LinkProps`-spreading wrappers compiling. (Aligned with TIM-833.)
+*
+* TIM-832: this function still emits the per-route block FIRST and the
+* catch-all block follows, so per-route remains the LAST overload set in
+* resolution order — the one TS reports against on failure. With a
+* discriminated union there is only one call signature in this block,
+* so the resolved-template-vs-pattern ordering reduces to placing the
+* pattern variant before the resolved-template variant inside the union.
+*/
+function formatTypedLinkOverloads(routes, importBase) {
+	const lines = [];
+	const baseProps = LINK_BASE_PROPS_TYPE;
+	const variants = [];
+	for (const route of routes) {
+		const hasDynamicParams = route.params.length > 0;
+		const paramsProp = hasDynamicParams ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}` : "segmentParams?: Record<string, unknown>";
+		const searchParamsType = route.hasSearchParams ? formatSearchParamsType(route, importBase) : null;
+		const patternSearchParamsProp = searchParamsType ? `searchParams?: Partial<${searchParamsType}>` : "searchParams?: Record<string, never>";
+		variants.push(`${baseProps} & { href: '${route.urlPath}'; ${paramsProp}; ${patternSearchParamsProp} }`);
+		if (hasDynamicParams) {
+			const templatePattern = buildResolvedPattern(route);
+			if (templatePattern) {
+				const resolvedSearchParamsProp = searchParamsType ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }` : "searchParams?: Record<string, never>";
+				variants.push(`${baseProps} & { href: \`${templatePattern}\`; segmentParams?: Record<string, never>; ${resolvedSearchParamsProp} }`);
+			}
+		}
+	}
+	lines.push("  interface LinkFunction {");
+	if (variants.length === 0) {
+		lines.push("  }");
+		return lines;
+	}
+	lines.push("    (");
+	lines.push("      props:");
+	for (const variant of variants) lines.push(`        | (${variant})`);
+	lines.push(`    ): import('react').JSX.Element`);
+	lines.push("  }");
+	return lines;
+}
+//#endregion
 //#region src/routing/codegen.ts
 /**
 * Route map codegen.
@@ -406,7 +613,7 @@ function findPageExtFile(dirPath, name, extSet) {
 */
 function generateRouteMap(tree, options = {}) {
 	const routes = [];
-	collectRoutes(tree.root, [], routes);
+	collectRoutes(tree.root, [], [], routes);
 	routes.sort((a, b) => a.urlPath.localeCompare(b.urlPath));
 	return formatDeclarationFile(routes, options.outputDir ?? options.appDir);
 }
@@ -416,22 +623,33 @@ function generateRouteMap(tree, options = {}) {
 * A route entry is created for any segment that has a `page` or `route` file.
 * Params accumulate from ancestor dynamic segments.
 */
-function collectRoutes(node, ancestorParams, routes) {
+function collectRoutes(node, ancestorParams, ancestorParamsFiles, routes) {
+	const ownParamsFile = node.params && fileHasExport(node.params.filePath, "segmentParams") ? node.params.filePath : void 0;
 	const params = [...ancestorParams];
 	if (node.paramName) {
-		const codecFile = findParamsExport(node);
+		const legacyFallback = ownParamsFile ? void 0 : findLegacyParamsExport(node);
 		params.push({
 			name: node.paramName,
 			type: paramTypeForSegment(node.segmentType),
-			codecFilePath: codecFile
+			legacyCodecFilePath: legacyFallback
 		});
 	}
+	const nextAncestorFiles = ownParamsFile ? [...ancestorParamsFiles, ownParamsFile] : ancestorParamsFiles;
 	const isPage = !!node.page;
 	const isApiRoute = !!node.route;
 	if (isPage || isApiRoute) {
+		const leafFirstChain = nextAncestorFiles.length > 0 ? [...nextAncestorFiles].reverse() : [];
+		const resolvedParams = params.map((p) => {
+			const codecFilePaths = leafFirstChain.length > 0 ? leafFirstChain : p.legacyCodecFilePath ? [p.legacyCodecFilePath] : void 0;
+			return {
+				name: p.name,
+				type: p.type,
+				codecFilePaths
+			};
+		});
 		const entry = {
 			urlPath: node.urlPath,
-			params: [...params],
+			params: resolvedParams,
 			hasSearchParams: false,
 			isApiRoute
 		};
@@ -446,8 +664,8 @@ function collectRoutes(node, ancestorParams, routes) {
 		}
 		routes.push(entry);
 	}
-	for (const child of node.children) collectRoutes(child, params, routes);
-	for (const [, slot] of node.slots) collectRoutes(slot, params, routes);
+	for (const child of node.children) collectRoutes(child, params, nextAncestorFiles, routes);
+	for (const [, slot] of node.slots) collectRoutes(slot, params, nextAncestorFiles, routes);
 }
 /**
 * Determine the TypeScript type for a segment's param.
@@ -476,14 +694,13 @@ function fileHasExport(filePath, exportName) {
 	}
 }
 /**
-* Find which file exports `segmentParams` for a dynamic segment.
+* Find a legacy `segmentParams` export on layout.tsx or page.tsx.
 *
-* Priority: params.ts (convention file) > layout > page.
-* params.ts is the canonical location (TIM-508). Layout/page fallback
-* exists for backward compat during migration.
+* Backward-compat shim: TIM-508 made params.ts the canonical location
+* for `segmentParams`. Layout/page exports are still accepted for the
+* OWN segment only (not inherited by descendants — see TIM-834).
 */
-function findParamsExport(node) {
-	if (node.params && fileHasExport(node.params.filePath, "segmentParams")) return node.params.filePath;
+function findLegacyParamsExport(node) {
 	if (node.layout && fileHasExport(node.layout.filePath, "segmentParams")) return node.layout.filePath;
 	if (node.page && fileHasExport(node.page.filePath, "segmentParams")) return node.page.filePath;
 }
@@ -497,6 +714,8 @@ function formatDeclarationFile(routes, importBase) {
 	lines.push("");
 	lines.push("export {};");
 	lines.push("");
+	lines.push(emitResolveSegmentFieldHelper());
+	lines.push("");
 	lines.push("declare module '@timber-js/app' {");
 	lines.push("  interface Routes {");
 	for (const route of routes) {
@@ -550,59 +769,11 @@ function formatDeclarationFile(routes, importBase) {
 function formatParamsType(params, importBase) {
 	if (params.length === 0) return "{}";
 	return `{ ${params.map((p) => {
-		if (p.codecFilePath) {
-			const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, "");
-			let importPath;
-			if (importBase) importPath = "./" + relative(importBase, absPath).replace(/\\/g, "/");
-			else importPath = "./" + posix.basename(absPath);
-			const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
-			return `${p.name}: ${codecType}`;
-		}
-		return `${p.name}: ${p.type}`;
-	}).join("; ")} }`;
-}
-/**
-* Format the params type for Link overloads.
-*
-* Link params accept `string | number` for single dynamic segments
-* (convenience — values are stringified at runtime). Catch-all and
-* optional catch-all remain `string[]` / `string[] | undefined`.
-*
-* Uses DIRECT types (not conditional) to preserve excess property checking.
-*/
-function formatLinkParamsType(params, importBase) {
-	if (params.length === 0) return "{}";
-	return `{ ${params.map((p) => {
-		if (p.codecFilePath) {
-			const absPath = p.codecFilePath.replace(/\.(ts|tsx)$/, "");
-			let importPath;
-			if (importBase) importPath = "./" + relative(importBase, absPath).replace(/\\/g, "/");
-			else importPath = "./" + posix.basename(absPath);
-			const codecType = `(typeof import('${importPath}'))['segmentParams'] extends import('@timber-js/app/segment-params').ParamsDefinition<infer T> ? T[${JSON.stringify(p.name)}] : ${p.type}`;
-			return `${p.name}: ${codecType}`;
-		}
-		const type = p.type === "string" ? "string | number" : p.type;
-		return `${p.name}: ${type}`;
+		const codecType = buildCodecChainType(p, importBase, p.type);
+		return `${p.name}: ${codecType}`;
 	}).join("; ")} }`;
 }
 /**
-* Format the searchParams type for a route entry.
-*
-* When a page.tsx exports searchParams, we reference its inferred type via an import type.
-* The import path is relative to `importBase` (the directory where the .d.ts will be
-* written). When importBase is undefined, falls back to a bare relative path.
-*/
-function formatSearchParamsType(route, importBase) {
-	if (route.hasSearchParams && route.searchParamsPagePath) {
-		const absPath = route.searchParamsPagePath.replace(/\.(ts|tsx)$/, "");
-		let importPath;
-		if (importBase) importPath = "./" + relative(importBase, absPath).replace(/\\/g, "/");
-		else importPath = "./" + posix.basename(absPath);
-		return `(typeof import('${importPath}'))['searchParams'] extends import('@timber-js/app/search-params').SearchParamsDefinition<infer T> ? T : never`;
-	}
-	return "{}";
-}
-/**
 * Generate useQueryStates overloads.
 *
 * For each page route:
@@ -620,102 +791,6 @@ function formatUseQueryStatesOverloads(routes, importBase) {
 	lines.push("  export function useQueryStates<T extends Record<string, unknown>>(codecs: { [K in keyof T]: SearchParamCodec<T[K]> }, options?: QueryStatesOptions): [T, SetParams<T>]");
 	return lines;
 }
-/**
-* Build a TypeScript template literal pattern for a dynamic route.
-* e.g. '/products/[id]'        → '/products/${string}'
-*      '/blog/[...slug]'       → '/blog/${string}'
-*      '/docs/[[...path]]'     → '/docs/${string}' (also matches /docs)
-*      '/[org]/[repo]'         → '/${string}/${string}'
-*/
-function buildResolvedPattern(route) {
-	return route.urlPath.split("/").map((part) => {
-		if (part.startsWith("[[...") && part.endsWith("]]")) return "${string}";
-		if (part.startsWith("[...") && part.endsWith("]")) return "${string}";
-		if (part.startsWith("[") && part.endsWith("]")) return "${string}";
-		return part;
-	}).join("/");
-}
-/** Shared Link base-props type literal used in every emitted call signature. */
-var LINK_BASE_PROPS_TYPE = "Omit<import('react').AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> & { prefetch?: boolean; scroll?: boolean; preserveSearchParams?: true | string[]; onNavigate?: import('./client/link.js').OnNavigateHandler; children?: import('react').ReactNode }";
-/**
-* TIM-832: Catch-all call signatures for `<Link>` — external hrefs and
-* computed `string` variables. Emitted from codegen in a SEPARATE
-* `declare module` block (declared AFTER the per-route block) so the TS
-* "later overload set ordered first" rule places these catch-all
-* signatures ahead of per-route in resolution order, leaving per-route
-* as the final overload whose error message is reported on failure.
-*
-* The conditional `string extends H ? ... : never` protection preserves
-* TIM-624's guarantee that unknown internal path literals don't match
-* the catch-all — typos like `<Link href="/typo" />` still error.
-*/
-function formatLinkCatchAllOverloads() {
-	const lines = [];
-	const baseProps = LINK_BASE_PROPS_TYPE;
-	const catchAllSearchParams = "{ definition: SearchParamsDefinition<Record<string, unknown>>; values: Record<string, unknown> } | Record<string, unknown>";
-	const externalHref = "`http://${string}` | `https://${string}` | `mailto:${string}` | `tel:${string}` | `ftp://${string}` | `//${string}` | `#${string}` | `?${string}`";
-	lines.push("  // Typed Link overloads — catch-all (block 2 / emitted second)");
-	lines.push("  interface LinkFunction {");
-	lines.push(`    (props: ${baseProps} & {`);
-	lines.push(`      href: ${externalHref}`);
-	lines.push(`      segmentParams?: never`);
-	lines.push(`      searchParams?: ${catchAllSearchParams}`);
-	lines.push(`    }): import('react').JSX.Element`);
-	lines.push(`    <H extends string>(`);
-	lines.push(`      props: string extends H`);
-	lines.push(`        ? ${baseProps} & {`);
-	lines.push(`            href: H`);
-	lines.push(`            segmentParams?: Record<string, string | number | string[]>`);
-	lines.push(`            searchParams?: ${catchAllSearchParams}`);
-	lines.push(`          }`);
-	lines.push(`        : never`);
-	lines.push(`    ): import('react').JSX.Element`);
-	lines.push("  }");
-	return lines;
-}
-/**
-* Generate typed per-route Link call signatures via LinkFunction
-* interface merging.
-*
-* Each call signature uses DIRECT types (not conditional types) for
-* segmentParams, preserving TypeScript's excess property checking.
-* Interface merging is the only reliable way to add "overloads" via
-* module augmentation — function overloads can't be augmented.
-*
-* TIM-832: this function emits ONLY the per-route block. The catch-all
-* block is emitted separately by `formatLinkCatchAllOverloads` inside a
-* second `declare module` so TS overload ordering reports per-route
-* errors (see `formatDeclarationFile`).
-*/
-function formatTypedLinkOverloads(routes, importBase) {
-	const lines = [];
-	const baseProps = LINK_BASE_PROPS_TYPE;
-	lines.push("  interface LinkFunction {");
-	for (const route of routes) {
-		const hasDynamicParams = route.params.length > 0;
-		const paramsProp = hasDynamicParams ? `segmentParams: ${formatLinkParamsType(route.params, importBase)}` : "segmentParams?: never";
-		const searchParamsType = route.hasSearchParams ? formatSearchParamsType(route, importBase) : null;
-		const patternSearchParamsProp = searchParamsType ? `searchParams?: Partial<${searchParamsType}>` : "searchParams?: never";
-		if (hasDynamicParams) {
-			const templatePattern = buildResolvedPattern(route);
-			if (templatePattern) {
-				const resolvedSearchParamsProp = searchParamsType ? `searchParams?: { definition: SearchParamsDefinition<${searchParamsType}>; values: Partial<${searchParamsType}> }` : "searchParams?: never";
-				lines.push(`    (props: ${baseProps} & {`);
-				lines.push(`      href: \`${templatePattern}\``);
-				lines.push(`      segmentParams?: never`);
-				lines.push(`      ${resolvedSearchParamsProp}`);
-				lines.push(`    }): import('react').JSX.Element`);
-			}
-		}
-		lines.push(`    (props: ${baseProps} & {`);
-		lines.push(`      href: '${route.urlPath}'`);
-		lines.push(`      ${paramsProp}`);
-		lines.push(`      ${patternSearchParamsProp}`);
-		lines.push(`    }): import('react').JSX.Element`);
-	}
-	lines.push("  }");
-	return lines;
-}
 //#endregion
 //#region src/routing/interception.ts
 /**
@@ -795,4 +870,4 @@ function computeInterceptedBase(parentUrlPath, marker) {
 //#endregion
 export { DEFAULT_PAGE_EXTENSIONS as a, scanRoutes as i, generateRouteMap as n, INTERCEPTION_MARKERS as o, classifySegment as r, collectInterceptionRewrites as t };
 
-//# sourceMappingURL=interception-DRlhJWbu.js.map
+//# sourceMappingURL=interception-DSv3A2Zn.js.map