Update documentation & add changeset

Signed-off-by: Philipp Hugenroth <philipph@spotify.com>

.changeset/fuzzy-olives-impress.md

@@ -0,0 +1,8 @@
+---
+'@backstage/core-components': patch
+'@backstage/plugin-catalog': patch
+'@backstage/plugin-shortcuts': patch
+'@backstage/plugin-user-settings': patch
+---
+
+Add `MobileSidebar` component & use it for smaller screens to improve the UX on mobile devices by switching to a navigation at the bottom of the screen. For customizing the experience you can group `SidebarItems` in a `SidebarGroup` or create a `SidebarGroup` with a link. For an example take a look at the `Root.tsx` or the updated ["Adding a plugin page to the Sidebar"](https://backstage.io/docs/getting-started/configure-app-with-plugins) documentation.

docs/getting-started/configure-app-with-plugins.md

@@ -90,3 +90,20 @@ extension to `.icon.svg`. For example:
 ```ts
 import InternalToolIcon from './internal-tool.icon.svg';
 ```
+
+On mobile devices the `Sidebar` is displayed at the bottom of the screen. For
+customizing the experience you can group `SidebarItems` in a `SidebarGroup` or
+create a `SidebarGroup` with a link. All `SidebarGroups` are displayed in the
+bottom navigation with an icon.
+
+```ts
+// ... inside the AppSidebar component
+<SidebarGroup icon={<MenuIcon />} label="Menu">
+  ...
+  <SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
+  ...
+<SidebarGroup />
+```
+
+If no `SidebarGroup`is provided a default menu will display the `Sidebar`
+content.

packages/app/src/components/Root/Root.tsx

@@ -81,52 +81,42 @@ const SidebarLogo = () => {
   );
 };
 
-export const Root = ({ children }: PropsWithChildren<{}>) => {
-  return (
-    <SidebarPage>
-      <Sidebar>
-        <SidebarLogo />
-        <SidebarGroup label="Search" icon={<SearchIcon />} to="/search">
-          <SidebarSearch />
-        </SidebarGroup>
-        <SidebarDivider />
-        {/* Global nav, not org-specific */}
-        <SidebarGroup label="Menu" icon={<MenuIcon />}>
-          <SidebarItem icon={HomeIcon} to="catalog" text="Home" />
-          <SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
-          <SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
-          <SidebarItem icon={LayersIcon} to="explore" text="Explore" />
-          <SidebarItem
-            icon={CreateComponentIcon}
-            to="create"
-            text="Create..."
-          />
-          {/* End global nav */}
-          <SidebarDivider />
-          <SidebarScrollWrapper>
-            <SidebarItem icon={MapIcon} to="tech-radar" text="Tech Radar" />
-            <SidebarItem icon={RuleIcon} to="lighthouse" text="Lighthouse" />
-            <SidebarItem
-              icon={MoneyIcon}
-              to="cost-insights"
-              text="Cost Insights"
-            />
-            <SidebarItem icon={GraphiQLIcon} to="graphiql" text="GraphiQL" />
-          </SidebarScrollWrapper>
-          <SidebarDivider />
-          <Shortcuts />
-        </SidebarGroup>
-        <SidebarSpace />
-        <SidebarDivider />
-        <SidebarGroup
-          label="Settings"
-          icon={<UserSettingsSignInAvatar />}
-          to="/settings"
-        >
-          <SidebarSettings />
-        </SidebarGroup>
-      </Sidebar>
-      {children}
-    </SidebarPage>
-  );
-};
+export const Root = ({ children }: PropsWithChildren<{}>) => (
+  <SidebarPage>
+    <Sidebar>
+      <SidebarLogo />
+      {/* <SidebarGroup label="Search" icon={<SearchIcon />} to="/search"> */}
+      <SidebarSearch />
+      {/* </SidebarGroup> */}
+      <SidebarDivider />
+      {/* Global nav, not org-specific */}
+      {/* <SidebarGroup label="Menu" icon={<MenuIcon />}> */}
+      <SidebarItem icon={HomeIcon} to="catalog" text="Home" />
+      <SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
+      <SidebarItem icon={LibraryBooks} to="docs" text="Docs" />
+      <SidebarItem icon={LayersIcon} to="explore" text="Explore" />
+      <SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
+      {/* End global nav */}
+      <SidebarDivider />
+      <SidebarScrollWrapper>
+        <SidebarItem icon={MapIcon} to="tech-radar" text="Tech Radar" />
+        <SidebarItem icon={RuleIcon} to="lighthouse" text="Lighthouse" />
+        <SidebarItem icon={MoneyIcon} to="cost-insights" text="Cost Insights" />
+        <SidebarItem icon={GraphiQLIcon} to="graphiql" text="GraphiQL" />
+      </SidebarScrollWrapper>
+      <SidebarDivider />
+      <Shortcuts />
+      {/* </SidebarGroup> */}
+      <SidebarSpace />
+      <SidebarDivider />
+      {/* <SidebarGroup
+        label="Settings"
+        icon={<UserSettingsSignInAvatar />}
+        to="/settings"
+      > */}
+      <SidebarSettings />
+      {/* </SidebarGroup> */}
+    </Sidebar>
+    {children}
+  </SidebarPage>
+);

