@openedx/frontend-base 1.0.0-alpha.0

package/runtime/logging/interface.js

@@ -0,0 +1,109 @@
+/**
+ * #### Import members from **@openedx/frontend-base logging**
+ *
+ * Contains a shared interface for logging information. (The default implementation is in
+ * NewRelicLoggingService.js.) When in development mode, all messages will instead be sent to the console.
+ *
+ * The `initialize` function performs much of the logging configuration for you.  If, however,
+ * you're not using the `initialize` function, logging (via New Relic) can be configured via:
+ *
+ * ```
+ * import { getSiteConfig, configureLogging, NewRelicLoggingService, logInfo, logError } from '@openedx/frontend-base';
+ *
+ * configureLogging(NewRelicLoggingService, {
+ *   config: getSiteConfig(),
+ * });
+ *
+ * logInfo('Just so you know...');
+ * logInfo(new Error('Unimportant error'), { type: 'unimportant' });
+ * logError('Uhoh!');
+ * logError(new Error('Uhoh error!'));
+ * ```
+ *
+ * As shown in this example, logging depends on the configuration document.
+ *
+ * @module Logging
+ */
+
+import PropTypes from 'prop-types';
+
+const optionsShape = {
+  config: PropTypes.object.isRequired,
+};
+
+const serviceShape = {
+  logInfo: PropTypes.func.isRequired,
+  logError: PropTypes.func.isRequired,
+};
+
+let service = null;
+
+/**
+ *
+ */
+export function configureLogging(LoggingService, options) {
+  PropTypes.checkPropTypes(optionsShape, options, 'property', 'Logging');
+  service = new LoggingService(options);
+  PropTypes.checkPropTypes(serviceShape, service, 'property', 'LoggingService');
+  return service;
+}
+
+/**
+ * Logs a message to the 'info' log level. Can accept custom attributes as a property of the error
+ * object, or as an optional second parameter.
+ *
+ * @param {string|Error} infoStringOrErrorObject
+ * @param {Object} [customAttributes={}]
+ */
+export function logInfo(infoStringOrErrorObject, customAttributes) {
+  return service.logInfo(infoStringOrErrorObject, customAttributes);
+}
+
+/**
+ * Logs a message to the 'error' log level.  Can accept custom attributes as a property of the error
+ * object, or as an optional second parameter.
+ *
+ * @param {string|Error} errorStringOrObject
+ * @param {Object} [customAttributes={}]
+ */
+export function logError(errorStringOrObject, customAttributes) {
+  return service.logError(errorStringOrObject, customAttributes);
+}
+
+/**
+ * Sets a custom attribute that will be included with all subsequent log messages.
+ *
+ * @param {string} name
+ * @param {string|number|null} value
+ */
+export function setCustomAttribute(name, value) {
+  return service.setCustomAttribute(name, value);
+}
+
+/**
+ *
+ * @throws {Error} Thrown if the logging service has not yet been configured via {@link configureLogging}.
+ * @returns {LoggingService}
+ */
+export function getLoggingService() {
+  if (!service) {
+    throw Error('You must first configure the logging service.');
+  }
+  return service;
+}
+
+/**
+ * Sets the configured logging service back to null.
+ *
+ */
+export function resetLoggingService() {
+  service = null;
+}
+
+/**
+ * @name LoggingService
+ * @interface
+ * @memberof module:Logging
+ * @property {function} logError
+ * @property {function} logInfo
+ */

package/runtime/logging/types.ts

@@ -0,0 +1,4 @@
+export interface LoggingService {
+  logError: (errorStringOrObject: string | Error, customAttributes: any) => void,
+  logInfo: (infoStringOrErrorObject: string | Error, customAttributes: any) => void,
+}

package/runtime/react/AuthenticatedPageRoute.jsx

