Merge pull request #8455 from Sarabadu/master

[RFC] LayoutProvider and focusContent

.changeset/eight-insects-tan.md

@@ -0,0 +1,6 @@
+---
+'@backstage/core-components': patch
+---
+
+- Add `useContent` hook to have a reference to the current main content element
+- Sets the main content reference on `Content` component

.changeset/eleven-sloths-shake.md

@@ -0,0 +1,5 @@
+---
+'@backstage/plugin-search': patch
+---
+
+Removes the focus from the sidebar and focus the main content after select one search result or navigate to the search result list

packages/core-components/api-report.md

@@ -2403,6 +2403,12 @@ export function TrendLine(
     },
 ): JSX.Element | null;
 
+// @public
+export function useContent(): {
+  focusContent: () => void;
+  contentRef: React_2.MutableRefObject<HTMLElement | null> | undefined;
+};
+
 // Warning: (ae-forgotten-export) The symbol "SetQueryParams" needs to be exported by the entry point index.d.ts
 // Warning: (ae-missing-release-tag) "useQueryParamState" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //

packages/core-components/src/layout/Content/Content.tsx

@@ -17,6 +17,7 @@
 import { makeStyles, Theme } from '@material-ui/core/styles';
 import classNames from 'classnames';
 import React, { PropsWithChildren } from 'react';
+import { useContent } from '../Sidebar';
 
 /** @public */
 export type BackstageContentClassKey = 'root' | 'stretch' | 'noPadding';
@@ -62,9 +63,14 @@ type Props = {
 
 export function Content(props: PropsWithChildren<Props>) {
   const { className, stretch, noPadding, children, ...restProps } = props;
+
+  const { contentRef } = useContent();
+
   const classes = useStyles();
   return (
     <article
+      ref={contentRef}
+      tabIndex={-1}
       {...restProps}
       className={classNames(classes.root, className, {
         [classes.stretch]: stretch,

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

@@ -17,10 +17,13 @@
 import { makeStyles } from '@material-ui/core/styles';
 import useMediaQuery from '@material-ui/core/useMediaQuery';
 import classnames from 'classnames';
+
 import React, { useState, useContext, useRef } from 'react';
+import Button from '@material-ui/core/Button';
+
 import { sidebarConfig, SidebarContext } from './config';
 import { BackstageTheme } from '@backstage/theme';
-import { SidebarPinStateContext } from './Page';
+import { SidebarPinStateContext, useContent } from './Page';
 import { MobileSidebar } from './MobileSidebar';
 
 /** @public */
@@ -60,6 +63,15 @@ const useStyles = makeStyles<BackstageTheme>(
         duration: theme.transitions.duration.shorter,
       }),
     },
+    visuallyHidden: {
+      top: 0,
+      position: 'absolute',
+      zIndex: 1000,
+      transform: 'translateY(-200%)',
+      '&:focus': {
+        transform: 'translateY(5px)',
+      },
+    },
   }),
   { name: 'BackstageSidebar' },
 );
@@ -158,25 +170,36 @@ const DesktopSidebar = (props: SidebarProps) => {
   };
 
   return (
-    <SidebarContext.Provider
-      value={{
-        isOpen,
-        setOpen,
-      }}
-    >
-      <div
-        onMouseEnter={handleOpen}
-        onFocus={handleOpen}
-        onMouseLeave={handleClose}
-        onBlur={handleClose}
-        data-testid="sidebar-root"
-        className={classnames(classes.drawer, {
-          [classes.drawerOpen]: isOpen,
-        })}
+    <div style={{}}>
+      <A11ySkipSidebar />
+      <SidebarContext.Provider
+        value={{
+          isOpen,
+          setOpen,
+        }}
       >
-        {children}
-      </div>
-    </SidebarContext.Provider>
+        <div
+          className={classes.root}
+          data-testid="sidebar-root"
+          onMouseEnter={disableExpandOnHover ? () => {} : handleOpen}
+          onFocus={
+            disableExpandOnHover ? () => {} : ignoreChildEvent(handleOpen)
+          }
+          onMouseLeave={disableExpandOnHover ? () => {} : handleClose}
+          onBlur={
+            disableExpandOnHover ? () => {} : ignoreChildEvent(handleClose)
+          }
+        >
+          <div
+            className={classnames(classes.drawer, {
+              [classes.drawerOpen]: isOpen,
+            })}
+          >
+            {children}
+          </div>
+        </div>
+      </SidebarContext.Provider>
+    </div>
   );
 };
 
