@openedx/frontend-base 1.0.0-alpha.0

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

@@ -0,0 +1,84 @@
+import {
+  FunctionComponent,
+  ReactNode,
+  useEffect, useMemo, useState,
+} from 'react';
+
+import { useIntl } from '../../../i18n';
+import { ErrorBoundary } from '../../../react';
+import { IFRAME_RESIZE } from './constants';
+import {
+  dispatchMountedEvent,
+  dispatchReadyEvent,
+  dispatchUnmountedEvent,
+  useHostEvent
+} from './hooks';
+import messages from './IFrameContentWrapper.messages';
+
+const ErrorFallbackDefault = () => {
+  const { formatMessage } = useIntl();
+  return (
+    <div>
+      <h2>
+        {formatMessage(messages.unexpectedError)}
+      </h2>
+    </div>
+  );
+};
+
+interface IFrameContentWrapperProps {
+  children: ReactNode,
+  className?: string,
+  style?: Record<string, string>,
+  ready?: boolean,
+  errorFallbackComponent?: FunctionComponent,
+}
+
+export default function IFrameContentWrapper({
+  children, className, style = {}, ready = true, errorFallbackComponent,
+}: IFrameContentWrapperProps) {
+  const [dimensions, setDimensions] = useState({
+    width: 0,
+    height: 0,
+  });
+
+  const finalStyle = useMemo(() => ({
+    ...dimensions,
+    ...style,
+  }), [dimensions, style]);
+
+  // Need to confirm: When an error is caught here, the logging will be sent to the child MFE's logging service
+
+  const ErrorFallback = errorFallbackComponent ?? ErrorFallbackDefault;
+
+  useHostEvent(IFRAME_RESIZE, ({ payload }) => {
+    setDimensions({
+      width: payload.width,
+      height: payload.height,
+    });
+  });
+
+  useEffect(() => {
+    dispatchMountedEvent();
+
+    return () => {
+      dispatchUnmountedEvent();
+    };
+  }, []);
+
+  useEffect(() => {
+    // Ready defaults to true, but can be used to defer rendering the Plugin until certain processes
+    // have occurred or conditions have been met
+    if (ready) {
+      dispatchReadyEvent();
+    }
+  }, [ready]);
+
+  return (
+    <div className={className} style={finalStyle}>
+      <ErrorBoundary fallbackComponent={<ErrorFallback />}>
+        {children}
+      </ErrorBoundary>
+    </div>
+  );
+};

package/runtime/slots/widget/iframe/IFrameWidget.tsx

@@ -0,0 +1,59 @@
+import { Spinner } from '@openedx/paragon';
+import { useEffect, useState } from 'react';
+
+import classNames from 'classnames';
+import { dispatchPluginEvent, useElementSize, usePluginEvent } from './hooks';
+import { IFRAME_FEATURE_POLICY, IFRAME_MOUNTED, IFRAME_READY, IFRAME_RESIZE } from './constants';
+
+interface IFrameWidgetProps {
+  url: string,
+  title: string,
+}
+
+export default function IFrameWidget({ url, title }: IFrameWidgetProps) {
+  const [mounted, setMounted] = useState(false);
+  const [ready, setReady] = useState(false);
+
+  const { ref: iframeRef, element: iframeElement, width, height } = useElementSize();
+
+  useEffect(() => {
+    if (mounted) {
+      dispatchPluginEvent(iframeElement as HTMLIFrameElement, {
+        type: IFRAME_RESIZE,
+        payload: {
+          width,
+          height,
+        },
+      }, url);
+    }
+  }, [iframeElement, mounted, width, height, url]);
+
+  usePluginEvent(iframeElement, IFRAME_MOUNTED, () => {
+    setMounted(true);
+  });
+
+  usePluginEvent(iframeElement, IFRAME_READY, () => {
+    setReady(true);
+  });
+
+  const fallback = (
+    <Spinner animation="border" variant="light" screenReaderText="Loading" />
+  );
+
+  return (
+    <>
+      <iframe
+        ref={iframeRef}
+        title={title}
+        src={url}
+        allow={IFRAME_FEATURE_POLICY}
+        referrerPolicy="origin" // The sent referrer will be limited to the origin of the referring page: its scheme, host, and port.
+        className={classNames(
+          'border border-0 w-100',
+          { 'd-none': !ready },
+        )}
+      />
+      {!ready && fallback}
+    </>
+  );
+}

