docs: note about generic route record name

Author: posva

packages/router/src/typed-routes/route-location.ts

@@ -11,14 +11,7 @@ import type { _LiteralUnion } from '../types/utils'
 import type { RouteMap, RouteMapGeneric } from './route-map'
 import type { Router } from '../router'
 import type { RouteRecord, RouteRecordNormalized } from '../matcher/types'
-import { RouteRecordNameGeneric } from './route-records'
-
-/**
- * Possible values for a user-defined route record's name.
- */
-export type RouteRecordName = RouteMapGeneric extends RouteMap
-  ? RouteRecordNameGeneric
-  : keyof RouteMap
+import type { RouteRecordName, RouteRecordNameGeneric } from './route-records'
 
 /**
  * Generic version of {@link RouteLocation}. It is used when no {@link RouteMap} is provided.

packages/router/src/typed-routes/route-records.ts

@@ -1,9 +1,9 @@
-import {
+import type {
   RouteLocation,
   RouteLocationNormalized,
   RouteLocationRaw,
 } from './route-location'
-import { RouteMap } from './route-map'
+import type { RouteMap, RouteMapGeneric } from './route-map'
 
 /**
  * @internal
@@ -17,6 +17,15 @@ export type RouteRecordRedirectOption =
  */
 export type RouteRecordNameGeneric = string | symbol | undefined
 
+/**
+ * Possible values for a user-defined route record's name.
+ *
+ * NOTE: since `RouteRecordName` is a type, it evaluates too early and it's always be {@link RouteRecordNameGeneric}. If you need a typed version use {@link RouteMap | `keyof RouteMap`}
+ */
+export type RouteRecordName = RouteMapGeneric extends RouteMap
+  ? RouteRecordNameGeneric
+  : keyof RouteMap
+
 /**
  * @internal
  */