@@ -201,3 +224,31 @@ export const Sidebar = (props: SidebarProps) => {
     </DesktopSidebar>
   );
 };
+
+function A11ySkipSidebar() {
+  const { focusContent, contentRef } = useContent();
+  const classes = useStyles();
+
+  if (!contentRef?.current) {
+    return null;
+  }
+  return (
+    <Button
+      onClick={focusContent}
+      variant="contained"
+      className={classnames(classes.visuallyHidden)}
+    >
+      Skip to content
+    </Button>
+  );
+}
+
+function ignoreChildEvent(handlerFn: (e?: any) => void) {
+  // TODO type the event
+  return (event: any) => {
+    const currentTarget = event?.currentTarget as HTMLElement;
+    if (!currentTarget?.contains(event.relatedTarget as HTMLElement)) {
+      handlerFn(event);
+    }
+  };
+}

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

@@ -15,7 +15,16 @@
  */
 
 import { makeStyles } from '@material-ui/core/styles';
-import React, { createContext, useEffect, useState } from 'react';
+
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
 import { sidebarConfig } from './config';
 import { BackstageTheme } from '@backstage/theme';
 import { LocalStorage } from './localStorage';
@@ -28,6 +37,7 @@ const useStyles = makeStyles<BackstageTheme, { isPinned: boolean }>(
     root: {
       width: '100%',
       transition: 'padding-left 0.1s ease-out',
+      isolation: 'isolate',
       [theme.breakpoints.up('sm')]: {
         paddingLeft: ({ isPinned }) =>
           isPinned
@@ -38,6 +48,13 @@ const useStyles = makeStyles<BackstageTheme, { isPinned: boolean }>(
         paddingBottom: sidebarConfig.mobileSidebarHeight,
       },
     },
+    content: {
+      zIndex: 0,
+      isolation: 'isolate',
+      '&:focus': {
+        outline: 0,
+      },
+    },
   }),
   { name: 'BackstageSidebarPage' },
 );
@@ -75,11 +92,33 @@ export const SidebarPinStateContext = createContext<SidebarPinStateContextType>(
   },
 );
 