@@ -0,0 +1,43 @@
+import PropTypes from 'prop-types';
+
+import { getLoginRedirectUrl } from '../auth';
+import PageWrap from './PageWrap';
+import { useAuthenticatedUser } from './hooks';
+
+/**
+ * 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 `PageWrap`, also calls `sendPageEvent` when the route becomes active.
+ *
+ * @see PageWrap
+ * @see {@link module:frontend-base~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 = null, children }) {
+  const authenticatedUser = useAuthenticatedUser();
+  if (authenticatedUser === null) {
+    const destination = redirectUrl || getLoginRedirectUrl(global.location.href);
+    global.location.assign(destination);
+
+    return null;
+  }
+
+  return (
+    <PageWrap>
+      {children}
+    </PageWrap>
+  );
+}
+
+AuthenticatedPageRoute.propTypes = {
+  redirectUrl: PropTypes.string,
+  children: PropTypes.node.isRequired,
+};

package/runtime/react/CombinedAppProvider.tsx

@@ -0,0 +1,46 @@
+import { ReactNode } from 'react';
+import { App, AppProvider } from '../../types';
+import { getSiteConfig } from '../config';
+
+const combineProviders = (providers: AppProvider[]): AppProvider => {
+  return providers.reduce(
+    (AccumulatedProviders, CurrentProvider) => {
+      // eslint-disable-next-line react/prop-types
+      const CombinedProvider: AppProvider = ({ children }) => (
+        <AccumulatedProviders>
+          <CurrentProvider>{children}</CurrentProvider>
+        </AccumulatedProviders>
+      );
+      return CombinedProvider;
+    },
+    ({ children }) => <>{children}</>,
+  );
+};
+
+interface CombinedAppProviderProps {
+  children: ReactNode,
+}
+
+export default function CombinedAppProvider({ children }: CombinedAppProviderProps) {
+  const { apps } = getSiteConfig();
+
+  let providers: AppProvider[] = [];
+
+  if (apps) {
+    apps.forEach(
+      (app: App) => {
+        if (Array.isArray(app.providers)) {
+          providers = providers.concat(app.providers);
+        }
+      }
+    );
+  }
+
+  const CombinedProviders = combineProviders(providers);
+
+  return (
+    <CombinedProviders>
+      {children}
+    </CombinedProviders>
+  );
+};

package/runtime/react/CurrentAppContext.tsx

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

package/runtime/react/CurrentAppProvider.tsx

@@ -0,0 +1,46 @@
+import { ReactNode, useMemo, useState } from 'react';
+
+import { getAppConfig } from '../config';
+import { CONFIG_CHANGED } from '../constants';
+
+import CurrentAppContext from './CurrentAppContext';
+import { useSiteEvent } from './hooks';
+
+interface CurrentAppProviderProps {
+  appId: string,
+  children: ReactNode,
+}
+
+/**
+ * A wrapper component for React-based micro-frontends to initialize a number of common data/
+ * context providers.
+ *
+ * ```
+ * <CurrentAppProvider appId="my.app">
+ *   <HelloWorld />
+ * </CurrentAppProvider>
+ * ```
+ *
+ * This will provide the following to HelloWorld:
+ * - A `CurrentAppContext` provider for React context data.
+ *
+ * @param {Object} props
+ * @memberof module:React
+ */
+export default function CurrentAppProvider({ appId, children }: CurrentAppProviderProps) {
+  const [appConfig, setAppConfig] = useState(getAppConfig(appId));
+
+  useSiteEvent(CONFIG_CHANGED, () => {
+    setAppConfig(getAppConfig(appId));
+  });
+
+  const appContextValue = useMemo(() => ({
+    appConfig,
+  }), [appConfig]);
+
+  return (
+    <CurrentAppContext.Provider value={appContextValue}>
+      {children}
+    </CurrentAppContext.Provider>
+  );
+}

package/runtime/react/Divider.tsx

@@ -0,0 +1,5 @@
+export default function Divider() {
+  return (
+    <hr className="w-100 my-2" />
+  );
+}

package/runtime/react/ErrorBoundary.jsx

