0
# View Stacks Management
1

2
Advanced view stack management system for handling complex navigation scenarios including multi-outlet routing, view lifecycle management, and component state preservation.
3

4
## Accessing View Stacks
5

6
The ViewStacks system is provided through the `viewStacks` injected provider available in Vue components.
7

8
```typescript
9
import { inject } from 'vue';
10

11
export default {
12
  setup() {
13
    const viewStacks = inject('viewStacks');
14
    // Use view stack methods...
15
  }
16
}
17
```
18

19
## Capabilities
20

21
### View Stack Information
22

23
Get information about the current view stacks.
24

25
```typescript { .api }
26
/**
27
 * Get the number of active view stacks
28
 * @returns Number of active stacks, indicates linear vs non-linear navigation
29
 */
30
size(): number;
31

32
/**
33
 * Get the view stack for a specific outlet
34
 * @param outletId - Outlet identifier
35
 * @returns Array of ViewItems in the stack or undefined
36
 */
37
getViewStack(outletId: number): ViewItem[] | undefined;
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
// Check navigation complexity
44
const stackCount = viewStacks.size();
45
if (stackCount > 1) {
46
  console.log('App is using non-linear navigation');
47
}
48

49
// Get views for specific outlet
50
const mainStack = viewStacks.getViewStack(0);
51
console.log('Main outlet has', mainStack?.length, 'views');
52
```
53

54
### View Item Management
55

56
Create and manage individual view items in the navigation stack.
57

58
```typescript { .api }
59
/**
60
 * Create a new view item for the navigation stack
61
 * @param outletId - Outlet identifier for the view
62
 * @param vueComponent - Vue component instance
63
 * @param matchedRoute - Matched route from Vue Router
64
 * @param routeInfo - Route information object
65
 * @param ionPage - Optional ion-page HTML element
66
 * @returns New ViewItem instance
67
 */
68
createViewItem(
69
  outletId: number,
70
  vueComponent: any,
71
  matchedRoute: RouteLocationMatched,
72
  routeInfo: RouteInfo,
73
  ionPage?: HTMLElement
74
): ViewItem;
75

76
/**
77
 * Add a view item to its corresponding stack
78
 * @param viewItem - ViewItem to add to the stack
79
 */
80
add(viewItem: ViewItem): void;
81

82
/**
83
 * Remove a view item from its stack
84
 * @param viewItem - ViewItem to remove
85
 * @param outletId - Optional outlet ID for the removal
86
 */
87
remove(viewItem: ViewItem, outletId?: number): void;
88
```
89

90
**Usage Example:**
91

92
```typescript
93
// Create and add a new view item
94
const viewItem = viewStacks.createViewItem(
95
  0, // main outlet
96
  componentInstance,
97
  matchedRoute,
98
  routeInfo
99
);
100

101
viewStacks.add(viewItem);
102
```
103

104
### View Lookup and Search
105

106
Find view items based on various criteria.
107

108
```typescript { .api }
109
/**
110
 * Find view item by route information
111
 * @param routeInfo - Route information to search for
112
 * @param outletId - Optional outlet ID to limit search
113
 * @returns ViewItem if found, undefined otherwise
114
 */
115
findViewItemByRouteInfo(routeInfo: RouteInfo, outletId?: number): ViewItem | undefined;
116

117
/**
118
 * Find view item by pathname
119
 * @param pathname - Route pathname to search for
120
 * @param outletId - Optional outlet ID to limit search
121
 * @returns ViewItem if found, undefined otherwise
122
 */
123
findViewItemByPathname(pathname: string, outletId?: number): ViewItem | undefined;
124

125
/**
126
 * Find the leaving view item based on route information
127
 * @param routeInfo - Route information for the leaving view
128
 * @param outletId - Optional outlet ID to limit search
129
 * @param mustBeIonRoute - Whether the view must be an Ionic route (default: true)
130
 * @returns ViewItem if found, undefined otherwise
131
 */
132
findLeavingViewItemByRouteInfo(
133
  routeInfo: RouteInfo,
134
  outletId?: number,
135
  mustBeIonRoute?: boolean
136
): ViewItem | undefined;
137
```
138

139
**Usage Examples:**
140

