@inventreedb/ui 0.0.1

package/src/hooks/UseForm.tsx

@@ -0,0 +1,161 @@
+import { t } from '@lingui/core/macro';
+import { Alert, Divider, Stack } from '@mantine/core';
+import { useId } from '@mantine/hooks';
+import { useEffect, useMemo, useRef } from 'react';
+
+import type {
+  ApiFormModalProps,
+  BulkEditApiFormModalProps
+} from '@lib/types/Forms';
+import { OptionsApiForm } from '../components/forms/ApiForm';
+import { useModal } from './UseModal';
+
+/**
+ * Construct and open a modal form
+ */
+export function useApiFormModal(props: ApiFormModalProps) {
+  const id = useId();
+  const modalClose = useRef(() => {});
+
+  const formProps = useMemo<ApiFormModalProps>(
+    () => ({
+      ...props,
+      actions: [
+        ...(props.actions || []),
+        {
+          text: props.cancelText ?? t`Cancel`,
+          color: props.cancelColor ?? 'blue',
+          onClick: () => {
+            modalClose.current();
+          }
+        }
+      ],
+      onFormSuccess: (data) => {
+        modalClose.current();
+        props.onFormSuccess?.(data);
+      },
+      onFormError: (error: any) => {
+        props.onFormError?.(error);
+      }
+    }),
+    [props]
+  );
+
+  const modal = useModal({
+    title: formProps.title,
+    onOpen: formProps.onOpen,
+    onClose: formProps.onClose,
+    closeOnClickOutside: formProps.closeOnClickOutside,
+    size: props.size ?? 'xl',
+    children: (
+      <Stack gap={'xs'}>
+        <Divider />
+        <OptionsApiForm props={formProps} id={id} />
+      </Stack>
+    )
+  });
+
+  useEffect(() => {
+    modalClose.current = modal.close;
+  }, [modal.close]);
+
+  return modal;
+}
+
+/**
+ * Open a modal form to create a new model instance
+ */
+export function useCreateApiFormModal(props: ApiFormModalProps) {
+  const createProps = useMemo<ApiFormModalProps>(
+    () => ({
+      ...props,
+      fetchInitialData: props.fetchInitialData ?? false,
+      successMessage:
+        props.successMessage === null
+          ? null
+          : (props.successMessage ?? t`Item Created`),
+      method: props.method ?? 'POST'
+    }),
+    [props]
+  );
+
+  return useApiFormModal(createProps);
+}
+
+/**
+ * Open a modal form to edit a model instance
+ */
+export function useEditApiFormModal(props: ApiFormModalProps) {
+  const editProps = useMemo<ApiFormModalProps>(
+    () => ({
+      ...props,
+      fetchInitialData: props.fetchInitialData ?? true,
+      successMessage:
+        props.successMessage === null
+          ? null
+          : (props.successMessage ?? t`Item Updated`),
+      method: props.method ?? 'PATCH'
+    }),
+    [props]
+  );
+
+  return useApiFormModal(editProps);
+}
+
+export function useBulkEditApiFormModal({
+  items,
+  ...props
+}: BulkEditApiFormModalProps) {
+  const bulkEditProps = useMemo<ApiFormModalProps>(
+    () => ({
+      ...props,
+      method: 'PATCH',
+      submitText: props.submitText ?? t`Update`,
+      successMessage:
+        props.successMessage === null
+          ? null
+          : (props.successMessage ?? t`Items Updated`),
+      preFormContent: props.preFormContent ?? (
+        <Alert color={'blue'}>{t`Update multiple items`}</Alert>
+      ),
+      fields: {
+        ...props.fields,
+        items: {
+          hidden: true,
+          field_type: 'number',
+          value: items
+        }
+      }
+    }),
+    [props, items]
+  );
+
+  return useApiFormModal(bulkEditProps);
+}
+
+/**
+ * Open a modal form to delete a model instance
+ */
+export function useDeleteApiFormModal(props: ApiFormModalProps) {
+  const deleteProps = useMemo<ApiFormModalProps>(
+    () => ({
+      ...props,
+      method: props.method ?? 'DELETE',
+      submitText: t`Delete`,
+      submitColor: 'red',
+      successMessage:
+        props.successMessage === null
+          ? null
+          : (props.successMessage ?? t`Item Deleted`),
+      preFormContent: props.preFormContent ?? (
+        <Alert
+          color={'red'}
+        >{t`Are you sure you want to delete this item?`}</Alert>
+      ),
+      fields: props.fields ?? {}
+    }),
+    [props]
+  );
+
+  return useApiFormModal(deleteProps);
+}

package/src/hooks/UseGenerator.tsx

