@inventreedb/ui 0.0.1

package/src/components/plugins/PluginPanel.tsx

@@ -0,0 +1,37 @@
+import { Stack } from '@mantine/core';
+import type { ReactNode } from 'react';
+
+import type { InvenTreePluginContext } from '@lib/types/Plugins';
+import type { PluginUIFeature } from './PluginUIFeature';
+import RemoteComponent from './RemoteComponent';
+
+/**
+ * A custom panel which can be used to display plugin content.
+ *
+ * - Content is loaded dynamically (via the API) when a page is first loaded
+ * - Content can be provided from an external javascript module, or with raw HTML
+ *
+ * If content is provided from an external source, it is expected to define a function `render_panel` which will render the content.
+ * const render_panel = (element: HTMLElement, params: any) => {...}
+ *
+ * Where:
+ *  - `element` is the HTML element to render the content into
+ *  - `params` is the set of run-time parameters to pass to the content rendering function
+ */
+export default function PluginPanelContent({
+  pluginFeature,
+  pluginContext
+}: Readonly<{
+  pluginFeature: PluginUIFeature;
+  pluginContext: InvenTreePluginContext;
+}>): ReactNode {
+  return (
+    <Stack gap='xs'>
+      <RemoteComponent
+        source={pluginFeature.source}
+        defaultFunctionName='renderPanel'
+        context={pluginContext}
+      />
+    </Stack>
+  );
+}

package/src/components/plugins/PluginSettingsPanel.tsx

@@ -0,0 +1,34 @@
+import type { InvenTreePluginContext } from '@lib/types/Plugins';
+import { useInvenTreeContext } from './PluginContext';
+import RemoteComponent from './RemoteComponent';
+
+/**
+ * Interface for the plugin admin data
+ */
+export interface PluginAdminInterface {
+  source: string;
+  context: any;
+}
+
+/**
+ * A panel which is used to display custom settings UI for a plugin.
+ *
+ * This settings panel is loaded dynamically,
+ * and requires that the plugin provides a javascript module,
+ * which exports a function `renderPluginSettings`
+ */
+export default function PluginSettingsPanel({
+  pluginAdmin
+}: Readonly<{
+  pluginAdmin: PluginAdminInterface;
+}>) {
+  const ctx: InvenTreePluginContext = useInvenTreeContext();
+
+  return (
+    <RemoteComponent
+      source={pluginAdmin.source}
+      defaultFunctionName='renderPluginSettings'
+      context={{ ...ctx, context: pluginAdmin.context }}
+    />
+  );
+}

package/src/components/plugins/PluginSource.tsx

@@ -0,0 +1,48 @@
+import { generateUrl } from '../../functions/urls';
+
+/*
+ * Load an external plugin source from a URL.
+ */
+export async function loadExternalPluginSource(source: string) {
+  source = source.trim();
+
+  // If no source is provided, clear the plugin content
+  if (!source) {
+    return null;
+  }
+
+  const url = generateUrl(source);
+
+  const module = await import(/* @vite-ignore */ url)
+    .catch((error) => {
+      console.error(`ERR: Failed to load plugin from ${url}:`, error);
+      return null;
+    })
+    .then((module) => {
+      return module;
+    });
+
+  return module;
+}
+
+/*
+ * Find a named function in an external plugin source.
+ */
+export async function findExternalPluginFunction(
+  source: string,
+  functionName: string
+): Promise<Function | null> {
+  // The source URL may also include the function name divided by a colon
+  // otherwise the provided function name will be used
+  if (source.includes(':')) {
+    [source, functionName] = source.split(':');
+  }
+
+  const module = await loadExternalPluginSource(source);
+
+  if (module?.[functionName]) {
+    return module[functionName];
+  }
+
+  return null;
+}

package/src/components/plugins/PluginUIFeature.tsx

