@openedx/frontend-base 1.0.0-alpha.0

package/runtime/constants.ts

@@ -0,0 +1,68 @@
+/** @constant */
+export const SITE_TOPIC = 'APP';
+
+export const SITE_PUBSUB_INITIALIZED = `${SITE_TOPIC}.PUBSUB_INITIALIZED`;
+
+/**
+ * Event published when the application initialization sequence has finished loading any dynamic
+ * configuration setup in a custom config handler.
+ *
+ * @event
+ */
+export const SITE_CONFIG_INITIALIZED = `${SITE_TOPIC}.CONFIG_INITIALIZED`;
+
+/**
+ * Event published when the application initialization sequence has finished determining the user's
+ * authentication state, creating an authenticated API client, and executing auth handlers.
+ *
+ * @event
+ */
+export const SITE_AUTH_INITIALIZED = `${SITE_TOPIC}.AUTH_INITIALIZED`;
+
+/**
+ * Event published when the application initialization sequence has finished initializing
+ * internationalization and executing any i18n handlers.
+ *
+ * @event
+ */
+export const SITE_I18N_INITIALIZED = `${SITE_TOPIC}.I18N_INITIALIZED`;
+
+/**
+ * Event published when the application initialization sequence has finished initializing the
+ * logging service and executing any logging handlers.
+ *
+ * @event
+ */
+export const SITE_LOGGING_INITIALIZED = `${SITE_TOPIC}.LOGGING_INITIALIZED`;
+
+/**
+ * Event published when the application initialization sequence has finished initializing the
+ * analytics service and executing any analytics handlers.
+ *
+ * @event
+ */
+export const SITE_ANALYTICS_INITIALIZED = `${SITE_TOPIC}.ANALYTICS_INITIALIZED`;
+
+/**
+ * Event published when the application initialization sequence has finished.  Applications should
+ * subscribe to this event and start rendering the UI when it has fired.
+ *
+ * @event
+ */
+export const SITE_READY = `${SITE_TOPIC}.READY`;
+
+/**
+ * Event published when the application initialization sequence has aborted.  This is frequently
+ * used to show an error page when an initialization error has occurred.
+ *
+ * @see {@link module:React~ErrorPage}
+ * @event
+ */
+export const SITE_INIT_ERROR = `${SITE_TOPIC}.INIT_ERROR`;
+
+/** @constant */
+export const CONFIG_TOPIC = 'CONFIG';
+
+export const CONFIG_CHANGED = `${CONFIG_TOPIC}.CHANGED`;
+
+export const ACTIVE_ROLES_CHANGED = 'ACTIVE_ROLES_CHANGED';

package/runtime/i18n/index.js

