From 95bacb367fed7b94158a18b352ed433ce006ec41 Mon Sep 17 00:00:00 2001 From: Josh Dover Date: Wed, 26 Feb 2020 12:43:12 -0700 Subject: [PATCH] Add ScopedHistory to AppMountParams (#56705) --- .../core/public/kibana-plugin-public.app.md | 4 +- .../public/kibana-plugin-public.app.mount.md | 2 +- ...plugin-public.applicationsetup.register.md | 4 +- .../public/kibana-plugin-public.appmount.md | 2 +- ...kibana-plugin-public.appmountdeprecated.md | 2 +- ...n-public.appmountparameters.appbasepath.md | 9 +- ...lugin-public.appmountparameters.history.md | 58 +++ ...kibana-plugin-public.appmountparameters.md | 3 +- .../core/public/kibana-plugin-public.md | 1 + ...ugin-public.scopedhistory._constructor_.md | 21 ++ ...bana-plugin-public.scopedhistory.action.md | 13 + ...ibana-plugin-public.scopedhistory.block.md | 18 + ...-plugin-public.scopedhistory.createhref.md | 13 + ...n-public.scopedhistory.createsubhistory.md | 13 + .../kibana-plugin-public.scopedhistory.go.md | 13 + ...bana-plugin-public.scopedhistory.goback.md | 13 + ...a-plugin-public.scopedhistory.goforward.md | 13 + ...bana-plugin-public.scopedhistory.length.md | 13 + ...bana-plugin-public.scopedhistory.listen.md | 13 + ...na-plugin-public.scopedhistory.location.md | 13 + .../kibana-plugin-public.scopedhistory.md | 41 +++ ...kibana-plugin-public.scopedhistory.push.md | 13 + ...ana-plugin-public.scopedhistory.replace.md | 13 + .../application/application_service.test.ts | 30 ++ .../application/application_service.tsx | 17 +- src/core/public/application/index.ts | 1 + .../integration_tests/router.test.tsx | 136 ++++++-- .../application/integration_tests/utils.tsx | 22 +- .../public/application/scoped_history.mock.ts | 57 +++ .../public/application/scoped_history.test.ts | 329 ++++++++++++++++++ src/core/public/application/scoped_history.ts | 318 +++++++++++++++++ src/core/public/application/types.ts | 76 +++- .../application/ui/app_container.test.tsx | 7 + .../public/application/ui/app_container.tsx | 9 +- src/core/public/application/ui/app_router.tsx | 22 +- src/core/public/index.ts | 1 + src/core/public/mocks.ts | 1 + src/core/public/public.api.md | 36 +- .../local_application_service.ts | 8 +- .../new_platform/new_platform.test.mocks.ts | 7 + .../public/new_platform/new_platform.test.ts | 6 +- .../ui/public/new_platform/new_platform.ts | 19 +- src/plugins/dev_tools/public/application.tsx | 8 +- .../core_plugin_a/public/application.tsx | 14 +- .../core_plugin_b/public/application.tsx | 14 +- .../plugins/core_plugin_legacy/index.ts | 1 + .../plugins/legacy_plugin/index.ts | 34 ++ .../plugins/legacy_plugin/package.json | 17 + .../plugins/legacy_plugin/public/index.tsx | 35 ++ .../plugins/legacy_plugin/tsconfig.json | 15 + .../core_plugins/application_leave_confirm.ts | 2 +- .../test_suites/core_plugins/applications.ts | 28 +- .../core_plugins/legacy_plugins.ts | 2 +- .../test_suites/core_plugins/rendering.ts | 8 +- .../public/legacy.ts | 4 +- .../public/register_route.ts | 4 +- x-pack/legacy/plugins/ml/public/plugin.ts | 1 + .../plugins/uptime/public/apps/plugin.ts | 1 - 58 files changed, 1479 insertions(+), 119 deletions(-) create mode 100644 docs/development/core/public/kibana-plugin-public.appmountparameters.history.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory._constructor_.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.action.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.block.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.createhref.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.createsubhistory.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.go.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.goback.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.goforward.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.length.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.listen.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.location.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.push.md create mode 100644 docs/development/core/public/kibana-plugin-public.scopedhistory.replace.md create mode 100644 src/core/public/application/scoped_history.mock.ts create mode 100644 src/core/public/application/scoped_history.test.ts create mode 100644 src/core/public/application/scoped_history.ts create mode 100644 test/plugin_functional/plugins/legacy_plugin/index.ts create mode 100644 test/plugin_functional/plugins/legacy_plugin/package.json create mode 100644 test/plugin_functional/plugins/legacy_plugin/public/index.tsx create mode 100644 test/plugin_functional/plugins/legacy_plugin/tsconfig.json diff --git a/docs/development/core/public/kibana-plugin-public.app.md b/docs/development/core/public/kibana-plugin-public.app.md index faea94c467726..f31db3674f5ba 100644 --- a/docs/development/core/public/kibana-plugin-public.app.md +++ b/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 Signature: ```typescript -export interface App extends AppBase +export interface App extends AppBase ``` ## Properties @@ -18,5 +18,5 @@ export interface App extends AppBase | --- | --- | --- | | [appRoute](./kibana-plugin-public.app.approute.md) | string | Override the application's routing path from /app/${id}. Must be unique across registered applications. Should not include the base path from HTTP. | | [chromeless](./kibana-plugin-public.app.chromeless.md) | boolean | Hide the UI chrome when the application is mounted. Defaults to false. Takes precedence over chrome service visibility settings. | -| [mount](./kibana-plugin-public.app.mount.md) | AppMount | AppMountDeprecated | 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) | AppMount<HistoryLocationState> | AppMountDeprecated<HistoryLocationState> | 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). | diff --git a/docs/development/core/public/kibana-plugin-public.app.mount.md b/docs/development/core/public/kibana-plugin-public.app.mount.md index 2af5f0277759a..4829307ff267c 100644 --- a/docs/development/core/public/kibana-plugin-public.app.mount.md +++ b/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 Signature: ```typescript -mount: AppMount | AppMountDeprecated; +mount: AppMount | AppMountDeprecated; ``` ## Remarks diff --git a/docs/development/core/public/kibana-plugin-public.applicationsetup.register.md b/docs/development/core/public/kibana-plugin-public.applicationsetup.register.md index 5c6c7cd252b0a..27c3e28c05a0d 100644 --- a/docs/development/core/public/kibana-plugin-public.applicationsetup.register.md +++ b/docs/development/core/public/kibana-plugin-public.applicationsetup.register.md @@ -9,14 +9,14 @@ Register an mountable application to the system. Signature: ```typescript -register(app: App): void; +register(app: App): void; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| app | App | an [App](./kibana-plugin-public.app.md) | +| app | App<HistoryLocationState> | an [App](./kibana-plugin-public.app.md) | Returns: diff --git a/docs/development/core/public/kibana-plugin-public.appmount.md b/docs/development/core/public/kibana-plugin-public.appmount.md index 84a52b09a119c..a001b1f75c99e 100644 --- a/docs/development/core/public/kibana-plugin-public.appmount.md +++ 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. Signature: ```typescript -export declare type AppMount = (params: AppMountParameters) => AppUnmount | Promise; +export declare type AppMount = (params: AppMountParameters) => AppUnmount | Promise; ``` diff --git a/docs/development/core/public/kibana-plugin-public.appmountdeprecated.md b/docs/development/core/public/kibana-plugin-public.appmountdeprecated.md index 8c8114182b60f..2bd2e956124c0 100644 --- a/docs/development/core/public/kibana-plugin-public.appmountdeprecated.md +++ b/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. Signature: ```typescript -export declare type AppMountDeprecated = (context: AppMountContext, params: AppMountParameters) => AppUnmount | Promise; +export declare type AppMountDeprecated = (context: AppMountContext, params: AppMountParameters) => AppUnmount | Promise; ``` ## Remarks diff --git a/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md b/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md index 041d976aa42a2..beedda98d8f4d 100644 --- a/docs/development/core/public/kibana-plugin-public.appmountparameters.appbasepath.md +++ b/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. Signature: @@ -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` diff --git a/docs/development/core/public/kibana-plugin-public.appmountparameters.history.md b/docs/development/core/public/kibana-plugin-public.appmountparameters.history.md new file mode 100644 index 0000000000000..9a3fa1a1bb48a --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.appmountparameters.history.md @@ -0,0 +1,58 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [AppMountParameters](./kibana-plugin-public.appmountparameters.md) > [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. + +Signature: + +```typescript +history: ScopedHistory; +``` + +## 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` + + + , + element + ); + + return () => ReactDOM.unmountComponentAtNode(element); +} + +``` + diff --git a/docs/development/core/public/kibana-plugin-public.appmountparameters.md b/docs/development/core/public/kibana-plugin-public.appmountparameters.md index c21889c28bda4..e652379fc3034 100644 --- a/docs/development/core/public/kibana-plugin-public.appmountparameters.md +++ b/docs/development/core/public/kibana-plugin-public.appmountparameters.md @@ -8,7 +8,7 @@ Signature: ```typescript -export interface AppMountParameters +export interface AppMountParameters ``` ## Properties @@ -17,5 +17,6 @@ export interface AppMountParameters | --- | --- | --- | | [appBasePath](./kibana-plugin-public.appmountparameters.appbasepath.md) | string | 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) | HTMLElement | The container element to render the application into. | +| [history](./kibana-plugin-public.appmountparameters.history.md) | ScopedHistory<HistoryLocationState> | A scoped history instance for your application. Should be used to wire up your applications Router. | | [onAppLeave](./kibana-plugin-public.appmountparameters.onappleave.md) | (handler: AppLeaveHandler) => void | 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. | diff --git a/docs/development/core/public/kibana-plugin-public.md b/docs/development/core/public/kibana-plugin-public.md index 95a4327728139..79bdb11b80fa4 100644 --- a/docs/development/core/public/kibana-plugin-public.md +++ b/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 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. | | [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. | diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory._constructor_.md b/docs/development/core/public/kibana-plugin-public.scopedhistory._constructor_.md new file mode 100644 index 0000000000000..d21c908890b6b --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory._constructor_.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [(constructor)](./kibana-plugin-public.scopedhistory._constructor_.md) + +## ScopedHistory.(constructor) + +Constructs a new instance of the `ScopedHistory` class + +Signature: + +```typescript +constructor(parentHistory: History, basePath: string); +``` + +## Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| parentHistory | History | | +| basePath | string | | + diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.action.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.action.md new file mode 100644 index 0000000000000..c3b52b9041871 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.action.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [action](./kibana-plugin-public.scopedhistory.action.md) + +## ScopedHistory.action property + +The last action dispatched on the history stack. + +Signature: + +```typescript +get action(): Action; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.block.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.block.md new file mode 100644 index 0000000000000..b6c5da58d4684 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.block.md @@ -0,0 +1,18 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [block](./kibana-plugin-public.scopedhistory.block.md) + +## ScopedHistory.block property + +Not supported. Use [AppMountParameters.onAppLeave](./kibana-plugin-public.appmountparameters.onappleave.md). + +Signature: + +```typescript +block: (prompt?: string | boolean | History.TransitionPromptHook | 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. + diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.createhref.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.createhref.md new file mode 100644 index 0000000000000..6bbd78dc9b3c9 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.createhref.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [createHref](./kibana-plugin-public.scopedhistory.createhref.md) + +## ScopedHistory.createHref property + +Creates an href (string) to the location. + +Signature: + +```typescript +createHref: (location: LocationDescriptorObject) => string; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.createsubhistory.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.createsubhistory.md new file mode 100644 index 0000000000000..045289c98e4ee --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.createsubhistory.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [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. + +Signature: + +```typescript +createSubHistory: (basePath: string) => ScopedHistory; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.go.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.go.md new file mode 100644 index 0000000000000..b9d124d06a109 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.go.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [go](./kibana-plugin-public.scopedhistory.go.md) + +## ScopedHistory.go property + +Send the user forward or backwards in the history stack. + +Signature: + +```typescript +go: (n: number) => void; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.goback.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.goback.md new file mode 100644 index 0000000000000..8f1d4b25ebcbf --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.goback.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [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. + +Signature: + +```typescript +goBack: () => void; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.goforward.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.goforward.md new file mode 100644 index 0000000000000..587d5035bb5b5 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.goforward.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [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. + +Signature: + +```typescript +goForward: () => void; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.length.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.length.md new file mode 100644 index 0000000000000..8a8d6accc1fbc --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.length.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [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. + +Signature: + +```typescript +get length(): number; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.listen.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.listen.md new file mode 100644 index 0000000000000..a0693e5a0428d --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.listen.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [listen](./kibana-plugin-public.scopedhistory.listen.md) + +## ScopedHistory.listen property + +Adds a listener for location updates. + +Signature: + +```typescript +listen: (listener: (location: Location, action: Action) => void) => UnregisterCallback; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.location.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.location.md new file mode 100644 index 0000000000000..c40f73333ec7d --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.location.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [location](./kibana-plugin-public.scopedhistory.location.md) + +## ScopedHistory.location property + +The current location of the history stack. + +Signature: + +```typescript +get location(): Location; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.md new file mode 100644 index 0000000000000..5b429c1e6ec9e --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.md @@ -0,0 +1,41 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [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. + +Signature: + +```typescript +export declare class ScopedHistory implements History +``` + +## Constructors + +| Constructor | Modifiers | Description | +| --- | --- | --- | +| [(constructor)(parentHistory, basePath)](./kibana-plugin-public.scopedhistory._constructor_.md) | | Constructs a new instance of the ScopedHistory class | + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [action](./kibana-plugin-public.scopedhistory.action.md) | | Action | The last action dispatched on the history stack. | +| [block](./kibana-plugin-public.scopedhistory.block.md) | | (prompt?: string | boolean | History.TransitionPromptHook<HistoryLocationState> | undefined) => UnregisterCallback | Not supported. Use [AppMountParameters.onAppLeave](./kibana-plugin-public.appmountparameters.onappleave.md). | +| [createHref](./kibana-plugin-public.scopedhistory.createhref.md) | | (location: LocationDescriptorObject<HistoryLocationState>) => string | Creates an href (string) to the location. | +| [createSubHistory](./kibana-plugin-public.scopedhistory.createsubhistory.md) | | <SubHistoryLocationState = unknown>(basePath: string) => ScopedHistory<SubHistoryLocationState> | 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. | +| [go](./kibana-plugin-public.scopedhistory.go.md) | | (n: number) => void | Send the user forward or backwards in the history stack. | +| [goBack](./kibana-plugin-public.scopedhistory.goback.md) | | () => void | 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) | | () => void | 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) | | number | 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) | | (listener: (location: Location<HistoryLocationState>, action: Action) => void) => UnregisterCallback | Adds a listener for location updates. | +| [location](./kibana-plugin-public.scopedhistory.location.md) | | Location<HistoryLocationState> | The current location of the history stack. | +| [push](./kibana-plugin-public.scopedhistory.push.md) | | (pathOrLocation: string | LocationDescriptorObject<HistoryLocationState>, state?: HistoryLocationState | undefined) => void | 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) | | (pathOrLocation: string | LocationDescriptorObject<HistoryLocationState>, state?: HistoryLocationState | undefined) => void | Replaces the current location in the history stack. Does not remove forward or backward entries. | + diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.push.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.push.md new file mode 100644 index 0000000000000..0d8d635d0f189 --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.push.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [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. + +Signature: + +```typescript +push: (pathOrLocation: string | LocationDescriptorObject, state?: HistoryLocationState | undefined) => void; +``` diff --git a/docs/development/core/public/kibana-plugin-public.scopedhistory.replace.md b/docs/development/core/public/kibana-plugin-public.scopedhistory.replace.md new file mode 100644 index 0000000000000..f9c1171d4217e --- /dev/null +++ b/docs/development/core/public/kibana-plugin-public.scopedhistory.replace.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [kibana-plugin-public](./kibana-plugin-public.md) > [ScopedHistory](./kibana-plugin-public.scopedhistory.md) > [replace](./kibana-plugin-public.scopedhistory.replace.md) + +## ScopedHistory.replace property + +Replaces the current location in the history stack. Does not remove forward or backward entries. + +Signature: + +```typescript +replace: (pathOrLocation: string | LocationDescriptorObject, state?: HistoryLocationState | undefined) => void; +``` diff --git a/src/core/public/application/application_service.test.ts b/src/core/public/application/application_service.test.ts index 5487ca53170dd..c25918c6b7328 100644 --- a/src/core/public/application/application_service.test.ts +++ b/src/core/public/application/application_service.test.ts @@ -588,6 +588,16 @@ describe('#start()', () => { expect(getUrlForApp('app1', { path: 'deep/link///' })).toBe('/base-path/app/app1/deep/link'); }); + it('does not append trailing slash if hash is provided in path parameter', async () => { + service.setup(setupDeps); + const { getUrlForApp } = await service.start(startDeps); + + expect(getUrlForApp('app1', { path: '#basic-hash' })).toBe('/base-path/app/app1#basic-hash'); + expect(getUrlForApp('app1', { path: '#/hash/router/path' })).toBe( + '/base-path/app/app1#/hash/router/path' + ); + }); + it('creates absolute URLs when `absolute` parameter is true', async () => { service.setup(setupDeps); const { getUrlForApp } = await service.start(startDeps); @@ -646,6 +656,26 @@ describe('#start()', () => { ); }); + it('appends a path if specified with hash', async () => { + const { register } = service.setup(setupDeps); + + register(Symbol(), createApp({ id: 'app2', appRoute: '/custom/path' })); + + const { navigateToApp } = await service.start(startDeps); + + await navigateToApp('myTestApp', { path: '#basic-hash' }); + expect(MockHistory.push).toHaveBeenCalledWith('/app/myTestApp#basic-hash', undefined); + + await navigateToApp('myTestApp', { path: '#/hash/router/path' }); + expect(MockHistory.push).toHaveBeenCalledWith('/app/myTestApp#/hash/router/path', undefined); + + await navigateToApp('app2', { path: '#basic-hash' }); + expect(MockHistory.push).toHaveBeenCalledWith('/custom/path#basic-hash', undefined); + + await navigateToApp('app2', { path: '#/hash/router/path' }); + expect(MockHistory.push).toHaveBeenCalledWith('/custom/path#/hash/router/path', undefined); + }); + it('includes state if specified', async () => { const { register } = service.setup(setupDeps); diff --git a/src/core/public/application/application_service.tsx b/src/core/public/application/application_service.tsx index 77f06e316c0aa..1c9492d81c7f6 100644 --- a/src/core/public/application/application_service.tsx +++ b/src/core/public/application/application_service.tsx @@ -76,10 +76,19 @@ function filterAvailable(m: Map, capabilities: Capabilities) { } const findMounter = (mounters: Map, appRoute?: string) => [...mounters].find(([, mounter]) => mounter.appRoute === appRoute); -const getAppUrl = (mounters: Map, appId: string, path: string = '') => - `/${mounters.get(appId)?.appRoute ?? `/app/${appId}`}/${path}` + +const getAppUrl = (mounters: Map, appId: string, path: string = '') => { + const appBasePath = mounters.get(appId)?.appRoute + ? `/${mounters.get(appId)!.appRoute}` + : `/app/${appId}`; + + // Only preppend slash if not a hash or query path + path = path.startsWith('#') || path.startsWith('?') ? path : `/${path}`; + + return `${appBasePath}${path}` .replace(/\/{2,}/g, '/') // Remove duplicate slashes .replace(/\/$/, ''); // Remove trailing slash +}; const allApplicationsFilter = '__ALL__'; @@ -93,7 +102,7 @@ interface AppUpdaterWrapper { * @internal */ export class ApplicationService { - private readonly apps = new Map(); + private readonly apps = new Map | LegacyApp>(); private readonly mounters = new Map(); private readonly capabilities = new CapabilitiesService(); private readonly appLeaveHandlers = new Map(); @@ -143,7 +152,7 @@ export class ApplicationService { return { registerMountContext: this.mountContext!.registerContext, - register: (plugin, app) => { + register: (plugin, app: App) => { app = { appRoute: `/app/${app.id}`, ...app }; if (this.registrationClosed) { diff --git a/src/core/public/application/index.ts b/src/core/public/application/index.ts index e7ea330657648..ec10d2bc22871 100644 --- a/src/core/public/application/index.ts +++ b/src/core/public/application/index.ts @@ -19,6 +19,7 @@ export { ApplicationService } from './application_service'; export { Capabilities } from './capabilities'; +export { ScopedHistory } from './scoped_history'; export { App, AppBase, diff --git a/src/core/public/application/integration_tests/router.test.tsx b/src/core/public/application/integration_tests/router.test.tsx index 0c5f5a138d58f..2f26bc1409104 100644 --- a/src/core/public/application/integration_tests/router.test.tsx +++ b/src/core/public/application/integration_tests/router.test.tsx @@ -25,15 +25,17 @@ import { AppRouter, AppNotFound } from '../ui'; import { EitherApp, MockedMounterMap, MockedMounterTuple } from '../test_types'; import { createRenderer, createAppMounter, createLegacyAppMounter, getUnmounter } from './utils'; import { AppStatus } from '../types'; +import { ScopedHistory } from '../scoped_history'; describe('AppContainer', () => { let mounters: MockedMounterMap; - let history: History; + let globalHistory: History; let appStatuses$: BehaviorSubject>; let update: ReturnType; + let scopedAppHistory: History; const navigate = (path: string) => { - history.push(path); + globalHistory.push(path); return update(); }; const mockMountersToMounters = () => @@ -53,20 +55,35 @@ describe('AppContainer', () => { beforeEach(() => { mounters = new Map([ - createAppMounter('app1', 'App 1'), + createAppMounter({ appId: 'app1', html: 'App 1' }), createLegacyAppMounter('legacyApp1', jest.fn()), - createAppMounter('app2', '
App 2
'), + createAppMounter({ appId: 'app2', html: '
App 2
' }), createLegacyAppMounter('baseApp:legacyApp2', jest.fn()), - createAppMounter('app3', '
Chromeless A
', '/chromeless-a/path'), - createAppMounter('app4', '
Chromeless B
', '/chromeless-b/path'), - createAppMounter('disabledApp', '
Disabled app
'), + createAppMounter({ + appId: 'app3', + html: '
Chromeless A
', + appRoute: '/chromeless-a/path', + }), + createAppMounter({ + appId: 'app4', + html: '
Chromeless B
', + appRoute: '/chromeless-b/path', + }), + createAppMounter({ appId: 'disabledApp', html: '
Disabled app
' }), createLegacyAppMounter('disabledLegacyApp', jest.fn()), + createAppMounter({ + appId: 'scopedApp', + extraMountHook: ({ history }) => { + scopedAppHistory = history; + history.push('/subpath'); + }, + }), ] as Array>); - history = createMemoryHistory(); + globalHistory = createMemoryHistory(); appStatuses$ = mountersToAppStatus$(); update = createRenderer( { }); it('should not mount when partial route path matches', async () => { - mounters.set(...createAppMounter('spaces', '
Custom Space
', '/spaces/fake-login')); - mounters.set(...createAppMounter('login', '
Login Page
', '/fake-login')); - history = createMemoryHistory(); + mounters.set( + ...createAppMounter({ + appId: 'spaces', + html: '
Custom Space
', + appRoute: '/spaces/fake-login', + }) + ); + mounters.set( + ...createAppMounter({ + appId: 'login', + html: '
Login Page
', + appRoute: '/fake-login', + }) + ); + globalHistory = createMemoryHistory(); update = createRenderer( { }); it('should not mount when partial route path has higher specificity', async () => { - mounters.set(...createAppMounter('login', '
Login Page
', '/fake-login')); - mounters.set(...createAppMounter('spaces', '
Custom Space
', '/spaces/fake-login')); - history = createMemoryHistory(); + mounters.set( + ...createAppMounter({ + appId: 'login', + html: '
Login Page
', + appRoute: '/fake-login', + }) + ); + mounters.set( + ...createAppMounter({ + appId: 'spaces', + html: '
Custom Space
', + appRoute: '/spaces/fake-login', + }) + ); + globalHistory = createMemoryHistory(); update = createRenderer( { // Hitting back button within app does not trigger re-render await navigate('/app/app1/page2'); - history.goBack(); + globalHistory.goBack(); await update(); expect(mounter.mount).toHaveBeenCalledTimes(1); expect(unmount).not.toHaveBeenCalled(); }); it('should not remount when when changing pages within app using hash history', async () => { - history = createHashHistory(); + globalHistory = createHashHistory(); update = createRenderer( { expect(unmount).toHaveBeenCalledTimes(1); }); + it('pushes global history changes to inner scoped history', async () => { + const scopedApp = mounters.get('scopedApp'); + await navigate('/app/scopedApp'); + + // Verify that internal app's redirect propagated + expect(scopedApp?.mounter.mount).toHaveBeenCalledTimes(1); + expect(scopedAppHistory.location.pathname).toEqual('/subpath'); + expect(globalHistory.location.pathname).toEqual('/app/scopedApp/subpath'); + + // Simulate user clicking on navlink again to return to app root + globalHistory.push('/app/scopedApp'); + // Should not call mount again + expect(scopedApp?.mounter.mount).toHaveBeenCalledTimes(1); + expect(scopedApp?.unmount).not.toHaveBeenCalled(); + // Inner scoped history should be synced + expect(scopedAppHistory.location.pathname).toEqual(''); + + // Make sure going back to subpath works + globalHistory.goBack(); + expect(scopedApp?.mounter.mount).toHaveBeenCalledTimes(1); + expect(scopedApp?.unmount).not.toHaveBeenCalled(); + expect(scopedAppHistory.location.pathname).toEqual('/subpath'); + expect(globalHistory.location.pathname).toEqual('/app/scopedApp/subpath'); + }); + it('calls legacy mount handler', async () => { await navigate('/app/legacyApp1'); - expect(mounters.get('legacyApp1')!.mounter.mount.mock.calls[0]).toMatchInlineSnapshot(` - Array [ - Object { - "appBasePath": "/app/legacyApp1", - "element":
, - "onAppLeave": [Function], - }, - ] - `); + expect(mounters.get('legacyApp1')!.mounter.mount.mock.calls[0][0]).toMatchObject({ + appBasePath: '/app/legacyApp1', + element: expect.any(HTMLDivElement), + onAppLeave: expect.any(Function), + history: expect.any(ScopedHistory), + }); }); it('handles legacy apps with subapps', async () => { await navigate('/app/baseApp'); - expect(mounters.get('baseApp:legacyApp2')!.mounter.mount.mock.calls[0]).toMatchInlineSnapshot(` - Array [ - Object { - "appBasePath": "/app/baseApp", - "element":
, - "onAppLeave": [Function], - }, - ] - `); + expect(mounters.get('baseApp:legacyApp2')!.mounter.mount.mock.calls[0][0]).toMatchObject({ + appBasePath: '/app/baseApp', + element: expect.any(HTMLDivElement), + onAppLeave: expect.any(Function), + history: expect.any(ScopedHistory), + }); }); it('displays error page if no app is found', async () => { diff --git a/src/core/public/application/integration_tests/utils.tsx b/src/core/public/application/integration_tests/utils.tsx index 4f34438fc822a..9092177da5ad4 100644 --- a/src/core/public/application/integration_tests/utils.tsx +++ b/src/core/public/application/integration_tests/utils.tsx @@ -40,11 +40,17 @@ export const createRenderer = (element: ReactElement | null): Renderer => { }); }; -export const createAppMounter = ( - appId: string, - html: string, - appRoute = `/app/${appId}` -): MockedMounterTuple => { +export const createAppMounter = ({ + appId, + html = `
App ${appId}
`, + appRoute = `/app/${appId}`, + extraMountHook, +}: { + appId: string; + html?: string; + appRoute?: string; + extraMountHook?: (params: AppMountParameters) => void; +}): MockedMounterTuple => { const unmount = jest.fn(); return [ appId, @@ -52,11 +58,15 @@ export const createAppMounter = ( mounter: { appRoute, appBasePath: appRoute, - mount: jest.fn(async ({ appBasePath: basename, element }: AppMountParameters) => { + mount: jest.fn(async (params: AppMountParameters) => { + const { appBasePath: basename, element } = params; Object.assign(element, { innerHTML: `
\nbasename: ${basename}\nhtml: ${html}\n
`, }); unmount.mockImplementation(() => Object.assign(element, { innerHTML: '' })); + if (extraMountHook) { + extraMountHook(params); + } return unmount; }), }, diff --git a/src/core/public/application/scoped_history.mock.ts b/src/core/public/application/scoped_history.mock.ts new file mode 100644 index 0000000000000..56de97e630bf0 --- /dev/null +++ b/src/core/public/application/scoped_history.mock.ts @@ -0,0 +1,57 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { Location } from 'history'; +import { ScopedHistory } from './scoped_history'; + +type ScopedHistoryMock = jest.Mocked>; +const createMock = ({ + pathname = '/', + search = '', + hash = '', + key, + state, +}: Partial = {}) => { + const mock: ScopedHistoryMock = { + block: jest.fn(), + createHref: jest.fn(), + createSubHistory: jest.fn(), + go: jest.fn(), + goBack: jest.fn(), + goForward: jest.fn(), + listen: jest.fn(), + push: jest.fn(), + replace: jest.fn(), + action: 'PUSH', + length: 1, + location: { + pathname, + search, + state, + hash, + key, + }, + }; + + return mock; +}; + +export const scopedHistoryMock = { + create: createMock, +}; diff --git a/src/core/public/application/scoped_history.test.ts b/src/core/public/application/scoped_history.test.ts new file mode 100644 index 0000000000000..c01eb50830516 --- /dev/null +++ b/src/core/public/application/scoped_history.test.ts @@ -0,0 +1,329 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { ScopedHistory } from './scoped_history'; +import { createMemoryHistory } from 'history'; + +describe('ScopedHistory', () => { + describe('construction', () => { + it('succeeds if current location matches basePath', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + expect(() => new ScopedHistory(gh, '/app/wow')).not.toThrow(); + gh.push('/app/wow/'); + expect(() => new ScopedHistory(gh, '/app/wow')).not.toThrow(); + gh.push('/app/wow/sub-page'); + expect(() => new ScopedHistory(gh, '/app/wow')).not.toThrow(); + }); + + it('fails if current location does not match basePath', () => { + const gh = createMemoryHistory(); + gh.push('/app/other'); + expect(() => new ScopedHistory(gh, '/app/wow')).toThrowErrorMatchingInlineSnapshot( + `"Browser location [/app/other] is not currently in expected basePath [/app/wow]"` + ); + }); + }); + + describe('navigation', () => { + it('supports push', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const pushSpy = jest.spyOn(gh, 'push'); + const h = new ScopedHistory(gh, '/app/wow'); + h.push('/new-page', { some: 'state' }); + expect(pushSpy).toHaveBeenCalledWith('/app/wow/new-page', { some: 'state' }); + expect(gh.length).toBe(3); // ['', '/app/wow', '/app/wow/new-page'] + expect(h.length).toBe(2); + }); + + it('supports unbound push', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const pushSpy = jest.spyOn(gh, 'push'); + const h = new ScopedHistory(gh, '/app/wow'); + const { push } = h; + push('/new-page', { some: 'state' }); + expect(pushSpy).toHaveBeenCalledWith('/app/wow/new-page', { some: 'state' }); + expect(gh.length).toBe(3); // ['', '/app/wow', '/app/wow/new-page'] + expect(h.length).toBe(2); + }); + + it('supports replace', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const replaceSpy = jest.spyOn(gh, 'replace'); + const h = new ScopedHistory(gh, '/app/wow'); // [''] + h.push('/first-page'); // ['', '/first-page'] + h.push('/second-page'); // ['', '/first-page', '/second-page'] + h.goBack(); // ['', '/first-page', '/second-page'] + h.replace('/first-page-replacement', { some: 'state' }); // ['', '/first-page-replacement', '/second-page'] + expect(replaceSpy).toHaveBeenCalledWith('/app/wow/first-page-replacement', { some: 'state' }); + expect(h.length).toBe(3); + expect(gh.length).toBe(4); // ['', '/app/wow', '/app/wow/first-page-replacement', '/app/wow/second-page'] + }); + + it('hides previous stack', () => { + const gh = createMemoryHistory(); + gh.push('/app/alpha'); + gh.push('/app/beta'); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + expect(h.length).toBe(1); + expect(h.location.pathname).toEqual(''); + }); + + it('cannot go back further than local stack', () => { + const gh = createMemoryHistory(); + gh.push('/app/alpha'); + gh.push('/app/beta'); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + h.push('/new-page'); + expect(h.length).toBe(2); + expect(h.location.pathname).toEqual('/new-page'); + + // Test first back + h.goBack(); + expect(h.length).toBe(2); + expect(h.location.pathname).toEqual(''); + expect(gh.location.pathname).toEqual('/app/wow'); + + // Second back should be no-op + h.goBack(); + expect(h.length).toBe(2); + expect(h.location.pathname).toEqual(''); + expect(gh.location.pathname).toEqual('/app/wow'); + }); + + it('cannot go forward further than local stack', () => { + const gh = createMemoryHistory(); + gh.push('/app/alpha'); + gh.push('/app/beta'); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + h.push('/new-page'); + expect(h.length).toBe(2); + + // Go back so we can go forward + h.goBack(); + expect(h.length).toBe(2); + expect(h.location.pathname).toEqual(''); + expect(gh.location.pathname).toEqual('/app/wow'); + + // Going forward should increase length and return to /new-page + h.goForward(); + expect(h.length).toBe(2); + expect(h.location.pathname).toEqual('/new-page'); + expect(gh.location.pathname).toEqual('/app/wow/new-page'); + + // Second forward should be no-op + h.goForward(); + expect(h.length).toBe(2); + expect(h.location.pathname).toEqual('/new-page'); + expect(gh.location.pathname).toEqual('/app/wow/new-page'); + }); + + it('reacts to navigations from parent history', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + h.push('/page-1'); + h.push('/page-2'); + + gh.goBack(); + expect(h.location.pathname).toEqual('/page-1'); + expect(h.length).toBe(3); + + gh.goForward(); + expect(h.location.pathname).toEqual('/page-2'); + expect(h.length).toBe(3); + + // Go back to /app/wow and push a new location + gh.goBack(); + gh.goBack(); + gh.push('/app/wow/page-3'); + expect(h.location.pathname).toEqual('/page-3'); + expect(h.length).toBe(2); // ['', '/page-3'] + }); + + it('increments length on push and removes length when going back and then pushing', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + expect(gh.length).toBe(2); + const h = new ScopedHistory(gh, '/app/wow'); + expect(h.length).toBe(1); + h.push('/page1'); + expect(h.length).toBe(2); + h.push('/page2'); + expect(h.length).toBe(3); + h.push('/page3'); + expect(h.length).toBe(4); + h.push('/page4'); + expect(h.length).toBe(5); + h.push('/page5'); + expect(h.length).toBe(6); + h.goBack(); // back/forward should not reduce the length + expect(h.length).toBe(6); + h.goBack(); + expect(h.length).toBe(6); + h.push('/page6'); // length should only change if a new location is pushed from a point further back in the history + expect(h.length).toBe(5); + h.goBack(); + expect(h.length).toBe(5); + h.goBack(); + expect(h.length).toBe(5); + h.push('/page7'); + expect(h.length).toBe(4); + }); + }); + + describe('teardown behavior', () => { + it('throws exceptions after falling out of scope', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + expect(gh.length).toBe(2); + const h = new ScopedHistory(gh, '/app/wow'); + gh.push('/app/other'); + expect(() => h.location).toThrowErrorMatchingInlineSnapshot( + `"ScopedHistory instance has fell out of navigation scope for basePath: /app/wow"` + ); + expect(() => h.push('/new-page')).toThrow(); + expect(() => h.replace('/new-page')).toThrow(); + expect(() => h.goBack()).toThrow(); + expect(() => h.goForward()).toThrow(); + }); + }); + + describe('listen', () => { + it('calls callback with scoped location', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + const listenPaths: string[] = []; + h.listen(l => listenPaths.push(l.pathname)); + h.push('/first-page'); + h.push('/second-page'); + h.push('/third-page'); + h.go(-2); + h.goForward(); + expect(listenPaths).toEqual([ + '/first-page', + '/second-page', + '/third-page', + '/first-page', + '/second-page', + ]); + }); + + it('stops calling callback after unlisten is called', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + const listenPaths: string[] = []; + const unlisten = h.listen(l => listenPaths.push(l.pathname)); + h.push('/first-page'); + unlisten(); + h.push('/second-page'); + h.push('/third-page'); + h.go(-2); + h.goForward(); + expect(listenPaths).toEqual(['/first-page']); + }); + + it('stops calling callback after browser leaves scope', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + const listenPaths: string[] = []; + h.listen(l => listenPaths.push(l.pathname)); + h.push('/first-page'); + gh.push('/app/other'); + gh.push('/second-page'); + gh.push('/third-page'); + gh.go(-2); + gh.goForward(); + expect(listenPaths).toEqual(['/first-page']); + }); + }); + + describe('createHref', () => { + it('creates scoped hrefs', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const h = new ScopedHistory(gh, '/app/wow'); + expect(h.createHref({ pathname: '' })).toEqual(`/`); + expect(h.createHref({ pathname: '/new-page', search: '?alpha=true' })).toEqual( + `/new-page?alpha=true` + ); + }); + }); + + describe('action', () => { + it('provides last history action', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + gh.push('/alpha'); + gh.goBack(); + const h = new ScopedHistory(gh, '/app/wow'); + expect(h.action).toBe('POP'); + gh.push('/app/wow/page-1'); + expect(h.action).toBe('PUSH'); + h.replace('/page-2'); + expect(h.action).toBe('REPLACE'); + }); + }); + + describe('createSubHistory', () => { + it('supports push', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const ghPushSpy = jest.spyOn(gh, 'push'); + const h1 = new ScopedHistory(gh, '/app/wow'); + h1.push('/new-page'); + const h1PushSpy = jest.spyOn(h1, 'push'); + const h2 = h1.createSubHistory('/new-page'); + h2.push('/sub-page', { some: 'state' }); + expect(h1PushSpy).toHaveBeenCalledWith('/new-page/sub-page', { some: 'state' }); + expect(ghPushSpy).toHaveBeenCalledWith('/app/wow/new-page/sub-page', { some: 'state' }); + expect(h2.length).toBe(2); + expect(h1.length).toBe(3); + expect(gh.length).toBe(4); + }); + + it('supports replace', () => { + const gh = createMemoryHistory(); + gh.push('/app/wow'); + const ghReplaceSpy = jest.spyOn(gh, 'replace'); + const h1 = new ScopedHistory(gh, '/app/wow'); + h1.push('/new-page'); + const h1ReplaceSpy = jest.spyOn(h1, 'replace'); + const h2 = h1.createSubHistory('/new-page'); + h2.push('/sub-page'); + h2.replace('/other-sub-page', { some: 'state' }); + expect(h1ReplaceSpy).toHaveBeenCalledWith('/new-page/other-sub-page', { some: 'state' }); + expect(ghReplaceSpy).toHaveBeenCalledWith('/app/wow/new-page/other-sub-page', { + some: 'state', + }); + expect(h2.length).toBe(2); + expect(h1.length).toBe(3); + expect(gh.length).toBe(4); + }); + }); +}); diff --git a/src/core/public/application/scoped_history.ts b/src/core/public/application/scoped_history.ts new file mode 100644 index 0000000000000..c5febc7604feb --- /dev/null +++ b/src/core/public/application/scoped_history.ts @@ -0,0 +1,318 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { + History, + Path, + LocationDescriptorObject, + TransitionPromptHook, + UnregisterCallback, + LocationListener, + Location, + Href, + Action, +} from 'history'; + +/** + * 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 {@link ScopedHistory.createSubHistory | createSubHistory} 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. + * + * @public + */ +export class ScopedHistory + implements History { + /** + * Tracks whether or not the user has left this history's scope. All methods throw errors if called after scope has + * been left. + */ + private isActive = true; + /** + * All active listeners on this history instance. + */ + private listeners = new Set>(); + /** + * Array of the local history stack. Only stores {@link Location.key} to use tracking an index of the current + * position of the window in the history stack. + */ + private locationKeys: Array = []; + /** + * The key of the current position of the window in the history stack. + */ + private currentLocationKeyIndex: number = 0; + + constructor(private readonly parentHistory: History, private readonly basePath: string) { + const parentPath = this.parentHistory.location.pathname; + if (!parentPath.startsWith(basePath)) { + throw new Error( + `Browser location [${parentPath}] is not currently in expected basePath [${basePath}]` + ); + } + + this.locationKeys.push(this.parentHistory.location.key); + this.setupHistoryListener(); + } + + /** + * 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. + * + * @param basePath the URL path scope for the sub history + */ + public createSubHistory = ( + basePath: string + ): ScopedHistory => { + return new ScopedHistory(this, basePath); + }; + + /** + * The number of entries in the history stack, including all entries forwards and backwards from the current location. + */ + public get length() { + this.verifyActive(); + return this.locationKeys.length; + } + + /** + * The current location of the history stack. + */ + public get location() { + this.verifyActive(); + return this.stripBasePath(this.parentHistory.location); + } + + /** + * The last action dispatched on the history stack. + */ + public get action() { + this.verifyActive(); + return this.parentHistory.action; + } + + /** + * Pushes a new location onto the history stack. If there are forward entries in the stack, they will be removed. + * + * @param pathOrLocation a string or location descriptor + * @param state + */ + public push = ( + pathOrLocation: Path | LocationDescriptorObject, + state?: HistoryLocationState + ): void => { + this.verifyActive(); + if (typeof pathOrLocation === 'string') { + this.parentHistory.push(this.prependBasePath(pathOrLocation), state); + } else { + this.parentHistory.push(this.prependBasePath(pathOrLocation)); + } + }; + + /** + * Replaces the current location in the history stack. Does not remove forward or backward entries. + * + * @param pathOrLocation a string or location descriptor + * @param state + */ + public replace = ( + pathOrLocation: Path | LocationDescriptorObject, + state?: HistoryLocationState + ): void => { + this.verifyActive(); + if (typeof pathOrLocation === 'string') { + this.parentHistory.replace(this.prependBasePath(pathOrLocation), state); + } else { + this.parentHistory.replace(this.prependBasePath(pathOrLocation)); + } + }; + + /** + * Send the user forward or backwards in the history stack. + * + * @param n number of positions in the stack to go. Negative numbers indicate number of entries backward, positive + * numbers for forwards. If passed 0, the current location will be reloaded. If `n` exceeds the number of + * entries available, this is a no-op. + */ + public go = (n: number): void => { + this.verifyActive(); + if (n === 0) { + this.parentHistory.go(n); + } else if (n < 0) { + if (this.currentLocationKeyIndex + 1 + n >= 1) { + this.parentHistory.go(n); + } + } else if (n <= this.currentLocationKeyIndex + this.locationKeys.length - 1) { + this.parentHistory.go(n); + } + // no-op if no conditions above are met + }; + + /** + * Send the user one location back in the history stack. Equivalent to calling + * {@link ScopedHistory.go | ScopedHistory.go(-1)}. If no more entries are available backwards, this is a no-op. + */ + public goBack = () => { + this.verifyActive(); + this.go(-1); + }; + + /** + * Send the user one location forward in the history stack. Equivalent to calling + * {@link ScopedHistory.go | ScopedHistory.go(1)}. If no more entries are available forwards, this is a no-op. + */ + public goForward = () => { + this.verifyActive(); + this.go(1); + }; + + /** + * Not supported. Use {@link AppMountParameters.onAppLeave}. + * + * @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. + */ + public block = ( + prompt?: boolean | string | TransitionPromptHook + ): UnregisterCallback => { + throw new Error( + `history.block is not supported. Please use the AppMountParams.onAppLeave API.` + ); + }; + + /** + * Adds a listener for location updates. + * + * @param listener a function that receives location updates. + * @returns an function to unsubscribe the listener. + */ + public listen = ( + listener: (location: Location, action: Action) => void + ): UnregisterCallback => { + this.verifyActive(); + this.listeners.add(listener); + return () => { + this.listeners.delete(listener); + }; + }; + + /** + * Creates an href (string) to the location. + * + * @param location + */ + public createHref = (location: LocationDescriptorObject): Href => { + this.verifyActive(); + return this.parentHistory.createHref(location); + }; + + private prependBasePath(path: Path): Path; + private prependBasePath( + location: LocationDescriptorObject + ): LocationDescriptorObject; + /** + * Prepends the scoped base path to the Path or Location + */ + private prependBasePath( + pathOrLocation: Path | LocationDescriptorObject + ): Path | LocationDescriptorObject { + if (typeof pathOrLocation === 'string') { + return this.prependBasePathToString(pathOrLocation); + } else { + return { + ...pathOrLocation, + pathname: + pathOrLocation.pathname !== undefined + ? this.prependBasePathToString(pathOrLocation.pathname) + : undefined, + }; + } + } + + /** + * Prepends the base path to string. + */ + private prependBasePathToString(path: string): string { + path = path.startsWith('/') ? path.slice(1) : path; + return path.length ? `${this.basePath}/${path}` : this.basePath; + } + + /** + * Removes the base path from a location. + */ + private stripBasePath(location: Location): Location { + return { + ...location, + pathname: location.pathname.replace(new RegExp(`^${this.basePath}`), ''), + }; + } + + /** Called on each public method to ensure that we have not fallen out of scope yet. */ + private verifyActive() { + if (!this.isActive) { + throw new Error( + `ScopedHistory instance has fell out of navigation scope for basePath: ${this.basePath}` + ); + } + } + + /** + * Sets up the listener on the parent history instance used to follow navigation updates and track our internal + * state. Also forwards events to child listeners with the base path stripped from the location. + */ + private setupHistoryListener() { + const unlisten = this.parentHistory.listen((location, action) => { + // If the user navigates outside the scope of this basePath, tear it down. + if (!location.pathname.startsWith(this.basePath)) { + unlisten(); + this.isActive = false; + return; + } + + /** + * Track location keys using the same algorithm the browser uses internally. + * - On PUSH, remove all items that came after the current location and append the new location. + * - On POP, set the current location, but do not change the entries. + * - On REPLACE, override the location for the current index with the new location. + */ + if (action === 'PUSH') { + this.locationKeys = [ + ...this.locationKeys.slice(0, this.currentLocationKeyIndex + 1), + location.key, + ]; + this.currentLocationKeyIndex = this.locationKeys.indexOf(location.key); // should always be the last index + } else if (action === 'POP') { + this.currentLocationKeyIndex = this.locationKeys.indexOf(location.key); + } else if (action === 'REPLACE') { + this.locationKeys[this.currentLocationKeyIndex] = location.key; + } else { + throw new Error(`Unrecognized history action: ${action}`); + } + + [...this.listeners].forEach(listener => { + listener(this.stripBasePath(location), action); + }); + }); + } +} diff --git a/src/core/public/application/types.ts b/src/core/public/application/types.ts index 977bb7a52da22..facb818c60ff9 100644 --- a/src/core/public/application/types.ts +++ b/src/core/public/application/types.ts @@ -32,6 +32,7 @@ import { IUiSettingsClient } from '../ui_settings'; import { RecursiveReadonly } from '../../utils'; import { SavedObjectsStart } from '../saved_objects'; import { AppCategory } from '../../types'; +import { ScopedHistory } from './scoped_history'; /** @public */ export interface AppBase { @@ -199,7 +200,7 @@ export type AppUpdater = (app: AppBase) => Partial | undefin * Extension of {@link AppBase | common app properties} with the mount function. * @public */ -export interface App extends AppBase { +export interface App extends AppBase { /** * A mount function called when the user navigates to this app's route. May have signature of {@link AppMount} or * {@link AppMountDeprecated}. @@ -208,7 +209,7 @@ export interface App extends AppBase { * When function has two arguments, it will be called with a {@link AppMountContext | context} as the first argument. * This behavior is **deprecated**, and consumers should instead use {@link CoreSetup.getStartServices}. */ - mount: AppMount | AppMountDeprecated; + mount: AppMount | AppMountDeprecated; /** * Hide the UI chrome when the application is mounted. Defaults to `false`. @@ -240,7 +241,9 @@ export interface LegacyApp extends AppBase { * * @public */ -export type AppMount = (params: AppMountParameters) => AppUnmount | Promise; +export type AppMount = ( + params: AppMountParameters +) => AppUnmount | Promise; /** * A mount function called when the user navigates to this app's route. @@ -256,9 +259,9 @@ export type AppMount = (params: AppMountParameters) => AppUnmount | Promise = ( context: AppMountContext, - params: AppMountParameters + params: AppMountParameters ) => AppUnmount | Promise; /** @@ -304,16 +307,65 @@ export interface AppMountContext { } /** @public */ -export interface AppMountParameters { +export interface AppMountParameters { /** * The container element to render the application into. */ element: HTMLElement; + /** + * A scoped history instance for your application. Should be used to wire up + * your applications Router. + * + * @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` + * + * + * , + * element + * ); + * + * return () => ReactDOM.unmountComponentAtNode(element); + * } + * ``` + */ + history: ScopedHistory; + /** * The route path for configuring navigation to the application. * This string should not include the base path from HTTP. * + * @deprecated Use {@link AppMountParameters.history} instead. + * * @example * * How to configure react-router with a base path: @@ -340,10 +392,10 @@ export interface AppMountParameters { * 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` * @@ -498,8 +550,9 @@ export interface ApplicationSetup { /** * Register an mountable application to the system. * @param app - an {@link App} + * @typeParam HistoryLocationState - shape of the `History` state on {@link AppMountParameters.history}, defaults to `unknown`. */ - register(app: App): void; + register(app: App): void; /** * Register an application updater that can be used to change the {@link AppUpdatableFields} fields @@ -551,7 +604,10 @@ export interface InternalApplicationSetup extends Pick( + plugin: PluginOpaqueId, + app: App + ): void; /** * Register metadata about legacy applications. Legacy apps will not be mounted when navigated to. diff --git a/src/core/public/application/ui/app_container.test.tsx b/src/core/public/application/ui/app_container.test.tsx index a46243a2da493..c538227e8f098 100644 --- a/src/core/public/application/ui/app_container.test.tsx +++ b/src/core/public/application/ui/app_container.test.tsx @@ -22,6 +22,8 @@ import { mount } from 'enzyme'; import { AppContainer } from './app_container'; import { Mounter, AppMountParameters, AppStatus } from '../types'; +import { createMemoryHistory } from 'history'; +import { ScopedHistory } from '../scoped_history'; describe('AppContainer', () => { const appId = 'someApp'; @@ -60,10 +62,15 @@ describe('AppContainer', () => { const wrapper = mount( + // Create a history using the appPath as the current location + new ScopedHistory(createMemoryHistory({ initialEntries: [appPath] }), appPath) + } /> ); diff --git a/src/core/public/application/ui/app_container.tsx b/src/core/public/application/ui/app_container.tsx index 885157843e7df..e12a0f2cf2fcd 100644 --- a/src/core/public/application/ui/app_container.tsx +++ b/src/core/public/application/ui/app_container.tsx @@ -28,18 +28,24 @@ import React, { import { AppLeaveHandler, AppStatus, AppUnmount, Mounter } from '../types'; import { AppNotFound } from './app_not_found_screen'; +import { ScopedHistory } from '../scoped_history'; interface Props { + /** Path application is mounted on without the global basePath */ + appPath: string; appId: string; mounter?: Mounter; appStatus: AppStatus; setAppLeaveHandler: (appId: string, handler: AppLeaveHandler) => void; + createScopedHistory: (appUrl: string) => ScopedHistory; } export const AppContainer: FunctionComponent = ({ mounter, appId, + appPath, setAppLeaveHandler, + createScopedHistory, appStatus, }: Props) => { const [appNotFound, setAppNotFound] = useState(false); @@ -67,6 +73,7 @@ export const AppContainer: FunctionComponent = ({ unmountRef.current = (await mounter.mount({ appBasePath: mounter.appBasePath, + history: createScopedHistory(appPath), element: elementRef.current!, onAppLeave: handler => setAppLeaveHandler(appId, handler), })) || null; @@ -75,7 +82,7 @@ export const AppContainer: FunctionComponent = ({ mount(); return unmount; - }, [appId, appStatus, mounter, setAppLeaveHandler]); + }, [appId, appStatus, mounter, createScopedHistory, setAppLeaveHandler, appPath]); return ( diff --git a/src/core/public/application/ui/app_router.tsx b/src/core/public/application/ui/app_router.tsx index 50e5f5ee1bd62..61c8bc3cadae5 100644 --- a/src/core/public/application/ui/app_router.tsx +++ b/src/core/public/application/ui/app_router.tsx @@ -17,7 +17,7 @@ * under the License. */ -import React, { FunctionComponent } from 'react'; +import React, { FunctionComponent, useMemo } from 'react'; import { Route, RouteComponentProps, Router, Switch } from 'react-router-dom'; import { History } from 'history'; import { Observable } from 'rxjs'; @@ -25,6 +25,7 @@ import { useObservable } from 'react-use'; import { AppLeaveHandler, AppStatus, Mounter } from '../types'; import { AppContainer } from './app_container'; +import { ScopedHistory } from '../scoped_history'; interface Props { mounters: Map; @@ -44,6 +45,11 @@ export const AppRouter: FunctionComponent = ({ appStatuses$, }) => { const appStatuses = useObservable(appStatuses$, new Map()); + const createScopedHistory = useMemo( + () => (appPath: string) => new ScopedHistory(history, appPath), + [history] + ); + return ( @@ -56,12 +62,12 @@ export const AppRouter: FunctionComponent = ({ ( + render={({ match: { url } }) => ( )} />, @@ -72,6 +78,7 @@ export const AppRouter: FunctionComponent = ({ render={({ match: { params: { appId }, + url, }, }: RouteComponentProps) => { // Find the mounter including legacy mounters with subapps: @@ -81,10 +88,11 @@ export const AppRouter: FunctionComponent = ({ return ( ); }} diff --git a/src/core/public/index.ts b/src/core/public/index.ts index 1bc660189384a..9c97993d7c2a6 100644 --- a/src/core/public/index.ts +++ b/src/core/public/index.ts @@ -109,6 +109,7 @@ export { AppNavLinkStatus, AppUpdatableFields, AppUpdater, + ScopedHistory, } from './application'; export { diff --git a/src/core/public/mocks.ts b/src/core/public/mocks.ts index 3301d71e2cdaf..8ea672890ca29 100644 --- a/src/core/public/mocks.ts +++ b/src/core/public/mocks.ts @@ -41,6 +41,7 @@ export { notificationServiceMock } from './notifications/notifications_service.m export { overlayServiceMock } from './overlays/overlay_service.mock'; export { uiSettingsServiceMock } from './ui_settings/ui_settings_service.mock'; export { savedObjectsServiceMock } from './saved_objects/saved_objects_service.mock'; +export { scopedHistoryMock } from './application/scoped_history.mock'; function createCoreSetupMock({ basePath = '' } = {}) { const mock = { diff --git a/src/core/public/public.api.md b/src/core/public/public.api.md index ba1988b857385..cd956eb17531a 100644 --- a/src/core/public/public.api.md +++ b/src/core/public/public.api.md @@ -4,25 +4,30 @@ ```ts +import { Action } from 'history'; import { Breadcrumb } from '@elastic/eui'; import { EuiButtonEmptyProps } from '@elastic/eui'; import { EuiConfirmModalProps } from '@elastic/eui'; import { EuiGlobalToastListToast } from '@elastic/eui'; import { ExclusiveUnion } from '@elastic/eui'; +import { History } from 'history'; import { IconType } from '@elastic/eui'; +import { Location } from 'history'; +import { LocationDescriptorObject } from 'history'; import { MaybePromise } from '@kbn/utility-types'; import { Observable } from 'rxjs'; import React from 'react'; import * as Rx from 'rxjs'; import { ShallowPromise } from '@kbn/utility-types'; import { UiSettingsParams as UiSettingsParams_2 } from 'src/core/server/types'; +import { UnregisterCallback } from 'history'; import { UserProvidedValues as UserProvidedValues_2 } from 'src/core/server/types'; // @public -export interface App extends AppBase { +export interface App extends AppBase { appRoute?: string; chromeless?: boolean; - mount: AppMount | AppMountDeprecated; + mount: AppMount | AppMountDeprecated; } // @public (undocumented) @@ -89,7 +94,7 @@ export type AppLeaveHandler = (factory: AppLeaveActionFactory) => AppLeaveAction // @public (undocumented) export interface ApplicationSetup { - register(app: App): void; + register(app: App): void; registerAppUpdater(appUpdater$: Observable): void; // @deprecated registerMountContext(contextName: T, provider: IContextProvider): void; @@ -112,7 +117,7 @@ export interface ApplicationStart { } // @public -export type AppMount = (params: AppMountParameters) => AppUnmount | Promise; +export type AppMount = (params: AppMountParameters) => AppUnmount | Promise; // @public @deprecated export interface AppMountContext { @@ -133,12 +138,14 @@ export interface AppMountContext { } // @public @deprecated -export type AppMountDeprecated = (context: AppMountContext, params: AppMountParameters) => AppUnmount | Promise; +export type AppMountDeprecated = (context: AppMountContext, params: AppMountParameters) => AppUnmount | Promise; // @public (undocumented) -export interface AppMountParameters { +export interface AppMountParameters { + // @deprecated appBasePath: string; element: HTMLElement; + history: ScopedHistory; onAppLeave: (handler: AppLeaveHandler) => void; } @@ -1175,6 +1182,23 @@ export interface SavedObjectsUpdateOptions { version?: string; } +// @public +export class ScopedHistory implements History { + constructor(parentHistory: History, basePath: string); + get action(): Action; + block: (prompt?: string | boolean | History.TransitionPromptHook | undefined) => UnregisterCallback; + createHref: (location: LocationDescriptorObject) => string; + createSubHistory: (basePath: string) => ScopedHistory; + go: (n: number) => void; + goBack: () => void; + goForward: () => void; + get length(): number; + listen: (listener: (location: Location, action: Action) => void) => UnregisterCallback; + get location(): Location; + push: (pathOrLocation: string | LocationDescriptorObject, state?: HistoryLocationState | undefined) => void; + replace: (pathOrLocation: string | LocationDescriptorObject, state?: HistoryLocationState | undefined) => void; + } + // @public export class SimpleSavedObject { constructor(client: SavedObjectsClientContract, { id, type, version, attributes, error, references, migrationVersion }: SavedObject); diff --git a/src/legacy/core_plugins/kibana/public/local_application_service/local_application_service.ts b/src/legacy/core_plugins/kibana/public/local_application_service/local_application_service.ts index 90328003c8292..14564cfd9ee78 100644 --- a/src/legacy/core_plugins/kibana/public/local_application_service/local_application_service.ts +++ b/src/legacy/core_plugins/kibana/public/local_application_service/local_application_service.ts @@ -68,7 +68,13 @@ export class LocalApplicationService { isUnmounted = true; }); (async () => { - const params = { element, appBasePath: '', onAppLeave: () => undefined }; + const params = { + element, + appBasePath: '', + onAppLeave: () => undefined, + // TODO: adapt to use Core's ScopedHistory + history: {} as any, + }; unmountHandler = isAppMountDeprecated(app.mount) ? await app.mount({ core: npStart.core }, params) : await app.mount(params); diff --git a/src/legacy/ui/public/new_platform/new_platform.test.mocks.ts b/src/legacy/ui/public/new_platform/new_platform.test.mocks.ts index e660ad1f55840..f44efe17ef8ee 100644 --- a/src/legacy/ui/public/new_platform/new_platform.test.mocks.ts +++ b/src/legacy/ui/public/new_platform/new_platform.test.mocks.ts @@ -17,8 +17,15 @@ * under the License. */ +import { scopedHistoryMock } from '../../../../core/public/mocks'; + export const setRootControllerMock = jest.fn(); jest.doMock('ui/chrome', () => ({ setRootController: setRootControllerMock, })); + +export const historyMock = scopedHistoryMock.create(); +jest.doMock('../../../../core/public', () => ({ + ScopedHistory: jest.fn(() => historyMock), +})); diff --git a/src/legacy/ui/public/new_platform/new_platform.test.ts b/src/legacy/ui/public/new_platform/new_platform.test.ts index e050ffd5b530c..498f05457bba9 100644 --- a/src/legacy/ui/public/new_platform/new_platform.test.ts +++ b/src/legacy/ui/public/new_platform/new_platform.test.ts @@ -17,7 +17,9 @@ * under the License. */ -import { setRootControllerMock } from './new_platform.test.mocks'; +jest.mock('history'); + +import { setRootControllerMock, historyMock } from './new_platform.test.mocks'; import { legacyAppRegister, __reset__, __setup__ } from './new_platform'; import { coreMock } from '../../../../core/public/mocks'; @@ -63,6 +65,7 @@ describe('ui/new_platform', () => { element: elementMock[0], appBasePath: '/test/base/path/app/test', onAppLeave: expect.any(Function), + history: historyMock, }); }); @@ -84,6 +87,7 @@ describe('ui/new_platform', () => { element: elementMock[0], appBasePath: '/test/base/path/app/test', onAppLeave: expect.any(Function), + history: historyMock, }); }); diff --git a/src/legacy/ui/public/new_platform/new_platform.ts b/src/legacy/ui/public/new_platform/new_platform.ts index b7994c7f68afb..00d76bc341322 100644 --- a/src/legacy/ui/public/new_platform/new_platform.ts +++ b/src/legacy/ui/public/new_platform/new_platform.ts @@ -20,7 +20,14 @@ import { IScope } from 'angular'; import { UiActionsStart, UiActionsSetup } from 'src/plugins/ui_actions/public'; import { IEmbeddableStart, IEmbeddableSetup } from 'src/plugins/embeddable/public'; -import { LegacyCoreSetup, LegacyCoreStart, App, AppMountDeprecated } from '../../../../core/public'; +import { createBrowserHistory } from 'history'; +import { + LegacyCoreSetup, + LegacyCoreStart, + App, + AppMountDeprecated, + ScopedHistory, +} from '../../../../core/public'; import { Plugin as DataPlugin } from '../../../../plugins/data/public'; import { Plugin as ExpressionsPlugin } from '../../../../plugins/expressions/public'; import { @@ -126,7 +133,7 @@ let legacyAppRegistered = false; * Exported for testing only. Use `npSetup.core.application.register` in legacy apps. * @internal */ -export const legacyAppRegister = (app: App) => { +export const legacyAppRegister = (app: App) => { if (legacyAppRegistered) { throw new Error(`core.application.register may only be called once for legacy plugins.`); } @@ -137,9 +144,15 @@ export const legacyAppRegister = (app: App) => { // Root controller cannot return a Promise so use an internal async function and call it immediately (async () => { + const appRoute = app.appRoute || `/app/${app.id}`; + const appBasePath = npSetup.core.http.basePath.prepend(appRoute); const params = { element, - appBasePath: npSetup.core.http.basePath.prepend(`/app/${app.id}`), + appBasePath, + history: new ScopedHistory( + createBrowserHistory({ basename: npSetup.core.http.basePath.get() }), + appRoute + ), onAppLeave: () => undefined, }; const unmount = isAppMountDeprecated(app.mount) diff --git a/src/plugins/dev_tools/public/application.tsx b/src/plugins/dev_tools/public/application.tsx index a179be6946c76..2c21b451cb9f7 100644 --- a/src/plugins/dev_tools/public/application.tsx +++ b/src/plugins/dev_tools/public/application.tsx @@ -91,7 +91,13 @@ function DevToolsWrapper({ if (mountedTool.current) { mountedTool.current.unmountHandler(); } - const params = { element, appBasePath: '', onAppLeave: () => undefined }; + const params = { + element, + appBasePath: '', + onAppLeave: () => undefined, + // TODO: adapt to use Core's ScopedHistory + history: {} as any, + }; const unmountHandler = isAppMountDeprecated(activeDevTool.mount) ? await activeDevTool.mount(appMountContext, params) : await activeDevTool.mount(params); diff --git a/test/plugin_functional/plugins/core_plugin_a/public/application.tsx b/test/plugin_functional/plugins/core_plugin_a/public/application.tsx index 7c1406f5b20c3..abea970749cbc 100644 --- a/test/plugin_functional/plugins/core_plugin_a/public/application.tsx +++ b/test/plugin_functional/plugins/core_plugin_a/public/application.tsx @@ -17,9 +17,10 @@ * under the License. */ +import { History } from 'history'; import React from 'react'; import ReactDOM from 'react-dom'; -import { BrowserRouter as Router, Route, withRouter, RouteComponentProps } from 'react-router-dom'; +import { Router, Route, withRouter, RouteComponentProps } from 'react-router-dom'; import { EuiPage, @@ -115,8 +116,8 @@ const Nav = withRouter(({ history, navigateToApp }: NavProps) => ( /> )); -const FooApp = ({ basename, context }: { basename: string; context: AppMountContext }) => ( - +const FooApp = ({ history, context }: { history: History; context: AppMountContext }) => ( +