@@ -0,0 +1,92 @@
+import { useDebouncedValue } from '@mantine/hooks';
+import { useQuery } from '@tanstack/react-query';
+import { useCallback, useState } from 'react';
+
+import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { apiUrl } from '@lib/functions/Api';
+import { api } from '../App';
+
+export type GeneratorState = {
+  query: Record<string, any>;
+  result: any;
+  update: (params: Record<string, any>, overwrite?: boolean) => void;
+};
+
+/* Hook for managing generation of data via the InvenTree API.
+ * We pass an endpoint, and start with an initially empty query.
+ * We can pass additional parameters to the query, and update the query as needed.
+ * Each update calls a new query to the API, and the result is stored in the state.
+ */
+export function useGenerator(
+  endpoint: ApiEndpoints,
+  key: string,
+  onGenerate?: (value: any) => void
+): GeneratorState {
+  // Track the result
+  const [result, setResult] = useState<any>(null);
+
+  // Track the generator query
+  const [query, setQuery] = useState<Record<string, any>>({});
+
+  // Prevent rapid updates
+  const [debouncedQuery] = useDebouncedValue<Record<string, any>>(query, 250);
+
+  // Callback to update the generator query
+  const update = useCallback(
+    (params: Record<string, any>, overwrite?: boolean) => {
+      if (overwrite) {
+        setQuery(params);
+      } else {
+        setQuery((query) => ({
+          ...query,
+          ...params
+        }));
+      }
+
+      queryGenerator.refetch();
+    },
+    []
+  );
+
+  // API query handler
+  const queryGenerator = useQuery({
+    enabled: false,
+    queryKey: ['generator', key, endpoint, debouncedQuery],
+    queryFn: async () => {
+      return api.post(apiUrl(endpoint), debouncedQuery).then((response) => {
+        const value = response?.data[key];
+        setResult(value);
+
+        if (onGenerate) {
+          onGenerate(value);
+        }
+
+        return response;
+      });
+    }
+  });
+
+  return {
+    query,
+    update,
+    result
+  };
+}
+
+// Generate a batch code with provided data
+export function useBatchCodeGenerator(onGenerate: (value: any) => void) {
+  return useGenerator(
+    ApiEndpoints.generate_batch_code,
+    'batch_code',
+    onGenerate
+  );
+}
+
+// Generate a serial number with provided data
+export function useSerialNumberGenerator(onGenerate: (value: any) => void) {
+  return useGenerator(
+    ApiEndpoints.generate_serial_number,
+    'serial_number',
+    onGenerate
+  );
+}

package/src/hooks/UseImportSession.tsx