141
```typescript
142
// Find view by current route
143
const currentView = viewStacks.findViewItemByRouteInfo(currentRouteInfo);
144

145
// Find view by pathname
146
const profileView = viewStacks.findViewItemByPathname('/profile');
147

148
// Find leaving view during navigation
149
const leavingView = viewStacks.findLeavingViewItemByRouteInfo(
150
  routeInfo,
151
  0, // main outlet
152
  true // must be Ionic route
153
);
154
```
155

156
### View Rendering and Lifecycle
157

158
Manage which views should be rendered and their lifecycle states.
159

160
```typescript { .api }
161
/**
162
 * Get child views that should be rendered for an outlet
163
 * @param outletId - Outlet identifier
164
 * @returns Array of ViewItems that should be mounted
165
 */
166
getChildrenToRender(outletId: number): ViewItem[];
167

168
/**
169
 * Register an ion-page element with a view item
170
 * @param viewItem - ViewItem to register the page with
171
 * @param ionPage - HTML element representing the ion-page
172
 */
173
registerIonPage(viewItem: ViewItem, ionPage: HTMLElement): void;
174

175
/**
176
 * Clear all views from a specific outlet stack
177
 * @param outletId - Outlet identifier to clear
178
 */
179
clear(outletId: number): void;
180
```
181

182
**Usage Examples:**
183

184
```typescript
185
// Get views to render in main outlet
186
const viewsToRender = viewStacks.getChildrenToRender(0);
187

188
// Register ion-page with view item
189
viewStacks.registerIonPage(viewItem, ionPageElement);
190

191
// Clear outlet when navigating away
192
viewStacks.clear(1); // Clear secondary outlet
193
```
194

195
### Advanced View Management
196

197
Handle complex navigation scenarios with view mounting and unmounting.
198

199
```typescript { .api }
200
/**
201
 * Unmount leaving views when navigating backwards
202
 * @param outletId - Outlet identifier
203
 * @param viewItem - Current view item
204
 * @param delta - Number of steps back (default: 1)
205
 */
206
unmountLeavingViews(outletId: number, viewItem: ViewItem, delta?: number): void;
207

208
/**
209
 * Mount intermediary views when navigating forward over multiple views
210
 * @param outletId - Outlet identifier  
211
 * @param viewItem - Current view item
212
 * @param delta - Number of steps forward (default: 1)
213
 */
214
mountIntermediaryViews(outletId: number, viewItem: ViewItem, delta?: number): void;
215
```
216

217
**Usage Examples:**
218

219
```typescript
220
// Clean up when going back multiple pages
221
viewStacks.unmountLeavingViews(0, currentView, 2);
222

223
// Remount views when jumping forward in history
224
viewStacks.mountIntermediaryViews(0, currentView, 3);
225
```
226

227
## View Stack Scenarios
228

229
### Multi-Outlet Navigation
230

231
When using multiple router outlets (e.g., tabs with nested navigation):
232

233
```typescript
234
// Tab 1 stack: outlet 0
235
// Tab 2 stack: outlet 1
236
// Modal stack: outlet 2
237

238
const tab1Views = viewStacks.getViewStack(0);
239
const tab2Views = viewStacks.getViewStack(1);
240
const modalViews = viewStacks.getViewStack(2);
241

242
console.log('Active stacks:', viewStacks.size()); // 3
243
```
244

245
### View Lifecycle Management
246

247
Views in the stack have specific lifecycle states:
248

249
```typescript
250
const viewItem = viewStacks.findViewItemByPathname('/profile');
251
if (viewItem) {
252
  console.log('View mounted:', viewItem.mount);
253
  console.log('Is ionic route:', viewItem.ionRoute);
254
  console.log('Has ion-page:', !!viewItem.ionPageElement);
255
}
256
```
257

258
### Complex Navigation Cleanup
259

260
When navigating back over multiple views:
261

262
```typescript
263
// Current stack: /home -> /list -> /detail -> /modal
264
// Going back to /home (delta = -3)
265

266
const currentView = viewStacks.findViewItemByPathname('/modal');
267
if (currentView) {
268
  // This will unmount /list, /detail, and /modal
269
  viewStacks.unmountLeavingViews(0, currentView, 3);
270
}
271
```