@@ -0,0 +1,118 @@
+/**
+ * #### Import members from **@openedx/frontend-base**
+ * The i18n module relies on react-intl and re-exports all of that package's exports.
+ *
+ * For each locale we want to support, react-intl needs 1) the locale-data, which includes
+ * information about how to format numbers, handle plurals, etc., and 2) the translations, as an
+ * object holding message id / translated string pairs.  A locale string and the messages object are
+ * passed into the IntlProvider element that wraps your element hierarchy.
+ *
+ * Note that react-intl has no way of checking if the translations you give it actually have
+ * anything to do with the locale you pass it; it will happily use whatever messages object you pass
+ * in.  However, if the locale data for the locale you passed into the IntlProvider was not
+ * correctly installed with addLocaleData, all of your translations will fall back to the default
+ * (in our case English), *even if you gave IntlProvider the correct messages object for that
+ * locale*.
+ *
+ * Messages are provided to this module via the configureI18n() function below.
+ *
+ *
+ * @module Internationalization
+ * @see {@link https://github.com/openedx/frontend-base/blob/master/docs/how_tos/i18n.rst}
+ * @see {@link https://formatjs.io/docs/react-intl/components/ Intl} for components exported from this module.
+ *
+ */
+
+/**
+ * @name createIntl
+ * @kind function
+ * @see {@link https://formatjs.io/docs/react-intl/api#createIntl Intl}
+ */
+
+/**
+ * @name FormattedDate
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#formatteddate Intl}
+ */
+
+/**
+ * @name FormattedTime
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#formattedtime Intl}
+ */
+
+/**
+ * @name FormattedRelativeTime
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#formattedrelativetime Intl}
+ */
+
+/**
+ * @name FormattedNumber
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#formattednumber Intl}
+ */
+
+/**
+ * @name FormattedPlural
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#formattedplural Intl}
+ */
+
+/**
+ * @name FormattedMessage
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#formattedmessage Intl}
+ */
+
+/**
+ * @name IntlProvider
+ * @kind class
+ * @see {@link https://formatjs.io/docs/react-intl/components/#intlprovider Intl}
+ */
+
+/**
+ * @name defineMessages
+ * @kind function
+ * @see {@link https://formatjs.io/docs/react-intl/api#definemessagesdefinemessage Intl}
+ */
+
+/**
+ * @name useIntl
+ * @kind function
+ * @see {@link https://formatjs.io/docs/react-intl/api#useIntl Intl}
+ */
+
+export {
+  createIntl,
+  defineMessages,
+  FormattedDate,
+  FormattedMessage,
+  FormattedNumber,
+  FormattedPlural,
+  FormattedRelativeTime,
+  FormattedTime,
+  IntlProvider,
+  useIntl
+} from 'react-intl';
+
+export {
+  addAppMessages,
+  configureI18n,
+  getLocale,
+  getLocalizedLanguageName,
+  getMessages,
+  getPrimaryLanguageSubtag,
+  getSupportedLanguageList,
+  handleRtl,
+  intlShape,
+  isRtl,
+  LOCALE_CHANGED,
+  LOCALE_TOPIC,
+  mergeMessages,
+  updateLocale
+} from './lib';
+
+export {
+  default as injectIntl
+} from './injectIntlWithShim';

package/runtime/i18n/injectIntlWithShim.jsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { injectIntl } from 'react-intl';
+import { EnvironmentTypes } from '../../types';
+import { getSiteConfig } from '../config';
+import { getLoggingService } from '../logging';
+import { intlShape } from './lib';
+
+/**
+ * This function wraps react-intl's injectIntl function in order to add error logging to the intl
+ * property's formatMessage function.
+ *
+ * @memberof I18n
+ */
+const injectIntlWithShim = (WrappedComponent) => {
+  class ShimmedIntlComponent extends React.Component {
+    constructor(props) {
+      super(props);
+      this.shimmedIntl = Object.create(this.props.intl, {
+        formatMessage: {
+          value: (definition, ...args) => {
+            if (definition === undefined || definition.id === undefined) {
+              const error = new Error('i18n error: An undefined message was supplied to intl.formatMessage.');
+              if (getSiteConfig().environment === EnvironmentTypes.DEVELOPMENT) {
+                console.error(error); // eslint-disable-line no-console
+                return '!!! Missing message supplied to intl.formatMessage !!!';
+              }
+              getLoggingService().logError(error);
+              return ''; // Fail silently in production
+            }
+            return this.props.intl.formatMessage(definition, ...args);
+          },
+        },
+      });
+    }
+
+    render() {
+      return <WrappedComponent {...this.props} intl={this.shimmedIntl} />;
+    }
+  }
+
+  ShimmedIntlComponent.propTypes = {
+    intl: intlShape.isRequired,
+  };
+
+  return injectIntl(ShimmedIntlComponent);
+};
+
+export default injectIntlWithShim;

package/runtime/i18n/lib.ts

