@edx/frontend-platform 4.6.0 → 4.6.2

package/src/pubSub.js

@@ -0,0 +1,47 @@
+/**
+ * #### Import members from **@edx/frontend-platform**
+ *
+ * The PubSub module is a thin wrapper around the base functionality of
+ * [PubSubJS](https://github.com/mroderick/PubSubJS).  For the sake of simplicity and not relying
+ * too heavily on implementation-specific features, it maintains a fairly simple API (subscribe,
+ * unsubscribe, and publish).
+ *
+ * Publish/Subscribe events should be used mindfully, especially in relation to application UI
+ * frameworks like React.  Given React's unidirectional data flow and prop/state management
+ * capabilities, using a pub/sub mechanism is at odds with that framework's best practices.
+ *
+ * That said, we use pub/sub in our application initialization sequence to allow applications to
+ * hook into the initialization lifecycle, and we also use them to publish when the application
+ * state has changed, i.e., when the config document or user's authentication state have changed.
+ *
+ * @module PubSub
+ */
+
+import PubSub from 'pubsub-js';
+
+/**
+ *
+ * @param {string} type
+ * @param {function} callback
+ * @returns {string} A subscription token that can be passed to `unsubscribe`
+ */
+export function subscribe(type, callback) {
+  return PubSub.subscribe(type, callback);
+}
+
+/**
+ *
+ * @param {string} token A subscription token provided by `subscribe`
+ */
+export function unsubscribe(token) {
+  return PubSub.unsubscribe(token);
+}
+
+/**
+ *
+ * @param {string} type
+ * @param {Object} data
+ */
+export function publish(type, data) {
+  return PubSub.publish(type, data);
+}

package/src/react/AppContext.jsx

@@ -0,0 +1,24 @@
+import React from 'react';
+
+/**
+ * `AppContext` provides data from `App` in a way that React components can readily consume, even
+ * if it's mutable data. `AppContext` contains the following data structure:
+ *
+ * ```
+ * {
+ *   authenticatedUser: <THE App.authenticatedUser OBJECT>,
+ *   config: <THE App.config OBJECT>
+ * }
+ * ```
+ * If the `App.authenticatedUser` or `App.config` data changes, `AppContext` will be updated
+ * accordingly and pass those changes onto React components using the context.
+ *
+ * `AppContext` is used in a React application like any other `[React Context](https://reactjs.org/docs/context.html)
+ * @memberof module:React
+ */
+const AppContext = React.createContext({
+  authenticatedUser: null,
+  config: {},
+});
+
+export default AppContext;

package/src/react/AppProvider.jsx

@@ -0,0 +1,93 @@
+import React, { useState, useMemo } from 'react';
+import PropTypes from 'prop-types';
+import { Router } from 'react-router-dom';
+
+import OptionalReduxProvider from './OptionalReduxProvider';
+
+import ErrorBoundary from './ErrorBoundary';
+import AppContext from './AppContext';
+import { useAppEvent, useTrackColorSchemeChoice } from './hooks';
+import { getAuthenticatedUser, AUTHENTICATED_USER_CHANGED } from '../auth';
+import { getConfig } from '../config';
+import { CONFIG_CHANGED } from '../constants';
+import { history } from '../initialize';
+import {
+  getLocale,
+  getMessages,
+  IntlProvider,
+  LOCALE_CHANGED,
+} from '../i18n';
+
+/**
+ * A wrapper component for React-based micro-frontends to initialize a number of common data/
+ * context providers.
+ *
+ * ```
+ * subscribe(APP_READY, () => {
+ *   ReactDOM.render(
+ *     <AppProvider>
+ *       <HelloWorld />
+ *     </AppProvider>
+ *   )
+ * });
+ * ```
+ *
+ * This will provide the following to HelloWorld:
+ * - An error boundary as described above.
+ * - An `AppContext` provider for React context data.
+ * - IntlProvider for @edx/frontend-i18n internationalization
+ * - Optionally a redux `Provider`. Will only be included if a `store` property is passed to
+ * `AppProvider`.
+ * - A `Router` for react-router.
+ *
+ * @param {Object} props
+ * @param {Object} [props.store] A redux store.
+ * @memberof module:React
+ */
+export default function AppProvider({ store, children }) {
+  const [config, setConfig] = useState(getConfig());
+  const [authenticatedUser, setAuthenticatedUser] = useState(getAuthenticatedUser());
+  const [locale, setLocale] = useState(getLocale());
+
+  useTrackColorSchemeChoice();
+
+  useAppEvent(AUTHENTICATED_USER_CHANGED, () => {
+    setAuthenticatedUser(getAuthenticatedUser());
+  });
+
+  useAppEvent(CONFIG_CHANGED, () => {
+    setConfig(getConfig());
+  });
+
+  useAppEvent(LOCALE_CHANGED, () => {
+    setLocale(getLocale());
+  });
+
+  const appContextValue = useMemo(() => ({ authenticatedUser, config, locale }), [authenticatedUser, config, locale]);
+
+  return (
+    <IntlProvider locale={locale} messages={getMessages()}>
+      <ErrorBoundary>
+        <AppContext.Provider
+          value={appContextValue}
+        >
+          <OptionalReduxProvider store={store}>
+            <Router history={history}>
+              {children}
+            </Router>
+          </OptionalReduxProvider>
+        </AppContext.Provider>
+      </ErrorBoundary>
+    </IntlProvider>
+  );
+}
+
+AppProvider.propTypes = {
+  // eslint-disable-next-line react/forbid-prop-types
+  store: PropTypes.object,
+  children: PropTypes.node.isRequired,
+};
+
+AppProvider.defaultProps = {
+  store: null,
+};

