@openedx/frontend-base 1.0.0-alpha.9 → 1.0.0

package/runtime/slots/hooks.ts

@@ -1,35 +0,0 @@
-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/layout/DefaultSlotLayout.test.tsx

@@ -1,31 +0,0 @@
-import { render } from '@testing-library/react';
-import { useWidgets } from '../widget/hooks';
-import DefaultSlotLayout from './DefaultSlotLayout';
-
-// Mock the useWidgets hook
-jest.mock('../widget/hooks', () => ({
-  useWidgets: jest.fn(),
-}));
-
-describe('DefaultSlotLayout', () => {
-  it('renders widgets returned by useWidgets hook', () => {
-    const mockWidgets = [
-      <div key="widget1">Widget One</div>,
-      <div key="widget2">Widget Two</div>,
-    ];
-    (useWidgets as jest.Mock).mockReturnValue(mockWidgets);
-
-    const { getByText } = render(<DefaultSlotLayout />);
-
-    expect(getByText('Widget One')).toBeInTheDocument();
-    expect(getByText('Widget Two')).toBeInTheDocument();
-  });
-
-  it('renders empty when no widgets are returned', () => {
-    (useWidgets as jest.Mock).mockReturnValue([]);
-
-    const { container } = render(<DefaultSlotLayout />);
-
-    expect(container).toBeEmptyDOMElement();
-  });
-});

package/runtime/slots/layout/DefaultSlotLayout.tsx

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

package/runtime/slots/layout/hooks.test.tsx

@@ -1,178 +0,0 @@
-import { renderHook } from '@testing-library/react';
-import { SlotOperation } from '../types';
-import * as slotHooks from '../hooks';
-import * as slotUtils from '../utils';
-import { WidgetAppendOperation, WidgetOperationTypes } from '../widget';
-import { useLayoutForSlotId, useLayoutOptions, useLayoutOptionsForId } from './hooks';
-import { LayoutOperationTypes, LayoutReplaceOperation } from './types';
-
-jest.mock('../hooks'); // mocks the useSlotOperations hook
-
-function MockLayout() {
-  return (
-    <div>Mock Component</div>
-  );
-}
-
-describe('useLayoutForSlotId', () => {
-  beforeEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('should return null when no replace layout operations are provided', () => {
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([]);
-    const { result } = renderHook(() => useLayoutForSlotId('test-slot.ui'));
-    expect(result.current).toBeNull();
-  });
-
-  it('should return a layout component when replace layout operation is present', () => {
-    const operation: LayoutReplaceOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-      component: MockLayout
-    };
-
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation]);
-    const { result } = renderHook(() => useLayoutForSlotId('test-slot.ui'));
-    expect(result.current).toEqual(MockLayout);
-  });
-
-  it('should return null if the operation condition is not satisfied', () => {
-    const operation: LayoutReplaceOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-      component: MockLayout
-    };
-
-    jest.spyOn(slotUtils, 'isSlotOperationConditionSatisfied').mockReturnValue(false);
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation]);
-    const { result } = renderHook(() => useLayoutForSlotId('test-slot.ui'));
-    expect(result.current).toBeNull();
-  });
-
-  it('should return a layout element when replace layout operation is present', () => {
-    const operation: LayoutReplaceOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-      element: <div>Mock layout</div>
-    };
-
-    // @ts-expect-error This is an intentionally malformed operation to test what happens when component/element are not present.
-    const malformedOperation: SlotOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-    };
-
-    const unrelatedOperation: WidgetAppendOperation = {
-      slotId: 'test-slot.ui',
-      id: 'test-slot.widget1',
-      op: WidgetOperationTypes.APPEND,
-      element: <div>Widget</div>
-    };
-
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation, malformedOperation, unrelatedOperation]);
-    const { result } = renderHook(() => useLayoutForSlotId('test-slot.ui'));
-    expect(result.current).toEqual(<div>Mock layout</div>);
-  });
-
-  it('should return the last layout component in the operations list', () => {
-    const SecondMockLayout = () => <div>First Component</div>;
-
-    const operation1: LayoutReplaceOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-      component: MockLayout
-    };
-
-    const operation2: LayoutReplaceOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-      component: SecondMockLayout
-    };
-
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation1, operation2]);
-    const { result } = renderHook(() => useLayoutForSlotId('test-slot.ui'));
-    expect(result.current).toEqual(SecondMockLayout);
-  });
-});
-
-describe('useLayoutOptionsForId', () => {
-  beforeEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('should return an empty object whent here are no layout options operations', () => {
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([]);
-    const { result } = renderHook(() => useLayoutOptionsForId('test-slot.ui'));
-    expect(result.current).toEqual({});
-  });
-
-  it('should return an object containing options from a single layout options operation', () => {
-    const mockOptions = { option1: 'value1' };
-    const operation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.OPTIONS,
-      options: mockOptions
-    };
-
-    const otherOperation: LayoutReplaceOperation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.REPLACE,
-      element: <div>Layout</div>
-    };
-
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation, otherOperation]);
-    const { result } = renderHook(() => useLayoutOptionsForId('test-slot.ui'));
-    expect(result.current).toEqual(mockOptions);
-  });
-
-  describe('when various failure conditions are true', () => {
-    const mockOptions = { option1: 'value1' };
-    const operation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.OPTIONS,
-      options: mockOptions
-    };
-
-    it('should return an empty object if the operation condition is not satisfied.', () => {
-      jest.spyOn(slotUtils, 'isSlotOperationConditionSatisfied').mockReturnValue(false);
-      (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation]);
-      const { result } = renderHook(() => useLayoutOptionsForId('test-slot.ui'));
-      expect(result.current).toEqual({});
-    });
-  });
-
-  it('should return merged layout options from multiple operations', () => {
-    const mockOptions1 = { option1: 'value1', optionOverride: 'foo', };
-    const mockOptions2 = { option2: 'value2', optionOverride: 'bar' };
-    const operation1 = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.OPTIONS,
-      options: mockOptions1
-    };
-    const operation2 = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.OPTIONS,
-      options: mockOptions2
-    };
-
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation1, operation2]);
-    const { result } = renderHook(() => useLayoutOptionsForId('test-slot.ui'));
-    expect(result.current).toEqual({ option1: 'value1', option2: 'value2', optionOverride: 'bar' });
-  });
-});
-
-describe('useLayoutOptions', () => {
-  it('should call useLayoutOptionsForId with the correct id ', () => {
-    const mockOptions1 = { option1: 'value1' };
-    const operation = {
-      slotId: 'test-slot.ui',
-      op: LayoutOperationTypes.OPTIONS,
-      options: mockOptions1
-    };
-    (slotHooks.useSlotOperations as jest.Mock).mockReturnValue([operation]);
-    jest.spyOn(slotHooks, 'useSlotContext').mockReturnValue({ id: 'test-slot.ui' });
-    const { result } = renderHook(() => useLayoutOptions());
-    expect(result.current).toEqual({ option1: 'value1' });
-  });
-});