@@ -0,0 +1,272 @@
+import merge from 'lodash.merge';
+import PropTypes from 'prop-types';
+import { MessageFormatElement } from 'react-intl';
+import Cookies from 'universal-cookie';
+
+import { LocalizedMessages } from '../../types';
+import { getSiteConfig } from '../config';
+import { publish } from '../subscriptions';
+
+const cookies = new Cookies();
+
+// This list is based on https://help.smartling.com/hc/en-us/articles/1260802028830-Right-to-left-RTL-Languages
+// There are very few resources available online outlining the locale codes for RTL languages;
+// If this list is inaccurate, we should change it.
+const rtlLocales = [
+  'ar', // Arabic (International)
+  'ar-ae', // Arabic (United Arab Emirates)
+  'ar-bh', // Arabic (Bahrain)
+  'ar-dj', // Arabic (Djibouti)
+  'ar-dz', // Arabic (Algeria)
+  'ar-eg', // Arabic (Egypt)
+  'ar-iq', // Arabic (Iraq)
+  'ar-jo', // Arabic (Jordan)
+  'ar-kw', // Arabic (Kuwait)
+  'ar-lb', // Arabic (Lebanon)
+  'ar-ly', // Arabic (Libya)
+  'ar-ma', // Arabic (Morocco)
+  'ar-om', // Arabic (Oman)
+  'ar-qa', // Arabic (Qatar)
+  'ar-sa', // Arabic (Saudi Arabia)
+  'ar-sd', // Arabic (Sudan)
+  'ar-sy', // Arabic (Syria)
+  'ar-tn', // Arabic (Tunisia)
+  'ar-ye', // Arabic (Yemen)
+  'fa', // Persian
+  'fa-af', // Dari/Persian (Afghanistan)
+  'fa-ir', // Persian (Iran)
+  'he', // Hebrew (he)
+  'he-il', // Hebrew
+  'iw', // Hebrew (iw)
+  'kd', // Kurdish (Sorani) RTL
+  'pk-pk', // Panjabi-Shahmuki (Pakistan)
+  'ps', // Pushto; Pashto
+  'ug', // Uighur; Uyghur
+  'ur', // Urdu
+  'ur-in', // Urdu (India)
+  'ur-pk', // Urdu (Pakistan)
+  'yi', // Yiddish
+  'yi-us', // Yiddish (United States)
+];
+
+let messages: Record<string, Record<string, string> | Record<string, MessageFormatElement[]> | undefined>;
+
+/**
+ * @memberof module:Internationalization
+ *
+ * Prior versions of react-intl (our primary implementation of the i18n service) included a
+ * PropTypes-based 'shape' for its `intl` object.  This has since been removed.  For legacy
+ * compatibility, we include an `intlShape` export that is set to PropTypes.object.  Usage of this
+ * export is deprecated.
+ *
+ * @deprecated
+ */
+export const intlShape = PropTypes.object;
+
+/**
+ * @memberof module:Internationalization
+ */
+export const LOCALE_TOPIC = 'LOCALE';
+
+/**
+ * @memberof module:Internationalization
+ */
+export const LOCALE_CHANGED = `${LOCALE_TOPIC}.CHANGED`;
+
+/**
+ *
+ * @memberof module:Internationalization
+ * @returns {Cookies}
+ */
+export function getCookies() {
+  return cookies;
+}
+
+/**
+ * Some of our dependencies function on primary language subtags, rather than full locales.
+ * This function strips a locale down to that first subtag.  Depending on the code, this
+ * may be 2 or more characters.
+ *
+ * @param {string} code
+ * @memberof module:Internationalization
+ */
+export function getPrimaryLanguageSubtag(code) {
+  return code.split('-')[0];
+}
+
+/**
+ * Finds the closest supported locale to the one provided.  This is done in three steps:
+ *
+ * 1. Returning the locale itself if its exact language code is supported.
+ * 2. Returning the primary language subtag of the language code if it is supported (ar for ar-eg,
+ * for instance).
+ * 3. Returning 'en' if neither of the above produce a supported locale.
+ *
+ * @param {string} locale
+ * @returns {string}
+ * @memberof module:Internationalization
+ */
+export function findSupportedLocale(locale) {
+  if (messages === undefined) {
+    throw new Error('findSupportedLocale called before configuring i18n. Call configureI18n with messages first.');
+  }
+
+  if (messages[locale] !== undefined) {
+    return locale;
+  }
+
+  if (messages[getPrimaryLanguageSubtag(locale)] !== undefined) {
+    return getPrimaryLanguageSubtag(locale);
+  }
+
+  return 'en';
+}
+
+/**
+ * Get the locale from the cookie or, failing that, the browser setting.
+ * Gracefully fall back to a more general primary language subtag or to English (en)
+ * if we don't support that language.
+ *
+ * @param {string|undefined} locale If a locale is provided, returns the closest supported locale. Optional.
+ * @throws An error if i18n has not yet been configured.
+ * @returns {string}
+ * @memberof module:Internationalization
+ */
+export function getLocale(locale?: string) {
+  if (messages === null) {
+    throw new Error('getLocale called before configuring i18n. Call configureI18n with messages first.');
+  }
+
+  // 1. Explicit application request
+  if (locale !== undefined) {
+    return findSupportedLocale(locale);
+  }
+  // 2. User setting in cookie
+
+  const { languagePreferenceCookieName } = getSiteConfig();
+  if (languagePreferenceCookieName) {
+    const languagePreference = cookies.get(languagePreferenceCookieName);
+    if (languagePreference) {
+      return findSupportedLocale(languagePreference.toLowerCase());
+    }
+  }
+
+  // 3. Browser language (default)
+  // Note that some browers prefer upper case for the region part of the locale, while others don't.
+  // Thus the toLowerCase, for consistency.
+  // https://developer.mozilla.org/en-US/docs/Web/API/NavigatorLanguage/language
+  return findSupportedLocale(globalThis.navigator.language.toLowerCase());
+}
+
+export function getLocalizedLanguageName(locale) {
+  const localizedName = (new Intl.DisplayNames([locale], { type: 'language' })).of(locale);
+
+  if (localizedName === undefined) {
+    throw new Error(`Unsupported locale: ${locale}`);
+  }
+
+  return `${localizedName.charAt(0).toLocaleUpperCase(locale)}${localizedName.slice(1)}`;
+}
+
+export function getSupportedLanguageList() {
+  const locales = Object.keys(messages);
+  locales.push('en'); // 'en' is not in the messages object because it's the default.
+  locales.sort();
+
+  return locales.map((locale) => ({
+    code: locale,
+    name: getLocalizedLanguageName(locale),
+  }));
+}
+
+export function updateLocale() {
+  handleRtl();
+  publish(LOCALE_CHANGED);
+}
+
+/**
+ * Returns messages for the provided locale, or the user's preferred locale if no argument is
+ * provided.
+ *
+ * @param {string} [locale=getLocale()]
+ * @memberof module:Internationalization
+ */
+export function getMessages(locale = getLocale()) {
+  if (messages === undefined) {
+    throw new Error('getMessages called before configuring i18n. Call configureI18n with messages first.');
+  }
+
+  return messages[locale];
+}
+
+/**
+ * Determines if the provided locale is a right-to-left language.
+ *
+ * @param {string} locale
+ * @memberof module:Internationalization
+ */
+export function isRtl(locale) {
+  return rtlLocales.includes(locale);
+}
+
+/**
+ * Handles applying the RTL stylesheet and "dir=rtl" attribute to the html tag if the current locale
+ * is a RTL language.
+ *
+ * @memberof module:Internationalization
+ */
+export function handleRtl() {
+  if (isRtl(getLocale())) {
+    globalThis.document.getElementsByTagName('html')[0].setAttribute('dir', 'rtl');
+  } else {
+    globalThis.document.getElementsByTagName('html')[0].setAttribute('dir', 'ltr');
+  }
+}
+
+/**
+ *
+ *
+ * @param {Object} newMessages
+ * @returns {Object}
+ * @memberof module:Internationalization
+ */
+export function mergeMessages(newMessages = {}) {
+  const msgs = Array.isArray(newMessages) ? merge({}, ...newMessages) : newMessages;
+  messages = merge(messages, msgs);
+
+  return messages;
+}
+
+/**
+ * Adds all the messages found in the loaded apps.
+ *
+ * @memberof module:Internationalization
+ */
+export function addAppMessages() {
+  const { apps } = getSiteConfig();
+  if (apps) {
+    apps.forEach((app) => {
+      mergeMessages(app.messages);
+    });
+  }
+}
+
+interface ConfigureI18nOptions {
+  messages: LocalizedMessages[] | LocalizedMessages,
+}
+
+/**
+ * Configures the i18n library with messages for your application.
+ *
+ * Logs a warning if it detects a locale it doesn't expect (as defined by the supportedLocales list
+ * above), or if an expected locale is not provided.
+ *
+ * @param {Object} options
+ * @param {Object} options.messages
+ * @memberof module:Internationalization
+ */
+export function configureI18n(options: ConfigureI18nOptions) {
+  messages = Array.isArray(options.messages) ? merge({}, ...options.messages) : options.messages;
+
+  handleRtl();
+}

