@inventreedb/ui 0.0.1

package/src/hooks/UsePluginPanels.tsx

@@ -0,0 +1,123 @@
+import { type UseQueryResult, useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+
+import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import type { ModelType } from '@lib/enums/ModelType';
+import { apiUrl } from '@lib/functions/Api';
+import type { InvenTreePluginContext } from '@lib/types/Plugins';
+import { api } from '../App';
+import { ApiIcon } from '../components/items/ApiIcon';
+import type { PanelType } from '../components/panels/Panel';
+import { useInvenTreeContext } from '../components/plugins/PluginContext';
+import PluginPanelContent from '../components/plugins/PluginPanel';
+import {
+  type PluginUIFeature,
+  PluginUIFeatureType
+} from '../components/plugins/PluginUIFeature';
+import { useGlobalSettingsState } from '../states/SettingsState';
+
+/**
+ * Type definition for a plugin panel which extends the standard PanelType
+ * @param pluginName - The name of the plugin which provides this panel
+ */
+export type PluginPanelType = PanelType & {
+  pluginName: string;
+  isLoading: boolean;
+};
+
+export type PluginPanelSet = {
+  panels: PluginPanelType[];
+  query: UseQueryResult;
+  isLoading: boolean;
+};
+
+export function usePluginPanels({
+  instance,
+  model,
+  id
+}: {
+  instance?: any;
+  model?: ModelType | string;
+  id?: string | number | null;
+}): PluginPanelSet {
+  const globalSettings = useGlobalSettingsState();
+
+  const pluginPanelsEnabled: boolean = useMemo(
+    () => globalSettings.isSet('ENABLE_PLUGINS_INTERFACE'),
+    [globalSettings]
+  );
+
+  // API query to fetch initial information on available plugin panels
+  const pluginQuery = useQuery({
+    enabled: pluginPanelsEnabled && !!model && id !== undefined,
+    queryKey: ['custom-plugin-panels', model, id],
+    queryFn: async () => {
+      if (!pluginPanelsEnabled || !model) {
+        return Promise.resolve([]);
+      }
+
+      const url = apiUrl(ApiEndpoints.plugin_ui_features_list, undefined, {
+        feature_type: PluginUIFeatureType.panel
+      });
+
+      return api
+        .get(url, {
+          params: {
+            target_model: model,
+            target_id: id
+          }
+        })
+        .then((response: any) => response.data)
+        .catch((_error: any) => {
+          console.error('ERR: Failed to fetch plugin panels');
+          return [];
+        });
+    }
+  });
+
+  // Cache the context data which is delivered to the plugins
+  const inventreeContext = useInvenTreeContext();
+
+  const contextData: InvenTreePluginContext =
+    useMemo<InvenTreePluginContext>(() => {
+      return {
+        ...inventreeContext,
+        model: model,
+        id: id,
+        instance: instance
+      };
+    }, [model, id, instance, inventreeContext]);
+
+  const pluginPanels: PluginPanelType[] = useMemo(() => {
+    return (
+      pluginQuery?.data?.map((props: PluginUIFeature) => {
+        const iconName: string = props?.icon || 'ti:plug:outline';
+
+        const ctx: InvenTreePluginContext = {
+          ...contextData,
+          context: props.context
+        };
+
+        return {
+          name: props.key,
+          pluginName: props.plugin_name,
+          label: props.title,
+          icon: <ApiIcon name={iconName} />,
+          content: (
+            <PluginPanelContent pluginFeature={props} pluginContext={ctx} />
+          )
+        };
+      }) ?? []
+    );
+  }, [pluginQuery.data, contextData]);
+
+  const panelSet: PluginPanelSet = useMemo(() => {
+    return {
+      panels: pluginPanels,
+      isLoading: pluginQuery.isLoading || pluginQuery.isFetching,
+      query: pluginQuery
+    };
+  }, [pluginPanels, pluginQuery]);
+
+  return panelSet;
+}

package/src/hooks/UsePluginUIFeature.tsx

@@ -0,0 +1,95 @@
+import { useQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
+
+import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { apiUrl } from '@lib/functions/Api';
+import { api } from '../App';
+import { useInvenTreeContext } from '../components/plugins/PluginContext';
+import { findExternalPluginFunction } from '../components/plugins/PluginSource';
+import type {
+  BaseUIFeature,
+  PluginUIFeatureAPIResponse,
+  PluginUIFuncWithoutInvenTreeContextType
+} from '../components/plugins/PluginUIFeatureTypes';
+import { useGlobalSettingsState } from '../states/SettingsState';
+
+export function usePluginUIFeature<UIFeatureT extends BaseUIFeature>({
+  enabled = true,
+  featureType,
+  context
+}: {
+  enabled?: boolean;
+  featureType: UIFeatureT['featureType'];
+  context: UIFeatureT['requestContext'];
+}) {
+  const globalSettings = useGlobalSettingsState();
+
+  const pluginUiFeaturesEnabled: boolean = useMemo(
+    () => globalSettings.isSet('ENABLE_PLUGINS_INTERFACE'),
+    [globalSettings]
+  );
+
+  // API query to fetch initial information on available plugin panels
+  const { data: pluginData } = useQuery<
+    PluginUIFeatureAPIResponse<UIFeatureT>[]
+  >({
+    enabled: pluginUiFeaturesEnabled && !!featureType && enabled,
+    queryKey: ['custom-ui-features', featureType, JSON.stringify(context)],
+    queryFn: async () => {
+      if (!pluginUiFeaturesEnabled || !featureType) {
+        return Promise.resolve([]);
+      }
+
+      return api
+        .get(
+          apiUrl(ApiEndpoints.plugin_ui_features_list, undefined, {
+            feature_type: featureType
+          }),
+          {
+            params: context
+          }
+        )
+        .then((response: any) => response.data)
+        .catch((error: any) => {
+          console.error(
+            `ERR: Failed to fetch plugin ui features for feature "${featureType}":`,
+            error
+          );
+          return [];
+        });
+    }
+  });
+
+  // Cache the context data which is delivered to the plugins
+  const inventreeContext = useInvenTreeContext();
+
+  return useMemo<
+    {
+      options: UIFeatureT['responseOptions'];
+      func: PluginUIFuncWithoutInvenTreeContextType<UIFeatureT>;
+    }[]
+  >(() => {
+    return (
+      pluginData?.map((feature) => {
+        return {
+          options: {
+            ...feature
+          },
+          func: (async (featureContext) => {
+            const func = await findExternalPluginFunction(
+              feature.source,
+              'getFeature'
+            );
+            if (!func) return;
+
+            return func({
+              featureContext,
+              inventreeContext,
+              serverContext: feature.context
+            });
+          }) as PluginUIFuncWithoutInvenTreeContextType<UIFeatureT>
+        };
+      }) || []
+    );
+  }, [pluginData, inventreeContext]);
+}

package/src/hooks/UsePlugins.tsx

@@ -0,0 +1,45 @@
+import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { useCallback } from 'react';
+import type { PluginInterface } from '../components/plugins/PluginInterface';
+import { useInstance } from './UseInstance';
+
+export interface UsePluginResult {
+  plugins: PluginInterface[];
+  withMixin: (mixin: string) => PluginInterface[];
+}
+
+/**
+ * Hook for storing information on active plugins
+ */
+export const usePlugins = (): UsePluginResult => {
+  const pluginQuery = useInstance({
+    endpoint: ApiEndpoints.plugin_list,
+    defaultValue: [],
+    hasPrimaryKey: false,
+    refetchOnMount: true,
+    refetchOnWindowFocus: false,
+    params: {
+      active: true
+    }
+  });
+
+  const pluginsWithMixin = useCallback(
+    (mixin: string) => {
+      return pluginQuery.instance.filter((plugin: PluginInterface) => {
+        return !!plugin.mixins[mixin];
+      });
+    },
+    [pluginQuery.instance]
+  );
+
+  return {
+    plugins: pluginQuery.instance,
+    withMixin: pluginsWithMixin
+  };
+};
+
+export const usePluginsWithMixin = (mixin: string): PluginInterface[] => {
+  const plugins = usePlugins();
+
+  return plugins.withMixin(mixin);
+};

package/src/hooks/UseSelectedRows.tsx

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/**
+ * Hook to manage multiple selected rows in a multi-action modal.
+ *
+ * - The hook is initially provided with a list of rows
+ * - A callback is provided to remove a row, based on the provided ID value
+ */
+export function useSelectedRows<T>({
+  rows,
+  pkField = 'pk'
+}: {
+  rows: T[];
+  pkField?: string;
+}) {
+  const [selectedRows, setSelectedRows] = useState<T[]>(rows);
+
+  // Update selection whenever input rows are updated
+  useEffect(() => {
+    setSelectedRows(rows);
+  }, [rows]);
+
+  // Callback to remove the selected row
+  const removeRow = useCallback(
+    (pk: any) => {
+      setSelectedRows((rows) =>
+        rows.filter((row: any) => row[pkField ?? 'pk'] !== pk)
+      );
+    },
+    [pkField]
+  );
+
+  return {
+    selectedRows,
+    removeRow
+  };
+}

package/src/hooks/UseStatusCodes.tsx

@@ -0,0 +1,50 @@
+import { useMemo } from 'react';
+
+import type { ModelType } from '@lib/enums/ModelType';
+import { getStatusCodes } from '../components/render/StatusRenderer';
+import { useGlobalStatusState } from '../states/StatusState';
+
+/**
+ * Hook to access status codes, which are enumerated by the backend.
+ *
+ * This hook is used to return a map of status codes for a given model type.
+ * It is a memoized wrapper around getStatusCodes,
+ * and returns a simplified KEY:value map of status codes.
+ *
+ * e.g. for the "PurchaseOrderStatus" enumeration, returns a map like:
+ *
+ * {
+ *   PENDING: 10
+ *   PLACED: 20
+ *   ON_HOLD: 25,
+ *   COMPLETE: 30,​
+ *   CANCELLED: 40,
+ *   LOST: 50,
+ *   RETURNED: 60
+ * }
+ */
+export default function useStatusCodes({
+  modelType
+}: {
+  modelType: ModelType | string;
+}) {
+  const statusCodeList = useGlobalStatusState.getState().status;
+
+  const codes = useMemo(() => {
+    const statusCodes = getStatusCodes(modelType) || null;
+
+    const codesMap: Record<any, any> = {};
+
+    if (!statusCodes) {
+      return codesMap;
+    }
+
+    Object.keys(statusCodes.values).forEach((name) => {
+      codesMap[name] = statusCodes.values[name].key;
+    });
+
+    return codesMap;
+  }, [modelType, statusCodeList]);
+
+  return codes;
+}

package/src/hooks/UseTable.tsx

@@ -0,0 +1,145 @@
+import { randomId, useLocalStorage } from '@mantine/hooks';
+import { useCallback, useMemo, useState } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+import type { FilterSetState } from '@lib/types/Filters';
+import type { TableState } from '@lib/types/Tables';
+import { useFilterSet } from './UseFilterSet';
+
+/**
+ * A custom hook for managing the state of an <InvenTreeTable> component.
+ *
+ * Refer to the TableState type definition for more information.
+ */
+
+export function useTable(tableName: string, idAccessor = 'pk'): TableState {
+  // Function to generate a new ID (to refresh the table)
+  function generateTableName() {
+    return `${tableName.replaceAll('-', '')}-${randomId()}`;
+  }
+
+  // Extract URL query parameters (e.g. ?active=true&overdue=false)
+  const [queryFilters, setQueryFilters] = useSearchParams();
+
+  const clearQueryFilters = useCallback(() => {
+    setQueryFilters({});
+  }, []);
+
+  const [tableKey, setTableKey] = useState<string>(generateTableName());
+
+  // Callback used to refresh (reload) the table
+  const refreshTable = useCallback(() => {
+    setTableKey(generateTableName());
+  }, [generateTableName]);
+
+  const filterSet: FilterSetState = useFilterSet(`table-${tableName}`);
+
+  // Array of expanded records
+  const [expandedRecords, setExpandedRecords] = useState<any[]>([]);
+
+  // Function to determine if a record is expanded
+  const isRowExpanded = useCallback(
+    (pk: number) => {
+      return expandedRecords.includes(pk);
+    },
+    [expandedRecords]
+  );
+
+  // Array of selected records
+  const [selectedRecords, setSelectedRecords] = useState<any[]>([]);
+
+  // Array of selected primary key values
+  const selectedIds = useMemo(
+    () => selectedRecords.map((r) => r[idAccessor || 'pk']),
+    [selectedRecords]
+  );
+
+  const clearSelectedRecords = useCallback(() => {
+    setSelectedRecords([]);
+  }, []);
+
+  const hasSelectedRecords = useMemo(() => {
+    return selectedRecords.length > 0;
+  }, [selectedRecords]);
+
+  // Total record count
+  const [recordCount, setRecordCount] = useState<number>(0);
+
+  // Pagination data
+  const [page, setPage] = useState<number>(1);
+  const [pageSize, setPageSize] = useLocalStorage<number>({
+    key: 'inventree-table-page-size',
+    defaultValue: 25
+  });
+
+  // A list of hidden columns, saved to local storage
+  const [hiddenColumns, setHiddenColumns] = useLocalStorage<string[]>({
+    key: `inventree-hidden-table-columns-${tableName}`,
+    defaultValue: []
+  });
+
+  // Search term
+  const [searchTerm, setSearchTerm] = useState<string>('');
+
+  // Table records
+  const [records, setRecords] = useState<any[]>([]);
+
+  // Update a single record in the table, by primary key value
+  const updateRecord = useCallback(
+    (record: any) => {
+      const _records = [...records];
+
+      // Find the matching record in the table
+      const index = _records.findIndex(
+        (r) => r[idAccessor || 'pk'] === record.pk
+      );
+
+      if (index >= 0) {
+        _records[index] = {
+          ..._records[index],
+          ...record
+        };
+      } else {
+        _records.push(record);
+      }
+
+      setRecords(_records);
+    },
+    [records]
+  );
+
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+
+  return {
+    tableKey,
+    refreshTable,
+    isLoading,
+    setIsLoading,
+    filterSet,
+    queryFilters,
+    setQueryFilters,
+    clearQueryFilters,
+    expandedRecords,
+    setExpandedRecords,
+    isRowExpanded,
+    selectedRecords,
+    selectedIds,
+    setSelectedRecords,
+    clearSelectedRecords,
+    hasSelectedRecords,
+    hiddenColumns,
+    setHiddenColumns,
+    searchTerm,
+    setSearchTerm,
+    recordCount,
+    setRecordCount,
+    page,
+    setPage,
+    pageSize,
+    setPageSize,
+    records,
+    setRecords,
+    updateRecord,
+    idAccessor
+  };
+}

package/src/hooks/UseWizard.tsx

@@ -0,0 +1,133 @@
+import { Alert, Stack } from '@mantine/core';
+import { IconExclamationCircle } from '@tabler/icons-react';
+import {
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useState
+} from 'react';
+import WizardDrawer from '../components/wizards/WizardDrawer';
+
+export interface WizardProps {
+  title: string;
+  steps: string[];
+  renderStep: (step: number) => ReactNode;
+  canStepForward?: (step: number) => boolean;
+  canStepBackward?: (step: number) => boolean;
+}
+
+export interface WizardState {
+  opened: boolean;
+  currentStep: number;
+  clearError: () => void;
+  error: string | null;
+  setError: (error: string | null) => void;
+  errorDetail: string | null;
+  setErrorDetail: (errorDetail: string | null) => void;
+  openWizard: () => void;
+  closeWizard: () => void;
+  nextStep: () => void;
+  previousStep: () => void;
+  wizard: ReactNode;
+}
+
+/**
+ * Hook for managing a wizard-style multi-step process.
+ * - Manage the current step of the wizard
+ * - Allows opening and closing the wizard
+ * - Handles progression between steps with optional validation
+ */
+export default function useWizard(props: WizardProps): WizardState {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [opened, setOpened] = useState(false);
+
+  const [error, setError] = useState<string | null>(null);
+  const [errorDetail, setErrorDetail] = useState<string | null>(null);
+
+  const clearError = useCallback(() => {
+    setError(null);
+    setErrorDetail(null);
+  }, []);
+
+  // Reset the wizard to an initial state when opened
+  useEffect(() => {
+    if (opened) {
+      setCurrentStep(0);
+      clearError();
+    }
+  }, [opened]);
+
+  // Open the wizard
+  const openWizard = useCallback(() => {
+    setOpened(true);
+  }, []);
+
+  // Close the wizard
+  const closeWizard = useCallback(() => {
+    setOpened(false);
+  }, []);
+
+  // Progress the wizard to the next step
+  const nextStep = useCallback(() => {
+    if (props.canStepForward && !props.canStepForward(currentStep)) {
+      return;
+    }
+
+    if (props.steps && currentStep < props.steps.length - 1) {
+      setCurrentStep(currentStep + 1);
+      clearError();
+    }
+  }, [currentStep, props.canStepForward]);
+
+  // Go back to the previous step
+  const previousStep = useCallback(() => {
+    if (props.canStepBackward && !props.canStepBackward(currentStep)) {
+      return;
+    }
+
+    if (currentStep > 0) {
+      setCurrentStep(currentStep - 1);
+      clearError();
+    }
+  }, [currentStep, props.canStepBackward]);
+
+  // Render the wizard contents for the current step
+  const contents = useMemo(() => {
+    return props.renderStep(currentStep);
+  }, [opened, currentStep, props.renderStep]);
+
+  return {
+    currentStep,
+    opened,
+    clearError,
+    error,
+    setError,
+    errorDetail,
+    setErrorDetail,
+    openWizard,
+    closeWizard,
+    nextStep,
+    previousStep,
+    wizard: (
+      <WizardDrawer
+        title={props.title}
+        currentStep={currentStep}
+        steps={props.steps}
+        opened={opened}
+        onClose={closeWizard}
+        onNextStep={nextStep}
+        onPreviousStep={previousStep}
+      >
+        <Stack gap='xs'>
+          {error && (
+            <Alert color='red' title={error} icon={<IconExclamationCircle />}>
+              {errorDetail}
+            </Alert>
+          )}
+          {contents}
+        </Stack>
+      </WizardDrawer>
+    )
+  };
+}

package/src/locales/ar/messages.d.ts

@@ -0,0 +1,4 @@
+import { Messages } from '@lingui/core';
+          declare const messages: Messages;
+          export { messages };
+