Add ScopedHistory to AppMountParams (#56705)

docs/development/core/public/kibana-plugin-public.app.md

@@ -9,7 +9,7 @@ Extension of [common app properties](./kibana-plugin-public.appbase.md) with the
 <b>Signature:</b>
 
 ```typescript
-export interface App extends AppBase 
+export interface App<HistoryLocationState = unknown> extends AppBase 
 ```
 
 ## Properties
@@ -18,5 +18,5 @@ export interface App extends AppBase
 |  --- | --- | --- |
 |  [appRoute](./kibana-plugin-public.app.approute.md) | <code>string</code> | Override the application's routing path from <code>/app/${id}</code>. Must be unique across registered applications. Should not include the base path from HTTP. |
 |  [chromeless](./kibana-plugin-public.app.chromeless.md) | <code>boolean</code> | Hide the UI chrome when the application is mounted. Defaults to <code>false</code>. Takes precedence over chrome service visibility settings. |
-|  [mount](./kibana-plugin-public.app.mount.md) | <code>AppMount &#124; AppMountDeprecated</code> | A mount function called when the user navigates to this app's route. May have signature of [AppMount](./kibana-plugin-public.appmount.md) or [AppMountDeprecated](./kibana-plugin-public.appmountdeprecated.md)<!-- -->. |
+|  [mount](./kibana-plugin-public.app.mount.md) | <code>AppMount&lt;HistoryLocationState&gt; &#124; AppMountDeprecated&lt;HistoryLocationState&gt;</code> | A mount function called when the user navigates to this app's route. May have signature of [AppMount](./kibana-plugin-public.appmount.md) or [AppMountDeprecated](./kibana-plugin-public.appmountdeprecated.md)<!-- -->. |
 

docs/development/core/public/kibana-plugin-public.app.mount.md

@@ -9,7 +9,7 @@ A mount function called when the user navigates to this app's route. May have si
 <b>Signature:</b>
 
 ```typescript
-mount: AppMount | AppMountDeprecated;
+mount: AppMount<HistoryLocationState> | AppMountDeprecated<HistoryLocationState>;
 ```
 
 ## Remarks

docs/development/core/public/kibana-plugin-public.applicationsetup.register.md

@@ -9,14 +9,14 @@ Register an mountable application to the system.
 <b>Signature:</b>
 
 ```typescript
-register(app: App): void;
+register<HistoryLocationState = unknown>(app: App<HistoryLocationState>): void;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  app | <code>App</code> | an [App](./kibana-plugin-public.app.md) |
+|  app | <code>App&lt;HistoryLocationState&gt;</code> | an [App](./kibana-plugin-public.app.md) |
 
 <b>Returns:</b>
 

docs/development/core/public/kibana-plugin-public.appmount.md

@@ -9,5 +9,5 @@ A mount function called when the user navigates to this app's route.
 <b>Signature:</b>
 
 ```typescript
-export declare type AppMount = (params: AppMountParameters) => AppUnmount | Promise<AppUnmount>;
+export declare type AppMount<HistoryLocationState = unknown> = (params: AppMountParameters<HistoryLocationState>) => AppUnmount | Promise<AppUnmount>;
 ```

docs/development/core/public/kibana-plugin-public.appmountdeprecated.md

@@ -13,7 +13,7 @@ A mount function called when the user navigates to this app's route.
 <b>Signature:</b>
 
 ```typescript
-export declare type AppMountDeprecated = (context: AppMountContext, params: AppMountParameters) => AppUnmount | Promise<AppUnmount>;
+export declare type AppMountDeprecated<HistoryLocationState = unknown> = (context: AppMountContext, params: AppMountParameters<HistoryLocationState>) => AppUnmount | Promise<AppUnmount>;
 ```
 
 ## Remarks

docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md

@@ -4,6 +4,11 @@
 
 ## AppMountParameters.appBasePath property
 
+> Warning: This API is now obsolete.
+> 
+> Use [AppMountParameters.history](./kibana-plugin-public.appmountparameters.history.md) instead.
+> 
+
 The route path for configuring navigation to the application. This string should not include the base path from HTTP.
 
 <b>Signature:</b>
@@ -39,10 +44,10 @@ import React from 'react';
 import ReactDOM from 'react-dom';
 import { BrowserRouter, Route } from 'react-router-dom';
 
-import { CoreStart, AppMountParams } from 'src/core/public';
+import { CoreStart, AppMountParameters } from 'src/core/public';
 import { MyPluginDepsStart } from './plugin';
 
-export renderApp = ({ appBasePath, element }: AppMountParams) => {
+export renderApp = ({ appBasePath, element }: AppMountParameters) => {
   ReactDOM.render(
     // pass `appBasePath` to `basename`
     <BrowserRouter basename={appBasePath}>

docs/development/core/public/kibana-plugin-public.appmountparameters.history.md

@@ -0,0 +1,58 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [AppMountParameters](./kibana-plugin-public.appmountparameters.md) &gt; [history](./kibana-plugin-public.appmountparameters.history.md)
+
+## AppMountParameters.history property
+
+A scoped history instance for your application. Should be used to wire up your applications Router.
+
+<b>Signature:</b>
+
+```typescript
+history: ScopedHistory<HistoryLocationState>;
+```
+
+## Example
+
+How to configure react-router with a base path:
+
+```ts
+// inside your plugin's setup function
+export class MyPlugin implements Plugin {
+  setup({ application }) {
+    application.register({
+     id: 'my-app',
+     appRoute: '/my-app',
+     async mount(params) {
+       const { renderApp } = await import('./application');
+       return renderApp(params);
+     },
+   });
+ }
+}
+
+```
+
+```ts
+// application.tsx
+import React from 'react';
+import ReactDOM from 'react-dom';
+import { Router, Route } from 'react-router-dom';
+
+import { CoreStart, AppMountParameters } from 'src/core/public';
+import { MyPluginDepsStart } from './plugin';
+
+export renderApp = ({ element, history }: AppMountParameters) => {
+  ReactDOM.render(
+    // pass `appBasePath` to `basename`
+    <Router history={history}>
+      <Route path="/" exact component={HomePage} />
+    </Router>,
+    element
+  );
+
+  return () => ReactDOM.unmountComponentAtNode(element);
+}
+
+```
+

docs/development/core/public/kibana-plugin-public.appmountparameters.md

@@ -8,7 +8,7 @@
 <b>Signature:</b>
 
 ```typescript
-export interface AppMountParameters 
+export interface AppMountParameters<HistoryLocationState = unknown> 
 ```
 
 ## Properties
@@ -17,5 +17,6 @@ export interface AppMountParameters
 |  --- | --- | --- |
 |  [appBasePath](./kibana-plugin-public.appmountparameters.appbasepath.md) | <code>string</code> | The route path for configuring navigation to the application. This string should not include the base path from HTTP. |
 |  [element](./kibana-plugin-public.appmountparameters.element.md) | <code>HTMLElement</code> | The container element to render the application into. |
+|  [history](./kibana-plugin-public.appmountparameters.history.md) | <code>ScopedHistory&lt;HistoryLocationState&gt;</code> | A scoped history instance for your application. Should be used to wire up your applications Router. |
 |  [onAppLeave](./kibana-plugin-public.appmountparameters.onappleave.md) | <code>(handler: AppLeaveHandler) =&gt; void</code> | A function that can be used to register a handler that will be called when the user is leaving the current application, allowing to prompt a confirmation message before actually changing the page.<!-- -->This will be called either when the user goes to another application, or when trying to close the tab or manually changing the url. |
 

docs/development/core/public/kibana-plugin-public.md

@@ -15,6 +15,7 @@ The plugin integrates with the core system via lifecycle events: `setup`<!-- -->
 |  Class | Description |
 |  --- | --- |
 |  [SavedObjectsClient](./kibana-plugin-public.savedobjectsclient.md) | Saved Objects is Kibana's data persisentence mechanism allowing plugins to use Elasticsearch for storing plugin state. The client-side SavedObjectsClient is a thin convenience library around the SavedObjects HTTP API for interacting with Saved Objects. |
+|  [ScopedHistory](./kibana-plugin-public.scopedhistory.md) | A wrapper around a <code>History</code> instance that is scoped to a particular base path of the history stack. Behaves similarly to the <code>basename</code> option except that this wrapper hides any history stack entries from outside the scope of this base path.<!-- -->This wrapper also allows Core and Plugins to share a single underlying global <code>History</code> instance without exposing the history of other applications.<!-- -->The [createSubHistory](./kibana-plugin-public.scopedhistory.createsubhistory.md) method is particularly useful for applications that contain any number of "sub-apps" which should not have access to the main application's history or basePath. |
 |  [SimpleSavedObject](./kibana-plugin-public.simplesavedobject.md) | This class is a very simple wrapper for SavedObjects loaded from the server with the [SavedObjectsClient](./kibana-plugin-public.savedobjectsclient.md)<!-- -->.<!-- -->It provides basic functionality for creating/saving/deleting saved objects, but doesn't include any type-specific implementations. |
 |  [ToastsApi](./kibana-plugin-public.toastsapi.md) | Methods for adding and removing global toast messages. |
 

docs/development/core/public/kibana-plugin-public.scopedhistory._constructor_.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [(constructor)](./kibana-plugin-public.scopedhistory._constructor_.md)
+
+## ScopedHistory.(constructor)
+
+Constructs a new instance of the `ScopedHistory` class
+
+<b>Signature:</b>
+
+```typescript
+constructor(parentHistory: History, basePath: string);
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  parentHistory | <code>History</code> |  |
+|  basePath | <code>string</code> |  |
+

docs/development/core/public/kibana-plugin-public.scopedhistory.action.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [action](./kibana-plugin-public.scopedhistory.action.md)
+
+## ScopedHistory.action property
+
+The last action dispatched on the history stack.
+
+<b>Signature:</b>
+
+```typescript
+get action(): Action;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.block.md

@@ -0,0 +1,18 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [block](./kibana-plugin-public.scopedhistory.block.md)
+
+## ScopedHistory.block property
+
+Not supported. Use [AppMountParameters.onAppLeave](./kibana-plugin-public.appmountparameters.onappleave.md)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+block: (prompt?: string | boolean | History.TransitionPromptHook<HistoryLocationState> | undefined) => UnregisterCallback;
+```
+
+## Remarks
+
+We prefer that applications use the `onAppLeave` API because it supports a more graceful experience that prefers a modal when possible, falling back to a confirm dialog box in the beforeunload case.
+

docs/development/core/public/kibana-plugin-public.scopedhistory.createhref.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [createHref](./kibana-plugin-public.scopedhistory.createhref.md)
+
+## ScopedHistory.createHref property
+
+Creates an href (string) to the location.
+
+<b>Signature:</b>
+
+```typescript
+createHref: (location: LocationDescriptorObject<HistoryLocationState>) => string;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.createsubhistory.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [createSubHistory](./kibana-plugin-public.scopedhistory.createsubhistory.md)
+
+## ScopedHistory.createSubHistory property
+
+Creates a `ScopedHistory` for a subpath of this `ScopedHistory`<!-- -->. Useful for applications that may have sub-apps that do not need access to the containing application's history.
+
+<b>Signature:</b>
+
+```typescript
+createSubHistory: <SubHistoryLocationState = unknown>(basePath: string) => ScopedHistory<SubHistoryLocationState>;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.go.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [go](./kibana-plugin-public.scopedhistory.go.md)
+
+## ScopedHistory.go property
+
+Send the user forward or backwards in the history stack.
+
+<b>Signature:</b>
+
+```typescript
+go: (n: number) => void;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.goback.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [goBack](./kibana-plugin-public.scopedhistory.goback.md)
+
+## ScopedHistory.goBack property
+
+Send the user one location back in the history stack. Equivalent to calling [ScopedHistory.go(-1)](./kibana-plugin-public.scopedhistory.go.md)<!-- -->. If no more entries are available backwards, this is a no-op.
+
+<b>Signature:</b>
+
+```typescript
+goBack: () => void;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.goforward.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [goForward](./kibana-plugin-public.scopedhistory.goforward.md)
+
+## ScopedHistory.goForward property
+
+Send the user one location forward in the history stack. Equivalent to calling [ScopedHistory.go(1)](./kibana-plugin-public.scopedhistory.go.md)<!-- -->. If no more entries are available forwards, this is a no-op.
+
+<b>Signature:</b>
+
+```typescript
+goForward: () => void;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.length.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [length](./kibana-plugin-public.scopedhistory.length.md)
+
+## ScopedHistory.length property
+
+The number of entries in the history stack, including all entries forwards and backwards from the current location.
+
+<b>Signature:</b>
+
+```typescript
+get length(): number;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.listen.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [listen](./kibana-plugin-public.scopedhistory.listen.md)
+
+## ScopedHistory.listen property
+
+Adds a listener for location updates.
+
+<b>Signature:</b>
+
+```typescript
+listen: (listener: (location: Location<HistoryLocationState>, action: Action) => void) => UnregisterCallback;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.location.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [location](./kibana-plugin-public.scopedhistory.location.md)
+
+## ScopedHistory.location property
+
+The current location of the history stack.
+
+<b>Signature:</b>
+
+```typescript
+get location(): Location<HistoryLocationState>;
+```

docs/development/core/public/kibana-plugin-public.scopedhistory.md

@@ -0,0 +1,41 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md)
+
+## ScopedHistory class
+
+A wrapper around a `History` instance that is scoped to a particular base path of the history stack. Behaves similarly to the `basename` option except that this wrapper hides any history stack entries from outside the scope of this base path.
+
+This wrapper also allows Core and Plugins to share a single underlying global `History` instance without exposing the history of other applications.
+
+The [createSubHistory](./kibana-plugin-public.scopedhistory.createsubhistory.md) method is particularly useful for applications that contain any number of "sub-apps" which should not have access to the main application's history or basePath.
+
+<b>Signature:</b>
+
+```typescript
+export declare class ScopedHistory<HistoryLocationState = unknown> implements History<HistoryLocationState> 
+```
+
+## Constructors
+
+|  Constructor | Modifiers | Description |
+|  --- | --- | --- |
+|  [(constructor)(parentHistory, basePath)](./kibana-plugin-public.scopedhistory._constructor_.md) |  | Constructs a new instance of the <code>ScopedHistory</code> class |
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [action](./kibana-plugin-public.scopedhistory.action.md) |  | <code>Action</code> | The last action dispatched on the history stack. |
+|  [block](./kibana-plugin-public.scopedhistory.block.md) |  | <code>(prompt?: string &#124; boolean &#124; History.TransitionPromptHook&lt;HistoryLocationState&gt; &#124; undefined) =&gt; UnregisterCallback</code> | Not supported. Use [AppMountParameters.onAppLeave](./kibana-plugin-public.appmountparameters.onappleave.md)<!-- -->. |
+|  [createHref](./kibana-plugin-public.scopedhistory.createhref.md) |  | <code>(location: LocationDescriptorObject&lt;HistoryLocationState&gt;) =&gt; string</code> | Creates an href (string) to the location. |
+|  [createSubHistory](./kibana-plugin-public.scopedhistory.createsubhistory.md) |  | <code>&lt;SubHistoryLocationState = unknown&gt;(basePath: string) =&gt; ScopedHistory&lt;SubHistoryLocationState&gt;</code> | Creates a <code>ScopedHistory</code> for a subpath of this <code>ScopedHistory</code>. Useful for applications that may have sub-apps that do not need access to the containing application's history. |
+|  [go](./kibana-plugin-public.scopedhistory.go.md) |  | <code>(n: number) =&gt; void</code> | Send the user forward or backwards in the history stack. |
+|  [goBack](./kibana-plugin-public.scopedhistory.goback.md) |  | <code>() =&gt; void</code> | Send the user one location back in the history stack. Equivalent to calling [ScopedHistory.go(-1)](./kibana-plugin-public.scopedhistory.go.md)<!-- -->. If no more entries are available backwards, this is a no-op. |
+|  [goForward](./kibana-plugin-public.scopedhistory.goforward.md) |  | <code>() =&gt; void</code> | Send the user one location forward in the history stack. Equivalent to calling [ScopedHistory.go(1)](./kibana-plugin-public.scopedhistory.go.md)<!-- -->. If no more entries are available forwards, this is a no-op. |
+|  [length](./kibana-plugin-public.scopedhistory.length.md) |  | <code>number</code> | The number of entries in the history stack, including all entries forwards and backwards from the current location. |
+|  [listen](./kibana-plugin-public.scopedhistory.listen.md) |  | <code>(listener: (location: Location&lt;HistoryLocationState&gt;, action: Action) =&gt; void) =&gt; UnregisterCallback</code> | Adds a listener for location updates. |
+|  [location](./kibana-plugin-public.scopedhistory.location.md) |  | <code>Location&lt;HistoryLocationState&gt;</code> | The current location of the history stack. |
+|  [push](./kibana-plugin-public.scopedhistory.push.md) |  | <code>(pathOrLocation: string &#124; LocationDescriptorObject&lt;HistoryLocationState&gt;, state?: HistoryLocationState &#124; undefined) =&gt; void</code> | Pushes a new location onto the history stack. If there are forward entries in the stack, they will be removed. |
+|  [replace](./kibana-plugin-public.scopedhistory.replace.md) |  | <code>(pathOrLocation: string &#124; LocationDescriptorObject&lt;HistoryLocationState&gt;, state?: HistoryLocationState &#124; undefined) =&gt; void</code> | Replaces the current location in the history stack. Does not remove forward or backward entries. |
+

docs/development/core/public/kibana-plugin-public.scopedhistory.push.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ScopedHistory](./kibana-plugin-public.scopedhistory.md) &gt; [push](./kibana-plugin-public.scopedhistory.push.md)
+
+## ScopedHistory.push property
+
+Pushes a new location onto the history stack. If there are forward entries in the stack, they will be removed.
+
+<b>Signature:</b>
+
+```typescript
+push: (pathOrLocation: string | LocationDescriptorObject<HistoryLocationState>, state?: HistoryLocationState | undefined) => void;
+```