feat: add direct plugin framework

src/plugins/directPlugins/DirectPlugin.jsx

@@ -0,0 +1,60 @@
+import React from 'react';
+
+/**
+ * Context which makes the list of all plugin changes (allPluginChanges) available to the <DirectSlot> components
+ * below it in the React tree
+ */
+export const DirectPluginContext = React.createContext([]);
+
+/**
+ * @description DirectPluginOperation defines the changes to be made to either the default widget(s) or to any
+ * that are inserted
+ * @property {string} Insert - inserts a new widget into the DirectPluginSlot
+ * @property {string} Hide - used to hide a default widget based on the widgetId
+ * @property {string} Modify - used to modify/replace a widget's content
+ * @property {string} Wrap - wraps a widget with a React element or fragment
+ *
+ */
+
+export const DirectPluginOperations = {
+  Insert: 'insert',
+  Hide: 'hide',
+  Modify: 'modify',
+  Wrap: 'wrap',
+};
+
+/**
+  This is what the allSlotChanges configuration should look like when passed into DirectPluginContext
+  {
+    id: "allDirectPluginChanges",
+    getDirectSlotChanges() {
+      return {
+        "main-nav": [
+          // Hide the "Drafts" link, except for administrators:
+          {
+            op: DirectPluginChangeOperation.Wrap,
+            widgetId: "drafts",
+            wrapper: HideExceptForAdmin,
+          },
+          // Add a new login link:
+          {
+            op: DirectPluginChangeOperation.Insert,
+            widget: { id: "login", priority: 50, content: {
+                url: "/login", icon: "person-fill", label: <FormattedMessage defaultMessage="Login" />
+            }},
+          },
+        ],
+      };
+    },
+  };
+ */
+
+/**
+  This is what a slotChanges configuration should include depending on the operation:
+  slotChanges = [
+    { op: DirectPluginOperation.Insert; widget: <DirectSlotWidget object> },
+    { op: DirectPluginOperation.Hide; widgetId: string },
+    { op: DirectPluginOperation.Modify; widgetId: string, fn: (widget: <DirectSlotWidget>) => <DirectSlotWidget> },
+    { op: DirectPluginOperation.Wrap; widgetId: string, wrapper: React.FC<{widget: React.ReactElement }> },
+  ]
+ */

src/plugins/directPlugins/DirectPluginSlot.jsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+import { DirectPluginContext } from './DirectPlugin';
+import organizePlugins from './utils';
+
+const DirectPluginSlot = ({ defaultContents, slotId, renderWidget }) => {
+  const allPluginChanges = React.useContext(DirectPluginContext);
+
+  const contents = React.useMemo(() => {
+    const slotChanges = allPluginChanges.getDirectSlotChanges()[slotId] ?? [];
+    return organizePlugins(defaultContents, slotChanges);
+  }, [allPluginChanges, defaultContents, slotId]);
+
+  return (
+    <>
+      {contents.map((c) => {
+        if (c.hidden) {
+          return null;
+        }
+        if (c.wrappers) {
+          // TODO: define how the reduce logic is able to wrap widgets and make it testable
+          // eslint-disable-next-line max-len
+          return c.wrappers.reduce((widget, wrapper) => React.createElement(wrapper, { widget, key: c.id }), renderWidget(c));
+        }
+        return renderWidget(c);
+      })}
+    </>
+  );
+};
+
+DirectPluginSlot.propTypes = {
+  defaultContents: PropTypes.shape([]),
+  slotId: PropTypes.string.isRequired,
+  renderWidget: PropTypes.func.isRequired,
+};
+
+DirectPluginSlot.defaultProps = {
+  defaultContents: [],
+};
+
+export default DirectPluginSlot;

src/plugins/directPlugins/index.js

@@ -0,0 +1,10 @@
+export {
+  default as DirectPluginSlot,
+} from './DirectPluginSlot';
+export {
+  DirectPluginContext,
+  DirectPluginOperations,
+} from './DirectPlugin';
+export {
+  default as organizePlugins,
+} from './utils';

src/plugins/directPlugins/mocks/DefaultComponentMock.jsx

