Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(web): type nested split route declarations (#6748)

dev-rbbef34ef023b4
diff --git a/apps/web/src/components/app/split-layout/split-router/app-routes.ts b/apps/web/src/components/app/split-layout/split-router/app-routes.ts
index 98c4adc3c5..07f40830e4 100644
--- a/apps/web/src/components/app/split-layout/split-router/app-routes.ts
+++ b/apps/web/src/components/app/split-layout/split-router/app-routes.ts
@@ -47,7 +47,7 @@ const agentsSplitRoutes = ['agents', 'coders', 'agent-chats'].map((section) =>
aliases: section === 'agent-chats' ? ['agent-chats/:id'] : undefined,
params: z.object({ id: z.string() }),
component: lazyView((views) => views.AgentsRouteView),
- remountKey: ({ id }: Record<string, unknown>) => String(id),
+ remountKey: ({ id }) => id,
claim: ({ id }) => ({
namespace: section === 'agent-chats' ? 'chat' : 'agent',
id,
diff --git a/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts b/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts
index 2011eb5ea1..694a00e1b3 100644
--- a/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts
+++ b/apps/web/src/components/app/split-layout/tests/layoutManager.test.ts
@@ -1,5 +1,8 @@
import { agentsRouteId } from '@app/features/agents-view/core/route';
-import { driveSplitRoute } from '@app/features/drive-view/primitives/drive-route';
+import {
+ driveDestination,
+ driveSplitRoute,
+} from '@app/features/drive-view/primitives/drive-route';
import {
getListNavigationSource,
listNavigationSourceId,
@@ -855,6 +858,24 @@ describe('layoutManager', () => {
id: 'drive-tab',
params: { tab: 'shared' },
});
+ router.navigate(
+ second.id,
+ driveDestination(
+ { kind: 'folder', id: 'another-folder' },
+ { type: 'md', id: 'nested-document' }
+ )
+ );
+ expect(router.route(second.id)?.matches).toEqual([
+ { id: 'drive', params: {} },
+ {
+ id: 'drive-folder',
+ params: { view: 'folder', folderId: 'another-folder' },
+ },
+ {
+ id: 'drive-folder-document',
+ params: { documentType: 'md', documentId: 'nested-document' },
+ },
+ ]);
expect(router.route(first.id)).toEqual(firstRoute);
expect(manager.splits()).toHaveLength(2);
router.dispose();
diff --git a/apps/web/src/features/drive-view/primitives/drive-route.ts b/apps/web/src/features/drive-view/primitives/drive-route.ts
index 2ff74d79a8..dc4584d81e 100644
--- a/apps/web/src/features/drive-view/primitives/drive-route.ts
+++ b/apps/web/src/features/drive-view/primitives/drive-route.ts
@@ -2,7 +2,11 @@ import {
deserializeFacetSelection,
normalizeFacetSelection,
} from '@app/features/soup/filters/facets/selection';
-import { defineRoute, routeParams } from '@app/lib/split-router/routes';
+import {
+ defineRoute,
+ defineRoutes,
+ routeParams,
+} from '@app/lib/split-router/routes';
import {
type CreateSearchParamsOptions,
isSafeName,
@@ -10,6 +14,7 @@ import {
type SplitRouteNavigationTarget,
type SplitRouteParams,
type SplitRouterEntry,
+ type SplitRouteUnion,
takeLast,
} from '@app/split-router';
import { URL_PARAMS as MARKDOWN_URL_PARAMS } from '@block-md/constants';
@@ -83,30 +88,35 @@ const tabRoute = defineRoute({
children: [tabDocument],
});
-export const driveSplitRoute = defineRoute({
- id: 'drive',
- path: 'drive',
- aliases: ['drive/owned', 'drive/tab/owned'],
- params: z.object({}),
- // Drive lists are independent workspaces, not singleton content. Only the
- // document children claim content; returning to a list must stay in its pane.
- search: ['drive'],
- externalSearch: (entry: Readonly<SplitRouterEntry>) => {
- const type = routeParams<DriveRouteParams>(
- entry.location.route
- ).documentType;
- if (
- type === 'md' ||
- type === 'task' ||
- type === 'snippet' ||
- type === 'skill'
- ) {
- return Object.values(MARKDOWN_URL_PARAMS);
- }
- return type === 'pdf' ? Object.values(PDF_URL_PARAMS) : [];
- },
- children: [folderRoute, tabRoute, rootDocument],
+const driveRoutes = defineRoutes({
+ definitions: [
+ defineRoute({
+ id: 'drive',
+ path: 'drive',
+ aliases: ['drive/owned', 'drive/tab/owned'],
+ params: z.object({}),
+ // Drive lists are independent workspaces, not singleton content. Only the
+ // document children claim content; returning to a list must stay in its pane.
+ search: ['drive'],
+ externalSearch: (entry: Readonly<SplitRouterEntry>) => {
+ const type = routeParams<DriveRouteParams>(
+ entry.location.route
+ ).documentType;
+ if (
+ type === 'md' ||
+ type === 'task' ||
+ type === 'snippet' ||
+ type === 'skill'
+ ) {
+ return Object.values(MARKDOWN_URL_PARAMS);
+ }
+ return type === 'pdf' ? Object.values(PDF_URL_PARAMS) : [];
+ },
+ children: [folderRoute, tabRoute, rootDocument],
+ }),
+ ],
});
+export const driveSplitRoute = driveRoutes.definitions[0];
export function driveLocationFromParams(
params: DriveRouteParams
@@ -124,12 +134,7 @@ export function driveDocumentFromParams(
}
type DriveDestination = SplitRouteNavigationTarget<
- | typeof driveSplitRoute
- | typeof folderRoute
- | typeof tabRoute
- | typeof rootDocument
- | typeof folderDocument
- | typeof tabDocument
+ SplitRouteUnion<typeof driveRoutes>
>;
/** One typed destination builder for list and detail navigation. */
@@ -137,6 +142,7 @@ export function driveDestination(
location: DriveLocation,
document?: DriveDocumentRoute
): DriveDestination {
+ const [folder, tab, rootDetail] = driveSplitRoute.children;
const detail = document && {
documentId: document.id,
documentType: document.type,
@@ -147,17 +153,17 @@ export function driveDestination(
folderId: location.id ?? undefined,
};
return detail
- ? { route: folderDocument, params: { ...params, ...detail } }
- : { route: folderRoute, params };
+ ? { route: folder.children[0], params: { ...params, ...detail } }
+ : { route: folder, params };
}
if (location.tab !== 'owned') {
const params = { tab: location.tab };
return detail
- ? { route: tabDocument, params: { ...params, ...detail } }
- : { route: tabRoute, params };
+ ? { route: tab.children[0], params: { ...params, ...detail } }
+ : { route: tab, params };
}
return detail
- ? { route: rootDocument, params: detail }
+ ? { route: rootDetail, params: detail }
: { route: driveSplitRoute, params: {} };
}
diff --git a/apps/web/src/lib/split-router/README.md b/apps/web/src/lib/split-router/README.md
index 136d36247a..12f4293145 100644
--- a/apps/web/src/lib/split-router/README.md
+++ b/apps/web/src/lib/split-router/README.md
@@ -9,9 +9,12 @@ stay outside this library.
- Supply one static `SplitRoutes` declaration tree, or an explicit
`SplitRoutesManifest`. A router compiles its own manifest once and exposes it as
`router.routes`; there is no global runtime cache.
-- `defineRoute()` preserves literal IDs and synchronous Standard Schema param
- types. Use route-object destinations and `useRouteParams(route)` for typed
- navigation and reads.
+- `defineRoute()` infers node-local callback and synchronous Standard Schema
+ output types, including `remountKey`. `defineRoutes()` preserves the static
+ tree and adds ancestor types to references taken from that tree.
+- `useRouteParams(route)` reads only that node's params. `useParams(route)` reads
+ the merged branch through that node; `useParams()` still reads the entire
+ active branch.
- Matching follows declaration order, trying canonical patterns before aliases.
Schema and child failures backtrack. Formatting always uses canonical paths.
- Every accepted location has a nonempty, structurally valid match branch.
@@ -20,6 +23,62 @@ stay outside this library.
- Nested outlets preserve component identity while their match remains stable.
Use `remountKey` for intentional resets.
+## Typed nested routes
+
+```ts
+const routes = defineRoutes({
+ definitions: [defineRoute({
+ id: 'folder',
+ path: 'drive/folder/:folderId',
+ params: z.object({ folderId: z.string() }),
+ children: [defineRoute({
+ id: 'document',
+ path: 'document/:documentId',
+ params: z.object({ documentId: z.string() }),
+ remountKey: ({ documentId }) => documentId,
+ })],
+ })],
+});
+const folder = routes.definitions[0];
+const document = folder.children[0];
+
+navigate({
+ route: document,
+ params: { folderId: 'folder-1', documentId: 'document-1' },
+});
+const branch = useParams(document); // folderId + documentId
+const local = useRouteParams(document); // documentId only
+```
+
+`defineRoutes` returns the same objects: it does not clone, mutate, compile, or
+cache the tree. Its ancestry metadata exists only in TypeScript. Take references
+from its returned tree to get inherited types; previously declared child variables
+retain their original local-only types. Use `defineRoute` at nodes with callbacks
+so their schema outputs provide contextual parameter types.
+
+Tree-bound destinations require the complete branch params, including when opening
+another pane. Standalone `defineRoute` references remain local-only and may inherit
+matching ancestor values from the current pane. Explicit destination params override
+those inherited values before each node's serializer runs. Serializers can therefore
+receive additional branch fields; serialize the fields owned by that node. Transformed
+outputs such as `Date` still require `serializeParams` and are not revalidated as inputs.
+
+`InferSplitRouteParams` is node-local; `InferSplitRouteBranchParams` describes merged
+reads; `InferSplitRouteNavigationParams` describes the flat destination bag.
+`SplitRouteUnion<typeof routes>` collects references throughout a tree for destination
+builders. `SplitRouteNavigationTarget<A | B>` keeps each route paired with its params.
+
+Prefer distinct parameter names across ancestors and descendants, especially when
+using claims, which receive the final merged bag. Reads honor child shadowing and
+retain parent values when optional child fields are absent. Flat destinations must
+satisfy every node's parameter types; incompatible shadows are rejected. Use path
+navigation when repeated names need different values at different levels.
+
+Without a schema, literal paths infer strings, optional strings, and `string[]` for
+catch-all parameters. Reads include differently named alias params; destinations use
+the canonical path's params. Renamed aliases need a schema or serializer that maps
+those fields back to canonical names. Widened `string` paths retain untyped params.
+
## Search and history
- Raw query values are `Record<string, string[]>`; repeated values retain order.
diff --git a/apps/web/src/lib/split-router/index.ts b/apps/web/src/lib/split-router/index.ts
index 141ec24564..dc954a4f4e 100644
--- a/apps/web/src/lib/split-router/index.ts
+++ b/apps/web/src/lib/split-router/index.ts
@@ -26,6 +26,7 @@ export {
createRoutesManifest,
decodeRoute,
defineRoute,
+ defineRoutes,
encodeRoute,
filterRouteSearch,
getExternalSearchKeys,
@@ -64,6 +65,9 @@ export {
} from './solid';
export type {
BrowserHistoryIntent,
+ DefinedSplitRoutes,
+ InferSplitRouteBranchParams,
+ InferSplitRouteNavigationParams,
InferSplitRouteParams,
SerializedSearchParams,
SplitLocation,
@@ -97,6 +101,7 @@ export type {
SplitRouterSettledChange,
SplitRouteState,
SplitRoutes,
+ SplitRouteUnion,
SplitSearchState,
SplitSearchUpdate,
SplitSearchUpdateOptions,
diff --git a/apps/web/src/lib/split-router/navigation.ts b/apps/web/src/lib/split-router/navigation.ts
index 31745cf8c3..ea07b7ad29 100644
--- a/apps/web/src/lib/split-router/navigation.ts
+++ b/apps/web/src/lib/split-router/navigation.ts
@@ -45,8 +45,9 @@ function resolveRouteTarget(
return {
id: definition.id,
- params:
- index === branch.length - 1 ? { ...params, ...targetParams } : params,
+ // Explicit branch params override inherited values at every level before
+ // each node serializes its own schema output into path segments.
+ params: { ...params, ...targetParams },
};
});
diff --git a/apps/web/src/lib/split-router/routes.ts b/apps/web/src/lib/split-router/routes.ts
index ce1bb622ef..ab5ca18e55 100644
--- a/apps/web/src/lib/split-router/routes.ts
+++ b/apps/web/src/lib/split-router/routes.ts
@@ -2,6 +2,8 @@ import type { StandardSchemaV1 } from '@standard-schema/spec';
import { compileRoutePattern, type RoutePattern } from './path';
import { assertSafeSearchName } from './search';
import type {
+ DefinedSplitRoutes,
+ InferSplitRouteParams,
SplitRouteClaim,
SplitRouteDefinition,
SplitRouteMatch,
@@ -25,41 +27,67 @@ type SplitRouteDefinitionConstraint = {
serializeParams?: unknown;
claim?: unknown;
search?: readonly string[] | '*';
- externalSearch?: readonly string[] | ((entry: never) => readonly string[]);
- remountKey?: (params: never) => string | number | undefined;
+ externalSearch?: SplitRouteDefinition['externalSearch'];
+ remountKey?: unknown;
+};
+
+type RouteParamCallbacks<TParams> = {
+ serializeParams?: (params: TParams) => SplitRouteRawParams;
+ claim?: (params: TParams) => SplitRouteClaim | undefined;
+ remountKey?: (params: TParams) => string | number | undefined;
};
export function defineRoute<
const TParamsSchema extends StandardSchemaV1,
const TDefinition extends SplitRouteDefinitionConstraint,
+>(
+ definition: TDefinition & { params: TParamsSchema } & RouteParamCallbacks<
+ StandardSchemaV1.InferOutput<TParamsSchema>
+ >
+): TDefinition & { params: TParamsSchema } & RouteParamCallbacks<
+ StandardSchemaV1.InferOutput<TParamsSchema>
+ >;
+export function defineRoute<
+ const TPath extends string,
+ const TAliases extends readonly string[] | undefined,
+ const TDefinition extends SplitRouteDefinitionConstraint,
>(
definition: TDefinition & {
- params: TParamsSchema;
- serializeParams?: (
- params: StandardSchemaV1.InferOutput<TParamsSchema>
- ) => SplitRouteRawParams;
- claim?: (
- params: StandardSchemaV1.InferOutput<TParamsSchema>
- ) => SplitRouteClaim | undefined;
- }
-): TDefinition & {
- params: TParamsSchema;
- serializeParams?: (
- params: StandardSchemaV1.InferOutput<TParamsSchema>
- ) => SplitRouteRawParams;
- claim?: (
- params: StandardSchemaV1.InferOutput<TParamsSchema>
- ) => SplitRouteClaim | undefined;
-};
+ path: TPath;
+ aliases: TAliases;
+ params?: undefined;
+ } & RouteParamCallbacks<
+ InferSplitRouteParams<{ path: TPath; aliases: TAliases }>
+ >
+): TDefinition & { path: TPath; aliases: TAliases };
export function defineRoute<
+ const TPath extends string,
const TDefinition extends SplitRouteDefinitionConstraint,
->(definition: TDefinition & { params?: undefined }): TDefinition;
+>(
+ definition: TDefinition & {
+ path: TPath;
+ aliases?: undefined;
+ params?: undefined;
+ } & RouteParamCallbacks<InferSplitRouteParams<{ path: TPath }>>
+): TDefinition & { path: TPath };
export function defineRoute(
definition: SplitRouteDefinitionConstraint
): SplitRouteDefinitionConstraint {
return definition;
}
+/** Preserve the declaration tree and infer ancestry without constructing runtime state. */
+export function defineRoutes<
+ const TRoutes extends Omit<SplitRoutes, 'definitions'> & {
+ definitions: readonly SplitRouteDefinitionConstraint[];
+ },
+>(
+ routes: TRoutes &
+ (NoInfer<TRoutes> extends SplitRoutes ? unknown : SplitRoutes)
+): DefinedSplitRoutes<TRoutes> {
+ return routes as DefinedSplitRoutes<TRoutes>;
+}
+
export type RouteParamsCodec = {
parse(params: SplitRouteRawParams): SplitRouteParams | undefined;
serialize(params: SplitRouteParams): SplitRouteParams;
diff --git a/apps/web/src/lib/split-router/solid.tsx b/apps/web/src/lib/split-router/solid.tsx
index 784229f788..06c8712642 100644
--- a/apps/web/src/lib/split-router/solid.tsx
+++ b/apps/web/src/lib/split-router/solid.tsx
@@ -18,6 +18,7 @@ import {
type SplitRoutesManifest,
} from './routes';
import type {
+ InferSplitRouteBranchParams,
InferSplitRouteParams,
SplitNavigate,
SplitNavigateOptions,
@@ -140,12 +141,23 @@ export function useSplitHistory() {
return () => router.history(splitId());
}
-export function useParams<T extends SplitRouteParams = SplitRouteParams>(): T {
+export function useParams<const TRoute extends { id: string }>(
+ route: TRoute
+): InferSplitRouteBranchParams<TRoute>;
+export function useParams<T extends SplitRouteParams = SplitRouteParams>(): T;
+export function useParams(through?: { id: string }): SplitRouteParams {
const router = useSplitRouterState<unknown>();
const splitId = useSplitRouterScope<unknown>();
- const params = createMemo(() => routeParams(router.route(splitId())));
+ const params = createMemo(() => {
+ const route = router.route(splitId());
+ if (!through || !route) return routeParams(route);
+ const index = route.matches.findIndex((match) => match.id === through.id);
+ if (index < 0) return {};
+ const [first, ...rest] = route.matches;
+ return routeParams({ matches: [first, ...rest.slice(0, index)] });
+ });
- return reactiveRecord(params) as T;
+ return reactiveRecord(params);
}
export function useRouteParams<const TRoute extends { id: string }>(
diff --git a/apps/web/src/lib/split-router/tests/navigation.test.ts b/apps/web/src/lib/split-router/tests/navigation.test.ts
index 35422f890f..a46022a6ef 100644
--- a/apps/web/src/lib/split-router/tests/navigation.test.ts
+++ b/apps/web/src/lib/split-router/tests/navigation.test.ts
@@ -5,9 +5,15 @@ import {
createRoutesManifest,
decodeRoute,
defineRoute,
+ defineRoutes,
routeParams,
} from '../routes';
-import type { SplitNavigate, SplitRouterEntry } from '../types';
+import type {
+ SplitNavigate,
+ SplitRouteNavigationTarget,
+ SplitRouterEntry,
+ SplitRouteUnion,
+} from '../types';
const workspaceDetailRoute = defineRoute({
id: 'workspace-detail',
@@ -35,9 +41,10 @@ const workspaceRoute = defineRoute({
children: [workspaceFolderRoute, workspacePageRoute],
});
-const routes = createRoutesManifest({
- definitions: [workspaceRoute],
-});
+const tree = defineRoutes({ definitions: [workspaceRoute] });
+const routes = createRoutesManifest(tree);
+const boundDetail = tree.definitions[0].children[0].children[0];
+const boundPage = tree.definitions[0].children[1];
function entry(path: string[]): SplitRouterEntry {
return decodeRoute(routes, path)!;
@@ -50,6 +57,22 @@ function assertTypedRouteTargets(navigate: SplitNavigate<string>) {
});
navigate({ route: workspaceRoute });
navigate({ route: workspacePageRoute, params: { page: 2 } });
+ navigate({
+ route: boundDetail,
+ params: { folderId: 'folder', documentId: 'doc' },
+ });
+ // @ts-expect-error A tree-bound destination requires its ancestor params too.
+ navigate({ route: boundDetail, params: { documentId: 'doc' } });
+ // @ts-expect-error Ancestor fields keep their schema output types.
+ navigate({ route: boundDetail, params: { folderId: 4, documentId: 'doc' } });
+ // @ts-expect-error A route union cannot pair one route with another route's params.
+ const mismatched: SplitRouteNavigationTarget<
+ typeof boundDetail | typeof boundPage
+ > = { route: boundPage, params: { folderId: 'folder', documentId: 'doc' } };
+ void mismatched;
+ const destination: SplitRouteNavigationTarget<SplitRouteUnion<typeof tree>> =
+ { route: boundDetail, params: { folderId: 'folder', documentId: 'doc' } };
+ navigate(destination);
// @ts-expect-error navigation uses the schema output type
navigate({ route: workspacePageRoute, params: { page: '2' } });
// @ts-expect-error documentId is required by the route schema
@@ -79,6 +102,59 @@ describe('split route navigation', () => {
]);
});
+ it.each([['workspace'], ['workspace', 'folder', 'old-folder']])(
+ 'uses explicit ancestor params from %j',
+ (...path) => {
+ const current = entry(path);
+ const next = resolveNavigation(routes, current, undefined, {
+ route: boundDetail,
+ params: { folderId: 'new-folder', documentId: 'document-1' },
+ });
+ expect(next?.location.route.matches).toEqual([
+ { id: 'workspace', params: {} },
+ { id: 'workspace-folder', params: { folderId: 'new-folder' } },
+ { id: 'workspace-detail', params: { documentId: 'document-1' } },
+ ]);
+ }
+ );
+
+ it('serializes transformed ancestor outputs without validating them as inputs', () => {
+ const dated = defineRoutes({
+ definitions: [
+ defineRoute({
+ id: 'day',
+ path: 'day/:date',
+ params: z.object({
+ date: z.string().transform((date) => new Date(date)),
+ }),
+ serializeParams: ({ date }) => ({
+ date: date.toISOString().slice(0, 10),
+ }),
+ children: [
+ defineRoute({
+ id: 'day-item',
+ path: 'item/:id',
+ params: z.object({ id: z.string() }),
+ }),
+ ],
+ }),
+ ],
+ });
+ const manifest = createRoutesManifest({
+ definitions: [...tree.definitions, ...dated.definitions],
+ });
+ const current = decodeRoute(manifest, ['workspace'])!;
+ const date = new Date('2026-01-02T00:00:00Z');
+ const next = resolveNavigation(manifest, current, undefined, {
+ route: dated.definitions[0].children[0],
+ params: { date, id: 'one' },
+ });
+ expect(next?.location.route.matches).toEqual([
+ { id: 'day', params: { date } },
+ { id: 'day-item', params: { id: 'one' } },
+ ]);
+ });
+
it('appends explicit child-relative paths to the current route', () => {
const current = entry(['workspace', 'folder', 'folder-1']);
const next = resolveNavigation(
diff --git a/apps/web/src/lib/split-router/tests/routes.test.ts b/apps/web/src/lib/split-router/tests/routes.test.ts
index afca13c46c..233859416a 100644
--- a/apps/web/src/lib/split-router/tests/routes.test.ts
+++ b/apps/web/src/lib/split-router/tests/routes.test.ts
@@ -4,6 +4,7 @@ import {
createRoutesManifest,
decodeRoute,
defineRoute,
+ defineRoutes,
encodeRoute,
findRouteBranch,
getExternalSearchKeys,
@@ -12,7 +13,12 @@ import {
validateRouteParams,
validateSplitRoutes,
} from '../routes';
-import type { InferSplitRouteParams } from '../types';
+import type {
+ InferSplitRouteBranchParams,
+ InferSplitRouteNavigationParams,
+ InferSplitRouteParams,
+ SplitRoutes,
+} from '../types';
const documentClaim = ({ documentId }: { documentId: string }) => ({
namespace: 'document',
@@ -23,6 +29,7 @@ const driveRoute = defineRoute({
id: 'drive',
path: 'drive',
aliases: ['files'],
+ params: z.object({}),
search: ['drive'],
externalSearch: ['action'],
children: [
@@ -67,6 +74,7 @@ describe('split route parameter schemas', () => {
id: 'issue',
path: 'issue/:issueId',
params: z.object({ issueId: z.coerce.number().int().positive() }),
+ remountKey: ({ issueId }) => issueId.toFixed(0),
});
it('coerces URL strings to typed runtime values', () => {
@@ -99,6 +107,193 @@ describe('split route parameter schemas', () => {
});
});
+function assertInvalidRouteDeclarations() {
+ // @ts-expect-error Invalid callbacks are rejected by the declaration boundary.
+ defineRoutes({ definitions: [{ id: 'bad', path: 'bad', claim: 42 }] });
+ defineRoutes({
+ // @ts-expect-error Route parameter schemas must produce objects.
+ definitions: [defineRoute({ id: 'bad', path: 'bad', params: z.string() })],
+ });
+}
+
+describe('typed route trees', () => {
+ it('checks declaration contracts without widening node inference', () => {
+ expectTypeOf(assertInvalidRouteDeclarations).toBeFunction();
+ });
+ it('preserves declaration and schema identity while typing descendant ancestry', () => {
+ const declarations = {
+ definitions: [driveRoute] as const,
+ globalSearch: ['referral_code'] as const,
+ };
+ const tree = defineRoutes(declarations);
+ const detail = tree.definitions[0].children[0].children[0];
+ expect(tree).toBe(declarations);
+ expect(tree.definitions[0]).toBe(driveRoute);
+ expect(detail).toBe(driveRoute.children[0].children[0]);
+ expect(detail.params).toBe(driveRoute.children[0].children[0].params);
+ expect(createRoutesManifest(tree).byId.get(detail.id)?.definition).toBe(
+ detail
+ );
+ expectTypeOf(tree).toExtend<SplitRoutes>();
+ expectTypeOf<InferSplitRouteParams<typeof driveRoute>>().toEqualTypeOf<
+ z.output<typeof driveRoute.params>
+ >();
+ expectTypeOf(detail.id).toEqualTypeOf<'drive-folder-detail'>();
+ expectTypeOf<InferSplitRouteParams<typeof detail>>().toEqualTypeOf<{
+ documentId: string;
+ }>();
+ expectTypeOf<InferSplitRouteBranchParams<typeof detail>>().toEqualTypeOf<{
+ folderId: string;
+ documentId: string;
+ }>();
+ });
+
+ it('rebinds ancestry when an existing reference is composed into another tree', () => {
+ const tree = defineRoutes({ definitions: [driveRoute] });
+ const detail = tree.definitions[0].children[0].children[0];
+ const rebound = defineRoutes({ definitions: [detail] });
+ const root = rebound.definitions[0];
+ expect(root).toBe(detail);
+ expectTypeOf<InferSplitRouteBranchParams<typeof root>>().toEqualTypeOf<{
+ documentId: string;
+ }>();
+ expectTypeOf<InferSplitRouteNavigationParams<typeof root>>().toEqualTypeOf<{
+ documentId: string;
+ }>();
+ const widened: SplitRoutes = tree;
+ const redefined = defineRoutes(widened);
+ expectTypeOf(redefined.definitions[0]?.children).toEqualTypeOf<
+ SplitRoutes['definitions'][number]['children']
+ >();
+ });
+
+ it('infers schema-less path params, including optional and catch-all fields', () => {
+ const raw = defineRoute({
+ id: 'raw',
+ path: 'raw/:id/:tab?/*rest',
+ remountKey: ({ id, tab, rest }) => `${id}:${tab ?? ''}:${rest.join('/')}`,
+ });
+ expectTypeOf<InferSplitRouteParams<typeof raw>>().toEqualTypeOf<{
+ id: string;
+ tab?: string;
+ rest: string[];
+ }>();
+ expect(raw.remountKey({ id: 'one', rest: ['a', 'b'] })).toBe('one::a/b');
+ expectTypeOf<InferSplitRouteParams<{ id: 'bare' }>>().toEqualTypeOf<
+ Record<string, unknown>
+ >();
+ });
+
+ it('types differently named alias reads separately from canonical destinations', () => {
+ const route = defineRoute({
+ id: 'alias',
+ path: 'item/:id',
+ aliases: ['old/:legacyId'],
+ serializeParams: (params) => ({
+ id: 'id' in params ? params.id : params.legacyId,
+ }),
+ remountKey: (params) => ('id' in params ? params.id : params.legacyId),
+ });
+ expectTypeOf<InferSplitRouteParams<typeof route>>().toEqualTypeOf<
+ { id: string } | { legacyId: string }
+ >();
+ expectTypeOf<
+ InferSplitRouteNavigationParams<typeof route>
+ >().toEqualTypeOf<{ id: string }>();
+ const manifest = createRoutesManifest(
+ defineRoutes({ definitions: [route] })
+ );
+ const entry = decodeRoute(manifest, ['old', 'one'])!;
+ expect(routeParams(entry.location.route)).toEqual({ legacyId: 'one' });
+ expect(encodeRoute(manifest, entry)).toEqual(['item', 'one']);
+ });
+
+ it('retains optional ancestor fields and transformed schema outputs', () => {
+ const tree = defineRoutes({
+ definitions: [
+ defineRoute({
+ id: 'parent',
+ path: 'parent/:workspace?',
+ params: z.object({ workspace: z.string().optional() }),
+ children: [
+ defineRoute({
+ id: 'child',
+ path: ':page',
+ params: z.object({ page: z.coerce.number() }),
+ }),
+ ],
+ }),
+ ],
+ });
+ const child = tree.definitions[0].children[0];
+ expectTypeOf<InferSplitRouteBranchParams<typeof child>>().toEqualTypeOf<{
+ workspace?: string;
+ page: number;
+ }>();
+ expectTypeOf<
+ InferSplitRouteNavigationParams<typeof child>
+ >().toEqualTypeOf<{ workspace?: string; page: number }>();
+ });
+
+ it('retains required parent values when optional child fields are absent', () => {
+ const tree = defineRoutes({
+ definitions: [
+ defineRoute({
+ id: 'parent',
+ path: ':id',
+ params: z.object({ id: z.string() }),
+ children: [
+ defineRoute({
+ id: 'child',
+ path: 'child/:id?',
+ params: z.object({ id: z.coerce.number().optional() }),
+ }),
+ ],
+ }),
+ ],
+ });
+ const child = tree.definitions[0].children[0];
+ expectTypeOf<InferSplitRouteBranchParams<typeof child>>().toEqualTypeOf<{
+ id: string | number | undefined;
+ }>();
+ const manifest = createRoutesManifest(tree);
+ expect(
+ routeParams(decodeRoute(manifest, ['parent', 'child'])?.location.route)
+ ).toEqual({ id: 'parent' });
+ expect(
+ routeParams(
+ decodeRoute(manifest, ['parent', 'child', '2'])?.location.route
+ )
+ ).toEqual({ id: 2 });
+ });
+
+ it('models shadowed reads but rejects incompatible flat navigation params', () => {
+ const tree = defineRoutes({
+ definitions: [
+ defineRoute({
+ id: 'parent',
+ path: ':id',
+ params: z.object({ id: z.string() }),
+ children: [
+ defineRoute({
+ id: 'child',
+ path: ':id',
+ params: z.object({ id: z.coerce.number() }),
+ }),
+ ],
+ }),
+ ],
+ });
+ const child = tree.definitions[0].children[0];
+ expectTypeOf<InferSplitRouteBranchParams<typeof child>>().toEqualTypeOf<{
+ id: number;
+ }>();
+ expectTypeOf<
+ InferSplitRouteNavigationParams<typeof child>
+ >().toEqualTypeOf<{ id: never }>();
+ });
+});
+
describe('split route operations', () => {
it('finds a route with its ancestors in manifest order', () => {
const branch = findRouteBranch(routes, 'drive-folder-detail');
diff --git a/apps/web/src/lib/split-router/tests/solid.test.tsx b/apps/web/src/lib/split-router/tests/solid.test.tsx
index 9a09252757..aa99e207ac 100644
--- a/apps/web/src/lib/split-router/tests/solid.test.tsx
+++ b/apps/web/src/lib/split-router/tests/solid.test.tsx
@@ -1,13 +1,13 @@
import { cleanup, render } from '@solidjs/testing-library';
import { type Accessor, onCleanup } from 'solid-js';
-import { afterEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, expectTypeOf, it, vi } from 'vitest';
import { z } from 'zod';
import {
createSearchParams,
type SetSearchParams,
} from '../create-search-params';
import { createMemorySplitRouterLocation } from '../integrations/memory';
-import { defineRoute } from '../routes';
+import { defineRoute, defineRoutes } from '../routes';
import {
SplitRouter,
useCanGo,
@@ -104,6 +104,64 @@ afterEach(() => {
});
describe('Solid split router hooks', () => {
+ it('reads typed branch params only through the referenced node and stays reactive', () => {
+ const tree = defineRoutes({
+ definitions: [
+ defineRoute({
+ id: 'workspace',
+ path: 'workspace/:workspaceId/:id',
+ params: z.object({ workspaceId: z.string(), id: z.string() }),
+ children: [
+ defineRoute({
+ id: 'count',
+ path: 'count/:id',
+ params: z.object({ id: z.coerce.number() }),
+ }),
+ ],
+ }),
+ ],
+ });
+ const parent = tree.definitions[0];
+ const child = parent.children[0];
+ function ParamsView() {
+ const parentParams = useParams(parent);
+ const childParams = useParams(child);
+ const localParams = useRouteParams(child);
+ const missing = useParams(
+ defineRoute({ id: 'absent', path: 'absent/:id' })
+ );
+ expectTypeOf(parentParams).toEqualTypeOf<{
+ workspaceId: string;
+ id: string;
+ }>();
+ expectTypeOf(childParams).toEqualTypeOf<{
+ workspaceId: string;
+ id: number;
+ }>();
+ expectTypeOf(localParams).toEqualTypeOf<{ id: number }>();
+ return (
+ <div>{`${parentParams.workspaceId}:${parentParams.id}:${childParams.id}:${localParams.id}:${JSON.stringify(missing)}`}</div>
+ );
+ }
+ const location = createMemorySplitRouterLocation(
+ '/workspace/a/parent-a/count/2'
+ );
+ const result = render(() => (
+ <SplitRouter.Root
+ layout={createLayout()}
+ routes={tree}
+ location={location}
+ >
+ <SplitRouter.Scope splitId="split">
+ <ParamsView />
+ </SplitRouter.Scope>
+ </SplitRouter.Root>
+ ));
+ expect(result.getByText('a:parent-a:2:2:{}')).toBeTruthy();
+ location.set('/workspace/b/parent-b/count/3');
+ expect(result.getByText('b:parent-b:3:3:{}')).toBeTruthy();
+ });
+
it('renders the outlet fallback for a missing split without a route-less entry', () => {
const layout = createLayout();
const view = render(() => (
diff --git a/apps/web/src/lib/split-router/types.ts b/apps/web/src/lib/split-router/types.ts
index b918f40b28..320a9e3b2b 100644
--- a/apps/web/src/lib/split-router/types.ts
+++ b/apps/web/src/lib/split-router/types.ts
@@ -73,13 +73,15 @@ type SplitRouteReference = {
};
type SplitRouteTargetParams<TRoute extends SplitRouteReference> =
- {} extends InferSplitRouteParams<TRoute>
- ? { params?: InferSplitRouteParams<TRoute> }
- : { params: InferSplitRouteParams<TRoute> };
+ {} extends InferSplitRouteNavigationParams<TRoute>
+ ? { params?: InferSplitRouteNavigationParams<TRoute> }
+ : { params: InferSplitRouteNavigationParams<TRoute> };
export type SplitRouteNavigationTarget<
TRoute extends SplitRouteReference = SplitRouteReference,
-> = { route: TRoute } & SplitRouteTargetParams<TRoute>;
+> = TRoute extends unknown
+ ? { route: TRoute } & SplitRouteTargetParams<NoInfer<TRoute>>
+ : never;
export type SplitParentNavigationTarget = {
parent: true;
@@ -161,14 +163,170 @@ export type SplitRouteDefinition<
externalSearch?:
| readonly string[]
| ((entry: Readonly<SplitRouterEntry>) => readonly string[]);
- remountKey?: (params: SplitRouteParams) => string | number | undefined;
+ remountKey?: SplitRouteParamCallback<
+ StandardSchemaV1.InferOutput<TParamsSchema>,
+ string | number | undefined
+ >;
};
+type PathSegmentParams<TSegment extends string> =
+ TSegment extends `:${infer TName}?`
+ ? { [K in TName]?: string }
+ : TSegment extends `:${infer TName}`
+ ? { [K in TName]: string }
+ : TSegment extends `*${infer TName}`
+ ? { [K in TName]: string[] }
+ : {};
+
+type PathParams<TPath extends string> = TPath extends unknown
+ ? string extends TPath
+ ? SplitRouteParams
+ : TPath extends `${infer TSegment}/${infer TRest}`
+ ? PathSegmentParams<TSegment> & PathParams<TRest>
+ : PathSegmentParams<TPath>
+ : never;
+
+type Simplify<T> = { [K in keyof T]: T[K] };
+type RequiredParamKeys<T> = {
+ [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+type MergedParam<
+ TParent,
+ TLocal,
+ K extends PropertyKey,
+> = K extends keyof TLocal
+ ? {} extends Pick<TLocal, K>
+ ? K extends keyof TParent
+ ? TParent[K] | TLocal[K]
+ : TLocal[K]
+ : TLocal[K]
+ : K extends keyof TParent
+ ? TParent[K]
+ : never;
+
+// Object.assign retains the parent value when an optional child field is absent.
+type MergeRouteParams<TParent, TLocal> = TParent extends unknown
+ ? TLocal extends unknown
+ ? Simplify<
+ {
+ [K in
+ | RequiredParamKeys<TParent>
+ | RequiredParamKeys<TLocal>]: MergedParam<TParent, TLocal, K>;
+ } & {
+ [K in Exclude<
+ keyof TParent | keyof TLocal,
+ RequiredParamKeys<TParent> | RequiredParamKeys<TLocal>
+ >]?: MergedParam<TParent, TLocal, K>;
+ }
+ >
+ : never
+ : never;
+
+/** The schema output (or raw path params) owned by this node alone. */
export type InferSplitRouteParams<TRoute> = TRoute extends {
params: infer TSchema extends StandardSchemaV1;
}
? StandardSchemaV1.InferOutput<TSchema>
- : SplitRouteParams;
+ : TRoute extends { path: infer TPath extends string }
+ ? MergeRouteParams<
+ {},
+ PathParams<
+ | TPath
+ | (TRoute extends { aliases: infer TAliases }
+ ? Extract<TAliases, readonly string[]>[number]
+ : never)
+ >
+ >
+ : SplitRouteParams;
+
+type LocalNavigationParams<TRoute> = TRoute extends { params: StandardSchemaV1 }
+ ? InferSplitRouteParams<TRoute>
+ : TRoute extends { path: infer TPath extends string }
+ ? MergeRouteParams<{}, PathParams<TPath>>
+ : SplitRouteParams;
+
+// Type-only ancestry. defineRoutes never adds properties to the supplied objects.
+declare const branchParams: unique symbol;
+
+/** Params accumulated through this node, with child fields overriding ancestors. */
+export type InferSplitRouteBranchParams<TRoute> = TRoute extends {
+ readonly [branchParams]: { read: infer TParams };
+}
+ ? TParams
+ : InferSplitRouteParams<TRoute>;
+
+/** A flat destination bag must satisfy every ancestor's serializer. */
+export type InferSplitRouteNavigationParams<TRoute> = TRoute extends {
+ readonly [branchParams]: { navigate: infer TParams };
+}
+ ? TParams
+ : LocalNavigationParams<TRoute>;
+
+// Empty object schemas can infer an index signature of never. It must not
+// prohibit the fields supplied by other nodes in the same branch.
+type BranchParams<TParams> =
+ TParams extends Record<string, never>
+ ? {
+ [K in keyof TParams as string extends K
+ ? never
+ : number extends K
+ ? never
+ : K]: TParams[K];
+ }
+ : TParams;
+
+type DefinedRoute<TRoute, TParent, TParentNavigation> = TRoute extends unknown
+ ? Omit<TRoute, 'children' | typeof branchParams> & {
+ readonly [branchParams]: {
+ read: MergeRouteParams<
+ TParent,
+ BranchParams<InferSplitRouteParams<TRoute>>
+ >;
+ navigate: MergeRouteParams<
+ {},
+ TParentNavigation & BranchParams<LocalNavigationParams<TRoute>>
+ >;
+ };
+ } & (TRoute extends { children: infer TChildren extends readonly unknown[] }
+ ? {
+ readonly children: DefinedRouteList<
+ TChildren,
+ MergeRouteParams<
+ TParent,
+ BranchParams<InferSplitRouteParams<TRoute>>
+ >,
+ TParentNavigation & BranchParams<LocalNavigationParams<TRoute>>
+ >;
+ }
+ : Pick<TRoute, Extract<keyof TRoute, 'children'>>)
+ : never;
+
+type DefinedRouteList<
+ TDefinitions extends readonly unknown[],
+ TParent,
+ TParentNavigation,
+> = {
+ [K in keyof TDefinitions]: DefinedRoute<
+ TDefinitions[K],
+ TParent,
+ TParentNavigation
+ >;
+};
+
+/** The original static tree, with ancestry available on references from that tree. */
+export type DefinedSplitRoutes<
+ TRoutes extends { definitions: readonly unknown[] },
+> = Omit<TRoutes, 'definitions'> & {
+ readonly definitions: DefinedRouteList<TRoutes['definitions'], {}, {}>;
+};
+
+type RouteUnion<TRoute> = TRoute extends { children: readonly (infer TChild)[] }
+ ? TRoute | RouteUnion<TChild>
+ : TRoute;
+
+export type SplitRouteUnion<TRoutes extends SplitRoutes> = RouteUnion<
+ TRoutes['definitions'][number]
+>;
export type UnmatchedSplitPathContext = {
segments: string[];
@@ -181,11 +339,11 @@ export type UnmatchedSplitPathHandler = (
/** Static route declarations. Do not mutate them during a router's lifetime. */
export type SplitRoutes<TComponent = unknown> = {
- definitions: SplitRouteDefinition<TComponent>[];
- unmatchedPathHandlers?: UnmatchedSplitPathHandler[];
+ definitions: readonly SplitRouteDefinition<TComponent>[];
+ unmatchedPathHandlers?: readonly UnmatchedSplitPathHandler[];
defaultEntry?: () => SplitRouterEntry;
- globalSearch?: string[];
- basePath?: string | string[];
+ globalSearch?: readonly string[];
+ basePath?: string | readonly string[];
};
export type SplitRouterLayoutEntry<TSplitId> = SplitRouterEntry & {
@@ -247,8 +405,8 @@ export type SplitRouterOptions<TSplitId> = {
};
export type SplitNavigate<TSplitId> = {
- <const TRoute extends SplitRouteReference>(
- to: SplitRouteNavigationTarget<TRoute>,
+ <const TTarget extends { route: SplitRouteReference }>(
+ to: TTarget & SplitRouteNavigationTarget<NoInfer<TTarget['route']>>,
options?: SplitNavigateOptions<TSplitId>
): void;
(to: SplitNonRouteNavigateTo, options?: SplitNavigateOptions<TSplitId>): void;
@@ -262,9 +420,9 @@ export interface SplitRouter<TSplitId> {
splitId: TSplitId,
namespace: string
): SerializedSearchParams | undefined;
- navigate<const TRoute extends SplitRouteReference>(
+ navigate<const TTarget extends { route: SplitRouteReference }>(
splitId: TSplitId,
- to: SplitRouteNavigationTarget<TRoute>,
+ to: TTarget & SplitRouteNavigationTarget<NoInfer<TTarget['route']>>,
options?: SplitNavigateOptions<TSplitId>
): void;
navigate(