package/runtime/slots/widget/iframe/constants.ts

@@ -0,0 +1,19 @@
+// IFrame lifecycle events
+export const IFRAME_MOUNTED = 'IFRAME_MOUNTED';
+export const IFRAME_UNMOUNTED = 'IFRAME_UNMOUNTED';
+export const IFRAME_READY = 'IFRAME_READY';
+export const IFRAME_RESIZE = 'IFRAME_RESIZE';
+
+/**
+ * Feature policy for iframe, allowing access to certain courseware-related media.
+ *
+ * We must use the wildcard (*) origin for each feature, as courseware content
+ * may be embedded in external iframes. Notably, xblock-lti-consumer is a popular
+ * block that iframes external course content.
+
+ * This policy was selected in conference with the edX Security Working Group.
+ * Changes to it should be vetted by them (security@edx.org).
+ */
+export const IFRAME_FEATURE_POLICY = (
+  'fullscreen; microphone *; camera *; midi *; geolocation *; encrypted-media *'
+);

package/runtime/slots/widget/iframe/hooks.ts

@@ -0,0 +1,179 @@
+/**
+ * Hooks file for functions that handle the communication between a Plugin and its Host
+ */
+
+import {
+  LegacyRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState
+} from 'react';
+
+import { IFRAME_MOUNTED, IFRAME_READY, IFRAME_UNMOUNTED } from './constants';
+import { MessageEventCallback } from './types';
+
+/* Listening for events */
+
+/**
+ * Dynamically add an event listener to the provided source window.
+ * The source window can be the global parent (ie. the "window" object in the browser)
+ * or it can be the content window of an individual element (ie. iFrame plugin container)
+ */
+export function useMessageEvent(srcWindow: Window | null, type: string, callback: MessageEventCallback) {
+  // useLayoutEffect is called before the browser repaints the screen
+  useLayoutEffect(() => {
+    // Create a listener callback function
+    const listener = (event: MessageEvent<{ type: string, payload: any }>) => {
+      // Filter messages to those from our source window.
+      // NOTE: the "srcWindow" is determined by the below useHostEvent and usePluginEvent functions
+      if (event.source === srcWindow) {
+        // Fire callback if the type from the listened event matches the type from the message event
+        if (event.data.type === type) {
+          callback({ type, payload: event.data.payload });
+        }
+      }
+    };
+    // Add the listener to the global object if the srcWindow is not null
+    if (srcWindow !== null) {
+      global.addEventListener('message', listener);
+    }
+    // useEffect cleanup
+    return () => {
+      global.removeEventListener('message', listener);
+    };
+  }, [srcWindow, type, callback]);
+}
+
+/**
+ * Called by the Plugin component to use events that were listened to (ie. PLUGIN_RESIZE)
+ */
+export function useHostEvent(type: string, callback: MessageEventCallback) {
+  useMessageEvent(global.parent, type, callback);
+}
+
+/**
+ * Used to listen for events from a wrapped Plugin element (eg. PluginContainerIframe)
+ *
+ * @param element - Plugin element (eg. <iframe>)
+ * @param type - Event type (eg. PLUGIN_RESIZE)
+ * @param callback - Function to call when the event is triggered
+ */
+export function usePluginEvent(element: HTMLIFrameElement | undefined, type: string, callback: MessageEventCallback) {
+  const contentWindow = element ? element.contentWindow : null;
+  useMessageEvent(contentWindow, type, callback);
+}
+
+/** Dispatching events */
+
+/**
+ * Base dispatch function called by dispatchHostEvent and dispatchPluginEvent.
+ * Uses the `postMessage` method to enable cross-origin communication between Window objects
+ *
+ * @param targetWindow - Window that the message event is being dispatched to
+ * @param message - Data object for the message
+ * @param targetOrigin - URL for the window that the message event is being dispatched from
+ */
+export function dispatchMessageEvent(targetWindow: Window | null, message: any, targetOrigin: string) {
+  /** Checking targetOrigin falsiness here since '', null or undefined would all be
+   * reasons not to try to post a message to the origin.
+   */
+  if (targetWindow && targetOrigin) {
+    targetWindow.postMessage(message, targetOrigin);
+  }
+}
+
+/**
+ * Used to dispatch events for a Plugin
+ *
+ * @param element - Plugin element (eg. <iframe>)
+ * @param message - Data object for the message
+ * @param targetOrigin - URL for the window that the message event is being dispatched from
+ */
+export function dispatchPluginEvent(element: HTMLIFrameElement, message: any, targetOrigin: string) {
+  dispatchMessageEvent(element.contentWindow, message, targetOrigin);
+}
+
+/**
+ * Used to dispatch events for the Host
+ *
+ * @param message - Data object for the message
+ */
+export function dispatchHostEvent(message: any) {
+  dispatchMessageEvent(global.parent, message, global.document.referrer);
+}
+
+// Called inside Plugin when 'ready' prop is true
+export function dispatchReadyEvent() {
+  dispatchHostEvent({ type: IFRAME_READY });
+}
+
+// Below mounted events are called in a useEffect inside Plugin with [] dependencies — https://react.dev/learn/synchronizing-with-effects
+export function dispatchMountedEvent() {
+  dispatchHostEvent({ type: IFRAME_MOUNTED });
+}
+
+export function dispatchUnmountedEvent() {
+  dispatchHostEvent({ type: IFRAME_UNMOUNTED });
+}
+
+/**
+ * Used to determine the size of an element as it is being resized in the browser.
+ * ResizeObserver (https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) is used to maintain a reference to the element's content/border box.
+ *
+ * @returns Memoized value that contains a reference to the Plugin element (eg. iframe)
+ */
+export function useElementSize() {
+  // Holds a reference to the ResizeObserver
+  const observerRef = useRef<ResizeObserver>();
+
+  const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+  const [offset, setOffset] = useState({ x: 0, y: 0 });
+  const [element, setElement] = useState<HTMLIFrameElement | undefined>();
+  // Sets a reference to the Plugin element when passed to the Plugin element as a "ref" attribute (eg. <iframe>)
+  const measuredRef: LegacyRef<HTMLIFrameElement> = useCallback(_element => {
+    setElement(_element);
+  }, []);
+
+  useEffect(() => {
+    // Create a new ResizeObserver
+    observerRef.current = new ResizeObserver(() => {
+      if (element) {
+        // Set dimensions and any offset
+        setDimensions({
+          width: element.clientWidth,
+          height: element.clientHeight,
+        });
+        setOffset({
+          x: element.offsetLeft,
+          y: element.offsetTop,
+        });
+      }
+    });
+    if (element) {
+      // Tell the ResizeObserver to start watching the element — this enables the hook to detect resizing
+      observerRef.current.observe(element);
+    }
+  }, [element]);
+
+  return useMemo<{
+    ref: LegacyRef<HTMLIFrameElement>,
+    element: HTMLIFrameElement | undefined,
+    width: number,
+    height: number,
+    x: number,
+    y: number,
+  }>(
+    () => ({
+      ref: measuredRef,
+      element: element,
+      width: dimensions.width,
+      height: dimensions.height,
+      x: offset.x,
+      y: offset.y
+    }),
+    [measuredRef, element, dimensions, offset],
+  );
+}

