-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
feat(router-core): replay view transitions on browser Back/Forward #7697
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
gkurt
wants to merge
3
commits into
TanStack:main
Choose a base branch
from
gkurt:feat/replay-view-transition-on-traversal
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+357
−8
Open
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| '@tanstack/router-core': patch | ||
| --- | ||
|
|
||
| feat: add `replayViewTransitionOnTraversal` router option | ||
|
|
||
| Replays the view transition a navigation opted into (`<Link viewTransition>` / `navigate({ viewTransition })`) when the user later traverses that entry with the browser Back/Forward buttons, instead of a hard cut. Replay is symmetric (`A→B` plays on both back and forward). Opt-in, kept in-memory so a functional `types` survives, and does not affect `defaultViewTransition`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
40 changes: 40 additions & 0 deletions
40
examples/react/view-transitions/src/directionAwareTransition.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,40 @@ | ||
| import type { ViewTransitionOptions } from '@tanstack/react-router' | ||
|
|
||
| /** | ||
| * A direction-aware view transition based on PAGE ORDER, not history position. | ||
| * | ||
| * `__TSR_index` only tracks the history stack, so a "Previous Page" link (a | ||
| * forward PUSH) increments it even though you're moving to an earlier page. | ||
| * Instead we rank pages by their place in the app's sequence and slide toward | ||
| * the later page — so the same logical move always animates the same way, | ||
| * whether reached by a link or by browser Back/Forward. | ||
| * | ||
| * `types` is a FUNCTION, so it re-resolves against each navigation's from/to; | ||
| * `replayViewTransitionOnTraversal` keeps it live by reference so Back/Forward | ||
| * recompute the correct direction. | ||
| */ | ||
| const PAGE_ORDER = ['/', '/how-it-works', '/explore', '/posts'] | ||
|
|
||
| function pageRank(pathname: string): number { | ||
| // longest matching prefix so e.g. /posts/123 ranks with /posts | ||
| let best = -1 | ||
| let bestLen = -1 | ||
| PAGE_ORDER.forEach((p, i) => { | ||
| const matches = p === '/' ? pathname === '/' : pathname.startsWith(p) | ||
| if (matches && p.length > bestLen) { | ||
| best = i | ||
| bestLen = p.length | ||
| } | ||
| }) | ||
| return best | ||
| } | ||
|
|
||
| export const slideByDirection: ViewTransitionOptions = { | ||
| types: ({ fromLocation, toLocation }) => { | ||
| if (!fromLocation) return ['slide-left'] | ||
| const from = pageRank(fromLocation.pathname) | ||
| const to = pageRank(toLocation.pathname) | ||
| // Moving to a later page slides left; to an earlier page slides right. | ||
| return [to >= from ? 'slide-left' : 'slide-right'] | ||
| }, | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
189 changes: 189 additions & 0 deletions
189
packages/router-core/tests/view-transition-traversal.test.ts
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest' | ||
| import { createMemoryHistory } from '@tanstack/history' | ||
| import { BaseRootRoute, BaseRoute } from '../src' | ||
| import { createTestRouter } from './routerTestUtils' | ||
| import type { ViewTransitionOptions } from '../src' | ||
|
|
||
| /** | ||
| * Tests for `replayViewTransitionOnTraversal`: a view transition opted into during a | ||
| * navigation (PUSH/REPLACE) should be replayed when the user traverses that entry with the | ||
| * browser Back/Forward buttons (BACK/FORWARD/GO), and should be a no-op otherwise. | ||
| */ | ||
|
|
||
| type StartVT = (arg: any) => any | ||
|
|
||
| let startViewTransitionSpy: ReturnType<typeof vi.fn> | ||
|
|
||
| beforeEach(() => { | ||
| // jsdom has no document.startViewTransition; mock one that runs the update callback | ||
| // synchronously and records how it was invoked. | ||
| startViewTransitionSpy = vi.fn<StartVT>((arg) => { | ||
| const update = typeof arg === 'function' ? arg : arg.update | ||
| update?.() | ||
| return { | ||
| ready: Promise.resolve(), | ||
| finished: Promise.resolve(), | ||
| updateCallbackDone: Promise.resolve(), | ||
| skipTransition: () => {}, | ||
| } | ||
| }) | ||
| ;(document as any).startViewTransition = startViewTransitionSpy | ||
| }) | ||
|
|
||
| afterEach(() => { | ||
| delete (document as any).startViewTransition | ||
| vi.restoreAllMocks() | ||
| }) | ||
|
|
||
| function createRouter(options: { replayViewTransitionOnTraversal?: boolean } = {}) { | ||
| const rootRoute = new BaseRootRoute({}) | ||
| const indexRoute = new BaseRoute({ getParentRoute: () => rootRoute, path: '/' }) | ||
| const aRoute = new BaseRoute({ getParentRoute: () => rootRoute, path: '/a' }) | ||
| const bRoute = new BaseRoute({ getParentRoute: () => rootRoute, path: '/b' }) | ||
|
|
||
| return createTestRouter({ | ||
| routeTree: rootRoute.addChildren([indexRoute, aRoute, bRoute]), | ||
| history: createMemoryHistory({ initialEntries: ['/'] }), | ||
| ...options, | ||
| }) | ||
| } | ||
|
|
||
| /** Mimics the Transitioner: load runs on every history event. */ | ||
| async function mount(router: ReturnType<typeof createRouter>) { | ||
| router.history.subscribe(router.load) | ||
| await router.load() | ||
| } | ||
|
|
||
| /** Drive a browser-style traversal and await the load it triggers. */ | ||
| async function traverse(router: ReturnType<typeof createRouter>, fn: () => void) { | ||
| fn() | ||
| await router.latestLoadPromise | ||
| } | ||
|
|
||
| describe('replayViewTransitionOnTraversal', () => { | ||
| test('replays the view transition on browser back', async () => { | ||
| const router = createRouter({ replayViewTransitionOnTraversal: true }) | ||
| await mount(router) | ||
|
|
||
| await router.navigate({ to: '/a', viewTransition: true }) | ||
| expect(startViewTransitionSpy).toHaveBeenCalledTimes(1) // the forward navigation itself | ||
| startViewTransitionSpy.mockClear() | ||
|
|
||
| await traverse(router, () => router.history.back()) | ||
|
|
||
| // Back to "/" replays the transition recorded for the "/a" entry. | ||
| expect(startViewTransitionSpy).toHaveBeenCalledTimes(1) | ||
| expect(router.state.location.pathname).toBe('/') | ||
| }) | ||
|
|
||
| test('replays the view transition on browser forward', async () => { | ||
| const router = createRouter({ replayViewTransitionOnTraversal: true }) | ||
| await mount(router) | ||
|
|
||
| await router.navigate({ to: '/a', viewTransition: true }) | ||
| await traverse(router, () => router.history.back()) | ||
| startViewTransitionSpy.mockClear() | ||
|
|
||
| await traverse(router, () => router.history.forward()) | ||
|
|
||
| // Forward to "/a" replays via the arriving entry's recorded transition. | ||
| expect(startViewTransitionSpy).toHaveBeenCalledTimes(1) | ||
| expect(router.state.location.pathname).toBe('/a') | ||
| }) | ||
|
|
||
| test('does not transition a traversal across an edge that never opted in', async () => { | ||
| const router = createRouter({ replayViewTransitionOnTraversal: true }) | ||
| await mount(router) | ||
|
|
||
| await router.navigate({ to: '/a' }) // plain navigation, no viewTransition | ||
| expect(startViewTransitionSpy).not.toHaveBeenCalled() | ||
|
|
||
| await traverse(router, () => router.history.back()) | ||
|
|
||
| expect(startViewTransitionSpy).not.toHaveBeenCalled() | ||
| expect(router.state.location.pathname).toBe('/') | ||
| }) | ||
|
|
||
| test('does not clobber an explicitly-set shouldViewTransition during a traversal', async () => { | ||
| const router = createRouter({ replayViewTransitionOnTraversal: true }) | ||
| router.isViewTransitionTypesSupported = true | ||
| await mount(router) | ||
|
|
||
| const recorded: ViewTransitionOptions = { types: ['recorded'] } | ||
| await router.navigate({ to: '/a', viewTransition: recorded }) | ||
| startViewTransitionSpy.mockClear() | ||
|
|
||
| // Something set a transition for this traversal explicitly; replay must not override it. | ||
| const explicit: ViewTransitionOptions = { types: ['explicit'] } | ||
| router.shouldViewTransition = explicit | ||
|
|
||
| await traverse(router, () => router.history.back()) | ||
|
|
||
| expect(startViewTransitionSpy).toHaveBeenCalledTimes(1) | ||
| expect(startViewTransitionSpy.mock.calls[0]![0]).toMatchObject({ | ||
| types: ['explicit'], | ||
| }) | ||
| }) | ||
|
|
||
| test('preserves a ViewTransitionOptions object with functional types by identity', async () => { | ||
| const router = createRouter({ replayViewTransitionOnTraversal: true }) | ||
| router.isViewTransitionTypesSupported = true | ||
| await mount(router) | ||
|
|
||
| // A function is NOT structured-cloneable, so this value could not survive being written | ||
| // to history.state — it survives only because the map holds it by reference. | ||
| const typesFn = vi.fn(() => ['slide']) | ||
| const vt: ViewTransitionOptions = { types: typesFn } | ||
|
|
||
| await router.navigate({ to: '/a', viewTransition: vt }) | ||
|
|
||
| // The exact object is held by reference for the "/a" entry (index 1). | ||
| expect(router.viewTransitionsByIndex.get(1)).toBe(vt) | ||
|
|
||
| startViewTransitionSpy.mockClear() | ||
| typesFn.mockClear() | ||
|
|
||
| await traverse(router, () => router.history.back()) | ||
|
|
||
| // The functional `types` was invoked and resolved on replay. | ||
| expect(typesFn).toHaveBeenCalledTimes(1) | ||
| expect(startViewTransitionSpy).toHaveBeenCalledTimes(1) | ||
| expect(startViewTransitionSpy.mock.calls[0]![0]).toMatchObject({ | ||
| types: ['slide'], | ||
| }) | ||
| }) | ||
|
|
||
| test('only traversals touching the transitioned entry replay', async () => { | ||
| const router = createRouter({ replayViewTransitionOnTraversal: true }) | ||
| await mount(router) | ||
|
|
||
| await router.navigate({ to: '/a' }) // "/a" = index 1, plain | ||
| await router.navigate({ to: '/b', viewTransition: true }) // "/b" = index 2, recorded | ||
| startViewTransitionSpy.mockClear() | ||
|
|
||
| // Leaving the transitioned "/b" entry replays. | ||
| await traverse(router, () => router.history.back()) | ||
| expect(router.state.location.pathname).toBe('/a') | ||
| expect(startViewTransitionSpy).toHaveBeenCalledTimes(1) | ||
| startViewTransitionSpy.mockClear() | ||
|
|
||
| // A traversal between two non-transitioned entries ("/a" -> "/") does not. | ||
| await traverse(router, () => router.history.back()) | ||
| expect(router.state.location.pathname).toBe('/') | ||
| expect(startViewTransitionSpy).not.toHaveBeenCalled() | ||
| }) | ||
|
|
||
| test('is a no-op when the option is disabled (default)', async () => { | ||
| const router = createRouter() // option not set | ||
| await mount(router) | ||
|
|
||
| await router.navigate({ to: '/a', viewTransition: true }) | ||
| startViewTransitionSpy.mockClear() | ||
|
|
||
| await traverse(router, () => router.history.back()) | ||
|
|
||
| // No replay: browser back is a hard cut by default. | ||
| expect(startViewTransitionSpy).not.toHaveBeenCalled() | ||
| expect(router.viewTransitionsByIndex.size).toBe(0) | ||
| }) | ||
| }) |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.