@@ -0,0 +1,33 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+import { Icon } from '@edx/paragon';
+import { DirectPluginSlot, DirectPluginContext } from '..';
+import { navLinksPlugin } from './PluginComponentsMock';
+
+// TODO: remove DirectPluginsContext and enabledPlugins from here once we have an example app
+// these simply demonstrate how the root App would have needed this setup in order to pass in the plugin config
+// and make it available to a given DirectPluginSlot
+
+const enabledPlugins = [
+  navLinksPlugin,
+];
+
+const MyApp = () => (
+  <DirectPluginContext value={enabledPlugins}>
+    <div>
+      <DirectPluginSlot
+        slotId="side-bar-nav"
+        defaultContents={navLinksPlugin.defaultLinks}
+        renderWidget={(link) => (
+          <a
+            href={link.content.url}
+            key={link.id}
+          >
+            <Icon src={link.content.icon} /> {link.content.label}
+          </a>
+        )}
+      />
+    </div>
+  </DirectPluginContext>
+);
+
+export default MyApp;

src/plugins/directPlugins/mocks/PluginComponentsMock.jsx

@@ -0,0 +1,65 @@
+/* eslint-disable react/prop-types */
+// eslint-disable-next-line import/no-extraneous-dependencies
+import React from 'react';
+import {
+  House, Star, InsertDriveFile, Login,
+} from '@edx/paragon/icons';
+import { DirectPluginOperations } from '..';
+
+/** This is for us to be able to mock in tests */
+const isAdminHelper = () => true;
+
+/** This is a React widget that wraps its children and makes them visible only to administrators */
+const HideExceptForAdmin = ({ widget }) => {
+  const isAdmin = isAdminHelper();
+  return <React.Fragment key={widget.key}>{isAdmin ? widget : null}</React.Fragment>;
+};
+
+const navLinksPlugin = {
+  id: 'links-demo', // id isn't used anywhere, but can be extended to
+  defaultComponentProps: [
+    {
+      id: 'home',
+      priority: 5,
+      content: { url: '/', icon: House, label: 'Home' },
+    },
+    {
+      id: 'lookup',
+      priority: 25,
+      content: { url: '/lookup', icon: Star, label: 'Lookup' },
+    },
+    {
+      id: 'drafts',
+      priority: 35,
+      content: { url: '/drafts', icon: InsertDriveFile, label: 'Drafts' },
+    },
+  ],
+  getDirectSlotChanges() {
+    return {
+      'side-bar-nav': [ // slot id that is used by directpluginslot
+        // Hide the "Drafts" link, except for administrators:
+        {
+          op: DirectPluginOperations.Wrap,
+          widgetId: 'drafts',
+          wrapper: HideExceptForAdmin,
+        },
+        // Add a new login link after the rest of default plugins:
+        {
+          op: DirectPluginOperations.Insert,
+          widget: {
+            id: 'login',
+            priority: 50,
+            content: {
+              url: '/login', icon: Login, label: 'Login',
+            },
+          },
+        },
+      ],
+    };
+  },
+};
+
+export {
+  isAdminHelper,
+  navLinksPlugin,
+};

src/plugins/directPlugins/utils.jsx

@@ -0,0 +1,41 @@
+import { DirectPluginOperations } from './DirectPlugin';
+
+/**
+ * Called by DirectPluginSlot to prepare the plugin changes for the given slot
+ *
+ * @param {Array} defaultContents - The default widgets where the plugin slot exists.
+ * @param {Array} slotChanges - All of the changes assigned to the specific plugin slot
+ * @returns {Array} - A sorted list of widgets with any additional properties needed to render them in the plugin slot
+ */
+const organizePlugins = (defaultContents, slotChanges) => {
+  const newContents = [...defaultContents];
+
+  slotChanges.forEach(change => {
+    if (change.op === DirectPluginOperations.Insert) {
+      newContents.push(change.widget);
+    } else if (change.op === DirectPluginOperations.Hide) {
+      const widget = newContents.find((w) => w.id === change.widgetId);
+      if (widget) { widget.hidden = true; }
+    } else if (change.op === DirectPluginOperations.Modify) {
+      const widgetIdx = newContents.findIndex((w) => w.id === change.widgetId);
+      if (widgetIdx >= 0) {
+        const widget = { ...newContents[widgetIdx] };
+        newContents[widgetIdx] = change.fn(widget);
+      }
+    } else if (change.op === DirectPluginOperations.Wrap) {
+      const widgetIdx = newContents.findIndex((w) => w.id === change.widgetId);
+      if (widgetIdx >= 0) {
+        const newWidget = { wrappers: [], ...newContents[widgetIdx] };
+        newWidget.wrappers.push(change.wrapper);
+        newContents[widgetIdx] = newWidget;
+      }
+    } else {
+      throw new Error('unknown direct plugin change operation');
+    }
+  });
+
+  newContents.sort((a, b) => (a.priority - b.priority) * 10_000 + a.id.localeCompare(b.id));
+  return newContents;
+};
+
+export default organizePlugins;