Add core nav logo extension

Customizing the look and feel of Backstage sometimes requires altering
the Core Nav logos. This feature introduces a createNavLogoExtension so
that users may utilize their own logos.

Signed-off-by: Craig Tracey <craig@arctir.com>

.changeset/brave-parents-stare.md

@@ -0,0 +1,6 @@
+---
+'@backstage/frontend-plugin-api': patch
+'@backstage/frontend-app-api': patch
+---
+
+Added the nav logo extension for customization of sidebar logo

packages/frontend-app-api/src/extensions/CoreNav.tsx

@@ -19,6 +19,7 @@ import {
   createExtension,
   coreExtensionData,
   createExtensionInput,
+  LogoElements,
   NavTarget,
   useRouteRef,
 } from '@backstage/frontend-plugin-api';
@@ -51,14 +52,16 @@ const useSidebarLogoStyles = makeStyles({
   },
 });
 
-const SidebarLogo = () => {
+const SidebarLogo = (props: LogoElements) => {
   const classes = useSidebarLogoStyles();
   const { isOpen } = useSidebarOpenState();
 
   return (
     <div className={classes.root}>
       <Link to="/" underline="none" className={classes.link} aria-label="Home">
-        {isOpen ? <LogoFull /> : <LogoIcon />}
+        {isOpen
+          ? props?.logoFull ?? <LogoFull />
+          : props?.logoIcon ?? <LogoIcon />}
       </Link>
     </div>
   );
@@ -78,6 +81,15 @@ export const CoreNav = createExtension({
     items: createExtensionInput({
       target: coreExtensionData.navTarget,
     }),
+    logos: createExtensionInput(
+      {
+        elements: coreExtensionData.logoElements,
+      },
+      {
+        singleton: true,
+        optional: true,
+      },
+    ),
   },
   output: {
     element: coreExtensionData.reactElement,
@@ -86,7 +98,7 @@ export const CoreNav = createExtension({
     return {
       element: (
         <Sidebar>
-          <SidebarLogo />
+          <SidebarLogo {...inputs.logos?.elements} />
           <SidebarDivider />
           {inputs.items.map((item, index) => (
             <SidebarNavItem {...item.target} key={index} />

packages/frontend-plugin-api/api-report.md

@@ -262,6 +262,7 @@ export const coreExtensionData: {
   routeRef: ConfigurableExtensionDataRef<RouteRef<AnyRouteRefParams>, {}>;
   navTarget: ConfigurableExtensionDataRef<NavTarget, {}>;
   theme: ConfigurableExtensionDataRef<AppTheme, {}>;
+  logoElements: ConfigurableExtensionDataRef<LogoElements, {}>;
 };
 
 // @public (undocumented)
@@ -641,6 +642,12 @@ export { IdentityApi };
 
 export { identityApiRef };
 
+// @public (undocumented)
+export type LogoElements = {
+  logoIcon?: JSX_2.Element;
+  logoFull?: JSX_2.Element;
+};
+
 export { microsoftAuthApiRef };
 
 // @public (undocumented)

packages/frontend-plugin-api/src/extensions/createNavLogoExtension.test.tsx

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed 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 React from 'react';
+import { createNavLogoExtension } from './createNavLogoExtension';
+
+jest.mock('@backstage/core-plugin-api', () => ({
+  ...jest.requireActual('@backstage/core-plugin-api'),
+}));
+
+describe('createNavLogoExtension', () => {
+  it('creates the extension properly', () => {
+    expect(
+      createNavLogoExtension({
+        id: 'test',
+        logoFull: <div>Logo Full</div>,
+        logoIcon: <div>Logo Icon</div>,
+      }),
+    ).toEqual({
+      $$type: '@backstage/Extension',
+      id: 'test',
+      attachTo: { id: 'core.nav', input: 'logos' },
+      disabled: false,
+      inputs: {},
+      output: {
+        logos: expect.anything(),
+      },
+      factory: expect.any(Function),
+    });
+  });
+});

packages/frontend-plugin-api/src/extensions/createNavLogoExtension.tsx

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed 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 { coreExtensionData, createExtension } from '../wiring';
+
+/**
+ * Helper for creating extensions for a nav logos.
+ * @public
+ */
+export function createNavLogoExtension(options: {
+  id: string;
+  logoIcon: JSX.Element;
+  logoFull: JSX.Element;
+}) {
+  const { id, logoIcon, logoFull } = options;
+  return createExtension({
+    id,
+    attachTo: { id: 'core.nav', input: 'logos' },
+    output: {
+      logos: coreExtensionData.logoElements,
+    },
+    factory: () => {
+      return {
+        logos: {
+          logoIcon,
+          logoFull,
+        },
+      };
+    },
+  });
+}

packages/frontend-plugin-api/src/wiring/coreExtensionData.ts

@@ -30,6 +30,12 @@ export type NavTarget = {
   routeRef: RouteRef<undefined>;
 };
 
+/** @public */
+export type LogoElements = {
+  logoIcon?: JSX.Element;
+  logoFull?: JSX.Element;
+};
+
 /** @public */
 export const coreExtensionData = {
   reactElement: createExtensionDataRef<JSX.Element>('core.reactElement'),
@@ -38,4 +44,5 @@ export const coreExtensionData = {
   routeRef: createExtensionDataRef<RouteRef>('core.routing.ref'),
   navTarget: createExtensionDataRef<NavTarget>('core.nav.target'),
   theme: createExtensionDataRef<AppTheme>('core.theme'),
+  logoElements: createExtensionDataRef<LogoElements>('core.logos'),
 };

packages/frontend-plugin-api/src/wiring/index.ts

@@ -14,7 +14,11 @@
  * limitations under the License.
  */
 
-export { coreExtensionData, type NavTarget } from './coreExtensionData';
+export {
+  coreExtensionData,
+  type LogoElements,
+  type NavTarget,
+} from './coreExtensionData';
 export {
   createExtension,
   type Extension,