feat(react-router): Add useHistoryState hook for type-safe history state management

[naoya7076]

Remaining tasks

useHistoryState

• Enable useHistoryState to access validated state from match object

Dev tool update

Currently displaying all states, but some are unnecessary.

• Filter out states starting with __.

Conflict resolution

Resolve the conflict in packages/react-router/src/router.ts.

Unit test fix

Review and fix packages/react-router/tests/useHistoryState.test.tsx.

Overview

This PR introduces the new useHistoryState hook and related functionality to enable type-safe history state management in TanStack Router.

#975 (comment)

Background

In the current implementation of TanStack Router, to pass type-safe state (History State) between routes that isn't part of the path or params, we need to define types globally. This leads to two main issues:

1. Type pollution - types appear in places where they aren't needed
2. Interface bloat - as more states are added, the global interface grows excessively

For example:

declare module '@tanstack/react-router' {
  interface HistoryState {
    user?: MyUserType;
    project?: MyProjectType;
  }
}

Additionally, when migrating from react-router to TanStack Router, developers want to be able to handle state in a type-safe manner, similar to how they could with react-router:
#284

const history = useHistory();
history.replace({ pathname: '/', state: { name: 'Lily' }});
...
const location = useLocation();
// do something with location.state...

This PR addresses these issues by adding route-specific, type-safe history state management.

Changes

• Added useHistoryState hook export in the main package index
• Extended the FileRoute class to support state validation with TStateValidator generic parameter
• Created a full example in examples/react/basic-history-state demonstrating usage patterns
• The example shows how to:
  • Define state schemas using Zod
  • Pass state during navigation with Link and navigate
  • Retrieve state in different ways (direct route access, from parameter, selection, non-strict mode)
  • Handle optional properties like message in state objects

Key features of useHistoryState

• Type-safe access to history state passed during navigation
• Support for default values and optional properties
• Ability to select specific state properties
• Non-strict mode for accessing raw state object

Example usage

Users can define state validation on routes:

validateState: (input) =>
  z.object({
    color: z.enum(['white', 'red', 'green', 'blue']).default('white'),
    visited: z.boolean().default(false),
    message: z.string().optional(),
  }).parse(input),

Then use it in components:

// From route directly
const state = postRoute.useHistoryState()

// With select to extract specific values
const color = useHistoryState({
  from: '/posts/post',
  select: (state) => state.color
})