@@ -0,0 +1,174 @@
+import { t } from '@lingui/core/macro';
+import { Alert, Stack, Text } from '@mantine/core';
+import { IconExclamationCircle } from '@tabler/icons-react';
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState
+} from 'react';
+
+import type { TemplateI } from '../../tables/settings/TemplateTable';
+import type {
+  EditorComponent,
+  PreviewAreaComponent,
+  PreviewAreaRef
+} from '../editors/TemplateEditor/TemplateEditor';
+import type {
+  PluginUIFuncWithoutInvenTreeContextType,
+  TemplateEditorUIFeature,
+  TemplatePreviewUIFeature
+} from './PluginUIFeatureTypes';
+
+/**
+ * Enumeration for available plugin UI feature types.
+ */
+export enum PluginUIFeatureType {
+  dashboard = 'dashboard',
+  panel = 'panel',
+  template_editor = 'template_editor',
+  template_preview = 'template_preview'
+}
+
+/**
+ * Type definition for a UI component which can be loaded via plugin.
+ * Ref: src/backend/InvenTree/plugin/base/ui/serializers.py:PluginUIFeatureSerializer
+ *
+ * @param plugin_name: The name of the plugin
+ * @param feature_type: The type of the UI feature (see PluginUIFeatureType)
+ * @param key: The unique key for the feature (used to identify the feature in the DOM)
+ * @param title: The title of the feature (human readable)
+ * @param description: A description of the feature (human readable, optional)
+ * @param options: Additional options for the feature (optional, depends on the feature type)
+ * @param context: Additional context data passed to the rendering function (optional)
+ * @param source: The source of the feature (must point to an accessible javascript module)
+ *
+ */
+export interface PluginUIFeature {
+  plugin_name: string;
+  feature_type: PluginUIFeatureType;
+  key: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  options?: any;
+  context?: any;
+  source: string;
+}
+
+export const getPluginTemplateEditor = (
+  func: PluginUIFuncWithoutInvenTreeContextType<TemplateEditorUIFeature>,
+  template: TemplateI
+) =>
+  forwardRef((props, ref) => {
+    const elRef = useRef<HTMLDivElement>();
+    const [error, setError] = useState<string | undefined>(undefined);
+
+    const initialCodeRef = useRef<string>();
+    const setCodeRef = useRef<(code: string) => void>();
+    const getCodeRef = useRef<() => string>();
+
+    useImperativeHandle(ref, () => ({
+      setCode: (code) => {
+        // if the editor is not yet initialized, store the initial code in a ref to set it later
+        if (setCodeRef.current) {
+          setCodeRef.current(code);
+        } else {
+          initialCodeRef.current = code;
+        }
+      },
+      getCode: () => getCodeRef.current?.()
+    }));
+
+    useEffect(() => {
+      let unmountHandler: (() => void) | undefined;
+      (async () => {
+        try {
+          unmountHandler = await func({
+            ref: elRef.current!,
+            registerHandlers: ({ getCode, setCode }) => {
+              setCodeRef.current = setCode;
+              getCodeRef.current = getCode;
+
+              if (initialCodeRef.current) {
+                setCode(initialCodeRef.current);
+              }
+            },
+            template
+          });
+        } catch (error) {
+          setError(t`Error occurred while rendering the template editor.`);
+          console.error(error);
+        }
+      })();
+
+      return () => {
+        if (typeof unmountHandler === 'function') {
+          unmountHandler();
+        }
+      };
+    }, []);
+
+    return (
+      <Stack gap='xs' style={{ display: 'flex', flex: 1 }}>
+        {error && (
+          <Alert
+            color='red'
+            title={t`Error Loading Plugin Editor`}
+            icon={<IconExclamationCircle />}
+          >
+            <Text>{error}</Text>
+          </Alert>
+        )}
+        <div ref={elRef as any} style={{ display: 'flex', flex: 1 }} />
+      </Stack>
+    );
+  }) as EditorComponent;
+
+export const getPluginTemplatePreview = (
+  func: PluginUIFuncWithoutInvenTreeContextType<TemplatePreviewUIFeature>,
+  template: TemplateI
+) =>
+  forwardRef((props, ref) => {
+    const elRef = useRef<HTMLDivElement>();
+    const [error, setError] = useState<string | undefined>(undefined);
+
+    const updatePreviewRef = useRef<PreviewAreaRef['updatePreview']>();
+
+    useImperativeHandle(ref, () => ({
+      updatePreview: (...args) => updatePreviewRef.current?.(...args)
+    }));
+
+    useEffect(() => {
+      (async () => {
+        try {
+          func({
+            ref: elRef.current!,
+            registerHandlers: ({ updatePreview }) => {
+              updatePreviewRef.current = updatePreview;
+            },
+            template
+          });
+        } catch (error) {
+          setError(t`Error occurred while rendering the template preview.`);
+          console.error(error);
+        }
+      })();
+    }, []);
+
+    return (
+      <Stack gap='xs' style={{ display: 'flex', flex: 1 }}>
+        {error && (
+          <Alert
+            color='red'
+            title={t`Error Loading Plugin Preview`}
+            icon={<IconExclamationCircle />}
+          >
+            <Text>{error}</Text>
+          </Alert>
+        )}
+        <div ref={elRef as any} style={{ display: 'flex', flex: 1 }} />
+      </Stack>
+    );
+  }) as PreviewAreaComponent;

