Deprecate chrome.navlinks.update and add documentation (#54893)

* add migration example on application status updater

* update example with proper licensing plugin usage

* fix line width

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

@@ -1,25 +1,30 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ChromeNavLinks](./kibana-plugin-public.chromenavlinks.md) &gt; [update](./kibana-plugin-public.chromenavlinks.update.md)
-
-## ChromeNavLinks.update() method
-
-Update the navlink for the given id with the updated attributes. Returns the updated navlink or `undefined` if it does not exist.
-
-<b>Signature:</b>
-
-```typescript
-update(id: string, values: ChromeNavLinkUpdateableFields): ChromeNavLink | undefined;
-```
-
-## Parameters
-
-|  Parameter | Type | Description |
-|  --- | --- | --- |
-|  id | <code>string</code> |  |
-|  values | <code>ChromeNavLinkUpdateableFields</code> |  |
-
-<b>Returns:</b>
-
-`ChromeNavLink | undefined`
-
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-public](./kibana-plugin-public.md) &gt; [ChromeNavLinks](./kibana-plugin-public.chromenavlinks.md) &gt; [update](./kibana-plugin-public.chromenavlinks.update.md)
+
+## ChromeNavLinks.update() method
+
+> Warning: This API is now obsolete.
+> 
+> Uses the [AppBase.updater$](./kibana-plugin-public.appbase.updater_.md) property when registering your application with [ApplicationSetup.register()](./kibana-plugin-public.applicationsetup.register.md) instead.
+> 
+
+Update the navlink for the given id with the updated attributes. Returns the updated navlink or `undefined` if it does not exist.
+
+<b>Signature:</b>
+
+```typescript
+update(id: string, values: ChromeNavLinkUpdateableFields): ChromeNavLink | undefined;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  id | <code>string</code> |  |
+|  values | <code>ChromeNavLinkUpdateableFields</code> |  |
+
+<b>Returns:</b>
+
+`ChromeNavLink | undefined`
+

src/core/MIGRATION.md

@@ -1131,6 +1131,7 @@ import { npStart: { core } } from 'ui/new_platform';
 | Legacy Platform                                       | New Platform                                                                                                                                                                               | Notes                                                                                                                                          |
 | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
 | `chrome.addBasePath`                                  | [`core.http.basePath.prepend`](/docs/development/core/public/kibana-plugin-public.httpservicebase.basepath.md)                                                                             |                                                                                                                                                |
+| `chrome.navLinks.update`                              | [`core.appbase.updater`](/docs/development/core/public/kibana-plugin-public.appbase.updater_.md)                                                                                           | Use the `updater$` property when registering your application via `core.application.register`                                                  |
 | `chrome.breadcrumbs.set`                              | [`core.chrome.setBreadcrumbs`](/docs/development/core/public/kibana-plugin-public.chromestart.setbreadcrumbs.md)                                                                           |                                                                                                                                                |
 | `chrome.getUiSettingsClient`                          | [`core.uiSettings`](/docs/development/core/public/kibana-plugin-public.uisettingsclient.md)                                                                                                |                                                                                                                                                |
 | `chrome.helpExtension.set`                            | [`core.chrome.setHelpExtension`](/docs/development/core/public/kibana-plugin-public.chromestart.sethelpextension.md)                                                                       |                                                                                                                                                |

src/core/MIGRATION_EXAMPLES.md

@@ -15,6 +15,7 @@ APIs to their New Platform equivalents.
       - [4. New Platform plugin](#4-new-platform-plugin)
     - [Accessing Services](#accessing-services)
   - [Chrome](#chrome)
+    - [Updating an application navlink](#updating-application-navlink)
 
 ## Configuration
 
@@ -462,7 +463,59 @@ elsewhere.
 | `chrome.setVisible`                                   | [`core.chrome.setIsVisible`](/docs/development/core/public/kibana-plugin-public.chromestart.setisvisible.md)                        |                                                                                                                                                                                  |
 | `chrome.getInjected`                                  | [`core.injectedMetadata.getInjected`](/docs/development/core/public/kibana-plugin-public.coresetup.injectedmetadata.md) (temporary) | A temporary API is available to read injected vars provided by legacy plugins. This will be removed after [#41990](https://github.com/elastic/kibana/issues/41990) is completed. |
 | `chrome.setRootTemplate` / `chrome.setRootController` | --                                                                                                                                  | Use application mounting via `core.application.register` (not currently avaiable to legacy plugins).                                                                             |
+| `chrome.navLinks.update`                              | [`core.appbase.updater`](/docs/development/core/public/kibana-plugin-public.appbase.updater_.md)                                    | Use the `updater$` property when registering your application via `core.application.register`                                                                                    |
 
 In most cases, the most convenient way to access these APIs will be via the
 [AppMountContext](/docs/development/core/public/kibana-plugin-public.appmountcontext.md)
 object passed to your application when your app is mounted on the page.
+
+### Updating an application navlink
+
+In the legacy platform, the navlink could be updated using `chrome.navLinks.update`
+
+```ts
+uiModules.get('xpack/ml').run(() => {
+  const showAppLink = xpackInfo.get('features.ml.showLinks', false);
+  const isAvailable = xpackInfo.get('features.ml.isAvailable', false);
+
+  const navLinkUpdates = {
+    // hide by default, only show once the xpackInfo is initialized
+    hidden: !showAppLink,
+    disabled: !showAppLink || (showAppLink && !isAvailable),
+  };
+
+  npStart.core.chrome.navLinks.update('ml', navLinkUpdates);
+});
+```
+
+In the new platform, navlinks should not be updated directly. Instead, it is now possible to add an `updater` when 
+registering an application to change the application or the navlink state at runtime.
+
+```ts
+// my_plugin has a required dependencie to the `licensing` plugin
+interface MyPluginSetupDeps {
+  licensing: LicensingPluginSetup;
+}
+
+export class MyPlugin implements Plugin {
+  setup({ application }, { licensing }: MyPluginSetupDeps) {
+    const updater$ = licensing.license$.pipe(
+      map(license => {
+        const { hidden, disabled } = calcStatusFor(license);
+        if (hidden) return { navLinkStatus: AppNavLinkStatus.hidden };
+        if (disabled) return { navLinkStatus: AppNavLinkStatus.disabled };
+        return { navLinkStatus: AppNavLinkStatus.default };
+      })
+    );
+
+    application.register({
+      id: 'my-app',
+      title: 'My App',
+      updater$,
+      async mount(params) {
+        const { renderApp } = await import('./application');
+        return renderApp(params);
+      },
+    });
+  }
+```

src/core/public/chrome/nav_links/nav_links_service.ts

@@ -72,6 +72,10 @@ export interface ChromeNavLinks {
   /**
    * Update the navlink for the given id with the updated attributes.
    * Returns the updated navlink or `undefined` if it does not exist.
+   *
+   * @deprecated Uses the {@link AppBase.updater$} property when registering
+   * your application with {@link ApplicationSetup.register} instead.
+   *
    * @param id
    * @param values
    */

src/core/public/public.api.md

@@ -279,6 +279,7 @@ export interface ChromeNavLinks {
     getNavLinks$(): Observable<Array<Readonly<ChromeNavLink>>>;
     has(id: string): boolean;
     showOnly(id: string): void;
+    // @deprecated
     update(id: string, values: ChromeNavLinkUpdateableFields): ChromeNavLink | undefined;
 }