@openedx/frontend-base 1.0.0-alpha.0

package/runtime/routing/utils.ts

@@ -0,0 +1,34 @@
+import { RouteObject } from 'react-router';
+
+import { RoleRouteObject } from '../../types';
+import { getSiteConfig } from '../config';
+
+export function getUrlByRouteRole(role: string) {
+  const { apps, externalRoutes } = getSiteConfig();
+
+  if (apps) {
+    for (const app of apps) {
+      if (Array.isArray(app.routes)) {
+        for (const route of app.routes) {
+          if (route?.handle?.role === role) {
+            return route.path ?? null;
+          }
+        }
+      }
+    }
+  }
+
+  if (externalRoutes) {
+    for (const externalRoute of externalRoutes) {
+      if (externalRoute.role === role) {
+        return externalRoute.url;
+      }
+    }
+  }
+
+  return null;
+}
+
+export function isRoleRouteObject(match: RouteObject): match is RoleRouteObject {
+  return match.handle !== undefined && 'role' in match.handle;
+}

package/runtime/scripts/GoogleAnalyticsLoader.ts

@@ -0,0 +1,59 @@
+/**
+ * @implements {GoogleAnalyticsLoader}
+ * @memberof module:GoogleAnalytics
+ */
+class GoogleAnalyticsLoader {
+  analyticsId: string;
+
+  constructor({ config }) {
+    this.analyticsId = config.GOOGLE_ANALYTICS_4_ID;
+  }
+
+  loadScript() {
+    if (!this.analyticsId) {
+      return;
+    }
+
+    global.googleAnalytics = global.googleAnalytics || [];
+    // @ts-expect-error We just added googleAnalytics to global, it's there.
+    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];
+      if (first?.parentNode === null) {
+        throw new Error('No script to insert Google analytics script before.');
+      }
+      first.parentNode.insertBefore(scriptSrc, first);
+      first.parentNode.insertBefore(scriptGtag, first);
+      googleAnalytics._loadOptions = options;
+    };
+
+    // Load GoogleAnalytics with your key.
+    googleAnalytics.load(this.analyticsId);
+  }
+}
+
+export default GoogleAnalyticsLoader;

package/runtime/scripts/index.ts

@@ -0,0 +1 @@
+export { default as GoogleAnalyticsLoader } from './GoogleAnalyticsLoader';

package/runtime/setupTest.js

@@ -0,0 +1,49 @@
+import '@testing-library/jest-dom';
+
+import siteConfig from 'site.config';
+import { mergeSiteConfig } from './config';
+
+jest.mock('universal-cookie', () => {
+  const mCookie = {
+    get: jest.fn(),
+    remove: jest.fn(),
+  };
+  return jest.fn(() => mCookie);
+});
+
+mergeSiteConfig(siteConfig);
+
+global.PARAGON_THEME = {
+  paragon: {
+    version: '1.0.0',
+    themeUrls: {
+      core: {
+        fileName: 'core.min.css',
+      },
+      defaults: {
+        light: 'light',
+      },
+      variants: {
+        light: {
+          fileName: 'light.min.css',
+        },
+      },
+    },
+  },
+  brand: {
+    version: '1.0.0',
+    themeUrls: {
+      core: {
+        fileName: 'core.min.css',
+      },
+      defaults: {
+        light: 'light',
+      },
+      variants: {
+        light: {
+          fileName: 'light.min.css',
+        },
+      },
+    },
+  },
+};

package/runtime/slots/Slot.tsx

@@ -0,0 +1,32 @@
+import { ComponentType, createElement, isValidElement, ReactNode } from 'react';
+import DefaultSlotLayout from './layout/DefaultSlotLayout';
+import { useLayoutForSlotId } from './layout/hooks';
+import SlotContext from './SlotContext';
+
+interface SlotProps {
+  id: string,
+  children?: ReactNode,
+  layout?: ComponentType | ReactNode,
+  [key: string]: unknown,
+}
+
+export default function Slot({ id, children, layout = DefaultSlotLayout, ...props }: SlotProps) {
+  let layoutElement: ComponentType | ReactNode = layout;
+
+  const overrideLayout = useLayoutForSlotId(id);
+
+  // Weed out any ReactNode types that aren't actually JSX.
+  if (overrideLayout && overrideLayout !== null && overrideLayout !== undefined && typeof overrideLayout !== 'boolean') {
+    layoutElement = overrideLayout;
+  }
+
+  if (!isValidElement(layoutElement)) {
+    layoutElement = createElement(layoutElement as ComponentType);
+  }
+
+  return (
+    <SlotContext.Provider value={{ id, children, ...props }}>
+      {layoutElement}
+    </SlotContext.Provider>
+  );
+}