package/runtime/index.ts

@@ -0,0 +1,134 @@
+export {
+  configureAnalytics,
+  getAnalyticsService,
+  identifyAnonymousUser,
+  identifyAuthenticatedUser,
+  MockAnalyticsService,
+  resetAnalyticsService,
+  SegmentAnalyticsService,
+  sendPageEvent,
+  sendTrackEvent,
+  sendTrackingLogEvent
+} from './analytics';
+
+export {
+  AUTHENTICATED_USER_CHANGED,
+  AUTHENTICATED_USER_TOPIC,
+  AxiosJwtAuthService,
+  configureAuth,
+  ensureAuthenticatedUser,
+  fetchAuthenticatedUser,
+  getAuthenticatedHttpClient,
+  getAuthenticatedUser,
+  getAuthService,
+  getHttpClient,
+  getLoginRedirectUrl,
+  getLogoutRedirectUrl,
+  hydrateAuthenticatedUser,
+  MockAuthService,
+  redirectToLogin,
+  redirectToLogout,
+  setAuthenticatedUser
+} from './auth';
+
+export {
+  getSiteConfig,
+  setSiteConfig,
+  mergeSiteConfig,
+  addAppConfigs,
+  getAppConfig,
+  mergeAppConfig,
+  setActiveRouteRoles,
+  getActiveRouteRoles,
+  addActiveWidgetRole,
+  removeActiveWidgetRole,
+  getActiveWidgetRoles,
+  getActiveRoles,
+  getExternalLinkUrl
+} from './config';
+
+export * from './constants';
+
+export {
+  configureI18n,
+  createIntl,
+  defineMessages,
+  FormattedDate,
+  FormattedMessage,
+  FormattedNumber,
+  FormattedPlural,
+  FormattedRelativeTime,
+  FormattedTime,
+  getLocale,
+  getLocalizedLanguageName,
+  getMessages,
+  getPrimaryLanguageSubtag,
+  getSupportedLanguageList,
+  handleRtl,
+  injectIntl,
+  IntlProvider,
+  intlShape,
+  isRtl,
+  LOCALE_CHANGED,
+  LOCALE_TOPIC,
+  mergeMessages,
+  updateLocale,
+  useIntl
+} from './i18n';
+
+export {
+  auth,
+  getBasename,
+  initError,
+  initialize
+} from './initialize';
+
+export {
+  configureLogging,
+  getLoggingService,
+  logError,
+  logInfo,
+  MockLoggingService,
+  NewRelicLoggingService,
+  resetLoggingService
+} from './logging';
+
+export {
+  CurrentAppContext,
+  CurrentAppProvider,
+  SiteContext,
+  SiteProvider,
+  AuthenticatedPageRoute,
+  Divider,
+  ErrorBoundary,
+  ErrorPage,
+  LoginRedirect,
+  PageWrap,
+  useSiteEvent,
+  useAuthenticatedUser,
+  useSiteConfig,
+  useAppConfig
+} from './react';
+
+export {
+  clearAllSubscriptions,
+  publish,
+  subscribe,
+  unsubscribe
+} from './subscriptions';
+
+export {
+  initializeMockApp,
+  mockMessages
+} from './testing';
+
+export {
+  camelCaseObject,
+  convertKeyNames,
+  getQueryParameters,
+  isValidVariableName,
+  modifyObjectKeys,
+  snakeCaseObject
+} from './utils';
+
+export * from './slots';