feat: Introduce registerCollapsibleNavHeader to ChromeService

This commit introduces an enhancement to the ChromeService class
within our core application. It adds a new method named
`registerCollapsibleNavHeader`, allowing plugins to customize the
rendering of the collapsible navigation header in the global chrome UI.

With this new capability, plugins can now register their own
rendering logic for the collapsible navigation header. This feature
enhances the extensibility of our core system, empowering plugins to
provide a more tailored and user-friendly navigation experience.

Key changes in this commit include:

1. The addition of the `registerCollapsibleNavHeader` method to the
ChromeService class.
2. Appropriate updates to tests and typings to support the newly
introduced functionality.

Signed-off-by: Yulong Ruan <[email protected]>

src/core/public/chrome/chrome_service.mock.ts

@@ -33,6 +33,12 @@ import type { PublicMethodsOf } from '@osd/utility-types';
 import { ChromeBadge, ChromeBreadcrumb, ChromeService, InternalChromeStart } from './';
 import { getLogosMock } from '../../common/mocks';
 
+const createSetupContractMock = () => {
+  return {
+    registerCollapsibleNavHeader: jest.fn(),
+  };
+};
+
 const createStartContractMock = () => {
   const startContract: DeeplyMockedKeys<InternalChromeStart> = {
     getHeaderComponent: jest.fn(),
@@ -95,6 +101,7 @@ const createStartContractMock = () => {
 type ChromeServiceContract = PublicMethodsOf<ChromeService>;
 const createMock = () => {
   const mocked: jest.Mocked<ChromeServiceContract> = {
+    setup: jest.fn(),
     start: jest.fn(),
     stop: jest.fn(),
   };
@@ -105,4 +112,5 @@ const createMock = () => {
 export const chromeServiceMock = {
   create: createMock,
   createStartContract: createStartContractMock,
+  createSetupContract: createSetupContractMock,
 };

src/core/public/chrome/chrome_service.tsx

@@ -98,6 +98,8 @@ interface StartDeps {
   uiSettings: IUiSettingsClient;
 }
 
+type CollapsibleNavHeaderRender = () => JSX.Element | null;
+
 /** @internal */
 export class ChromeService {
   private isVisible$!: Observable<boolean>;
@@ -107,6 +109,7 @@ export class ChromeService {
   private readonly navLinks = new NavLinksService();
   private readonly recentlyAccessed = new RecentlyAccessedService();
   private readonly docTitle = new DocTitleService();
+  private collapsibleNavHeaderRender?: CollapsibleNavHeaderRender;
 
   constructor(private readonly params: ConstructorParams) {}
 
@@ -142,6 +145,14 @@ export class ChromeService {
     );
   }
 
+  public setup() {
+    return {
+      registerCollapsibleNavHeader: (render: CollapsibleNavHeaderRender) => {
+        this.collapsibleNavHeaderRender = render;
+      },
+    };
+  }
+
   public async start({
     application,
     docLinks,
@@ -262,6 +273,7 @@ export class ChromeService {
           branding={injectedMetadata.getBranding()}
           logos={logos}
           survey={injectedMetadata.getSurvey()}
+          collapsibleNavHeaderRender={this.collapsibleNavHeaderRender}
         />
       ),
 
@@ -325,6 +337,20 @@ export class ChromeService {
   }
 }
 
+/**
+ * ChromeSetup allows plugins to customize the global chrome header UI rendering
+ * before the header UI is mounted.
+ *
+ * @example
+ * Customize the Collapsible Nav's (left nav menu) header section:
+ * ```ts
+ * core.chrome.registerCollapsibleNavHeader(() => <CustomNavHeader />)
+ * ```
+ */
+export interface ChromeSetup {
+  registerCollapsibleNavHeader: (render: CollapsibleNavHeaderRender) => void;
+}
+
 /**
  * ChromeStart allows plugins to customize the global chrome header UI and
  * enrich the UX with additional information about the current location of the

src/core/public/chrome/index.ts

@@ -32,6 +32,7 @@ export {
   ChromeBadge,
   ChromeBreadcrumb,
   ChromeService,
+  ChromeSetup,
   ChromeStart,
   InternalChromeStart,
   ChromeHelpExtension,

src/core/public/chrome/ui/header/collapsible_nav.tsx

@@ -89,6 +89,7 @@ function setIsCategoryOpen(id: string, isOpen: boolean, storage: Storage) {
 interface Props {
   appId$: InternalApplicationStart['currentAppId$'];
   basePath: HttpStart['basePath'];
+  collapsibleNavHeaderRender?: () => JSX.Element | null;
   id: string;
   isLocked: boolean;
   isNavOpen: boolean;
@@ -106,6 +107,7 @@ interface Props {
 
 export function CollapsibleNav({
   basePath,
+  collapsibleNavHeaderRender,
   id,
   isLocked,
   isNavOpen,
@@ -150,6 +152,7 @@ export function CollapsibleNav({
       onClose={closeNav}
       outsideClickCloses={false}
     >
+      {collapsibleNavHeaderRender && collapsibleNavHeaderRender()}
       {customNavLink && (
         <Fragment>
           <EuiFlexItem grow={false} style={{ flexShrink: 0 }}>

src/core/public/chrome/ui/header/header.tsx

@@ -72,6 +72,7 @@ export interface HeaderProps {
   appTitle$: Observable<string>;
   badge$: Observable<ChromeBadge | undefined>;
   breadcrumbs$: Observable<ChromeBreadcrumb[]>;
+  collapsibleNavHeaderRender?: () => JSX.Element | null;
   customNavLink$: Observable<ChromeNavLink | undefined>;
   homeHref: string;
   isVisible$: Observable<boolean>;
@@ -105,6 +106,7 @@ export function Header({
   branding,
   survey,
   logos,
+  collapsibleNavHeaderRender,
   ...observables
 }: HeaderProps) {
   const isVisible = useObservable(observables.isVisible$, false);
@@ -246,6 +248,7 @@ export function Header({
 
         <CollapsibleNav
           appId$={application.currentAppId$}
+          collapsibleNavHeaderRender={collapsibleNavHeaderRender}
           id={navId}
           isLocked={isLocked}
           navLinks$={observables.navLinks$}

src/core/public/core_system.ts

@@ -167,10 +167,12 @@ export class CoreSystem {
       });
       const application = this.application.setup({ context, http });
       this.coreApp.setup({ application, http, injectedMetadata, notifications });
+      const chrome = this.chrome.setup();
 
       const core: InternalCoreSetup = {
         application,
         context,
+        chrome,
         fatalErrors: this.fatalErrorsSetup,
         http,
         injectedMetadata,

src/core/public/index.ts

@@ -63,6 +63,7 @@ import {
   ChromeNavLinks,
   ChromeNavLinkUpdateableFields,
   ChromeDocTitle,
+  ChromeSetup,
   ChromeStart,
   ChromeRecentlyAccessed,
   ChromeRecentlyAccessedHistoryItem,
@@ -219,6 +220,8 @@ export interface CoreSetup<TPluginsStart extends object = object, TStart = unkno
    * @deprecated
    */
   context: ContextSetup;
+  /** {@link ChromeSetup} */
+  chrome: ChromeSetup;
   /** {@link FatalErrorsSetup} */
   fatalErrors: FatalErrorsSetup;
   /** {@link HttpSetup} */

src/core/public/plugins/plugin_context.ts

@@ -111,6 +111,7 @@ export function createPluginSetupContext<
       registerMountContext: (contextName, provider) =>
         deps.application.registerMountContext(plugin.opaqueId, contextName, provider),
     },
+    chrome: deps.chrome,
     context: deps.context,
     fatalErrors: deps.fatalErrors,
     http: deps.http,

src/core/public/plugins/plugins_service.test.ts

@@ -102,6 +102,7 @@ describe('PluginsService', () => {
     ];
     mockSetupDeps = {
       application: applicationServiceMock.createInternalSetupContract(),
+      chrome: chromeServiceMock.createSetupContract(),
       context: contextServiceMock.createSetupContract(),
       fatalErrors: fatalErrorsServiceMock.createSetupContract(),
       http: httpServiceMock.createSetupContract(),