Adding MainContainer, ActiveMainContext, and related files (#195)

* Introducing SkipToLinks to the ApplicationContainer.

* Adding wdio tests

* Adding CHANGELOG entry

* Adding newlines

* Copying files from integration branch

* Updating implementation to be more straightforward.

* Final API updates. Adding tests.

* Adding node version range

* Working around flaky tests

* Removing unnecessary default

* Adding comment

Author: tbiethman

CHANGELOG.md

@@ -10,6 +10,7 @@
   * Adding SessionContext
   * ApplicationBase updates
   * Adding SkipToLink
+  * Adding MainContainer
 
 ## Unreleased
 

package.json

@@ -7,7 +7,7 @@
   "version": "1.35.0",
   "description": "A framework to support application development with Terra components",
   "engines": {
-    "node": ">=10"
+    "node": ">=10 <13"
   },
   "repository": {
     "type": "git",
@@ -104,7 +104,6 @@
     "terra-slide-panel-manager": "^5.19.0",
     "terra-status-view": "^4.10.0",
     "terra-theme-context": "^1.0.0",
-    "terra-theme-provider": "^4.0.0",
     "terra-toolbar": "^1.20.0",
     "terra-visually-hidden-text": "^2.30.0",
     "uuid": "^3.0.0",

src/application-container/ApplicationContainer.jsx

@@ -4,6 +4,7 @@ import classNames from 'classnames/bind';
 
 import { NavigationPromptCheckpoint } from '../navigation-prompt';
 import WindowManager from '../utils/window-manager';
+import ActiveMainProvider from '../main-container/private/ActiveMainProvider';
 
 import ApplicationContainerErrorBoundary from './private/ApplicationContainerErrorBoundary';
 import useSkipToLinks from './private/skip-to-links/useSkipToLinks';
@@ -63,9 +64,11 @@ const ApplicationContainer = ({
       <div className={cx('application-container')} data-testid="application-container">
         <SkipToLinks />
         <SkipToLinksProvider>
-          <ApplicationContainerErrorBoundary>
-            {children}
-          </ApplicationContainerErrorBoundary>
+          <ActiveMainProvider>
+            <ApplicationContainerErrorBoundary>
+              {children}
+            </ApplicationContainerErrorBoundary>
+          </ActiveMainProvider>
         </SkipToLinksProvider>
       </div>
     </NavigationPromptCheckpoint>

src/application-container/index.js

@@ -1,5 +1,4 @@
 import ApplicationContainer from './ApplicationContainer';
-import useActiveMainPage from './useActiveMainPage';
 import ApplicationContainerContext, {
   useApplicationContainer,
   contextShape as applicationContainerContextShape,
@@ -11,7 +10,6 @@ import ApplicationConceptContext, {
 
 export default ApplicationContainer;
 export {
-  useActiveMainPage,
   ApplicationContainerContext,
   useApplicationContainer,
   applicationContainerContextShape,

src/application-container/private/active-main-page/ActiveMainPageContext.jsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+/**
+ * The ActiveMainContext is used to communicate data related to the current
+ * active main content to the application.
+ */
+const ActiveMainContext = React.createContext({});
+
+/**
+ * Hook to simplify consumption of the ActiveMainContext.
+ * @returns The ActiveMainContext value found at the consuming render location.
+ */
+const useActiveMain = () => React.useContext(ActiveMainContext);
+
+const contextShape = {
+  /**
+   * The string label describing the active main content to be used for display purposes.
+   */
+  label: PropTypes.string,
+  /**
+   * A collection of data related to the active main content.
+   */
+  metaData: PropTypes.object,
+};
+
+export default ActiveMainContext;
+export { useActiveMain, contextShape };

src/application-container/useActiveMainPage.jsx

@@ -0,0 +1,105 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import classNames from 'classnames';
+import classNamesBind from 'classnames/bind';
+
+import { ApplicationIntlContext } from '../application-intl';
+import SkipToLink from '../application-container/private/skip-to-links/SkipToLink';
+import NavigationItemContext from '../navigation-item/NavigationItemContext';
+
+import ActiveMainRegistrationContext from './private/ActiveMainRegistrationContext';
+
+import styles from './MainContainer.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const propTypes = {
+  /**
+   * The elements to render within the main element.
+   */
+  children: PropTypes.node,
+  /**
+   * A string label describing the content within the main element. This value
+   * will be applied to the element as a user-facing aria-label and should be
+   * translated, if necessary. It will also be provided to consumers of the
+   * ActiveMainContext when this element is active.
+   */
+  label: PropTypes.string.isRequired,
+  /**
+   * An object containing meta data related to the main element. This data is
+   * provided to consumers of the ActiveMainContext to provide additional
+   * information regarding the active main content.
+   */
+  metaData: PropTypes.object,
+  /**
+   * A function to be called when a ref has been assigned for the created
+   * `<main>` element.
+   */
+  refCallback: PropTypes.func,
+};
+
+/**
+ * The MainContainer can be used to create a semantic `<main>` element for the
+ * application, within which the application's most important and dynamic
+ * content will reside. A SkipToLink will be registered automatically to ensure
+ * this content can be accessed quickly.
+ */
+const MainContainer = ({
+  children, refCallback, label, metaData, ...otherProps
+}) => {
+  const applicationIntl = React.useContext(ApplicationIntlContext);
+  const activeMainRegistration = React.useContext(ActiveMainRegistrationContext);
+  const navigationItem = React.useContext(NavigationItemContext);
+
+  const mainElementRef = React.useRef();
+  const unregisterActiveMainRef = React.useRef();
+
+  React.useEffect(() => {
+    unregisterActiveMainRef.current = activeMainRegistration.register({
+      label,
+      metaData,
+    });
+  }, [
+    activeMainRegistration,
+    label,
+    metaData,
+    navigationItem.isActive,
+    navigationItem.navigationKeys,
+  ]);
+
+  React.useEffect(() => () => {
+    // A separate effect is used to unregister the active main when it is
+    // unmounted to limit registration thrash on updates to props.
+    unregisterActiveMainRef.current();
+  }, []);
+
+  return (
+    <main
+      aria-label={label}
+      className={classNames(cx('main-container'), otherProps.className)}
+      tabIndex="-1"
+      ref={(mainRef) => {
+        mainElementRef.current = mainRef;
+
+        if (refCallback) {
+          refCallback(mainRef);
+        }
+      }}
+      {...otherProps}
+    >
+      <SkipToLink
+        description={applicationIntl.formatMessage({
+          id: 'terraApplication.mainContainer.skipToLabel',
+        })}
+        onSelect={() => {
+          mainElementRef.current.focus();
+        }}
+      />
+      {children}
+    </main>
+  );
+};
+
+MainContainer.propTypes = propTypes;
+
+export default MainContainer;

src/main-container/ActiveMainContext.jsx

@@ -0,0 +1,5 @@
+:local {
+  .main-container {
+    outline: none;
+  }
+}

src/main-container/MainContainer.jsx

@@ -0,0 +1,8 @@
+import MainContainer from './MainContainer';
+import ActiveMainContext, {
+  useActiveMain,
+  contextShape as activeMainContextShape,
+} from './ActiveMainContext';
+
+export default MainContainer;
+export { ActiveMainContext, useActiveMain, activeMainContextShape };