package/runtime/slots/SlotContext.tsx

@@ -0,0 +1,8 @@
+import { createContext, ReactNode } from 'react';
+
+const SlotContext = createContext<{ id: string, children?: ReactNode, [key: string]: unknown }>({
+  id: '',
+  children: null,
+});
+
+export default SlotContext;

package/runtime/slots/hooks.ts

@@ -0,0 +1,35 @@
+import { useContext, useEffect, useState } from 'react';
+import { useLocation } from 'react-router-dom';
+
+import { SlotOperation } from './types';
+import { getSlotOperations } from './utils';
+import SlotContext from './SlotContext';
+import { createWidgetAppendOperation } from './widget';
+
+/**
+ * The useSlotOperations hook will trigger re-renders when the slot configuration changes.
+ * It is a fundamental hook that is used by many of the others to ensure they're using up-to-date
+ * config as it changes.
+ */
+export function useSlotOperations(id: string) {
+  const { children } = useSlotContext();
+  const location = useLocation();
+  const [operations, setOperations] = useState<SlotOperation[]>([]);
+
+  useEffect(() => {
+    // Setting default content has to happen inside `useEffect()` so that re-renders only happen
+    // when [children] props change.  This avoids an endless render loop.  After all, the whole
+    // point of a slot is to modify its children via slot operations.
+    const defaultOperation = createWidgetAppendOperation('defaultContent', id, children);
+    setOperations(getSlotOperations(id, defaultOperation));
+
+    // We depend on [location] to force re-renders on navigation.  This guarantees changes in active
+    // roles (and thus, changes in what conditional widgets are shown) properly.
+  }, [id, children, location]);
+
+  return operations;
+}
+
+export function useSlotContext() {
+  return useContext(SlotContext);
+}

package/runtime/slots/index.ts

@@ -0,0 +1,7 @@
+export * from './hooks';
+export type * from './types';
+export * from './layout';
+export { default as Slot } from './Slot';
+export { default as SlotContext } from './SlotContext';
+export * from './utils';
+export * from './widget';

package/runtime/slots/layout/DefaultSlotLayout.tsx

@@ -0,0 +1,9 @@
+import { useWidgets } from '../widget/hooks';
+
+export default function DefaultSlotLayout() {
+  const widgets = useWidgets();
+
+  return (
+    <>{widgets}</>
+  );
+}

package/runtime/slots/layout/hooks.ts