@@ -0,0 +1,47 @@
+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}
+ */
+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 this.props.fallbackComponent || <ErrorPage />;
+    }
+    return this.props.children;
+  }
+}
+
+ErrorBoundary.propTypes = {
+  children: PropTypes.node,
+  fallbackComponent: PropTypes.node,
+};
+
+ErrorBoundary.defaultProps = {
+  children: null,
+  fallbackComponent: undefined,
+};
+
+export default ErrorBoundary;

package/runtime/react/ErrorPage.jsx

@@ -0,0 +1,72 @@
+import React, { useState } from 'react';
+import PropTypes from 'prop-types';
+import {
+  Button, Container, Row, Col,
+} from '@openedx/paragon';
+
+import { useSiteEvent } 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 = null,
+}) {
+  const [locale, setLocale] = useState(getLocale());
+
+  useSiteEvent(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" data-testid="error-page">
+        <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,
+};
+
+export default ErrorPage;

package/runtime/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-base~redirectToLogin}
+ * @memberof module:React
+ */
+export default function LoginRedirect() {
+  useEffect(() => {
+    redirectToLogin(global.location.href);
+  }, []);
+  return null;
+}

package/runtime/react/PageWrap.jsx

@@ -0,0 +1,24 @@
+/* eslint-disable react/prop-types */
+// eslint-disable-next-line no-unused-vars
+import { useEffect } from 'react';
+import { useLocation } from 'react-router-dom';
+
+import { sendPageEvent } from '../analytics';
+
+/**
+ * A Wrapper component that calls `sendPageEvent` when it becomes active.
+ *
+ * @see {@link module:frontend-base~sendPageEvent}
+ * @memberof module:React
+ * @param {Object} props
+ */
+export default function PageWrap({ children }) {
+  const location = useLocation();
+
+  useEffect(() => {
+    sendPageEvent();
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location.pathname]);
+
+  return children;
+}

package/runtime/react/SiteContext.tsx

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

package/runtime/react/SiteProvider.tsx

@@ -0,0 +1,78 @@
+import { ReactNode, useMemo, useState } from 'react';
+
+import { AUTHENTICATED_USER_CHANGED, getAuthenticatedUser } from '../auth';
+import { getSiteConfig } from '../config';
+import { CONFIG_CHANGED } from '../constants';
+import {
+  getLocale,
+  getMessages,
+  IntlProvider,
+  LOCALE_CHANGED,
+} from '../i18n';
+
+import CombinedAppProvider from './CombinedAppProvider';
+import ErrorBoundary from './ErrorBoundary';
+import SiteContext from './SiteContext';
+import { useSiteEvent } from './hooks';
+
+interface SiteProviderProps {
+  children: ReactNode,
+}
+
+/**
+ * A wrapper component for React-based micro-frontends to initialize a number of common data/
+ * context providers.
+ *
+ * ```
+ * subscribe(SITE_READY, () => {
+ *   ReactDOM.render(
+ *     <SiteProvider>
+ *       <HelloWorld />
+ *     </SiteProvider>
+ *   )
+ * });
+ * ```
+ *
+ * This will provide the following to HelloWorld:
+ * - An error boundary as described above.
+ * - An `SiteContext` provider for React context data.
+ * - IntlProvider for @edx/frontend-i18n internationalization
+ *
+ * @param {Object} props
+ * @memberof module:React
+ */
+export default function SiteProvider({ children }: SiteProviderProps) {
+  const [siteConfig, setSiteConfig] = useState(getSiteConfig());
+  const [authenticatedUser, setAuthenticatedUser] = useState(getAuthenticatedUser());
+  const [locale, setLocale] = useState(getLocale());
+
+  useSiteEvent(AUTHENTICATED_USER_CHANGED, () => {
+    setAuthenticatedUser(getAuthenticatedUser());
+  });
+
+  useSiteEvent(CONFIG_CHANGED, () => {
+    setSiteConfig(getSiteConfig());
+  });
+
+  useSiteEvent(LOCALE_CHANGED, () => {
+    setLocale(getLocale());
+  });
+
+  const siteContextValue = useMemo(() => ({
+    authenticatedUser,
+    siteConfig,
+    locale
+  }), [authenticatedUser, siteConfig, locale]);
+
+  return (
+    <IntlProvider locale={locale} messages={getMessages()}>
+      <ErrorBoundary>
+        <SiteContext.Provider value={siteContextValue}>
+          <CombinedAppProvider>
+            {children}
+          </CombinedAppProvider>
+        </SiteContext.Provider>
+      </ErrorBoundary>
+    </IntlProvider>
+  );
+}