package/src/components/plugins/PluginUIFeatureTypes.ts

@@ -0,0 +1,78 @@
+import type { ModelType } from '@lib/enums/ModelType';
+import type { InvenTreePluginContext } from '@lib/types/Plugins';
+import type { InvenTreeIconType } from '../../functions/icons';
+import type { TemplateI } from '../../tables/settings/TemplateTable';
+import type { TemplateEditorProps } from '../editors/TemplateEditor/TemplateEditor';
+import type { PluginUIFeature } from './PluginUIFeature';
+
+// #region  Type Helpers
+export type BaseUIFeature = {
+  featureType: string;
+  requestContext: Record<string, any>;
+  responseOptions: Record<string, any>;
+  featureContext: Record<string, any>;
+  featureReturnType: any;
+};
+
+export type PluginUIGetFeatureType<
+  T extends BaseUIFeature,
+  ServerContext extends Record<string, unknown>
+> = (params: {
+  featureContext: T['featureContext'];
+  inventreeContext: InvenTreePluginContext;
+  serverContext: ServerContext;
+}) => T['featureReturnType'];
+
+export type PluginUIFuncWithoutInvenTreeContextType<T extends BaseUIFeature> = (
+  featureContext: T['featureContext']
+) => T['featureReturnType'];
+
+export type PluginUIFeatureAPIResponse<T extends BaseUIFeature> = {
+  feature_type: T['featureType'];
+  source: string;
+} & T['responseOptions'];
+
+// #region Types
+export type TemplateEditorUIFeature = {
+  featureType: 'template_editor';
+  requestContext: {
+    template_type: ModelType.labeltemplate | ModelType.reporttemplate;
+    template_model: ModelType;
+  };
+  responseOptions: PluginUIFeature;
+  featureContext: {
+    ref: HTMLDivElement;
+    registerHandlers: (handlers: {
+      setCode: (code: string) => void;
+      getCode: () => string;
+    }) => void;
+    template: TemplateI;
+  };
+  featureReturnType: (() => void) | undefined;
+};
+
+export type TemplatePreviewUIFeature = {
+  featureType: 'template_preview';
+  requestContext: {
+    template_type: ModelType.labeltemplate | ModelType.reporttemplate;
+    template_model: ModelType;
+  };
+  responseOptions: {
+    key: string;
+    title: string;
+    icon: InvenTreeIconType;
+  };
+  featureContext: {
+    ref: HTMLDivElement;
+    template: TemplateI;
+    registerHandlers: (handlers: {
+      updatePreview: (
+        code: string,
+        previewItem: string,
+        saveTemplate: boolean,
+        templateEditorProps: TemplateEditorProps
+      ) => void | Promise<void>;
+    }) => void;
+  };
+  featureReturnType: undefined;
+};

package/src/components/plugins/RemoteComponent.tsx