package/runtime/slots/layout/hooks.ts

@@ -1,65 +0,0 @@
-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/types.ts

@@ -1,45 +0,0 @@
-/**
- * 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.test.ts

@@ -1,67 +0,0 @@
-import { SlotOperation } from '../types';
-import { WidgetOperationTypes } from '../widget';
-import { LayoutOperationTypes } from './types';
-import { isLayoutOperation, isLayoutOptionsOperation, isLayoutReplaceOperation } from './utils';
-
-describe('UI Layout Operation utilities', () => {
-  describe('isLayoutOperation', () => {
-    it('should return true for valid LayoutOperation', () => {
-      const operation: SlotOperation = {
-        slotId: 'mock.slot.ui',
-        op: LayoutOperationTypes.OPTIONS,
-        options: {},
-      };
-      expect(isLayoutOperation(operation)).toBe(true);
-    });
-
-    it('should return false for invalid LayoutOperation', () => {
-      const operation: SlotOperation = {
-        slotId: 'mock.slot.ui',
-        op: WidgetOperationTypes.APPEND,
-        id: 'mock.slot.widget',
-        element: '',
-      };
-      expect(isLayoutOperation(operation)).toBe(false);
-    });
-  });
-
-  describe('isLayoutOptionsOperation', () => {
-    it('should return true for valid LayoutOptionsOperation', () => {
-      const operation: SlotOperation = {
-        slotId: 'mock.slot.ui',
-        op: LayoutOperationTypes.OPTIONS,
-        options: {},
-      };
-      expect(isLayoutOptionsOperation(operation)).toBe(true);
-    });
-
-    it('should return false for invalid LayoutOptionsOperation', () => {
-      const operation: SlotOperation = {
-        slotId: 'mock.slot.ui',
-        op: LayoutOperationTypes.REPLACE,
-        element: '',
-      };
-      expect(isLayoutOptionsOperation(operation)).toBe(false);
-    });
-  });
-
-  describe('isLayoutReplaceOperation', () => {
-    it('should return true for valid LayoutReplaceOperation', () => {
-      const operation: SlotOperation = {
-        slotId: 'mock.slot.ui',
-        op: LayoutOperationTypes.REPLACE,
-        element: '',
-      };
-      expect(isLayoutReplaceOperation(operation)).toBe(true);
-    });
-
-    it('should return false for invalid LayoutReplaceOperation', () => {
-      const operation: SlotOperation = {
-        slotId: 'mock.slot.ui',
-        op: LayoutOperationTypes.OPTIONS,
-        options: {},
-      };
-      expect(isLayoutReplaceOperation(operation)).toBe(false);
-    });
-  });
-});

package/runtime/slots/layout/utils.ts

@@ -1,14 +0,0 @@
-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

@@ -1,24 +0,0 @@
-/**
- * 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[],
-  inactive?: string[],
-  authenticated?: boolean,
-  callback?: () => boolean,
-}
-
-export interface BaseSlotOperation {
-  slotId: string,
-  condition?: SlotOperationCondition,
-}
-
-// Aggregate Slot Operations
-
-export type SlotOperation = WidgetOperation | LayoutOperation;

package/runtime/slots/utils.test.ts

@@ -1,64 +0,0 @@
-import { getSiteConfig } from '../config';
-import { SlotOperation } from './types';
-import { getSlotOperations } from './utils';
-import { WidgetOperationTypes } from '.';
-
-jest.mock('../config');
-
-describe('getSlotOperations', () => {
-  it('should return an empty array if no apps are configured', () => {
-    (getSiteConfig as jest.Mock).mockReturnValue({ apps: [] });
-    const result = getSlotOperations('test-slot.ui');
-    expect(result).toEqual([]);
-  });
-
-  it('should return an empty array if no slots are present in apps', () => {
-    (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: [] }] });
-    const result = getSlotOperations('test-slot.ui');
-    expect(result).toEqual([]);
-  });
-
-  it('should return an empty array if no matching slotId is found', () => {
-    const mockSlots: SlotOperation[] = [{ slotId: 'other-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' }];
-    (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: mockSlots }] });
-    const result = getSlotOperations('test-slot.ui');
-    expect(result).toEqual([]);
-  });
-
-  it('should return the correct slot operations for a given slotId', () => {
-    const mockSlots: SlotOperation[] = [
-      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
-      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
-      { slotId: 'other-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget3', element: '' },
-    ];
-    (getSiteConfig as jest.Mock).mockReturnValue({ apps: [{ slots: mockSlots }] });
-    const result = getSlotOperations('test-slot.ui');
-    expect(result).toEqual([
-      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
-      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
-    ]);
-  });
-
-  it('should handle multiple apps with slots correctly', () => {
-    (getSiteConfig as jest.Mock).mockReturnValue({
-      apps: [
-        {
-          slots: [
-            { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
-          ]
-        },
-        {
-          slots: [
-            { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
-            { slotId: 'other-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget3', element: '' },
-          ]
-        }
-      ]
-    });
-    const result = getSlotOperations('test-slot.ui');
-    expect(result).toEqual([
-      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget1', element: '' },
-      { slotId: 'test-slot.ui', op: WidgetOperationTypes.APPEND, id: 'widget2', element: '' },
-    ]);
-  });
-});

package/runtime/slots/utils.ts

@@ -1,78 +0,0 @@
-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 || condition?.inactive !== undefined) {
-    const activeRoles: string[] = getActiveRoles();
-
-    if (condition?.active !== undefined) {
-      let activeConditionRoleFound = false;
-      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?.inactive !== undefined) {
-      let inactiveConditionRoleFound = false;
-      for (const conditionRole of condition.inactive) {
-        if (activeRoles.includes(conditionRole)) {
-          inactiveConditionRoleFound = true;
-          break;
-        }
-      }
-
-      // If we find an active role from our inactive list, then we've failed this condition.
-      if (inactiveConditionRoleFound) {
-        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

@@ -1,9 +0,0 @@
-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

@@ -1,30 +0,0 @@
-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>
-  );
-}