+type PageContextType = {
+  content: {
+    contentRef?: React.MutableRefObject<HTMLElement | null>;
+  };
+};
+
+const PageContext = createContext<PageContextType>({
+  content: {
+    contentRef: undefined,
+  },
+});
 export function SidebarPage(props: SidebarPageProps) {
   const [isPinned, setIsPinned] = useState(() =>
     LocalStorage.getSidebarPinState(),
   );
 
+  const contentRef = useRef(null);
+
+  const pageContext = useMemo(
+    () => ({
+      content: {
+        contentRef,
+      },
+    }),
+    [contentRef],
+  );
+
   useEffect(() => {
     LocalStorage.setSidebarPinState(isPinned);
   }, [isPinned]);
@@ -92,6 +131,7 @@ export function SidebarPage(props: SidebarPageProps) {
   const toggleSidebarPinState = () => setIsPinned(!isPinned);
 
   const classes = useStyles({ isPinned });
+
   return (
     <SidebarPinStateContext.Provider
       value={{
@@ -100,7 +140,43 @@ export function SidebarPage(props: SidebarPageProps) {
         isMobile,
       }}
     >
-      <div className={classes.root}>{props.children}</div>
+      <PageContext.Provider value={pageContext}>
+        <div className={classes.root}>{props.children}</div>
+      </PageContext.Provider>
     </SidebarPinStateContext.Provider>
   );
 }
+
+/**
+ * This hook provides a react ref to the main content.
+ * Allows to set an element as the main content and focus on that component.
+ *
+ * *Note: If `contentRef` is not set `focusContent` is noop. `Content` component sets this ref automaticaly*
+ *
+ * @public
+ * @example
+ * Focus current content
+ * ```tsx
+ *  const { focusContent} = useContent();
+ * ...
+ *  <Button onClick={focusContent}>
+ *     focus main content
+ *  </Button>
+ * ```
+ * @example
+ * Set the reference to an Html element
+ * ```
+ *  const { contentRef } = useContent();
+ * ...
+ *  <article ref={contentRef} tabIndex={-1}>Main Content</article>
+ * ```
+ */
+export function useContent() {
+  const { content } = useContext(PageContext);
+
+  const focusContent = useCallback(() => {
+    content?.contentRef?.current?.focus();
+  }, [content]);
+
+  return { focusContent, contentRef: content?.contentRef };
+}

packages/core-components/src/layout/Sidebar/index.ts

@@ -30,6 +30,7 @@ export type { SidebarClassKey, SidebarProps } from './Bar';
 export {
   SidebarPage,
   SidebarPinStateContext as SidebarPinStateContext,
+  useContent,
 } from './Page';
 export type {
   SidebarPinStateContextType as SidebarPinStateContextType,

plugins/search/src/components/SearchModal/SearchModal.tsx

@@ -24,6 +24,7 @@ import {
   Grid,
   List,
   Paper,
+  useTheme,
 } from '@material-ui/core';
 import LaunchIcon from '@material-ui/icons/Launch';
 import { makeStyles } from '@material-ui/core/styles';
@@ -33,7 +34,7 @@ import { SearchResult } from '../SearchResult';
 import { SearchContextProvider, useSearch } from '../SearchContext';
 import { SearchResultPager } from '../SearchResultPager';
 import { useRouteRef } from '@backstage/core-plugin-api';
-import { Link } from '@backstage/core-components';
+import { Link, useContent } from '@backstage/core-components';
 import { rootRouteRef } from '../../plugin';
 
 export interface SearchModalProps {
@@ -61,9 +62,12 @@ export const Modal = ({ open = true, toggleModal }: SearchModalProps) => {
   const classes = useStyles();
 
   const { term } = useSearch();
+  const { focusContent } = useContent();
+  const { transitions } = useTheme();
 
   const handleResultClick = () => {
     toggleModal();
+    setTimeout(focusContent, transitions.duration.leavingScreen);
   };
 
   const handleKeyPress = () => {
@@ -94,7 +98,13 @@ export const Modal = ({ open = true, toggleModal }: SearchModalProps) => {
           alignItems="center"
         >
           <Grid item>
-            <Link onClick={toggleModal} to={`${getSearchLink()}?query=${term}`}>
+            <Link
+              onClick={() => {
+                toggleModal();
+                setTimeout(focusContent, transitions.duration.leavingScreen);
+              }}
+              to={`${getSearchLink()}?query=${term}`}
+            >
               <span className={classes.viewResultsLink}>View Full Results</span>
               <LaunchIcon color="primary" />
             </Link>

plugins/search/src/components/SidebarSearch/SidebarSearch.tsx

@@ -18,8 +18,8 @@ import React, { useCallback } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { rootRouteRef } from '../../plugin';
 
-import { SidebarSearchField } from '@backstage/core-components';
 import { useRouteRef, IconComponent } from '@backstage/core-plugin-api';
+import { SidebarSearchField, useContent } from '@backstage/core-components';
 
 export type SidebarSearchProps = {
   icon?: IconComponent;
@@ -27,14 +27,15 @@ export type SidebarSearchProps = {
 
 export const SidebarSearch = (props: SidebarSearchProps) => {
   const searchRoute = useRouteRef(rootRouteRef);
+  const { focusContent } = useContent();
   const navigate = useNavigate();
   const handleSearch = useCallback(
     (query: string): void => {
       const queryString = qs.stringify({ query }, { addQueryPrefix: true });
-
+      focusContent();
       navigate(`${searchRoute()}${queryString}`);
     },
-    [navigate, searchRoute],
+    [focusContent, navigate, searchRoute],
   );
 
   return (