You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Use usePreMountDestination for RHP-to-fullscreen pre-mounting
4
+
---
5
+
6
+
## [PERF-18] Use usePreMountDestination for RHP-to-fullscreen pre-mounting
7
+
8
+
### Reasoning
9
+
10
+
Modal-to-destination flows need the destination mounted before the RHP dismisses. Otherwise users see a gap on narrow layout or a flash of the previous page on wide layout.
11
+
12
+
`usePreMountDestination` centralizes this lifecycle:
13
+
14
+
- Idle-priority pre-insert on narrow layout, with a fallback timer so the work is not starved
15
+
- Reveal-before-dismiss fallback on wide layout or if narrow pre-insert has not finished
16
+
- Automatic cleanup for back-out and unmount paths
17
+
18
+
When reviewing these flows, focus on whether the navigation lifecycle is correct for the user path:
19
+
20
+
- The destination route is stable at mount time
21
+
-`reveal()` is called only after validation, synchronous writes, and target-route selection are complete
22
+
- The caller handles flow-specific no-op cases before calling `reveal()`
23
+
- Cleanup or preservation is handled on back-out and unmount
-`reveal(afterTransition?)`: if the hook owns a pre-inserted narrow route, clears the pre-insert flag and dismisses the RHP over that route. Otherwise, inserts the destination under the RHP and then dismisses it.
57
+
-`cleanupPreMount()`: removes the owned pre-inserted destination before a back-out path closes the RHP without revealing the destination.
58
+
59
+
**Caller responsibilities:**
60
+
61
+
- Keep flow-specific checks and synchronous work outside the hook.
62
+
- Handle no-op cases before calling `reveal()`, such as when the destination route is already the active fullscreen route behind the modal.
63
+
- Pass `reveal(afterTransition)` only for work that must run after the dismiss/reveal transition.
64
+
- Call `cleanupPreMount()` on every back-out path that closes the RHP without calling `reveal()`.
65
+
66
+
**Scheduling:**
67
+
68
+
- Mount-time pre-insert always waits for the RHP open transition before scheduling idle pre-insert work.
69
+
- If no upcoming transition starts within 500ms, the hook proceeds with idle pre-insert scheduling. This only prevents missing the RHP open transition; broader transition timing changes should be discussed separately.
70
+
71
+
### Review Focus
72
+
73
+
Prioritize judgment-based issues:
74
+
75
+
- Whether the flow is actually an RHP/modal-to-different-fullscreen reveal
76
+
- Whether the destination is stable and known when the hook mounts
77
+
- Whether the caller keeps flow-specific checks and synchronous writes outside `reveal()`
78
+
- Whether the caller handles no-op cases where the destination is already active
79
+
- Whether a back-out path calls `cleanupPreMount()`
80
+
- Whether an unmount-before-submit flow needs `shouldPreservePreInsertedRouteOnUnmount`
81
+
82
+
### When to use
83
+
84
+
Use `usePreMountDestination` when **all** of these are true:
85
+
86
+
- The flow dismisses an RHP/modal to reveal a **different** fullscreen destination
87
+
- The destination route is **known at mount time**
88
+
- The user spends enough time on the confirmation screen for pre-insert to complete before dismiss (narrow layout)
89
+
90
+
### When NOT to use
91
+
92
+
- Destination is not known in advance
93
+
- There is no modal/RHP to dismiss
94
+
- The destination is already the screen behind the modal
95
+
- The transition is already fast enough. Profile first, do not add complexity speculatively
96
+
- Flow-specific dismiss strategies that do not use pre-insert/reveal. Keep those helpers
97
+
98
+
### Review Metadata
99
+
100
+
Flag when:
101
+
102
+
-`usePreMountDestination` is used in a flow that does not dismiss an RHP/modal to reveal a different fullscreen destination
103
+
-`usePreMountDestination` is used with a destination that is not stable/known at mount time
104
+
- A caller relies on `reveal(afterTransition)` for work that must happen before navigation, such as validation, target-route selection, or a synchronous write needed before the destination is revealed
105
+
- A back-out path closes the RHP without calling `cleanupPreMount()` when the component owns a pre-inserted route
106
+
- A submit path unmounts the component before `reveal()` runs but does not preserve the pre-inserted route with `shouldPreservePreInsertedRouteOnUnmount`
107
+
- New code reimplements pre-insert timing, back-out cleanup, or reveal-before-dismiss orchestration inline instead of using the hook, even if it avoids a direct `preInsertFullscreenUnderRHP` call
108
+
109
+
**DO NOT flag if:**
110
+
111
+
- The code uses `usePreMountDestination` correctly with the matching reveal method for the flow
112
+
- The call site is an approved exception (`IOURequestStepConfirmation`, `useSkipConfirmationPreInsert` until migrated)
113
+
- The flow uses specialized dismiss helpers that intentionally bypass pre-insert/reveal
constwarnMessage=(platform: string): string=>`Number of hubs in _routes.yml does not match number of hubs in docs/${platform}/articles. Please update _routes.yml with hub info.`;
40
54
constdisclaimer='# This file is auto-generated. Do not edit it directly. Use npm run createDocsRoutes instead.\n';
41
55
constdocsDir=`${process.cwd()}/docs`;
@@ -109,24 +123,55 @@ function getOrderFromArticleFrontMatter(path: string): number | undefined {
0 commit comments