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

[naoya7076]

Overview

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

• Router V2 #975 (comment)
• How to replace location.state？ #284 (reply in thread)

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;
  }
}

#284
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:

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

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
})

Need help

Unit test fix

• packages/react-router/tests/route.test-d.tsx:L1234-L1236
• packages/solid-router/tests/route.test-d.tsx:L1289-L1291
  There are two failing tests that I couldn't fix on my own. Any advice would be appreciated!