package/src/react/AuthenticatedPageRoute.jsx

@@ -0,0 +1,60 @@
+import React, { useContext } from 'react';
+import PropTypes from 'prop-types';
+import { useRouteMatch } from 'react-router-dom';
+
+import AppContext from './AppContext';
+import PageRoute from './PageRoute';
+import { getLoginRedirectUrl } from '../auth';
+
+/**
+ * A react-router route that redirects to the login page when the route becomes active and the user
+ * is not authenticated.  If the application has been initialized with `requireAuthenticatedUser`
+ * false, an authenticatedPageRoute can be used to protect a subset of the application's routes,
+ * rather than the entire application.
+ *
+ * It can optionally accept an override URL to redirect to instead of the login page.
+ *
+ * Like a `PageRoute`, also calls `sendPageEvent` when the route becomes active.
+ *
+ * @see PageRoute
+ * @see {@link module:frontend-platform/analytics~sendPageEvent}
+ * @memberof module:React
+ * @param {Object} props
+ * @param {string} props.redirectUrl The URL anonymous users should be redirected to, rather than
+ * viewing the route's contents.
+ */
+export default function AuthenticatedPageRoute({ redirectUrl, ...props }) {
+  const { authenticatedUser } = useContext(AppContext);
+
+  const match = useRouteMatch({
+    // eslint-disable-next-line react/prop-types
+    path: props.path,
+    // eslint-disable-next-line react/prop-types
+    exact: props.exact,
+    // eslint-disable-next-line react/prop-types
+    strict: props.strict,
+    // eslint-disable-next-line react/prop-types
+    sensitive: props.sensitive,
+  });
+
+  if (authenticatedUser === null) {
+    if (match) {
+      const destination = redirectUrl || getLoginRedirectUrl(global.location.href);
+      global.location.assign(destination);
+    }
+    // This emulates a Route's way of displaying nothing if the route's path doesn't match the
+    // current URL.
+    return null;
+  }
+  return (
+    <PageRoute {...props} />
+  );
+}
+
+AuthenticatedPageRoute.propTypes = {
+  redirectUrl: PropTypes.string,
+};
+
+AuthenticatedPageRoute.defaultProps = {
+  redirectUrl: null,
+};

package/src/react/ErrorBoundary.jsx

@@ -0,0 +1,44 @@
+import React, { Component } from 'react';
+import PropTypes from 'prop-types';
+
+import { logError } from '../logging';
+
+import ErrorPage from './ErrorPage';
+
+/**
+ * Error boundary component used to log caught errors and display the error page.
+ *
+ * @memberof module:React
+ * @extends {Component}
+ */
+export default class ErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError() {
+    // Update state so the next render will show the fallback UI.
+    return { hasError: true };
+  }
+
+  componentDidCatch(error, info) {
+    logError(error, { stack: info.componentStack });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <ErrorPage />;
+    }
+
+    return this.props.children;
+  }
+}
+
+ErrorBoundary.propTypes = {
+  children: PropTypes.node,
+};
+
+ErrorBoundary.defaultProps = {
+  children: null,
+};

