@inventreedb/ui 0.0.1

package/src/hooks/UseCalendar.tsx

@@ -0,0 +1,178 @@
+import type FullCalendar from '@fullcalendar/react';
+import type { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { apiUrl } from '@lib/functions/Api';
+import type { FilterSetState } from '@lib/types/Filters';
+import type { UseModalReturn } from '@lib/types/Modals';
+import type { DateValue } from '@mantine/dates';
+import { type UseQueryResult, useQuery } from '@tanstack/react-query';
+import dayjs from 'dayjs';
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { api } from '../App';
+import { showApiErrorMessage } from '../functions/notifications';
+import useDataExport from './UseDataExport';
+import { useFilterSet } from './UseFilterSet';
+
+/*
+ * Type definition for representing the state of a calendar:
+ *
+ * ref: A reference to the FullCalendar component
+ * filterSet: The current filter set state
+ * monthName: The name of the current month (e.g. "January 2022")
+ * setMonthName: A function to set the month name
+ * searchTerm: The current search term for the calendar
+ * setSearchTerm: A function to set the search term
+ * startDate: The start date of the current date range
+ * setStartDate: A function to set the start date
+ * endDate: The end date of the current date range
+ * setEndDate: A function to set the end date
+ * nextMonth: A function to navigate to the next month
+ * prevMonth: A function to navigate to the previous month
+ * currentMonth: A function to navigate to the current month
+ * selectMonth: A function to select a specific month
+ */
+export type CalendarState = {
+  name: string;
+  ref: React.RefObject<FullCalendar>;
+  filterSet: FilterSetState;
+  monthName: string;
+  setMonthName: (name: string) => void;
+  searchTerm: string;
+  startDate: Date | null;
+  setStartDate: (date: Date | null) => void;
+  endDate: Date | null;
+  setEndDate: (date: Date | null) => void;
+  setSearchTerm: (term: string) => void;
+  nextMonth: () => void;
+  prevMonth: () => void;
+  currentMonth: () => void;
+  selectMonth: (date: DateValue) => void;
+  query: UseQueryResult;
+  exportModal: UseModalReturn;
+  data: any;
+};
+
+export default function useCalendar({
+  name,
+  endpoint,
+  queryParams
+}: {
+  name: string;
+  endpoint: ApiEndpoints;
+  queryParams?: any;
+}): CalendarState {
+  const ref = useRef<FullCalendar | null>(null);
+
+  const filterSet = useFilterSet(`calendar-${name}`);
+
+  const [searchTerm, setSearchTerm] = useState<string>('');
+
+  const [monthName, setMonthName] = useState<string>('');
+
+  const [startDate, setStartDate] = useState<Date | null>(null);
+
+  const [endDate, setEndDate] = useState<Date | null>(null);
+
+  // Generate a set of API query filters
+  const queryFilters: Record<string, any> = useMemo(() => {
+    // Expand date range by one month, to ensure we capture all events
+
+    let params = {
+      ...(queryParams || {})
+    };
+
+    if (filterSet.activeFilters) {
+      filterSet.activeFilters.forEach((filter) => {
+        params[filter.name] = filter.value;
+      });
+    }
+
+    params = {
+      ...params,
+      min_date: startDate
+        ? dayjs(startDate).subtract(1, 'month').format('YYYY-MM-DD')
+        : null,
+      max_date: endDate
+        ? dayjs(endDate).add(1, 'month').format('YYYY-MM-DD')
+        : null,
+      search: searchTerm
+    };
+
+    return params;
+  }, [startDate, endDate, searchTerm, filterSet.activeFilters, queryParams]);
+
+  const query = useQuery({
+    enabled: !!startDate && !!endDate,
+    queryKey: ['calendar', name, endpoint, queryFilters],
+    queryFn: async () => {
+      // Fetch data from the API
+      return api
+        .get(apiUrl(endpoint), {
+          params: queryFilters
+        })
+        .then((response) => {
+          return response.data ?? [];
+        })
+        .catch((error) => {
+          showApiErrorMessage({
+            error: error,
+            title: 'Error fetching calendar data'
+          });
+        });
+    }
+  });
+
+  // Navigate to the previous month
+  const prevMonth = useCallback(() => {
+    ref.current?.getApi().prev();
+  }, [ref]);
+
+  // Navigate to the next month
+  const nextMonth = useCallback(() => {
+    ref.current?.getApi().next();
+  }, [ref]);
+
+  // Navigate to the current month
+  const currentMonth = useCallback(() => {
+    ref.current?.getApi().today();
+  }, [ref]);
+
+  // Callback to select a specific month from a picker
+  const selectMonth = useCallback(
+    (date: DateValue) => {
+      if (date && ref?.current) {
+        const api = ref.current.getApi();
+
+        api.gotoDate(date);
+      }
+    },
+    [ref]
+  );
+
+  // Modal for exporting data from the calendar
+  const exportModal = useDataExport({
+    url: apiUrl(endpoint),
+    enabled: true,
+    filters: queryFilters
+  });
+
+  return {
+    name,
+    filterSet,
+    ref,
+    monthName,
+    setMonthName,
+    searchTerm,
+    setSearchTerm,
+    nextMonth,
+    prevMonth,
+    currentMonth,
+    selectMonth,
+    startDate,
+    setStartDate,
+    endDate,
+    setEndDate,
+    exportModal,
+    query: query,
+    data: query.data
+  };
+}

package/src/hooks/UseDashboardItems.tsx

@@ -0,0 +1,118 @@
+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 type { DashboardWidgetProps } from '../components/dashboard/DashboardWidget';
+import DashboardWidgetLibrary from '../components/dashboard/DashboardWidgetLibrary';
+import { useInvenTreeContext } from '../components/plugins/PluginContext';
+import {
+  type PluginUIFeature,
+  PluginUIFeatureType
+} from '../components/plugins/PluginUIFeature';
+import RemoteComponent from '../components/plugins/RemoteComponent';
+import { identifierString } from '../functions/conversion';
+import { useGlobalSettingsState } from '../states/SettingsState';
+import { useUserState } from '../states/UserState';
+
+interface DashboardLibraryProps {
+  items: DashboardWidgetProps[];
+  loaded: boolean;
+}
+
+/**
+ * Custom hook to load available dashboard items.
+ *
+ * - Loads from library of "builtin" dashboard items
+ * - Loads plugin-defined dashboard items (via the API)
+ */
+export function useDashboardItems(): DashboardLibraryProps {
+  const user = useUserState();
+  const globalSettings = useGlobalSettingsState();
+
+  const pluginsEnabled: boolean = useMemo(
+    () => globalSettings.isSet('ENABLE_PLUGINS_INTERFACE'),
+    [globalSettings]
+  );
+
+  const builtin = DashboardWidgetLibrary();
+
+  const pluginQuery = useQuery({
+    enabled: pluginsEnabled,
+    queryKey: ['plugin-dashboard-items', user],
+    refetchOnMount: true,
+    queryFn: async () => {
+      if (!pluginsEnabled) {
+        return Promise.resolve([]);
+      }
+
+      const url = apiUrl(ApiEndpoints.plugin_ui_features_list, undefined, {
+        feature_type: PluginUIFeatureType.dashboard
+      });
+
+      return api
+        .get(url)
+        .then((response: any) => response.data)
+        .catch((_error: any) => {
+          console.error('ERR: Failed to fetch plugin dashboard items');
+          return [];
+        });
+    }
+  });
+
+  // Cache the context data which is delivered to the plugins
+  const inventreeContext = useInvenTreeContext();
+
+  const pluginDashboardItems: DashboardWidgetProps[] = useMemo(() => {
+    return (
+      pluginQuery?.data?.map((item: PluginUIFeature) => {
+        const pluginContext = {
+          ...inventreeContext,
+          context: item.context
+        };
+
+        return {
+          label: identifierString(`p-${item.plugin_name}-${item.key}`),
+          title: item.title,
+          description: item.description,
+          minWidth: item.options?.width ?? 2,
+          minHeight: item.options?.height ?? 1,
+          render: () => {
+            return (
+              <RemoteComponent
+                source={item.source}
+                defaultFunctionName='renderDashboardItem'
+                context={pluginContext}
+              />
+            );
+          }
+        };
+      }) ?? []
+    );
+  }, [pluginQuery, inventreeContext]);
+
+  const items: DashboardWidgetProps[] = useMemo(() => {
+    const widgets = [...builtin, ...pluginDashboardItems];
+
+    return widgets.filter((item) => item.enabled ?? true);
+  }, [builtin, pluginDashboardItems]);
+
+  const loaded: boolean = useMemo(() => {
+    if (pluginsEnabled) {
+      return (
+        !pluginQuery.isFetching &&
+        !pluginQuery.isLoading &&
+        pluginQuery.isFetched &&
+        pluginQuery.isSuccess
+      );
+    } else {
+      return true;
+    }
+  }, [pluginsEnabled, pluginQuery]);
+
+  return {
+    items: items,
+    loaded: loaded
+  };
+}

package/src/hooks/UseDataExport.tsx

@@ -0,0 +1,125 @@
+import type { ApiFormFieldSet } from '@lib/types/Forms';
+import { t } from '@lingui/core/macro';
+import { useQuery } from '@tanstack/react-query';
+import { useMemo, useState } from 'react';
+import { useApi } from '../contexts/ApiContext';
+import { extractAvailableFields } from '../functions/forms';
+import useDataOutput from './UseDataOutput';
+import { useCreateApiFormModal } from './UseForm';
+
+/**
+ * Custom hook for managing data export functionality
+ * This is intended to be used from a table or calendar view,
+ * to export the data displayed in the table or calendar
+ */
+export default function useDataExport({
+  url,
+  enabled,
+  filters,
+  searchTerm
+}: {
+  url: string;
+  enabled: boolean;
+  filters: any;
+  searchTerm?: string;
+}) {
+  const api = useApi();
+
+  // Selected plugin to use for data export
+  const [pluginKey, setPluginKey] = useState<string>('inventree-exporter');
+
+  const [exportId, setExportId] = useState<number | undefined>(undefined);
+
+  const progress = useDataOutput({
+    title: t`Exporting Data`,
+    id: exportId
+  });
+
+  // Construct a set of export parameters
+  const exportParams = useMemo(() => {
+    const queryParams: Record<string, any> = {
+      export: true
+    };
+
+    if (!!pluginKey) {
+      queryParams.export_plugin = pluginKey;
+    }
+
+    // Add in any additional parameters which have a defined value
+    for (const [key, value] of Object.entries(filters ?? {})) {
+      if (value != undefined) {
+        queryParams[key] = value;
+      }
+    }
+
+    if (!!searchTerm) {
+      queryParams.search = searchTerm;
+    }
+
+    return queryParams;
+  }, [pluginKey, filters, searchTerm]);
+
+  // Fetch available export fields via OPTIONS request
+  const extraExportFields = useQuery({
+    enabled: !!url && enabled,
+    queryKey: ['export-fields', pluginKey, url, exportParams],
+    gcTime: 500,
+    queryFn: () =>
+      api
+        .options(url, {
+          params: exportParams
+        })
+        .then((response: any) => {
+          return extractAvailableFields(response, 'GET') || {};
+        })
+        .catch(() => {
+          return {};
+        })
+  });
+
+  // Construct a field set for the export form
+  const exportFields: ApiFormFieldSet = useMemo(() => {
+    const extraFields: ApiFormFieldSet = extraExportFields.data || {};
+
+    const fields: ApiFormFieldSet = {
+      export_format: {},
+      export_plugin: {},
+      ...extraFields
+    };
+
+    fields.export_format = {
+      ...fields.export_format,
+      required: true
+    };
+
+    fields.export_plugin = {
+      ...fields.export_plugin,
+      required: true,
+      onValueChange: (value: string) => {
+        if (!!value) {
+          setPluginKey(value);
+        }
+      }
+    };
+
+    return fields;
+  }, [extraExportFields]);
+
+  // Modal for exporting data
+  const exportModal = useCreateApiFormModal({
+    url: url,
+    queryParams: new URLSearchParams(exportParams),
+    title: t`Export Data`,
+    method: 'GET',
+    fields: exportFields,
+    submitText: t`Export`,
+    successMessage: null,
+    timeout: 30 * 1000,
+    onFormSuccess: (response: any) => {
+      setExportId(response.pk);
+      setPluginKey('inventree-exporter');
+    }
+  });
+
+  return exportModal;
+}

package/src/hooks/UseDataOutput.tsx

@@ -0,0 +1,109 @@
+import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { apiUrl } from '@lib/functions/Api';
+import { t } from '@lingui/core/macro';
+import { notifications, showNotification } from '@mantine/notifications';
+import { IconCircleCheck } from '@tabler/icons-react';
+import { useQuery } from '@tanstack/react-query';
+import { useEffect, useState } from 'react';
+import { ProgressBar } from '../components/items/ProgressBar';
+import { useApi } from '../contexts/ApiContext';
+import { generateUrl } from '../functions/urls';
+
+/**
+ * Hook for monitoring a data output process running on the server
+ */
+export default function useDataOutput({
+  title,
+  id
+}: {
+  title: string;
+  id?: number;
+}) {
+  const api = useApi();
+
+  const [loading, setLoading] = useState<boolean>(false);
+
+  useEffect(() => {
+    if (!!id) {
+      setLoading(true);
+      showNotification({
+        id: `data-output-${id}`,
+        title: title,
+        loading: true,
+        autoClose: false,
+        withCloseButton: false,
+        message: <ProgressBar size='lg' value={0} progressLabel />
+      });
+    } else setLoading(false);
+  }, [id, title]);
+
+  const progress = useQuery({
+    enabled: !!id && loading,
+    refetchInterval: 500,
+    queryKey: ['data-output', id, title],
+    queryFn: () =>
+      api
+        .get(apiUrl(ApiEndpoints.data_output, id))
+        .then((response) => {
+          const data = response?.data ?? {};
+
+          if (data.complete) {
+            setLoading(false);
+            notifications.update({
+              id: `data-output-${id}`,
+              loading: false,
+              autoClose: 2500,
+              title: title,
+              message: t`Process completed successfully`,
+              color: 'green',
+              icon: <IconCircleCheck />
+            });
+
+            if (data.output) {
+              const url = generateUrl(data.output);
+              window.open(url.toString(), '_blank');
+            }
+          } else if (!!data.error) {
+            setLoading(false);
+            notifications.update({
+              id: `data-output-${id}`,
+              loading: false,
+              autoClose: 2500,
+              title: title,
+              message: t`Process failed`,
+              color: 'red'
+            });
+          } else {
+            notifications.update({
+              id: `data-output-${id}`,
+              loading: true,
+              autoClose: false,
+              withCloseButton: false,
+              message: (
+                <ProgressBar
+                  size='lg'
+                  maximum={data.total}
+                  value={data.progress}
+                  progressLabel={data.total > 0}
+                  animated
+                />
+              )
+            });
+          }
+
+          return data;
+        })
+        .catch(() => {
+          setLoading(false);
+          notifications.update({
+            id: `data-output-${id}`,
+            loading: false,
+            autoClose: 2500,
+            title: title,
+            message: t`Process failed`,
+            color: 'red'
+          });
+          return {};
+        })
+  });
+}

package/src/hooks/UseFilter.tsx

@@ -0,0 +1,67 @@
+/*
+ * Custom hook for retrieving a list of items from the API,
+ * and turning them into "filters" for use in the frontend table framework.
+ */
+import { useQuery } from '@tanstack/react-query';
+import { useCallback, useMemo } from 'react';
+
+import type { TableFilterChoice } from '@lib/types/Filters';
+import { useApi } from '../contexts/ApiContext';
+import { resolveItem } from '../functions/conversion';
+
+type UseFilterProps = {
+  url: string;
+  method?: 'GET' | 'POST' | 'OPTIONS';
+  params?: any;
+  accessor?: string;
+  transform: (item: any) => TableFilterChoice;
+};
+
+export function useFilters(props: UseFilterProps) {
+  const api = useApi();
+
+  const query = useQuery({
+    enabled: true,
+    gcTime: 500,
+    queryKey: [props.url, props.method, props.params],
+    queryFn: async () => {
+      return await api
+        .request({
+          url: props.url,
+          method: props.method ?? 'GET',
+          params: props.params
+        })
+        .then((response) => {
+          const data = resolveItem(response, props.accessor ?? 'data');
+
+          if (data == null || data == undefined) {
+            return [];
+          }
+
+          return data;
+        })
+        .catch((error) => []);
+    }
+  });
+
+  const choices: TableFilterChoice[] = useMemo(() => {
+    const opts = query.data?.map(props.transform) ?? [];
+
+    // Ensure stringiness
+    return opts.map((opt: any) => {
+      return {
+        value: opt.value.toString(),
+        label: opt?.label?.toString() ?? opt.value.toString()
+      };
+    });
+  }, [props.transform, query.data]);
+
+  const refresh = useCallback(() => {
+    query.refetch();
+  }, []);
+
+  return {
+    choices,
+    refresh
+  };
+}

package/src/hooks/UseFilterSet.tsx

@@ -0,0 +1,24 @@
+import type { FilterSetState, TableFilter } from '@lib/types/Filters';
+import { useLocalStorage } from '@mantine/hooks';
+import { useCallback } from 'react';
+
+export function useFilterSet(filterKey: string): FilterSetState {
+  // Array of active filters (saved to local storage)
+  const [activeFilters, setActiveFilters] = useLocalStorage<TableFilter[]>({
+    key: `inventree-filterset-${filterKey}`,
+    defaultValue: [],
+    getInitialValueInEffect: false
+  });
+
+  // Callback to clear all active filters from the table
+  const clearActiveFilters = useCallback(() => {
+    setActiveFilters([]);
+  }, []);
+
+  return {
+    filterKey,
+    activeFilters,
+    setActiveFilters,
+    clearActiveFilters
+  };
+}