@@ -0,0 +1,65 @@
+import { ComponentType, ReactNode, useEffect, useState } from 'react';
+import { useSlotContext, useSlotOperations } from '../hooks';
+import { isSlotOperationConditionSatisfied } from '../utils';
+import { LayoutComponentProps, LayoutElementProps, LayoutOperation } from './types';
+import { isLayoutOperation, isLayoutOptionsOperation, isLayoutReplaceOperation } from './utils';
+
+function hasLayoutComponentProps(operation: LayoutOperation): operation is (LayoutOperation & LayoutComponentProps) {
+  return isLayoutOperation(operation) && 'component' in operation;
+}
+
+function hasLayoutElementProps(operation: LayoutOperation): operation is (LayoutOperation & LayoutElementProps) {
+  return isLayoutOperation(operation) && 'element' in operation;
+}
+
+export function useLayoutForSlotId(id: string) {
+  const operations = useSlotOperations(id);
+  let layoutElement: ReactNode | ComponentType = null;
+
+  for (const operation of operations) {
+    if (isSlotOperationConditionSatisfied(operation)) {
+      if (isLayoutReplaceOperation(operation)) {
+        if (hasLayoutComponentProps(operation)) {
+          layoutElement = operation.component;
+        } else if (hasLayoutElementProps(operation)) {
+          layoutElement = operation.element;
+        }
+      }
+    }
+  }
+  return layoutElement;
+}
+
+/**
+ * useLayoutOptions iterates through the slot's operations to find any which are "layout
+ * options" operations.  It merges these into a single object and returns them - operations are
+ * merged in declaration order, meaning last one in wins.  useLayoutOptions only triggers a
+ * re-render when the options change.
+ */
+export function useLayoutOptions() {
+  const { id } = useSlotContext();
+  return useLayoutOptionsForId(id);
+}
+
+export function useLayoutOptionsForId(id: string) {
+  const operations = useSlotOperations(id);
+  const [options, setOptions] = useState<Record<string, unknown>>({});
+
+  useEffect(() => {
+    const findOptions = () => {
+      let nextOptions: Record<string, unknown> = {};
+      for (const operation of operations) {
+        if (isSlotOperationConditionSatisfied(operation)) {
+          if (isLayoutOptionsOperation(operation)) {
+            nextOptions = { ...nextOptions, ...operation.options };
+          }
+        }
+      }
+      return nextOptions;
+    };
+
+    setOptions(findOptions());
+  }, [operations]);
+
+  return options;
+}

package/runtime/slots/layout/index.ts

@@ -0,0 +1,5 @@
+export { default as DefaultSlotLayout } from './DefaultSlotLayout';
+export * from './hooks';
+export type * from './types';
+export { LayoutOperationTypes } from './types';
+export * from './utils';

package/runtime/slots/layout/types.ts

@@ -0,0 +1,45 @@
+/**
+ * Base UI Layout Operations
+ *
+ * "Layout" operations are a sub-type of UI operations which affect the layout component of a UI
+ * slot.  They have no effect on the widgets loaded into a UI slot.
+ */
+
+import { ReactNode } from 'react';
+import { BaseSlotOperation } from '../types';
+
+export enum LayoutOperationTypes {
+  OPTIONS = 'layoutOptions',
+  REPLACE = 'layoutReplace',
+}
+
+export interface BaseLayoutOperation extends BaseSlotOperation {
+  op: LayoutOperationTypes,
+}
+
+// Concrete UI Layout Operations
+
+export type LayoutOptionsOperation = BaseLayoutOperation & {
+  op: LayoutOperationTypes.OPTIONS,
+  options: Record<string, unknown>,
+};
+
+export interface LayoutComponentProps {
+  component: React.ComponentType,
+}
+
+export interface LayoutElementProps {
+  element: ReactNode,
+}
+
+export type LayoutRendererProps = (
+  LayoutComponentProps | LayoutElementProps
+);
+
+export type LayoutReplaceOperation = BaseLayoutOperation & LayoutRendererProps & {
+  op: LayoutOperationTypes.REPLACE,
+};
+
+// Aggregate UI Layout Operations
+
+export type LayoutOperation = LayoutOptionsOperation | LayoutReplaceOperation;

package/runtime/slots/layout/utils.ts

@@ -0,0 +1,14 @@
+import { SlotOperation } from '../types';
+import { LayoutOperation, LayoutOperationTypes, LayoutOptionsOperation, LayoutReplaceOperation } from './types';
+
+export function isLayoutOperation(operation: SlotOperation): operation is LayoutOperation {
+  return Object.values(LayoutOperationTypes).includes(operation.op as LayoutOperationTypes);
+}
+
+export function isLayoutOptionsOperation(operation: SlotOperation): operation is LayoutOptionsOperation {
+  return isLayoutOperation(operation) && operation.op === LayoutOperationTypes.OPTIONS;
+}
+
+export function isLayoutReplaceOperation(operation: SlotOperation): operation is LayoutReplaceOperation {
+  return isLayoutOperation(operation) && operation.op === LayoutOperationTypes.REPLACE;
+}

package/runtime/slots/types.ts