@@ -0,0 +1,137 @@
+import { t } from '@lingui/core/macro';
+import { Alert, MantineProvider, Stack, Text } from '@mantine/core';
+import { IconExclamationCircle } from '@tabler/icons-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { InvenTreePluginContext } from '@lib/types/Plugins';
+import { type Root, createRoot } from 'react-dom/client';
+import { api, queryClient } from '../../App';
+import { ApiProvider } from '../../contexts/ApiContext';
+import { LanguageContext } from '../../contexts/LanguageContext';
+import { identifierString } from '../../functions/conversion';
+import { Boundary } from '../Boundary';
+import { findExternalPluginFunction } from './PluginSource';
+
+/**
+ * A remote component which can be used to display plugin content.
+ * Content is loaded dynamically (from an external source).
+ *
+ * @param pluginFeature: The plugin feature to render
+ * @param defaultFunctionName: The default function name to call (if not overridden by pluginFeature.source)
+ * @param pluginContext: The context to pass to the plugin function
+ *
+ */
+export default function RemoteComponent({
+  source,
+  defaultFunctionName,
+  context
+}: Readonly<{
+  source: string;
+  defaultFunctionName: string;
+  context: InvenTreePluginContext;
+}>) {
+  const componentRef = useRef<HTMLDivElement>();
+  const [rootElement, setRootElement] = useState<Root | null>(null);
+
+  useEffect(() => {
+    if (componentRef.current && !rootElement) {
+      setRootElement(createRoot(componentRef.current));
+    }
+  }, [componentRef.current]);
+
+  const [renderingError, setRenderingError] = useState<string | undefined>(
+    undefined
+  );
+
+  const sourceFile = useMemo(() => {
+    return source.split(':')[0];
+  }, [source]);
+
+  // Determine the function to call in the external plugin source
+  const functionName = useMemo(() => {
+    // The "source" string may contain a function name, e.g. "source.js:myFunction"
+    if (source.includes(':')) {
+      return source.split(':')[1];
+    }
+
+    // By default, return the default function name
+    return defaultFunctionName;
+  }, [source, defaultFunctionName]);
+
+  const reloadPluginContent = useCallback(() => {
+    if (!rootElement) {
+      return;
+    }
+
+    if (sourceFile && functionName) {
+      findExternalPluginFunction(sourceFile, functionName)
+        .then((func) => {
+          if (!!func) {
+            try {
+              if (func.length > 1) {
+                // Support "legacy" plugin functions which call createRoot() internally
+                // Ref: https://github.com/inventree/InvenTree/pull/9439/
+                func(componentRef.current, context);
+              } else {
+                // Render the plugin component into the target element
+                // Note that we have to provide the right context(s) to the component
+                // This approach ensures that the component is rendered in the correct context tree
+                rootElement.render(
+                  <ApiProvider client={queryClient} api={api}>
+                    <MantineProvider
+                      theme={context.theme}
+                      defaultColorScheme={context.colorScheme}
+                    >
+                      <LanguageContext>{func(context)}</LanguageContext>
+                    </MantineProvider>
+                  </ApiProvider>
+                );
+              }
+
+              setRenderingError('');
+            } catch (error) {
+              setRenderingError(`${error}`);
+              console.error(error);
+            }
+          } else {
+            setRenderingError(`${sourceFile}:${functionName}`);
+          }
+        })
+        .catch((_error) => {
+          console.error(
+            `ERR: Failed to load remove plugin function: ${sourceFile}:${functionName}`
+          );
+        });
+    } else {
+      setRenderingError(
+        `${t`Invalid source or function name`} - ${sourceFile}:${functionName}`
+      );
+    }
+  }, [componentRef, rootElement, sourceFile, functionName, context]);
+
+  // Reload the plugin content dynamically
+  useEffect(() => {
+    reloadPluginContent();
+  }, [sourceFile, functionName, context, rootElement]);
+
+  return (
+    <Boundary
+      label={identifierString(`RemoteComponent-${sourceFile}-${functionName}`)}
+    >
+      <Stack gap='xs'>
+        {renderingError && (
+          <Alert
+            color='red'
+            title={t`Error Loading Content`}
+            icon={<IconExclamationCircle />}
+          >
+            <Text>
+              {t`Error occurred while loading plugin content`}: {renderingError}
+            </Text>
+          </Alert>
+        )}
+        {componentRef && <div ref={componentRef as any} />}
+      </Stack>
+    </Boundary>
+  );
+}