package/runtime/react/hooks.ts

@@ -0,0 +1,106 @@
+import { useCallback, useContext, useEffect, useState } from 'react';
+import { useMatches } from 'react-router';
+
+import { sendTrackEvent } from '../analytics';
+import { getActiveRoles, setActiveRouteRoles } from '../config';
+import { ACTIVE_ROLES_CHANGED } from '../constants';
+import { isRoleRouteObject } from '../routing';
+import { subscribe, unsubscribe } from '../subscriptions';
+
+import SiteContext from './SiteContext';
+import CurrentAppContext from './CurrentAppContext';
+
+/**
+ * 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 useSiteEvent = (type, callback) => {
+  useEffect(() => {
+    subscribe(type, callback);
+
+    return () => {
+      unsubscribe(type, callback);
+    };
+  }, [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-base.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);
+      }
+    };
+  }, []);
+};
+
+export function useAuthenticatedUser() {
+  const { authenticatedUser } = useContext(SiteContext);
+  return authenticatedUser;
+}
+
+export function useSiteConfig() {
+  const { siteConfig } = useContext(SiteContext);
+  return siteConfig;
+}
+
+export function useAppConfig() {
+  const { appConfig } = useContext(CurrentAppContext);
+  return appConfig;
+}
+
+export function useActiveRouteRoleWatcher() {
+  const matches = useMatches();
+
+  // We create this callback so we can use it right away to populate the default state value.
+  const findActiveRouteRoles = useCallback(() => {
+    // Starts with the widget roles and adds the others in.
+    const roles: string[] = [];
+
+    // Route roles
+    for (const match of matches) {
+      if (isRoleRouteObject(match)) {
+        if (!roles.includes(match.handle.role)) {
+          roles.push(match.handle.role);
+        }
+      }
+    }
+
+    return roles;
+  }, [matches]);
+
+  useEffect(() => {
+    setActiveRouteRoles(findActiveRouteRoles());
+  }, [matches, findActiveRouteRoles]);
+}
+
+export function useActiveRoles() {
+  const [roles, setRoles] = useState<string[]>(getActiveRoles());
+  useSiteEvent(ACTIVE_ROLES_CHANGED, () => {
+    setRoles(getActiveRoles());
+  });
+
+  return roles;
+}

package/runtime/react/index.ts

@@ -0,0 +1,19 @@
+/**
+ * #### Import members from **@openedx/frontend-base** React
+ * The React module provides a variety of React components, hooks, and contexts for use in an
+ * application.
+ *
+ * @module React
+ */
+
+export { default as CurrentAppContext } from './CurrentAppContext';
+export { default as CurrentAppProvider } from './CurrentAppProvider';
+export { default as SiteContext } from './SiteContext';
+export { default as SiteProvider } from './SiteProvider';
+export { default as AuthenticatedPageRoute } from './AuthenticatedPageRoute';
+export { default as Divider } from './Divider';
+export { default as ErrorBoundary } from './ErrorBoundary';
+export { default as ErrorPage } from './ErrorPage';
+export { useSiteEvent, useAuthenticatedUser, useSiteConfig, useAppConfig } from './hooks';
+export { default as LoginRedirect } from './LoginRedirect';
+export { default as PageWrap } from './PageWrap';

package/runtime/routing/index.ts

@@ -0,0 +1 @@
+export * from './utils';