@@ -0,0 +1,139 @@
+import { useCallback, useMemo } from 'react';
+
+import { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { ModelType } from '@lib/enums/ModelType';
+import { useInstance } from './UseInstance';
+import useStatusCodes from './UseStatusCodes';
+
+/*
+ * Custom hook for managing the state of a data import session
+ */
+
+export type ImportSessionState = {
+  sessionId: number;
+  sessionData: any;
+  setSessionData: (data: any) => void;
+  refreshSession: () => void;
+  sessionQuery: any;
+  status: number;
+  availableFields: Record<string, any>;
+  availableColumns: string[];
+  mappedFields: any[];
+  columnMappings: any[];
+  fieldDefaults: any;
+  fieldOverrides: any;
+  fieldFilters: any;
+  rowCount: number;
+  completedRowCount: number;
+};
+
+export function useImportSession({
+  sessionId
+}: {
+  sessionId: number;
+}): ImportSessionState {
+  // Query manager for the import session
+  const {
+    instance: sessionData,
+    setInstance,
+    refreshInstance: refreshSession,
+    instanceQuery: sessionQuery
+  } = useInstance({
+    endpoint: ApiEndpoints.import_session_list,
+    pk: sessionId,
+    defaultValue: {}
+  });
+
+  const setSessionData = useCallback((data: any) => {
+    setInstance(data);
+  }, []);
+
+  const importSessionStatus = useStatusCodes({
+    modelType: ModelType.importsession
+  });
+
+  // Current step of the import process
+  const status: number = useMemo(() => {
+    return sessionData?.status ?? importSessionStatus.INITIAL;
+  }, [sessionData, importSessionStatus]);
+
+  // List of available writeable database field definitions
+  const availableFields: any[] = useMemo(() => {
+    return sessionData?.available_fields ?? [];
+  }, [sessionData]);
+
+  // List of available data file columns
+  const availableColumns: string[] = useMemo(() => {
+    let cols = sessionData?.columns ?? [];
+
+    // Filter out any blank or duplicate columns
+    cols = cols.filter((col: string) => !!col);
+    cols = cols.filter(
+      (col: string, index: number) => cols.indexOf(col) === index
+    );
+
+    return cols;
+  }, [sessionData.columns]);
+
+  const columnMappings: any[] = useMemo(() => {
+    let mapping =
+      sessionData?.column_mappings?.map((mapping: any) => ({
+        ...mapping,
+        ...(availableFields[mapping.field] ?? {})
+      })) ?? [];
+
+    mapping = mapping.sort((a: any, b: any) => {
+      if (a?.required && !b?.required) return -1;
+      if (!a?.required && b?.required) return 1;
+      return 0;
+    });
+
+    return mapping;
+  }, [sessionData, availableColumns]);
+
+  // List of field which have been mapped to columns
+  const mappedFields: any[] = useMemo(() => {
+    return (
+      sessionData?.column_mappings?.filter((column: any) => !!column.column) ??
+      []
+    );
+  }, [sessionData]);
+
+  const fieldDefaults: any = useMemo(() => {
+    return sessionData?.field_defaults ?? {};
+  }, [sessionData]);
+
+  const fieldOverrides: any = useMemo(() => {
+    return sessionData?.field_overrides ?? {};
+  }, [sessionData]);
+
+  const fieldFilters: any = useMemo(() => {
+    return sessionData?.field_filters ?? {};
+  }, [sessionData]);
+
+  const rowCount: number = useMemo(() => {
+    return sessionData?.row_count ?? 0;
+  }, [sessionData]);
+
+  const completedRowCount: number = useMemo(() => {
+    return sessionData?.completed_row_count ?? 0;
+  }, [sessionData]);
+
+  return {
+    sessionData,
+    setSessionData,
+    sessionId,
+    refreshSession,
+    sessionQuery,
+    status,
+    availableFields,
+    availableColumns,
+    columnMappings,
+    mappedFields,
+    fieldDefaults,
+    fieldOverrides,
+    fieldFilters,
+    rowCount,
+    completedRowCount
+  };
+}

package/src/hooks/UseInstance.tsx

@@ -0,0 +1,137 @@
+import { type QueryObserverResult, useQuery } from '@tanstack/react-query';
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ApiEndpoints } from '@lib/enums/ApiEndpoints';
+import { apiUrl } from '@lib/functions/Api';
+import type { PathParams } from '@lib/types/Core';
+import { useApi } from '../contexts/ApiContext';
+
+export interface UseInstanceResult {
+  instance: any;
+  setInstance: (instance: any) => void;
+  refreshInstance: () => void;
+  refreshInstancePromise: () => Promise<QueryObserverResult<any, any>>;
+  instanceQuery: any;
+  requestStatus: number;
+  isLoaded: boolean;
+}
+
+/**
+ * Custom hook for loading a single instance of an instance from the API
+ *
+ * - Queries the API for a single instance of an object, and returns the result.
+ * - Provides a callback function to refresh the instance
+ *
+ * To use this hook:
+ * const { instance, refreshInstance } = useInstance(url: string, pk: number)
+ */
+
+export function useInstance<T = any>({
+  endpoint,
+  pk,
+  params = {},
+  defaultValue = {},
+  pathParams,
+  hasPrimaryKey = true,
+  refetchOnMount = true,
+  refetchOnWindowFocus = false,
+  throwError = false,
+  updateInterval
+}: {
+  endpoint: ApiEndpoints;
+  pk?: string | number | undefined;
+  hasPrimaryKey?: boolean;
+  params?: any;
+  pathParams?: PathParams;
+  defaultValue?: any;
+  refetchOnMount?: boolean;
+  refetchOnWindowFocus?: boolean;
+  throwError?: boolean;
+  updateInterval?: number;
+}): UseInstanceResult {
+  const api = useApi();
+
+  const [instance, setInstance] = useState<T | undefined>(defaultValue);
+
+  const [requestStatus, setRequestStatus] = useState<number>(0);
+
+  const instanceQuery = useQuery<T>({
+    queryKey: [
+      'instance',
+      endpoint,
+      pk,
+      JSON.stringify(params),
+      JSON.stringify(pathParams)
+    ],
+    queryFn: async () => {
+      if (hasPrimaryKey) {
+        if (
+          pk == null ||
+          pk == undefined ||
+          pk.toString().length == 0 ||
+          pk == '-1'
+        ) {
+          setInstance(defaultValue);
+          return defaultValue;
+        }
+      }
+
+      const url = apiUrl(endpoint, pk, pathParams);
+
+      return api
+        .get(url, {
+          timeout: 10000,
+          params: params
+        })
+        .then((response) => {
+          setRequestStatus(response.status);
+          switch (response.status) {
+            case 200:
+              setInstance(response.data);
+              return response.data;
+            default:
+              setInstance(defaultValue);
+              return defaultValue;
+          }
+        })
+        .catch((error) => {
+          setRequestStatus(error.response?.status || 0);
+          setInstance(defaultValue);
+          console.error(`ERR: Error fetching instance ${url}:`, error);
+
+          if (throwError) throw error;
+
+          return defaultValue;
+        });
+    },
+    refetchOnMount: refetchOnMount,
+    refetchOnWindowFocus: refetchOnWindowFocus ?? false,
+    refetchInterval: updateInterval
+  });
+
+  const isLoaded = useMemo(() => {
+    return (
+      instanceQuery.isFetched &&
+      instanceQuery.isSuccess &&
+      !instanceQuery.isError
+    );
+  }, [instanceQuery]);
+
+  const refreshInstance = useCallback(() => {
+    instanceQuery.refetch();
+  }, []);
+
+  const refreshInstancePromise = useCallback(() => {
+    return instanceQuery.refetch();
+  }, []);
+
+  return {
+    instance,
+    setInstance,
+    refreshInstance,
+    refreshInstancePromise,
+    instanceQuery,
+    requestStatus,
+    isLoaded
+  };
+}

