ILM locators (#102313)

* feat: 🎸 add url service types

* refactor: 💡 move locator types into its own folder

* feat: 🎸 add abstract locator implementation

* feat: 🎸 implement abstract locator client

* feat: 🎸 add browser-side locators service

* feat: 🎸 implement locator .getLocation()

* feat: 🎸 implement navigate function

* feat: 🎸 implement locator service in /common folder

* feat: 🎸 expose locators client on browser and server

* refactor: 💡 make locators async

* chore: 🤖 add deprecation notice to URL generators

* docs: ✏️ add deprecation notice to readme

* feat: 🎸 create management app locator

* refactor: 💡 simplify management locator

* feat: 🎸 export management app locator from plugin contract

* feat: 🎸 implement ILM locator

* feat: 🎸 improve share plugin exports

* feat: 🎸 improve management app locator

* feat: 🎸 add useLocatorUrl React hook

* feat: 🎸 add .getUrl() method to locators

* feat: 🎸 migrate ILM app to use URL locators

* fix: 🐛 correct typescript errors

* Fix TypeScript errors in mock

* Fix ILM locator unit tests

* style: 💄 shorten import

Co-authored-by: Vadim Kibana <vadimkibana@gmail.com>
Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>

src/plugins/management/common/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+export { ManagementAppLocator } from './locator';

src/plugins/management/common/locator.test.ts

@@ -7,16 +7,16 @@
  */
 
 import { MANAGEMENT_APP_ID } from './contants';
-import { ManagementAppLocator, MANAGEMENT_APP_LOCATOR } from './locator';
+import { ManagementAppLocatorDefinition, MANAGEMENT_APP_LOCATOR } from './locator';
 
 test('locator has the right ID', () => {
-  const locator = new ManagementAppLocator();
+  const locator = new ManagementAppLocatorDefinition();
 
   expect(locator.id).toBe(MANAGEMENT_APP_LOCATOR);
 });
 
 test('returns management app ID', async () => {
-  const locator = new ManagementAppLocator();
+  const locator = new ManagementAppLocatorDefinition();
   const location = await locator.getLocation({
     sectionId: 'a',
     appId: 'b',
@@ -28,26 +28,26 @@ test('returns management app ID', async () => {
 });
 
 test('returns Kibana location for section ID and app ID pair', async () => {
-  const locator = new ManagementAppLocator();
+  const locator = new ManagementAppLocatorDefinition();
   const location = await locator.getLocation({
     sectionId: 'ingest',
     appId: 'index',
   });
 
   expect(location).toMatchObject({
-    route: '/ingest/index',
+    path: '/ingest/index',
     state: {},
   });
 });
 
 test('when app ID is not provided, returns path to just the section ID', async () => {
-  const locator = new ManagementAppLocator();
+  const locator = new ManagementAppLocatorDefinition();
   const location = await locator.getLocation({
     sectionId: 'data',
   });
 
   expect(location).toMatchObject({
-    route: '/data',
+    path: '/data',
     state: {},
   });
 });

src/plugins/management/common/locator.ts

@@ -7,7 +7,7 @@
  */
 
 import { SerializableState } from 'src/plugins/kibana_utils/common';
-import { LocatorDefinition } from 'src/plugins/share/common';
+import { LocatorDefinition, LocatorPublic } from 'src/plugins/share/common';
 import { MANAGEMENT_APP_ID } from './contants';
 
 export const MANAGEMENT_APP_LOCATOR = 'MANAGEMENT_APP_LOCATOR';
@@ -17,15 +17,18 @@ export interface ManagementAppLocatorParams extends SerializableState {
   appId?: string;
 }
 
-export class ManagementAppLocator implements LocatorDefinition<ManagementAppLocatorParams> {
+export type ManagementAppLocator = LocatorPublic<ManagementAppLocatorParams>;
+
+export class ManagementAppLocatorDefinition
+  implements LocatorDefinition<ManagementAppLocatorParams> {
   public readonly id = MANAGEMENT_APP_LOCATOR;
 
   public readonly getLocation = async (params: ManagementAppLocatorParams) => {
-    const route = `/${params.sectionId}${params.appId ? '/' + params.appId : ''}`;
+    const path = `/${params.sectionId}${params.appId ? '/' + params.appId : ''}`;
 
     return {
       app: MANAGEMENT_APP_ID,
-      route,
+      path,
       state: {},
     };
   };

src/plugins/management/public/mocks/index.ts

@@ -33,9 +33,11 @@ const createSetupContract = (): ManagementSetup => ({
   locator: {
     getLocation: jest.fn(async () => ({
       app: 'MANAGEMENT',
-      route: '',
+      path: '',
       state: {},
     })),
+    getUrl: jest.fn(),
+    useUrl: jest.fn(),
     navigate: jest.fn(),
   },
 });

src/plugins/management/public/plugin.ts

@@ -25,7 +25,7 @@ import {
 } from '../../../core/public';
 
 import { MANAGEMENT_APP_ID } from '../common/contants';
-import { ManagementAppLocator } from '../common/locator';
+import { ManagementAppLocatorDefinition } from '../common/locator';
 import {
   ManagementSectionsService,
   getSectionsServiceStartPrivate,
@@ -74,7 +74,7 @@ export class ManagementPlugin
 
   public setup(core: CoreSetup, { home, share }: ManagementSetupDependencies) {
     const kibanaVersion = this.initializerContext.env.packageInfo.version;
-    const locator = share.url.locators.create(new ManagementAppLocator());
+    const locator = share.url.locators.create(new ManagementAppLocatorDefinition());
 
     if (home) {
       home.featureCatalogue.register({

src/plugins/management/server/plugin.ts

@@ -9,7 +9,7 @@
 import { PluginInitializerContext, CoreSetup, CoreStart, Plugin, Logger } from 'kibana/server';
 import { LocatorPublic } from 'src/plugins/share/common';
 import type { SharePluginSetup } from 'src/plugins/share/server';
-import { ManagementAppLocator, ManagementAppLocatorParams } from '../common/locator';
+import { ManagementAppLocatorDefinition, ManagementAppLocatorParams } from '../common/locator';
 import { capabilitiesProvider } from './capabilities_provider';
 
 interface ManagementSetupDependencies {
@@ -31,7 +31,7 @@ export class ManagementServerPlugin
   public setup(core: CoreSetup, { share }: ManagementSetupDependencies) {
     this.logger.debug('management: Setup');
 
-    const locator = share.url.locators.create(new ManagementAppLocator());
+    const locator = share.url.locators.create(new ManagementAppLocatorDefinition());
 
     core.capabilities.registerProvider(capabilitiesProvider);
 

src/plugins/share/common/index.ts

@@ -6,4 +6,4 @@
  * Side Public License, v 1.
  */
 
-export { LocatorDefinition, LocatorPublic } from './url_service';
+export { LocatorDefinition, LocatorPublic, useLocatorUrl } from './url_service';

src/plugins/share/common/url_service/__tests__/locators.test.ts

@@ -53,7 +53,7 @@ describe('locators', () => {
 
     expect(location).toEqual({
       app: 'test_app',
-      route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=21',
+      path: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=21',
       state: { isFlyoutOpen: true },
     });
   });
@@ -97,7 +97,7 @@ describe('locators', () => {
       expect(deps.navigate).toHaveBeenCalledWith(
         {
           app: 'test_app',
-          route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=1',
+          path: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=1',
           state: {
             isFlyoutOpen: false,
           },
@@ -130,7 +130,7 @@ describe('locators', () => {
       expect(deps.navigate).toHaveBeenCalledWith(
         {
           app: 'test_app',
-          route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=1',
+          path: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=1',
           state: {
             isFlyoutOpen: false,
           },
@@ -153,7 +153,7 @@ describe('locators', () => {
       expect(deps.navigate).toHaveBeenCalledWith(
         {
           app: 'test_app',
-          route: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=2',
+          path: '/my-object/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx?page=2',
           state: {
             isFlyoutOpen: false,
           },

src/plugins/share/common/url_service/__tests__/setup.ts

@@ -21,7 +21,7 @@ export const testLocator: LocatorDefinition<TestLocatorState> = {
   getLocation: async ({ savedObjectId, pageNumber, showFlyout }) => {
     return {
       app: 'test_app',
-      route: `/my-object/${savedObjectId}?page=${pageNumber}`,
+      path: `/my-object/${savedObjectId}?page=${pageNumber}`,
       state: {
         isFlyoutOpen: showFlyout,
       },
@@ -34,6 +34,9 @@ export const urlServiceTestSetup = (partialDeps: Partial<UrlServiceDependencies>
     navigate: async () => {
       throw new Error('not implemented');
     },
+    getUrl: async () => {
+      throw new Error('not implemented');
+    },
     ...partialDeps,
   };
   const service = new UrlService(deps);

src/plugins/share/common/url_service/locators/index.ts

@@ -9,3 +9,4 @@
 export * from './types';
 export * from './locator';
 export * from './locator_client';
+export { useLocatorUrl } from './use_locator_url';

src/plugins/share/common/url_service/locators/locator.ts

@@ -7,16 +7,27 @@
  */
 
 import type { SavedObjectReference } from 'kibana/server';
+import { DependencyList } from 'react';
 import type { PersistableState, SerializableState } from 'src/plugins/kibana_utils/common';
+import { useLocatorUrl } from './use_locator_url';
 import type {
   LocatorDefinition,
   LocatorPublic,
   KibanaLocation,
   LocatorNavigationParams,
+  LocatorGetUrlParams,
 } from './types';
 
 export interface LocatorDependencies {
+  /**
+   * Navigate without reloading the page to a KibanaLocation.
+   */
   navigate: (location: KibanaLocation, params?: LocatorNavigationParams) => Promise<void>;
+
+  /**
+   * Resolve a Kibana URL given KibanaLocation.
+   */
+  getUrl: (location: KibanaLocation, getUrlParams: LocatorGetUrlParams) => Promise<string>;
 }
 
 export class Locator<P extends SerializableState> implements PersistableState<P>, LocatorPublic<P> {
@@ -57,13 +68,29 @@ export class Locator<P extends SerializableState> implements PersistableState<P>
     return await this.definition.getLocation(params);
   }
 
+  public async getUrl(params: P, { absolute = false }: LocatorGetUrlParams = {}): Promise<string> {
+    const location = await this.getLocation(params);
+    const url = this.deps.getUrl(location, { absolute });
+
+    return url;
+  }
+
   public async navigate(
     params: P,
     { replace = false }: LocatorNavigationParams = {}
   ): Promise<void> {
     const location = await this.getLocation(params);
+
     await this.deps.navigate(location, {
       replace,
     });
   }
+
+  /* eslint-disable react-hooks/rules-of-hooks */
+  public readonly useUrl = (
+    params: P,
+    getUrlParams?: LocatorGetUrlParams,
+    deps: DependencyList = []
+  ): string => useLocatorUrl<P>(this, params, getUrlParams, deps);
+  /* eslint-enable react-hooks/rules-of-hooks */
 }

src/plugins/share/common/url_service/locators/types.ts

@@ -6,6 +6,7 @@
  * Side Public License, v 1.
  */
 
+import { DependencyList } from 'react';
 import { PersistableState, SerializableState } from 'src/plugins/kibana_utils/common';
 
 /**
@@ -51,23 +52,57 @@ export interface LocatorDefinition<P extends SerializableState>
  */
 export interface LocatorPublic<P> {
   /**
-   * Returns a relative URL to the client-side redirect endpoint using this
-   * locator. (This method is necessary for compatibility with URL generators.)
+   * Returns a reference to a Kibana client-side location.
+   *
+   * @param params URL locator parameters.
    */
   getLocation(params: P): Promise<KibanaLocation>;
 
+  /**
+   * Returns a URL as a string.
+   *
+   * @param params URL locator parameters.
+   * @param getUrlParams URL construction parameters.
+   */
+  getUrl(params: P, getUrlParams?: LocatorGetUrlParams): Promise<string>;
+
   /**
    * Navigate using the `core.application.navigateToApp()` method to a Kibana
    * location generated by this locator. This method is available only on the
    * browser.
+   *
+   * @param params URL locator parameters.
+   * @param navigationParams Navigation parameters.
    */
   navigate(params: P, navigationParams?: LocatorNavigationParams): Promise<void>;
+
+  /**
+   * React hook which returns a URL string given locator parameters. Returns
+   * empty string if URL is being loaded or an error happened.
+   */
+  useUrl: (params: P, getUrlParams?: LocatorGetUrlParams, deps?: DependencyList) => string;
 }
 
+/**
+ * Parameters used when navigating on client-side using browser history object.
+ */
 export interface LocatorNavigationParams {
+  /**
+   * Whether to replace a navigation entry in history queue or push a new entry.
+   */
   replace?: boolean;
 }
 
+/**
+ * Parameters used when constructing a string URL.
+ */
+export interface LocatorGetUrlParams {
+  /**
+   * Whether to return an absolute long URL or relative short URL.
+   */
+  absolute?: boolean;
+}
+
 /**
  * This interface represents a location in Kibana to which one can navigate
  * using the `core.application.navigateToApp()` method.
@@ -79,9 +114,9 @@ export interface KibanaLocation<S = object> {
   app: string;
 
   /**
-   * A URL route within a Kibana application.
+   * A relative URL path within a Kibana application.
    */
-  route: string;
+  path: string;
 
   /**
    * A serializable location state object, which the app can use to determine

src/plugins/share/common/url_service/locators/use_locator_url.ts

@@ -0,0 +1,46 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the Elastic License
+ * 2.0 and the Server Side Public License, v 1; you may not use this file except
+ * in compliance with, at your election, the Elastic License 2.0 or the Server
+ * Side Public License, v 1.
+ */
+
+import { DependencyList, useEffect, useState } from 'react';
+import useMountedState from 'react-use/lib/useMountedState';
+import { SerializableState } from 'src/plugins/kibana_utils/common';
+import { LocatorGetUrlParams, LocatorPublic } from '../../../common/url_service';
+
+export const useLocatorUrl = <P extends SerializableState>(
+  locator: LocatorPublic<P> | null | undefined,
+  params: P,
+  getUrlParams?: LocatorGetUrlParams,
+  deps: DependencyList = []
+): string => {
+  const [url, setUrl] = useState<string>('');
+  const isMounted = useMountedState();
+
+  /* eslint-disable react-hooks/exhaustive-deps */
+  useEffect(() => {
+    if (!locator) {
+      setUrl('');
+      return;
+    }
+
+    locator
+      .getUrl(params, getUrlParams)
+      .then((result: string) => {
+        if (!isMounted()) return;
+        setUrl(result);
+      })
+      .catch((error) => {
+        if (!isMounted()) return;
+        // eslint-disable-next-line no-console
+        console.error('useLocatorUrl', error);
+        setUrl('');
+      });
+  }, [locator, ...deps]);
+  /* eslint-enable react-hooks/exhaustive-deps */
+
+  return url;
+};