packages/core-components/src/layout/Sidebar/MobileSidebar.tsx

@@ -22,11 +22,12 @@ import {
   makeStyles,
   Typography,
 } from '@material-ui/core';
+import CloseIcon from '@material-ui/icons/Close';
+import MenuIcon from '@material-ui/icons/Menu';
 import React, { createContext, useEffect, useState } from 'react';
 import { useLocation } from 'react-router';
 import { sidebarConfig } from './config';
 import { SidebarGroup } from './SidebarGroup';
-import CloseIcon from '@material-ui/icons/Close';
 
 type MobileSidebarContextType = {
   selectedMenuItemIndex: number;
@@ -115,8 +116,14 @@ export const MobileSidebar = ({ children }: React.PropsWithChildren<{}>) => {
   );
 
   if (!sidebarGroups) {
-    // error api
     return null; // think about the exception state
+  } else if (!sidebarGroups.length) {
+    // Render default SidebarGroup if no
+    sidebarGroups.push(
+      <SidebarGroup label="Menu" icon={<MenuIcon />}>
+        {children}
+      </SidebarGroup>,
+    );
   }
 
   const shouldShowGroupChildren =

packages/core-components/src/layout/Sidebar/Sidebar.stories.tsx

@@ -16,11 +16,13 @@
 
 import AddCircleOutlineIcon from '@material-ui/icons/AddCircleOutline';
 import HomeOutlinedIcon from '@material-ui/icons/HomeOutlined';
+import MenuIcon from '@material-ui/icons/Menu';
 import React from 'react';
 import { MemoryRouter } from 'react-router-dom';
 import {
   Sidebar,
   SidebarDivider,
+  SidebarGroup,
   SidebarIntro,
   SidebarItem,
   SidebarSearchField,
@@ -44,13 +46,15 @@ const handleSearch = (input: string) => {
 
 export const SampleSidebar = () => (
   <Sidebar>
-    <SidebarSearchField onSearch={handleSearch} to="/search" />
-    <SidebarDivider />
-    <SidebarItem icon={HomeOutlinedIcon} to="#" text="Home" />
-    <SidebarItem icon={HomeOutlinedIcon} to="#" text="Plugins" />
-    <SidebarItem icon={AddCircleOutlineIcon} to="#" text="Create..." />
-    <SidebarDivider />
-    <SidebarIntro />
-    <SidebarSpace />
+    <SidebarGroup label="Menu" icon={MenuIcon}>
+      <SidebarSearchField onSearch={handleSearch} to="/search" />
+      <SidebarDivider />
+      <SidebarItem icon={HomeOutlinedIcon} to="#" text="Home" />
+      <SidebarItem icon={HomeOutlinedIcon} to="#" text="Plugins" />
+      <SidebarItem icon={AddCircleOutlineIcon} to="#" text="Create..." />
+      <SidebarDivider />
+      <SidebarIntro />
+      <SidebarSpace />
+    </SidebarGroup>
   </Sidebar>
 );

plugins/cost-insights/README.md

@@ -79,21 +79,27 @@ To expose the plugin to your users, you can integrate the `cost-insights` route
  export const AppSidebar = () => (
    <Sidebar>
      <SidebarLogo />
-     <SidebarSearch />
+     <SidebarGroup icon={<SearchIcon />} to="/search">
+       <SidebarSearch />
+     </SidebarGroup>
      <SidebarDivider />
      {/* Global nav, not org-specific */}
-     <SidebarItem icon={HomeIcon} to="./" text="Home" />
-     <SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
-     <SidebarItem icon={LibraryBooks} to="/docs" text="Docs" />
-     <SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
-     <SidebarDivider />
-     <SidebarItem icon={MapIcon} to="tech-radar" text="Tech Radar" />
-+    <SidebarItem icon={MoneyIcon} to="cost-insights" text="Cost Insights" />
+     <SidebarGroup label="Menu" icon={<MenuIcon />}>
+       <SidebarItem icon={HomeIcon} to="./" text="Home" />
+       <SidebarItem icon={ExtensionIcon} to="api-docs" text="APIs" />
+       <SidebarItem icon={LibraryBooks} to="/docs" text="Docs" />
+       <SidebarItem icon={CreateComponentIcon} to="create" text="Create..." />
+       <SidebarDivider />
+       <SidebarItem icon={MapIcon} to="tech-radar" text="Tech Radar" />
+  +    <SidebarItem icon={MoneyIcon} to="cost-insights" text="Cost Insights" />
+     </SidebarGroup>
      {/* End global nav */}
      <SidebarDivider />
      <SidebarSpace />
      <SidebarDivider />
-     <SidebarSettings />
+     <SidebarGroup icon={<UserSettingsSignInAvatar />} to="/settings">
+       <SidebarSettings />
+     </SidebarGroup>
    </Sidebar>
  );
 ```