package/src/components/render/Build.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react';
+
+import { ModelType } from '@lib/enums/ModelType';
+import { getDetailUrl } from '../../functions/urls';
+import { type InstanceRenderInterface, RenderInlineModel } from './Instance';
+import { StatusRenderer } from './StatusRenderer';
+
+/**
+ * Inline rendering of a single BuildOrder instance
+ */
+export function RenderBuildOrder(
+  props: Readonly<InstanceRenderInterface>
+): ReactNode {
+  const { instance } = props;
+
+  return (
+    <RenderInlineModel
+      {...props}
+      primary={instance.reference}
+      secondary={instance.title}
+      suffix={StatusRenderer({
+        status: instance.status_custom_key,
+        type: ModelType.build
+      })}
+      image={instance.part_detail?.thumbnail || instance.part_detail?.image}
+      url={props.link ? getDetailUrl(ModelType.build, instance.pk) : undefined}
+    />
+  );
+}
+
+/*
+ * Inline rendering of a single BuildLine instance
+ */
+export function RenderBuildLine({
+  instance
+}: Readonly<InstanceRenderInterface>): ReactNode {
+  return (
+    <RenderInlineModel
+      primary={instance.part_detail.full_name}
+      secondary={instance.quantity}
+      suffix={StatusRenderer({
+        status: instance.status_custom_key,
+        type: ModelType.build
+      })}
+      image={instance.part_detail.thumbnail || instance.part_detail.image}
+    />
+  );
+}
+
+export function RenderBuildItem({
+  instance
+}: Readonly<InstanceRenderInterface>): ReactNode {
+  return <RenderInlineModel primary={instance.pk} />;
+}

package/src/components/render/Company.tsx

@@ -0,0 +1,114 @@
+import { Text } from '@mantine/core';
+import type { ReactNode } from 'react';
+
+import { ModelType } from '@lib/enums/ModelType';
+import { getDetailUrl } from '../../functions/urls';
+import { type InstanceRenderInterface, RenderInlineModel } from './Instance';
+
+/**
+ * Inline rendering of a single Address instance
+ */
+export function RenderAddress({
+  instance
+}: Readonly<InstanceRenderInterface>): ReactNode {
+  const text = [
+    instance.country,
+    instance.postal_code,
+    instance.postal_city,
+    instance.province,
+    instance.line1,
+    instance.line2
+  ]
+    .filter(Boolean)
+    .join(', ');
+
+  return <RenderInlineModel primary={instance.title} secondary={text} />;
+}
+
+/**
+ * Inline rendering of a single Company instance
+ */
+export function RenderCompany(
+  props: Readonly<InstanceRenderInterface>
+): ReactNode {
+  const { instance } = props;
+
+  return (
+    <RenderInlineModel
+      {...props}
+      image={instance.thumnbnail || instance.image}
+      primary={instance.name}
+      secondary={instance.description}
+      url={
+        props.link ? getDetailUrl(ModelType.company, instance.pk) : undefined
+      }
+    />
+  );
+}
+
+/**
+ * Inline rendering of a single Contact instance
+ */
+export function RenderContact({
+  instance
+}: Readonly<InstanceRenderInterface>): ReactNode {
+  return <RenderInlineModel primary={instance.name} />;
+}
+
+/**
+ * Inline rendering of a single SupplierPart instance
+ */
+export function RenderSupplierPart(
+  props: Readonly<InstanceRenderInterface>
+): ReactNode {
+  const { instance } = props;
+  const supplier = instance.supplier_detail ?? {};
+  const part = instance.part_detail ?? {};
+
+  return (
+    <RenderInlineModel
+      {...props}
+      primary={supplier?.name}
+      secondary={instance.SKU}
+      image={
+        part?.thumbnail ?? part?.image ?? supplier?.thumbnail ?? supplier?.image
+      }
+      suffix={
+        part.full_name ? <Text size='sm'>{part.full_name}</Text> : undefined
+      }
+      url={
+        props.link
+          ? getDetailUrl(ModelType.supplierpart, instance.pk)
+          : undefined
+      }
+    />
+  );
+}
+
+/**
+ * Inline rendering of a single ManufacturerPart instance
+ */
+export function RenderManufacturerPart(
+  props: Readonly<InstanceRenderInterface>
+): ReactNode {
+  const { instance } = props;
+  const part = instance.part_detail ?? {};
+  const manufacturer = instance.manufacturer_detail ?? {};
+
+  return (
+    <RenderInlineModel
+      {...props}
+      primary={manufacturer.name}
+      secondary={instance.MPN}
+      suffix={
+        part.full_name ? <Text size='sm'>{part.full_name}</Text> : undefined
+      }
+      image={manufacturer?.thumnbnail ?? manufacturer.image}
+      url={
+        props.link
+          ? getDetailUrl(ModelType.manufacturerpart, instance.pk)
+          : undefined
+      }
+    />
+  );
+}