package/src/react/ErrorPage.jsx

@@ -0,0 +1,76 @@
+import React, { useState } from 'react';
+import PropTypes from 'prop-types';
+import {
+  Button, Container, Row, Col,
+} from '@edx/paragon';
+
+import { useAppEvent } from './hooks';
+import {
+  FormattedMessage,
+  IntlProvider,
+  getMessages,
+  getLocale,
+  LOCALE_CHANGED,
+} from '../i18n';
+
+/**
+ * An error page that displays a generic message for unexpected errors.  Also contains a "Try
+ * Again" button to refresh the page.
+ *
+ * @memberof module:React
+ * @extends {Component}
+ */
+function ErrorPage({
+  message,
+}) {
+  const [locale, setLocale] = useState(getLocale());
+
+  useAppEvent(LOCALE_CHANGED, () => {
+    setLocale(getLocale());
+  });
+
+  /* istanbul ignore next */
+  const reload = () => {
+    global.location.reload();
+  };
+
+  return (
+    <IntlProvider locale={locale} messages={getMessages()}>
+      <Container fluid className="py-5 justify-content-center align-items-start text-center">
+        <Row>
+          <Col>
+            <p className="text-muted">
+              <FormattedMessage
+                id="unexpected.error.message.text"
+                defaultMessage="An unexpected error occurred. Please click the button below to refresh the page."
+                description="error message when an unexpected error occurs"
+              />
+            </p>
+            {message && (
+              <div role="alert" className="my-4">
+                <p>{message}</p>
+              </div>
+            )}
+            <Button onClick={reload}>
+              <FormattedMessage
+                id="unexpected.error.button.text"
+                defaultMessage="Try again"
+                description="text for button that tries to reload the app by refreshing the page"
+              />
+            </Button>
+          </Col>
+        </Row>
+      </Container>
+    </IntlProvider>
+  );
+}
+
+ErrorPage.propTypes = {
+  message: PropTypes.string,
+};
+
+ErrorPage.defaultProps = {
+  message: null,
+};
+
+export default ErrorPage;

package/src/react/LoginRedirect.jsx

@@ -0,0 +1,16 @@
+import { useEffect } from 'react';
+import { redirectToLogin } from '../auth';
+
+/**
+ * A React component that, when rendered, redirects to the login page as a side effect.  Uses
+ * `redirectToLogin` to perform the redirect.
+ *
+ * @see {@link module:frontend-platform/auth~redirectToLogin}
+ * @memberof module:React
+ */
+export default function LoginRedirect() {
+  useEffect(() => {
+    redirectToLogin(global.location.href);
+  }, []);
+  return null;
+}

package/src/react/OptionalReduxProvider.jsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { Provider } from 'react-redux';
+
+/**
+ * @memberof module:React
+ * @param {Object} props
+ */
+export default function OptionalReduxProvider({ store, children }) {
+  if (store === null) {
+    return children;
+  }
+
+  return (
+    <Provider store={store}>
+      {children}
+    </Provider>
+  );
+}
+
+OptionalReduxProvider.propTypes = {
+  store: PropTypes.object, // eslint-disable-line
+  children: PropTypes.node.isRequired,
+};
+
+OptionalReduxProvider.defaultProps = {
+  store: null,
+};

package/src/react/PageRoute.jsx