package/src/hooks/UseInstanceName.tsx

@@ -0,0 +1,14 @@
+import { useMemo } from 'react';
+
+import { useGlobalSettingsState } from '../states/SettingsState';
+
+/**
+ * Simple hook for returning the "instance name" of the Server
+ */
+export default function useInstanceName(): string {
+  const globalSettings = useGlobalSettingsState();
+
+  return useMemo(() => {
+    return globalSettings.getSetting('INVENTREE_INSTANCE', 'InvenTree');
+  }, [globalSettings]);
+}

package/src/hooks/UseModal.tsx

@@ -0,0 +1,38 @@
+import { Modal } from '@mantine/core';
+import { useDisclosure } from '@mantine/hooks';
+import { useCallback } from 'react';
+
+import type { UseModalProps, UseModalReturn } from '@lib/types/Modals';
+import { StylishText } from '../components/items/StylishText';
+
+export function useModal(props: UseModalProps): UseModalReturn {
+  const onOpen = useCallback(() => {
+    props.onOpen?.();
+  }, [props.onOpen]);
+
+  const onClose = useCallback(() => {
+    props.onClose?.();
+  }, [props.onClose]);
+
+  const [opened, { open, close, toggle }] = useDisclosure(false, {
+    onOpen,
+    onClose
+  });
+
+  return {
+    open,
+    close,
+    toggle,
+    modal: (
+      <Modal
+        opened={opened}
+        onClose={close}
+        closeOnClickOutside={props.closeOnClickOutside}
+        size={props.size ?? 'xl'}
+        title={<StylishText size='xl'>{props.title}</StylishText>}
+      >
+        {props.children}
+      </Modal>
+    )
+  };
+}

package/src/hooks/UsePlaceholder.tsx

@@ -0,0 +1,66 @@
+import { t } from '@lingui/core/macro';
+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';
+
+/**
+ * Hook for generating a placeholder text for a serial number input
+ *
+ * This hook fetches the latest serial number information for a given part and generates a placeholder string.
+ *
+ * @param partId The ID of the part to fetch serial number information for
+ * @param key A unique key to identify the query
+ * @param enabled Whether the query should be enabled
+ */
+export function useSerialNumberPlaceholder({
+  partId,
+  key,
+  enabled = true
+}: {
+  partId: number;
+  key: string;
+  enabled?: boolean;
+}): string | undefined {
+  // Fetch serial number information (if available)
+  const snQuery = useQuery({
+    queryKey: ['serial-placeholder', key, partId],
+    enabled: enabled ?? true,
+    queryFn: async () => {
+      if (!partId) {
+        return null;
+      }
+
+      const url = apiUrl(ApiEndpoints.part_serial_numbers, partId);
+
+      return api
+        .get(url)
+        .then((response) => {
+          if (response.status === 200) {
+            return response.data;
+          } else {
+            return null;
+          }
+        })
+        .catch(() => {
+          return null;
+        });
+    }
+  });
+
+  const placeholder = useMemo(() => {
+    if (!enabled) {
+      return undefined;
+    } else if (snQuery.data?.next) {
+      return `${t`Next serial number`}: ${snQuery.data.next}`;
+    } else if (snQuery.data?.latest) {
+      return `${t`Latest serial number`}: ${snQuery.data.latest}`;
+    } else {
+      return undefined;
+    }
+  }, [enabled, snQuery.data]);
+
+  return placeholder;
+}