refactor(history): use TSR_key namespace in state for hash (#4356)

Co-authored-by: SeanCassiere <33615041+SeanCassiere@users.noreply.github.com>

Author: naoya7076

docs/router/framework/react/api/router/ParsedHistoryStateType.md

@@ -7,7 +7,8 @@ The `ParsedHistoryState` type represents a parsed state object. Additionally to
 
 ```tsx
 export type ParsedHistoryState = HistoryState & {
-  key?: string
+  key?: string // TODO: Remove in v2 - use __TSR_key instead
+  __TSR_key?: string
   __TSR_index: number
 }
 ```

docs/router/framework/react/guide/scroll-restoration.md

@@ -71,7 +71,9 @@ Falling in behind Remix's own Scroll Restoration APIs, you can also customize th
 
 The `getKey` option receives the relevant `Location` state from TanStack Router and expects you to return a string to uniquely identify the scrollable measurements for that state.
 
-The default `getKey` is `(location) => location.state.key!`, where `key` is the unique key generated for each entry in the history.
+The default `getKey` is `(location) => location.state.__TSR_key!`, where `__TSR_key` is the unique key generated for each entry in the history.
+
+> Older versions, prior to `v1.121.34`, used `state.key` as the default key, but this has been deprecated in favor of `state.__TSR_key`. For now, `location.state.key` will still be available for compatibility, but it will be removed in the next major version.
 
 ## Examples
 
@@ -95,7 +97,7 @@ const router = createRouter({
     const paths = ['/', '/chat']
     return paths.includes(location.pathname)
       ? location.pathname
-      : location.state.key!
+      : location.state.__TSR_key!
   },
 })
 ```

packages/history/src/index.ts

@@ -53,7 +53,8 @@ export interface ParsedPath {
 export interface HistoryState {}
 
 export type ParsedHistoryState = HistoryState & {
-  key?: string
+  key?: string // TODO: Remove in v2 - use __TSR_key instead
+  __TSR_key?: string
   __TSR_index: number
 }
 
@@ -252,9 +253,11 @@ function assignKeyAndIndex(index: number, state: HistoryState | undefined) {
   if (!state) {
     state = {} as HistoryState
   }
+  const key = createRandomKey()
   return {
     ...state,
-    key: createRandomKey(),
+    key, // TODO: Remove in v2 - use __TSR_key instead
+    __TSR_key: key,
     [stateIndexKey]: index,
   } as ParsedHistoryState
 }
@@ -302,11 +305,13 @@ export function createBrowserHistory(opts?: {
       ))
 
   // Ensure there is always a key to start
-  if (!win.history.state?.key) {
+  if (!win.history.state?.__TSR_key && !win.history.state?.key) {
+    const addedKey = createRandomKey()
     win.history.replaceState(
       {
         [stateIndexKey]: 0,
-        key: createRandomKey(),
+        key: addedKey, // TODO: Remove in v2 - use __TSR_key instead
+        __TSR_key: addedKey,
       },
       '',
     )
@@ -615,6 +620,8 @@ export function parseHref(
   const hashIndex = href.indexOf('#')
   const searchIndex = href.indexOf('?')
 
+  const addedKey = createRandomKey()
+
   return {
     href,
     pathname: href.substring(
@@ -632,7 +639,7 @@ export function parseHref(
       searchIndex > -1
         ? href.slice(searchIndex, hashIndex === -1 ? undefined : hashIndex)
         : '',
-    state: state || { [stateIndexKey]: 0, key: createRandomKey() },
+    state: state || { [stateIndexKey]: 0, key: addedKey, __TSR_key: addedKey },
   }
 }
 

packages/react-router/src/Match.tsx

@@ -126,7 +126,7 @@ export const Match = React.memo(function MatchImpl({
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.key. Also, because it's below the root layout, it
+// location state.__TSR_key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -139,7 +139,7 @@ function OnRendered() {
 
   return (
     <script
-      key={router.latestLocation.state.key}
+      key={router.latestLocation.state.__TSR_key}
       suppressHydrationWarning
       ref={(el) => {
         if (

packages/react-router/tests/redirect.test.tsx

@@ -364,6 +364,7 @@ describe('redirect', () => {
           searchStr: '',
           state: {
             __TSR_index: 0,
+            __TSR_key: currentRedirect.options._fromLocation!.state.__TSR_key,
             key: currentRedirect.options._fromLocation!.state.key,
           },
         },

packages/router-core/src/router.ts

@@ -1016,7 +1016,8 @@ export class RouterCore<
     if (__tempLocation && (!__tempKey || __tempKey === this.tempLocationKey)) {
       // Sync up the location keys
       const parsedTempLocation = parse(__tempLocation) as any
-      parsedTempLocation.state.key = location.state.key
+      parsedTempLocation.state.key = location.state.key // TODO: Remove in v2 - use __TSR_key instead
+      parsedTempLocation.state.__TSR_key = location.state.__TSR_key
 
       delete parsedTempLocation.state.__tempLocation
 
@@ -1616,7 +1617,8 @@ export class RouterCore<
       // temporarily add the previous values to the next state so they don't affect
       // the comparison
       const ignoredProps = [
-        'key',
+        'key', // TODO: Remove in v2 - use __TSR_key instead
+        '__TSR_key',
         '__TSR_index',
         '__hashScrollIntoViewOptions',
       ] as const
@@ -1657,7 +1659,8 @@ export class RouterCore<
                 ...nextHistory.state,
                 __tempKey: undefined!,
                 __tempLocation: undefined!,
-                key: undefined!,
+                __TSR_key: undefined!,
+                key: undefined!, // TODO: Remove in v2 - use __TSR_key instead
               },
             },
           },

packages/router-core/src/scroll-restoration.ts

@@ -79,7 +79,7 @@ export const scrollRestorationCache = createScrollRestorationCache()
  */
 
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
-  return location.state.key! || location.href
+  return location.state.__TSR_key! || location.href
 }
 
 export function getCssSelector(el: any): string {

packages/solid-router/src/Match.tsx

@@ -131,7 +131,7 @@ export const Match = (props: { matchId: string }) => {
 // On Rendered can't happen above the root layout because it actually
 // renders a dummy dom element to track the rendered state of the app.
 // We render a script tag with a key that changes based on the current
-// location state.key. Also, because it's below the root layout, it
+// location state.__TSR_key. Also, because it's below the root layout, it
 // allows us to fire onRendered events even after a hydration mismatch
 // error that occurred above the root layout (like bad head/link tags,
 // which is common).
@@ -140,7 +140,7 @@ function OnRendered() {
 
   const location = useRouterState({
     select: (s) => {
-      return s.resolvedLocation?.state.key
+      return s.resolvedLocation?.state.__TSR_key
     },
   })
   Solid.createEffect(

packages/solid-router/tests/redirect.test.tsx

@@ -358,6 +358,7 @@ describe('redirect', () => {
         searchStr: '',
         state: {
           __TSR_index: 0,
+          __TSR_key: currentRedirect.options._fromLocation!.state.__TSR_key,
           key: currentRedirect.options._fromLocation!.state.key,
         },
       },