@@ -0,0 +1,23 @@
+/**
+ * Base Slot Operations
+ *
+ * These are properties shared by all slot operations defined below.
+ */
+
+import { LayoutOperation } from './layout/types';
+import { WidgetOperation } from './widget/types';
+
+export interface SlotOperationCondition {
+  active?: string[],
+  authenticated?: boolean,
+  callback?: () => boolean,
+}
+
+export interface BaseSlotOperation {
+  slotId: string,
+  condition?: SlotOperationCondition,
+}
+
+// Aggregate Slot Operations
+
+export type SlotOperation = WidgetOperation | LayoutOperation;

package/runtime/slots/utils.ts

@@ -0,0 +1,59 @@
+import { getAuthenticatedUser } from '../auth';
+import { getActiveRoles, getSiteConfig } from '../config';
+import { SlotOperation } from './types';
+
+export function getSlotOperations(id: string, defaultOperation?: SlotOperation) {
+  const { apps } = getSiteConfig();
+  const ops: SlotOperation[] = [];
+
+  if (defaultOperation) {
+    ops.push(defaultOperation);
+  }
+
+  if (apps) {
+    apps.forEach((app) => {
+      if (Array.isArray(app.slots)) {
+        app.slots.forEach((operation) => {
+          if (operation.slotId === id) {
+            ops.push(operation);
+          }
+        });
+      }
+    });
+  }
+
+  return ops;
+}
+
+export function isSlotOperationConditionSatisfied(operation: SlotOperation) {
+  const { condition } = operation;
+  if (condition?.authenticated !== undefined) {
+    const isAuthenticated = getAuthenticatedUser() !== null;
+    // If we failed the authenticated condition, return false.
+    if (condition.authenticated !== isAuthenticated) {
+      return false;
+    }
+  }
+
+  if (condition?.active !== undefined) {
+    let activeConditionRoleFound = false;
+    const activeRoles: string[] = getActiveRoles();
+    for (const conditionRole of condition.active) {
+      if (activeRoles.includes(conditionRole)) {
+        activeConditionRoleFound = true;
+        break;
+      }
+    }
+    // If we couldn't find an active role in our list, then we've failed this condition.
+    if (!activeConditionRoleFound) {
+      return false;
+    }
+  }
+
+  if (condition?.callback !== undefined && condition.callback() === false) {
+    return false;
+  }
+
+  // If there was no condition, we return true.
+  return true;
+}

package/runtime/slots/widget/WidgetContext.tsx

@@ -0,0 +1,9 @@
+import { createContext } from 'react';
+
+const WidgetContext = createContext<{ slotId: string, widgetId: string, role?: string }>({
+  slotId: '',
+  widgetId: '',
+  role: undefined,
+});
+
+export default WidgetContext;

package/runtime/slots/widget/WidgetProvider.tsx

@@ -0,0 +1,30 @@
+import { ReactNode, useEffect } from 'react';
+
+import { addActiveWidgetRole, removeActiveWidgetRole } from '../../config';
+import WidgetContext from './WidgetContext';
+
+interface WidgetProviderProps {
+  children: ReactNode,
+  slotId: string,
+  widgetId: string,
+  role?: string,
+}
+
+export default function WidgetProvider({ children, slotId, widgetId, role }: WidgetProviderProps) {
+  useEffect(() => {
+    if (role !== undefined) {
+      addActiveWidgetRole(role);
+    }
+    return () => {
+      if (role !== undefined) {
+        removeActiveWidgetRole(role);
+      }
+    };
+  }, [role]);
+
+  return (
+    <WidgetContext.Provider value={{ slotId, widgetId, role }}>
+      {children}
+    </WidgetContext.Provider>
+  );
+}

package/runtime/slots/widget/hooks.ts

