UNPKG

20.7 kBTypeScriptView Raw
1import type { DefaultRouterOptions, InitialState, NavigationAction, NavigationState, ParamListBase, PartialState, Route } from '@react-navigation/routers';
2import type * as React from 'react';
3declare global {
4 namespace ReactNavigation {
5 interface RootParamList {
6 }
7 }
8}
9type Keyof<T extends {}> = Extract<keyof T, string>;
10export type DefaultNavigatorOptions<ParamList extends ParamListBase, State extends NavigationState, ScreenOptions extends {}, EventMap extends EventMapBase> = DefaultRouterOptions<Keyof<ParamList>> & {
11 /**
12 * Optional ID for the navigator. Can be used with `navigation.getParent(id)` to refer to a parent.
13 */
14 id?: string;
15 /**
16 * Children React Elements to extract the route configuration from.
17 * Only `Screen`, `Group` and `React.Fragment` are supported as children.
18 */
19 children: React.ReactNode;
20 /**
21 * Event listeners for all the screens in the navigator.
22 */
23 screenListeners?: ScreenListeners<State, EventMap> | ((props: {
24 route: RouteProp<ParamList>;
25 navigation: any;
26 }) => ScreenListeners<State, EventMap>);
27 /**
28 * Default options for all screens under this navigator.
29 */
30 screenOptions?: ScreenOptions | ((props: {
31 route: RouteProp<ParamList>;
32 navigation: any;
33 }) => ScreenOptions);
34};
35export type EventMapBase = Record<string, {
36 data?: any;
37 canPreventDefault?: boolean;
38}>;
39export type EventMapCore<State extends NavigationState> = {
40 focus: {
41 data: undefined;
42 };
43 blur: {
44 data: undefined;
45 };
46 state: {
47 data: {
48 state: State;
49 };
50 };
51 beforeRemove: {
52 data: {
53 action: NavigationAction;
54 };
55 canPreventDefault: true;
56 };
57};
58export type EventArg<EventName extends string, CanPreventDefault extends boolean | undefined = false, Data = undefined> = {
59 /**
60 * Type of the event (e.g. `focus`, `blur`)
61 */
62 readonly type: EventName;
63 readonly target?: string;
64} & (CanPreventDefault extends true ? {
65 /**
66 * Whether `event.preventDefault()` was called on this event object.
67 */
68 readonly defaultPrevented: boolean;
69 /**
70 * Prevent the default action which happens on this event.
71 */
72 preventDefault(): void;
73} : {}) & (undefined extends Data ? {
74 readonly data?: Readonly<Data>;
75} : {
76 readonly data: Readonly<Data>;
77});
78export type EventListenerCallback<EventMap extends EventMapBase, EventName extends keyof EventMap> = (e: EventArg<Extract<EventName, string>, EventMap[EventName]['canPreventDefault'], EventMap[EventName]['data']>) => void;
79export type EventConsumer<EventMap extends EventMapBase> = {
80 /**
81 * Subscribe to events from the parent navigator.
82 *
83 * @param type Type of the event (e.g. `focus`, `blur`)
84 * @param callback Callback listener which is executed upon receiving the event.
85 */
86 addListener<EventName extends Keyof<EventMap>>(type: EventName, callback: EventListenerCallback<EventMap, EventName>): () => void;
87 removeListener<EventName extends Keyof<EventMap>>(type: EventName, callback: EventListenerCallback<EventMap, EventName>): void;
88};
89export type EventEmitter<EventMap extends EventMapBase> = {
90 /**
91 * Emit an event to child screens.
92 *
93 * @param options.type Type of the event (e.g. `focus`, `blur`)
94 * @param [options.data] Optional information regarding the event.
95 * @param [options.target] Key of the target route which should receive the event.
96 * If not specified, all routes receive the event.
97 */
98 emit<EventName extends Keyof<EventMap>>(options: {
99 type: EventName;
100 target?: string;
101 } & (EventMap[EventName]['canPreventDefault'] extends true ? {
102 canPreventDefault: true;
103 } : {}) & (undefined extends EventMap[EventName]['data'] ? {
104 data?: EventMap[EventName]['data'];
105 } : {
106 data: EventMap[EventName]['data'];
107 })): EventArg<EventName, EventMap[EventName]['canPreventDefault'], EventMap[EventName]['data']>;
108};
109export declare class PrivateValueStore<T extends [any, any, any]> {
110 /**
111 * UGLY HACK! DO NOT USE THE TYPE!!!
112 *
113 * TypeScript requires a type to be used to be able to infer it.
114 * The type should exist as its own without any operations such as union.
115 * So we need to figure out a way to store this type in a property.
116 * The problem with a normal property is that it shows up in intelliSense.
117 * Adding private keyword works, but the annotation is stripped away in declaration.
118 * Turns out if we use an empty string, it doesn't show up in intelliSense.
119 */
120 protected ''?: T;
121}
122type NavigationHelpersCommon<ParamList extends ParamListBase, State extends NavigationState = NavigationState> = {
123 /**
124 * Dispatch an action or an update function to the router.
125 * The update function will receive the current state,
126 *
127 * @param action Action object or update function.
128 */
129 dispatch(action: NavigationAction | ((state: State) => NavigationAction)): void;
130 /**
131 * Navigate to a route in current navigation tree.
132 *
133 * @param name Name of the route to navigate to.
134 * @param [params] Params object for the route.
135 */
136 navigate<RouteName extends keyof ParamList>(...args: RouteName extends unknown ? undefined extends ParamList[RouteName] ? [screen: RouteName] | [screen: RouteName, params: ParamList[RouteName]] : [screen: RouteName, params: ParamList[RouteName]] : never): void;
137 /**
138 * Navigate to a route in current navigation tree.
139 *
140 * @param route Object with `key` or `name` for the route to navigate to, and a `params` object.
141 */
142 navigate<RouteName extends keyof ParamList>(options: RouteName extends unknown ? {
143 key: string;
144 params?: ParamList[RouteName];
145 merge?: boolean;
146 } | {
147 name: RouteName;
148 key?: string;
149 params: ParamList[RouteName];
150 merge?: boolean;
151 } : never): void;
152 /**
153 * Reset the navigation state to the provided state.
154 *
155 * @param state Navigation state object.
156 */
157 reset(state: PartialState<State> | State): void;
158 /**
159 * Go back to the previous route in history.
160 */
161 goBack(): void;
162 /**
163 * Check if the screen is focused. The method returns `true` if focused, `false` otherwise.
164 * Note that this method doesn't re-render screen when the focus changes. So don't use it in `render`.
165 * To get notified of focus changes, use `addListener('focus', cb)` and `addListener('blur', cb)`.
166 * To conditionally render content based on focus state, use the `useIsFocused` hook.
167 */
168 isFocused(): boolean;
169 /**
170 * Check if dispatching back action will be handled by navigation.
171 * Note that this method doesn't re-render screen when the result changes. So don't use it in `render`.
172 */
173 canGoBack(): boolean;
174 /**
175 * Returns the name of the navigator specified in the `name` prop.
176 * If no name is specified, returns `undefined`.
177 */
178 getId(): string | undefined;
179 /**
180 * Returns the navigation helpers from a parent navigator based on the ID.
181 * If an ID is provided, the navigation helper from the parent navigator with matching ID (including current) will be returned.
182 * If no ID is provided, the navigation helper from the immediate parent navigator will be returned.
183 *
184 * @param id Optional ID of a parent navigator.
185 */
186 getParent<T = NavigationHelpers<ParamListBase> | undefined>(id?: string): T;
187 /**
188 * Returns the navigator's state.
189 * Note that this method doesn't re-render screen when the result changes. So don't use it in `render`.
190 */
191 getState(): State;
192} & PrivateValueStore<[ParamList, unknown, unknown]>;
193export type NavigationHelpers<ParamList extends ParamListBase, EventMap extends EventMapBase = {}> = NavigationHelpersCommon<ParamList> & EventEmitter<EventMap> & {
194 /**
195 * Update the param object for the route.
196 * The new params will be shallow merged with the old one.
197 *
198 * @param params Params object for the current route.
199 */
200 setParams<RouteName extends keyof ParamList>(params: Partial<ParamList[RouteName]>): void;
201};
202export type NavigationContainerProps = {
203 /**
204 * Initial navigation state for the child navigators.
205 */
206 initialState?: InitialState;
207 /**
208 * Callback which is called with the latest navigation state when it changes.
209 */
210 onStateChange?: (state: NavigationState | undefined) => void;
211 /**
212 * Callback which is called when an action is not handled.
213 */
214 onUnhandledAction?: (action: NavigationAction) => void;
215 /**
216 * Whether this navigation container should be independent of parent containers.
217 * If this is not set to `true`, this container cannot be nested inside another container.
218 * Setting it to `true` disconnects any children navigators from parent container.
219 */
220 independent?: boolean;
221 /**
222 * Children elements to render.
223 */
224 children: React.ReactNode;
225};
226export type NavigationProp<ParamList extends {}, RouteName extends keyof ParamList = Keyof<ParamList>, NavigatorID extends string | undefined = undefined, State extends NavigationState = NavigationState<ParamList>, ScreenOptions extends {} = {}, EventMap extends EventMapBase = {}> = Omit<NavigationHelpersCommon<ParamList, State>, 'getParent'> & {
227 /**
228 * Returns the navigation prop from a parent navigator based on the ID.
229 * If an ID is provided, the navigation prop from the parent navigator with matching ID (including current) will be returned.
230 * If no ID is provided, the navigation prop from the immediate parent navigator will be returned.
231 *
232 * @param id Optional ID of a parent navigator.
233 */
234 getParent<T = NavigationProp<ParamListBase> | undefined>(id?: NavigatorID): T;
235 /**
236 * Update the param object for the route.
237 * The new params will be shallow merged with the old one.
238 *
239 * @param params Params object for the current route.
240 */
241 setParams(params: ParamList[RouteName] extends undefined ? undefined : Partial<ParamList[RouteName]>): void;
242 /**
243 * Update the options for the route.
244 * The options object will be shallow merged with default options object.
245 *
246 * @param options Options object for the route.
247 */
248 setOptions(options: Partial<ScreenOptions>): void;
249} & EventConsumer<EventMap & EventMapCore<State>> & PrivateValueStore<[ParamList, RouteName, EventMap]>;
250export type RouteProp<ParamList extends ParamListBase, RouteName extends keyof ParamList = Keyof<ParamList>> = Route<Extract<RouteName, string>, ParamList[RouteName]>;
251export type CompositeNavigationProp<A extends NavigationProp<ParamListBase, string, any, any, any>, B extends NavigationHelpersCommon<ParamListBase, any>> = Omit<A & B, keyof NavigationProp<any>> & NavigationProp<
252/**
253 * Param list from both navigation objects needs to be combined
254 * For example, we should be able to navigate to screens in both A and B
255 */
256(A extends NavigationHelpersCommon<infer T> ? T : never) & (B extends NavigationHelpersCommon<infer U> ? U : never),
257/**
258 * The route name should refer to the route name specified in the first type
259 * Ideally it should work for any of them, but it's not possible to infer that way
260 */
261A extends NavigationProp<any, infer R> ? R : string,
262/**
263 * ID from both navigation objects needs to be combined for `getParent`
264 */
265(A extends NavigationProp<any, any, infer I> ? I : never) | (B extends NavigationProp<any, any, infer J> ? J : never),
266/**
267 * The type of state should refer to the state specified in the first type
268 */
269A extends NavigationProp<any, any, any, infer S> ? S : NavigationState,
270/**
271 * Screen options from both navigation objects needs to be combined
272 * This allows typechecking `setOptions`
273 */
274(A extends NavigationProp<any, any, any, any, infer O> ? O : {}) & (B extends NavigationProp<any, any, any, any, infer P> ? P : {}),
275/**
276 * Event consumer config should refer to the config specified in the first type
277 * This allows typechecking `addListener`/`removeListener`
278 */
279A extends NavigationProp<any, any, any, any, any, infer E> ? E : {}>;
280export type CompositeScreenProps<A extends {
281 navigation: NavigationProp<ParamListBase, string, string | undefined, any, any, any>;
282 route: RouteProp<ParamListBase>;
283}, B extends {
284 navigation: NavigationHelpersCommon<any, any>;
285}> = {
286 navigation: CompositeNavigationProp<A['navigation'], B['navigation']>;
287 route: A['route'];
288};
289export type Descriptor<ScreenOptions extends {}, Navigation extends NavigationProp<any, any, any, any, any, any>, Route extends RouteProp<any, any>> = {
290 /**
291 * Render the component associated with this route.
292 */
293 render(): JSX.Element;
294 /**
295 * Options for the route.
296 */
297 options: ScreenOptions;
298 /**
299 * Route object for the screen
300 */
301 route: Route;
302 /**
303 * Navigation object for the screen
304 */
305 navigation: Navigation;
306};
307export type ScreenListeners<State extends NavigationState, EventMap extends EventMapBase> = Partial<{
308 [EventName in keyof (EventMap & EventMapCore<State>)]: EventListenerCallback<EventMap, EventName>;
309}>;
310type ScreenComponentType<ParamList extends ParamListBase, RouteName extends keyof ParamList> = React.ComponentType<{
311 route: RouteProp<ParamList, RouteName>;
312 navigation: any;
313}> | React.ComponentType<{}>;
314export type RouteConfigComponent<ParamList extends ParamListBase, RouteName extends keyof ParamList> = {
315 /**
316 * React component to render for this screen.
317 */
318 component: ScreenComponentType<ParamList, RouteName>;
319 getComponent?: never;
320 children?: never;
321} | {
322 /**
323 * Lazily get a React component to render for this screen.
324 */
325 getComponent: () => ScreenComponentType<ParamList, RouteName>;
326 component?: never;
327 children?: never;
328} | {
329 /**
330 * Render callback to render content of this screen.
331 */
332 children: (props: {
333 route: RouteProp<ParamList, RouteName>;
334 navigation: any;
335 }) => React.ReactNode;
336 component?: never;
337 getComponent?: never;
338};
339export type RouteConfig<ParamList extends ParamListBase, RouteName extends keyof ParamList, State extends NavigationState, ScreenOptions extends {}, EventMap extends EventMapBase> = {
340 /**
341 * Optional key for this screen. This doesn't need to be unique.
342 * If the key changes, existing screens with this name will be removed or reset.
343 * Useful when we have some common screens and have conditional rendering.
344 */
345 navigationKey?: string;
346 /**
347 * Route name of this screen.
348 */
349 name: RouteName;
350 /**
351 * Navigator options for this screen.
352 */
353 options?: ScreenOptions | ((props: {
354 route: RouteProp<ParamList, RouteName>;
355 navigation: any;
356 }) => ScreenOptions);
357 /**
358 * Event listeners for this screen.
359 */
360 listeners?: ScreenListeners<State, EventMap> | ((props: {
361 route: RouteProp<ParamList, RouteName>;
362 navigation: any;
363 }) => ScreenListeners<State, EventMap>);
364 /**
365 * Function to return an unique ID for this screen.
366 * Receives an object with the route params.
367 * For a given screen name, there will always be only one screen corresponding to an ID.
368 * If `undefined` is returned, it acts same as no `getId` being specified.
369 */
370 getId?: ({ params }: {
371 params: ParamList[RouteName];
372 }) => string | undefined;
373 /**
374 * Initial params object for the route.
375 */
376 initialParams?: Partial<ParamList[RouteName]>;
377} & RouteConfigComponent<ParamList, RouteName>;
378export type RouteGroupConfig<ParamList extends ParamListBase, ScreenOptions extends {}> = {
379 /**
380 * Optional key for the screens in this group.
381 * If the key changes, all existing screens in this group will be removed or reset.
382 */
383 navigationKey?: string;
384 /**
385 * Navigator options for this screen.
386 */
387 screenOptions?: ScreenOptions | ((props: {
388 route: RouteProp<ParamList, keyof ParamList>;
389 navigation: any;
390 }) => ScreenOptions);
391 /**
392 * Children React Elements to extract the route configuration from.
393 * Only `Screen`, `Group` and `React.Fragment` are supported as children.
394 */
395 children: React.ReactNode;
396};
397export type NavigationContainerEventMap = {
398 /**
399 * Event which fires when the navigation state changes.
400 */
401 state: {
402 data: {
403 /**
404 * The updated state object after the state change.
405 */
406 state: NavigationState | PartialState<NavigationState> | undefined;
407 };
408 };
409 /**
410 * Event which fires when current options changes.
411 */
412 options: {
413 data: {
414 options: object;
415 };
416 };
417 /**
418 * Event which fires when an action is dispatched.
419 * Only intended for debugging purposes, don't use it for app logic.
420 * This event will be emitted before state changes have been applied.
421 */
422 __unsafe_action__: {
423 data: {
424 /**
425 * The action object which was dispatched.
426 */
427 action: NavigationAction;
428 /**
429 * Whether the action was a no-op, i.e. resulted any state changes.
430 */
431 noop: boolean;
432 /**
433 * Stack trace of the action, this will only be available during development.
434 */
435 stack: string | undefined;
436 };
437 };
438};
439export type NavigationContainerRef<ParamList extends {}> = NavigationHelpers<ParamList> & EventConsumer<NavigationContainerEventMap> & {
440 /**
441 * Reset the navigation state of the root navigator to the provided state.
442 *
443 * @param state Navigation state object.
444 */
445 resetRoot(state?: PartialState<NavigationState> | NavigationState): void;
446 /**
447 * Get the rehydrated navigation state of the navigation tree.
448 */
449 getRootState(): NavigationState;
450 /**
451 * Get the currently focused navigation route.
452 */
453 getCurrentRoute(): Route<string> | undefined;
454 /**
455 * Get the currently focused route's options.
456 */
457 getCurrentOptions(): object | undefined;
458 /**
459 * Whether the navigation container is ready to handle actions.
460 */
461 isReady(): boolean;
462};
463export type NavigationContainerRefWithCurrent<ParamList extends {}> = NavigationContainerRef<ParamList> & {
464 current: NavigationContainerRef<ParamList> | null;
465};
466export type TypedNavigator<ParamList extends ParamListBase, State extends NavigationState, ScreenOptions extends {}, EventMap extends EventMapBase, Navigator extends React.ComponentType<any>> = {
467 /**
468 * Navigator component which manages the child screens.
469 */
470 Navigator: React.ComponentType<Omit<React.ComponentProps<Navigator>, keyof DefaultNavigatorOptions<any, any, any, any>> & DefaultNavigatorOptions<ParamList, State, ScreenOptions, EventMap>>;
471 /**
472 * Component used for grouping multiple route configuration.
473 */
474 Group: React.ComponentType<RouteGroupConfig<ParamList, ScreenOptions>>;
475 /**
476 * Component used for specifying route configuration.
477 */
478 Screen: <RouteName extends keyof ParamList>(_: RouteConfig<ParamList, RouteName, State, ScreenOptions, EventMap>) => null;
479};
480export type NavigatorScreenParams<ParamList, State extends NavigationState = NavigationState> = {
481 screen?: never;
482 params?: never;
483 initial?: never;
484 path?: string;
485 state: PartialState<State> | State | undefined;
486} | {
487 [RouteName in keyof ParamList]: undefined extends ParamList[RouteName] ? {
488 screen: RouteName;
489 params?: ParamList[RouteName];
490 initial?: boolean;
491 path?: string;
492 state?: never;
493 } : {
494 screen: RouteName;
495 params: ParamList[RouteName];
496 initial?: boolean;
497 path?: string;
498 state?: never;
499 };
500}[keyof ParamList];
501export type PathConfig<ParamList extends {}> = {
502 path?: string;
503 exact?: boolean;
504 parse?: Record<string, (value: string) => any>;
505 stringify?: Record<string, (value: any) => string>;
506 screens?: PathConfigMap<ParamList>;
507 initialRouteName?: keyof ParamList;
508};
509export type PathConfigMap<ParamList extends {}> = {
510 [RouteName in keyof ParamList]?: NonNullable<ParamList[RouteName]> extends NavigatorScreenParams<infer T extends {}> ? string | PathConfig<T> : string | Omit<PathConfig<{}>, 'screens' | 'initialRouteName'>;
511};
512export {};
513//# sourceMappingURL=types.d.ts.map
\No newline at end of file