@@ -0,0 +1,31 @@
+/* eslint-disable react/prop-types */
+import React, { useEffect } from 'react';
+import { Route, useRouteMatch } from 'react-router-dom';
+import { sendPageEvent } from '../analytics';
+
+/**
+ * A react-router Route component that calls `sendPageEvent` when it becomes active.
+ *
+ * @see {@link module:frontend-platform/analytics~sendPageEvent}
+ * @memberof module:React
+ * @param {Object} props
+ */
+export default function PageRoute(props) {
+  const match = useRouteMatch({
+    path: props.path,
+    exact: props.exact,
+    strict: props.strict,
+    sensitive: props.sensitive,
+  });
+
+  useEffect(() => {
+    if (match) {
+      sendPageEvent();
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [JSON.stringify(match)]);
+
+  return (
+    <Route {...props} />
+  );
+}

package/src/react/hooks.js

@@ -0,0 +1,50 @@
+/* eslint-disable import/prefer-default-export */
+import { useEffect } from 'react';
+import { subscribe, unsubscribe } from '../pubSub';
+import { sendTrackEvent } from '../analytics';
+
+/**
+ * A React hook that allows functional components to subscribe to application events.  This should
+ * be used sparingly - for the most part, Context should be used higher-up in the application to
+ * provide necessary data to a given component, rather than utilizing a non-React-like Pub/Sub
+ * mechanism.
+ *
+ * @memberof module:React
+ * @param {string} type
+ * @param {function} callback
+ */
+export const useAppEvent = (type, callback) => {
+  useEffect(() => {
+    const subscriptionToken = subscribe(type, callback);
+
+    return function cleanup() {
+      unsubscribe(subscriptionToken);
+    };
+  }, [callback, type]);
+};
+
+/**
+ * A React hook that tracks user's preferred color scheme (light or dark) and sends respective
+ * event to the tracking service.
+ *
+ * @memberof module:React
+ */
+export const useTrackColorSchemeChoice = () => {
+  useEffect(() => {
+    const trackColorSchemeChoice = ({ matches }) => {
+      const preferredColorScheme = matches ? 'dark' : 'light';
+      sendTrackEvent('openedx.ui.frontend-platform.prefers-color-scheme.selected', { preferredColorScheme });
+    };
+    const colorSchemeQuery = window.matchMedia?.('(prefers-color-scheme: dark)');
+    if (colorSchemeQuery) {
+      // send user's initial choice
+      trackColorSchemeChoice(colorSchemeQuery);
+      colorSchemeQuery.addEventListener('change', trackColorSchemeChoice);
+    }
+    return () => {
+      if (colorSchemeQuery) {
+        colorSchemeQuery.removeEventListener('change', trackColorSchemeChoice);
+      }
+    };
+  }, []);
+};

package/src/react/index.js

@@ -0,0 +1,16 @@
+/**
+ * #### Import members from **@edx/frontend-platform/react**
+ * The React module provides a variety of React components, hooks, and contexts for use in an
+ * application.
+ *
+ * @module React
+ */
+
+export { default as AppContext } from './AppContext';
+export { default as AppProvider } from './AppProvider';
+export { default as AuthenticatedPageRoute } from './AuthenticatedPageRoute';
+export { default as ErrorBoundary } from './ErrorBoundary';
+export { default as ErrorPage } from './ErrorPage';
+export { default as LoginRedirect } from './LoginRedirect';
+export { default as PageRoute } from './PageRoute';
+export { useAppEvent } from './hooks';

package/src/scripts/GoogleAnalyticsLoader.js

@@ -0,0 +1,53 @@
+/**
+ * @implements {GoogleAnalyticsLoader}
+ * @memberof module:GoogleAnalytics
+ */
+class GoogleAnalyticsLoader {
+  constructor({ config }) {
+    this.analyticsId = config.GOOGLE_ANALYTICS_4_ID;
+  }
+
+  loadScript() {
+    if (!this.analyticsId) {
+      return;
+    }
+
+    global.googleAnalytics = global.googleAnalytics || [];
+    const { googleAnalytics } = global;
+
+    // If the snippet was invoked do nothing.
+    if (googleAnalytics.invoked) {
+      return;
+    }
+
+    // Invoked flag, to make sure the snippet
+    // is never invoked twice.
+    googleAnalytics.invoked = true;
+
+    googleAnalytics.load = (key, options) => {
+      const scriptSrc = document.createElement('script');
+      scriptSrc.type = 'text/javascript';
+      scriptSrc.async = true;
+      scriptSrc.src = `https://www.googletagmanager.com/gtag/js?id=${key}`;
+
+      const scriptGtag = document.createElement('script');
+      scriptGtag.innerHTML = `
+        window.dataLayer = window.dataLayer || [];
+        function gtag(){dataLayer.push(arguments);}
+        gtag('js', new Date());
+        gtag('config', '${key}');
+      `;
+
+      // Insert our scripts next to the first script element.
+      const first = document.getElementsByTagName('script')[0];
+      first.parentNode.insertBefore(scriptSrc, first);
+      first.parentNode.insertBefore(scriptGtag, first);
+      googleAnalytics._loadOptions = options; // eslint-disable-line no-underscore-dangle
+    };
+
+    // Load GoogleAnalytics with your key.
+    googleAnalytics.load(this.analyticsId);
+  }
+}
+
+export default GoogleAnalyticsLoader;

package/src/scripts/index.js

@@ -0,0 +1,2 @@
+/* eslint-disable import/prefer-default-export */
+export { default as GoogleAnalyticsLoader } from './GoogleAnalyticsLoader';

package/src/testing/index.js

@@ -0,0 +1,9 @@
+/**
+ * #### Import members from **@edx/frontend-platform/testing**
+ * The testing module provides helpers for writing tests in Jest.
+ *
+ * @module Testing
+ */
+
+export { default as initializeMockApp } from './initializeMockApp';
+export { default as mockMessages } from './mockMessages';

package/src/testing/initializeMockApp.js

@@ -0,0 +1,77 @@
+import { configure as configureAnalytics, MockAnalyticsService } from '../analytics';
+import { configure as configureI18n } from '../i18n';
+import { configure as configureLogging, MockLoggingService } from '../logging';
+import { configure as configureAuth, MockAuthService } from '../auth';
+import { getConfig } from '../config';
+import mockMessages from './mockMessages';
+
+/**
+ * Initializes a mock application for component testing. The mock application includes
+ * mock analytics, auth, and logging services, and the real i18n service.
+ *
+ * See MockAnalyticsService, MockAuthService, and MockLoggingService for mock implementation
+ * details. For the most part, the analytics and logging services just implement their functions
+ * with jest.fn() and do nothing else, whereas the MockAuthService actually has some behavior
+ * implemented, it just doesn't make any HTTP calls.
+ *
+ * Note that this mock application is not sufficient for testing the full application lifecycle or
+ * initialization callbacks/custom handlers as described in the 'initialize' function's
+ * documentation. It exists merely to set up the mock services that components themselves tend to
+ * interact with most often. It could be extended to allow for setting up custom handlers fairly
+ * easily, as this functionality would be more-or-less identical to what the real initialize
+ * function does.
+ *
+ * Example:
+ *
+ * ```
+ * import { initializeMockApp } from '@edx/frontend-platform/testing';
+ * import { logInfo } from '@edx/frontend-platform/logging';
+ *
+ * describe('initializeMockApp', () => {
+ *   it('mocks things correctly', () => {
+ *     const { loggingService } = initializeMockApp();
+ *     logInfo('test', {});
+ *     expect(loggingService.logInfo).toHaveBeenCalledWith('test', {});
+ *   });
+ * });
+ * ```
+ *
+ * @param {Object} [options]
+ * @param {*} [options.messages] A i18n-compatible messages object, or an array of such objects. If
+ * an array is provided, duplicate keys are resolved with the last-one-in winning.
+ * @param {UserData|null} [options.authenticatedUser] A UserData object representing the
+ * authenticated user. This is passed directly to MockAuthService.
+ * @memberof module:Testing
+ */
+export default function initializeMockApp({
+  messages = mockMessages,
+  authenticatedUser = null,
+} = {}) {
+  const loggingService = configureLogging(MockLoggingService, {
+    config: getConfig(),
+  });
+
+  const authService = configureAuth(MockAuthService, {
+    config: { ...getConfig(), authenticatedUser },
+    loggingService,
+  });
+
+  const analyticsService = configureAnalytics(MockAnalyticsService, {
+    config: getConfig(),
+    httpClient: authService.getAuthenticatedHttpClient(),
+    loggingService,
+  });
+
+  // The i18n service configure function has no return value, since there isn't a service class.
+  configureI18n({
+    config: getConfig(),
+    loggingService,
+    messages,
+  });
+
+  return {
+    analyticsService,
+    authService,
+    loggingService,
+  };
+}

package/src/testing/mockMessages.js

@@ -0,0 +1,21 @@
+/**
+ * An empty messages object suitable for fulfilling the i18n service's contract.
+ * @memberof module:Testing
+ */
+const messages = {
+  ar: {},
+  'es-419': {},
+  fr: {},
+  'zh-cn': {},
+  ca: {},
+  he: {},
+  id: {},
+  'ko-kr': {},
+  pl: {},
+  'pt-br': {},
+  ru: {},
+  th: {},
+  uk: {},
+};
+
+export default messages;