package/runtime/slots/widget/iframe/index.ts

@@ -0,0 +1,6 @@
+export { default as IFrameContentWrapper } from './IFrameContentWrapper';
+export { default as IFrameWidget } from './IFrameWidget';
+export type {
+  MessageEventCallback,
+  MessageEventCallbackParams
+} from './types';

package/runtime/slots/widget/iframe/types.ts

@@ -0,0 +1,7 @@
+export interface MessageEventCallbackParams {
+  type: string,
+  payload: any,
+}
+
+export type MessageEventCallback = ({ type, payload }: MessageEventCallbackParams) => void;
+;

package/runtime/slots/widget/index.ts

@@ -0,0 +1,6 @@
+export * from './hooks';
+export * from './iframe';
+export type * from './types';
+export { WidgetOperationTypes } from './types';
+export * from './utils';
+export { default as WidgetContext } from './WidgetContext';

package/runtime/slots/widget/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Base UI Widget Operations
+ *
+ * "Widget" operations are a sub-type of UI operations which allow manipulation of the list of widgets (UI components) loaded into the slot.  Widget operations are divided further into two sub-types: absolute and relative.
+ *
+ * Absolute widget operations allow simple list operations like appending and prepending which don't depend on any other list elements.
+ *
+ * Relative widget operations depend on a relationship to some other list element, such as "insert before" and "insert after".  Some affect those elements, some add something to the list near them.
+ */
+
+import { ReactNode } from 'react';
+import { BaseSlotOperation } from '../types';
+
+export enum WidgetOperationTypes {
+  /**
+   * Adds a widget to the end of the slot's list of widgets.
+   */
+  APPEND = 'widgetAppend',
+
+  /**
+   * Adds a widget to the beginning of the slot's list of widgets.
+   */
+  PREPEND = 'widgetPrepend',
+
+  /**
+   * Adds a widget after the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
+   */
+  INSERT_AFTER = 'widgetInsertAfter',
+
+  /**
+   * Adds a widget before the specified widget ID.  Multiple "insert after" operations on the same widget ID occur in the order they were declared.
+   */
+  INSERT_BEFORE = 'widgetInsertBefore',
+
+  /**
+   * Removes the specified widget ID and adds a widget in its place.  Multiple "replace" operations on the same widget ID occur in the order they were declared, and only the first will succeed unless the new widget's ID is the same as the one that was removed.
+   */
+  REPLACE = 'widgetReplace',
+
+  /**
+   * Removes the specified widget ID from the slot's list of widgets.  Subsequent relative widget operations on that widget ID will not be applied.
+   */
+  REMOVE = 'widgetRemove',
+
+  /**
+   * Provides options to the specified widget ID.  Multiple "options" operations on the same widget ID will merge with and override any duplicate properties in the options object - last one in wins.
+   */
+  OPTIONS = 'widgetOptions',
+}
+
+export type AbsoluteWidgetOperationTypes = WidgetOperationTypes.APPEND | WidgetOperationTypes.PREPEND;
+
+export type RelativeWidgetOperationTypes = WidgetOperationTypes.INSERT_AFTER | WidgetOperationTypes.INSERT_BEFORE | WidgetOperationTypes.REPLACE | WidgetOperationTypes.OPTIONS;
+
+export interface BaseWidgetOperation extends BaseSlotOperation {
+  op: WidgetOperationTypes,
+}
+
+// Widget renderer props
+
+export interface WidgetComponentProps {
+  component: React.ComponentType,
+}
+
+export interface WidgetElementProps {
+  element: ReactNode,
+}
+
+export interface WidgetIFrameProps {
+  url: string,
+  title: string,
+}
+
+export type WidgetRendererProps = (
+  WidgetComponentProps | WidgetElementProps | WidgetIFrameProps
+);
+
+export interface WidgetIdentityProps {
+  id: string,
+  role?: string,
+}
+
+export interface WidgetRelationshipProps {
+  relatedId: string,
+}
+
+// Concrete UI Widget Operations
+
+export type WidgetAppendOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & {
+  op: WidgetOperationTypes.APPEND,
+};
+
+export type WidgetPrependOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & {
+  op: WidgetOperationTypes.PREPEND,
+};
+
+export type WidgetInsertAfterOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {
+  op: WidgetOperationTypes.INSERT_AFTER,
+};
+
+export type WidgetInsertBeforeOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & {
+  op: WidgetOperationTypes.INSERT_BEFORE,
+};
+
+export type WidgetRemoveOperation = BaseWidgetOperation & WidgetRelationshipProps & {
+  op: WidgetOperationTypes.REMOVE,
+};
+
+export type WidgetOptionsOperation = BaseWidgetOperation & WidgetRelationshipProps & {
+  op: WidgetOperationTypes.OPTIONS,
+  options: Record<string, unknown>,
+};
+
+export type WidgetReplaceOperation = BaseWidgetOperation & WidgetIdentityProps & WidgetRendererProps & WidgetRelationshipProps & { op: WidgetOperationTypes.REPLACE };
+
+export type WidgetAbsoluteOperation = WidgetAppendOperation | WidgetPrependOperation;
+
+export type WidgetRelativeRendererOperation = WidgetInsertAfterOperation | WidgetInsertBeforeOperation | WidgetReplaceOperation;
+
+export type WidgetRelativeOperation = WidgetRelativeRendererOperation | WidgetRemoveOperation | WidgetOptionsOperation;
+
+export type WidgetRendererOperation = WidgetAbsoluteOperation | WidgetRelativeRendererOperation;
+
+export type WidgetOperation = WidgetAbsoluteOperation | WidgetRelativeOperation;
+
+/**
+ * An identified widget is a simple data structure to associate an ID with a ReactNode so we can
+ * apply widget operations to our list of widgets.  It helps us find a ReactNode with a particular
+ * ID for relative widget operations.
+ */
+export interface IdentifiedWidget {
+  id: string,
+  node: ReactNode,
+}