@@ -0,0 +1,105 @@
+import { useContext, useEffect, useState } from 'react';
+import { useSlotContext, useSlotOperations } from '../hooks';
+import { isSlotOperationConditionSatisfied } from '../utils';
+import { WidgetOperation } from './types';
+import { createWidgets, isWidgetAbsoluteOperation, isWidgetOperation, isWidgetOptionsOperation, isWidgetRelativeOperation } from './utils';
+import WidgetContext from './WidgetContext';
+
+export function useWidgets() {
+  const { id, ...props } = useSlotContext();
+  delete props.children;
+  return useWidgetsForId(id, props);
+}
+
+export function useWidgetsForId(id: string, componentProps?: Record<string, unknown>) {
+  const operations = useSortedWidgetOperations(id);
+  return createWidgets(operations, componentProps);
+}
+
+export function useWidgetOperations(id: string) {
+  const operations = useSlotOperations(id);
+  const [widgetOperations, setWidgetOperations] = useState<WidgetOperation[]>([]);
+
+  useEffect(() => {
+    const filteredOperations = operations.filter((operation): operation is WidgetOperation => {
+      return isWidgetOperation(operation) && isSlotOperationConditionSatisfied(operation);
+    });
+
+    setWidgetOperations(filteredOperations);
+  }, [operations]);
+
+  return widgetOperations;
+}
+
+export function useSortedWidgetOperations(id: string) {
+  const operations = useWidgetOperations(id);
+  const [sortedOperations, setSortedOperations] = useState<WidgetOperation[]>([]);
+
+  useEffect(() => {
+    // This sorts widget operations in an order that guarantees that any 'related' widgets
+    // needed by relatively positioned operations (INSERT_AFTER, INSERT_BEFORE) should already exist
+    // by the time the relative operations are evaluated.  It means the declaration order of
+    // operations in SiteConfig does not prevent an operation from interacting with a widget that was
+    // declared 'later'.
+    const sortedOperations = operations.sort((a: WidgetOperation, b: WidgetOperation) => {
+      // If both operations are widget operations, there are special sorting rules.
+      const aAbsolute = isWidgetAbsoluteOperation(a);
+      const bAbsolute = isWidgetAbsoluteOperation(b);
+      if (aAbsolute && bAbsolute) {
+        return 0;
+      } else if (aAbsolute) {
+        return -1;
+      } else if (bAbsolute) {
+        return 1;
+      } else if (isWidgetRelativeOperation(a) && isWidgetRelativeOperation(b)) {
+        if (a.id === b.relatedId) {
+          return -1;
+        } else if (b.id === a.relatedId) {
+          return 1;
+        }
+      }
+
+      return 0;
+    });
+
+    setSortedOperations(sortedOperations);
+  }, [operations]);
+
+  return sortedOperations;
+}
+
+/**
+ * useWidgetOptions iterates through the slot's operations to find any that are "widget options"
+ * operations specific to this widget.  It merges these into a single object and returns them -
+ * operations are merged in declaration order, meaning last one in wins.  useWidgetOptions only
+ * triggers a re-render when the options change.
+ */
+export function useWidgetOptions() {
+  const { slotId, widgetId } = useContext(WidgetContext);
+  return useWidgetOptionsForId(slotId, widgetId);
+}
+
+export function useWidgetOptionsForId(slotId: string, widgetId: string) {
+  const operations = useWidgetOperations(slotId);
+
+  const [options, setOptions] = useState<Record<string, unknown>>({});
+  useEffect(() => {
+    const findOptions = () => {
+      let nextOptions: Record<string, unknown> = {};
+      for (const operation of operations) {
+        if (isSlotOperationConditionSatisfied(operation)) {
+          if (isWidgetOptionsOperation(operation)) {
+            if (operation.relatedId === widgetId) {
+              nextOptions = { ...nextOptions, ...operation.options };
+            }
+          }
+        }
+      }
+      return nextOptions;
+    };
+
+    setOptions(findOptions());
+  }, [widgetId, operations]);
+
+  return options;
+}

package/runtime/slots/widget/iframe/IFrameContentWrapper.messages.tsx

@@ -0,0 +1,16 @@
+import { defineMessages } from '../../../i18n';
+
+const messages = defineMessages({
+  loading: {
+    id: 'loading.message.text',
+    defaultMessage: 'Loading',
+    description: 'the feature is currently loading',
+  },
+  unexpectedError: {
+    id: 'unexpected.error.message.text',
+    defaultMessage: ' Oops! An error occurred. Please refresh the screen to try again.',
+    description: 'error message when an unexpected error occurs',
+  },
+});
+
+export default messages;