@inventreedb/ui 0.10.0 → 0.11.0

package/lib/hooks/UseTable.tsx

@@ -0,0 +1,160 @@
+import { randomId } from '@mantine/hooks';
+import { useCallback, useMemo, useState } from 'react';
+import { useSearchParams } from 'react-router-dom';
+
+import type { FilterSetState, TableFilter } from '../types/Filters';
+import type { TableState } from '../types/Tables';
+import useFilterSet from './UseFilterSet';
+
+export type TableStateExtraProps = {
+  idAccessor?: string;
+  initialFilters?: TableFilter[];
+};
+
+/**
+ * A custom hook for managing the state of an <InvenTreeTable> component.
+ *
+ * Refer to the TableState type definition for more information.
+ */
+
+export default function useTable(
+  tableName: string,
+  tableProps: TableStateExtraProps = {
+    idAccessor: 'pk',
+    initialFilters: []
+  }
+): 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(
+    (clearSelection?: boolean) => {
+      setTableKey(generateTableName());
+      if (clearSelection) {
+        clearSelectedRecords();
+      }
+    },
+    [generateTableName]
+  );
+
+  const filterSet: FilterSetState = useFilterSet(
+    `table-${tableName}`,
+    tableProps.initialFilters
+  );
+
+  // 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 columns which are hidden
+  const [hiddenColumns, setHiddenColumns] = useState<string[]>([]);
+
+  // Array of selected records
+  const [selectedRecords, setSelectedRecords] = useState<any[]>([]);
+
+  // Array of selected primary key values
+  const selectedIds = useMemo(
+    () => selectedRecords.map((r) => r[tableProps.idAccessor || 'pk']),
+    [selectedRecords]
+  );
+
+  const clearSelectedRecords = useCallback(() => {
+    setSelectedRecords([]);
+  }, []);
+
+  const hasSelectedRecords = useMemo(() => {
+    return selectedRecords.length > 0;
+  }, [selectedRecords]);
+
+  // Total record count
+  const [recordCount, setRecordCount] = useState<number>(0);
+
+  const [page, setPage] = useState<number>(1);
+
+  // 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[tableProps.idAccessor || 'pk'] === record.pk
+      );
+
+      if (index >= 0) {
+        _records[index] = {
+          ..._records[index],
+          ...record
+        };
+      } else {
+        _records.push(record);
+      }
+
+      setRecords(_records);
+    },
+    [records]
+  );
+
+  const idAccessor = useMemo(
+    () => tableProps.idAccessor || 'pk',
+    [tableProps.idAccessor]
+  );
+
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+
+  return {
+    tableKey,
+    refreshTable,
+    isLoading,
+    setIsLoading,
+    filterSet,
+    queryFilters,
+    setQueryFilters,
+    clearQueryFilters,
+    expandedRecords,
+    setExpandedRecords,
+    isRowExpanded,
+    selectedRecords,
+    selectedIds,
+    setSelectedRecords,
+    clearSelectedRecords,
+    hasSelectedRecords,
+    searchTerm,
+    setSearchTerm,
+    recordCount,
+    setRecordCount,
+    hiddenColumns,
+    setHiddenColumns,
+    page,
+    setPage,
+    records,
+    setRecords,
+    updateRecord,
+    idAccessor
+  };
+}

package/lib/index.ts

@@ -15,10 +15,20 @@ export { UserRoles, UserPermissions } from './enums/Roles';
 export type {
   InvenTreePluginContext,
   InvenTreeFormsContext,
+  InvenTreeTablesContext,
+  ImporterDrawerContext,
   PluginVersion,
   StockAdjustmentFormsContext
 } from './types/Plugins';
-export type { RowAction, RowViewProps } from './types/Tables';
+
+export type {
+  RowAction,
+  RowViewProps,
+  TableColumn,
+  TableColumnProps,
+  InvenTreeTableProps,
+  InvenTreeTableRenderProps
+} from './types/Tables';
 
 export type {
   ApiFormFieldChoice,
@@ -42,6 +52,14 @@ export {
   getDetailUrl,
   navigateToLink
 } from './functions/Navigation';
+
+export {
+  notYetImplemented,
+  permissionDenied,
+  invalidResponse,
+  showTimeoutNotification
+} from './functions/Notification';
+
 export {
   checkPluginVersion,
   initPlugin
@@ -53,16 +71,32 @@ export {
   formatFileSize
 } from './functions/Formatting';
 
+export {
+  constructFormUrl,
+  mapFields,
+  type NestedDict
+} from './functions/Forms';
+
+export {
+  shortenString,
+  hashString
+} from './functions/String';
+
 // Common UI components
 export {
   ActionButton,
   type ActionButtonProps
 } from './components/ActionButton';
 export { AddItemButton } from './components/AddItemButton';
+export { Boundary, DefaultFallback } from './components/Boundary';
 export { ButtonMenu } from './components/ButtonMenu';
+export { CopyButton } from './components/CopyButton';
+export { CopyableCell } from './components/CopyableCell';
 export { ProgressBar } from './components/ProgressBar';
 export { PassFailButton, YesNoButton } from './components/YesNoButton';
 export { SearchInput } from './components/SearchInput';
+export { TableColumnSelect } from './components/TableColumnSelect';
+export { default as InvenTreeTable } from './components/InvenTreeTable';
 export {
   RowViewAction,
   RowDuplicateAction,
@@ -77,7 +111,21 @@ export {
   default as useMonitorDataOutput,
   type MonitorDataOutputProps
 } from './hooks/MonitorDataOutput';
+
 export {
   default as useMonitorBackgroundTask,
   type MonitorBackgroundTaskProps
 } from './hooks/MonitorBackgroundTask';
+
+export { default as useFilterSet } from './hooks/UseFilterSet';
+
+export {
+  default as useTable,
+  type TableStateExtraProps
+} from './hooks/UseTable';
+
+// State management
+export {
+  type StoredTableStateProps,
+  useStoredTableState
+} from './states/StoredTableState';

package/lib/states/StoredTableState.tsx

@@ -0,0 +1,91 @@
+import type { DataTableSortStatus } from 'mantine-datatable';
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+const DEFAULT_PAGE_SIZE: number = 25;
+
+/**
+ * Interfacing for storing persistent table state in the browser.
+ *
+ * The following properties are stored:
+ * - pageSize: The number of rows to display per page in the table.
+ * - hiddenColumns: An array of column names that are hidden in a given table.
+ * - columnNames: An object mapping table keys to arrays of column names.
+ * - sorting: An object mapping table keys to sorting configurations.
+ */
+export interface StoredTableStateProps {
+  pageSize: number;
+  setPageSize: (size: number) => void;
+  tableSorting: Record<string, any>;
+  getTableSorting: (tableKey: string) => DataTableSortStatus;
+  setTableSorting: (
+    tableKey: string
+  ) => (sorting: DataTableSortStatus<any>) => void;
+  tableColumnNames: Record<string, Record<string, string>>;
+  getTableColumnNames: (tableKey: string) => Record<string, string>;
+  setTableColumnNames: (
+    tableKey: string
+  ) => (names: Record<string, string>) => void;
+  clearTableColumnNames: () => void;
+  hiddenColumns: Record<string, string[]>;
+  getHiddenColumns: (tableKey: string) => string[] | null;
+  setHiddenColumns: (tableKey: string) => (columns: string[]) => void;
+}
+
+export const useStoredTableState = create<StoredTableStateProps>()(
+  persist(
+    (set, get) => ({
+      pageSize: DEFAULT_PAGE_SIZE,
+      setPageSize: (size: number) => {
+        set((state) => ({
+          pageSize: size
+        }));
+      },
+      tableSorting: {},
+      getTableSorting: (tableKey) => {
+        return get().tableSorting[tableKey] || {};
+      },
+      setTableSorting: (tableKey) => (sorting) => {
+        // Update the table sorting for the given table
+        set({
+          tableSorting: {
+            ...get().tableSorting,
+            [tableKey]: sorting
+          }
+        });
+      },
+      tableColumnNames: {},
+      getTableColumnNames: (tableKey) => {
+        return get().tableColumnNames[tableKey] || null;
+      },
+      setTableColumnNames: (tableKey) => (names) => {
+        // Update the table column names for the given table
+        set({
+          tableColumnNames: {
+            ...get().tableColumnNames,
+            [tableKey]: names
+          }
+        });
+      },
+      clearTableColumnNames: () => {
+        set({ tableColumnNames: {} });
+      },
+      hiddenColumns: {},
+      getHiddenColumns: (tableKey) => {
+        return get().hiddenColumns?.[tableKey] ?? null;
+      },
+      setHiddenColumns: (tableKey) => (columns) => {
+        // Update the hidden columns for the given table
+        set({
+          hiddenColumns: {
+            ...get().hiddenColumns,
+            [tableKey]: columns
+          }
+        });
+      }
+    }),
+    {
+      name: 'inventree-table-state'
+    }
+  )
+);

package/lib/types/Forms.tsx

@@ -68,6 +68,7 @@ export type ApiFormFieldHeader = {
  * @param adjustValue : Callback function to adjust the value of the field before it is sent to the API
  * @param addRow : Callback function to add a new row to a table field
  * @param onKeyDown : Callback function to get which key was pressed in the form to handle submission on enter
+ * @param singleFetchFunction : Optional function to fetch a single value for this field (used for fetching the initial value when editing an existing object)
  */
 export type ApiFormFieldType = {
   label?: string;
@@ -126,6 +127,7 @@ export type ApiFormFieldType = {
   addRow?: () => any;
   headers?: ApiFormFieldHeader[];
   depends_on?: string[];
+  singleFetchFunction?: (value: any) => Promise<any> | null;
 };
 
 export type ApiFormFieldSet = Record<string, ApiFormFieldType>;

package/lib/types/Plugins.tsx

@@ -13,6 +13,7 @@ import type {
 import type { UseModalReturn } from './Modals';
 import type { RenderInstanceProps } from './Rendering';
 import type { SettingsStateProps } from './Settings';
+import type { InvenTreeTableRenderProps } from './Tables';
 import type { UserStateProps } from './User';
 
 export interface PluginProps {
@@ -48,6 +49,10 @@ export type InvenTreeFormsContext = {
   stockActions: StockAdjustmentFormsContext;
 };
 
+export type InvenTreeTablesContext<T extends Record<string, any>> = {
+  renderTable: (props: InvenTreeTableRenderProps<T>) => React.ReactNode;
+};
+
 export type ImporterDrawerContext = {
   open: (sessionId: number, options?: { onClose?: () => void }) => void;
   close: () => void;
@@ -61,20 +66,22 @@ export type ImporterDrawerContext = {
  *
  * @param version - The version of the running InvenTree software stack
  * @param api - The Axios API instance (see ../states/ApiState.tsx)
+ * @param queryClient - The Tanstack QueryClient instance (see ../states/QueryState.tsx)
  * @param user - The current user instance (see ../states/UserState.tsx)
  * @param userSettings - The current user settings (see ../states/SettingsState.tsx)
  * @param globalSettings - The global settings (see ../states/SettingsState.tsx)
+ * @param modelInformation - A dictionary of available model information
+ * @param renderInstance - A component function for rendering a model instance
+ * @param host - The current host URL
+ * @param i18n - The i18n instance for translations (from @lingui/core)
+ * @param locale - The current locale string (e.g. 'en' / 'de')
  * @param navigate - The navigation function (see react-router-dom)
  * @param theme - The current Mantine theme
+ * @param colorScheme - The current Mantine color scheme (e.g. 'light' / 'dark')
  * @param forms - A set of functions for opening various API forms (see ../components/Forms.tsx)
+ * @param tables - A set of functions for rendering API tables
  * @param importer - A set of functions for controlling the global importer drawer (see ../components/importer/GlobalImporterDrawer.tsx)
- * @param colorScheme - The current Mantine color scheme (e.g. 'light' / 'dark')
- * @param host - The current host URL
- * @param i18n - The i18n instance for translations (from @lingui/core)
- * @param locale - The current locale string (e.g. 'en' / 'de')
  * @param model - The model type associated with the rendered component (if applicable)
- * @param modelInformation - A dictionary of available model information
- * @param renderInstance - A component function for rendering a model instance
  * @param id - The ID (primary key) of the model instance for the plugin (if applicable)
  * @param instance - The model instance data (if available)
  * @param reloadContent - A function which can be called to reload the plugin content
@@ -95,9 +102,10 @@ export type InvenTreePluginContext = {
   locale: string;
   navigate: NavigateFunction;
   theme: MantineTheme;
+  colorScheme: MantineColorScheme;
   forms: InvenTreeFormsContext;
+  tables: InvenTreeTablesContext<any>;
   importer: ImporterDrawerContext;
-  colorScheme: MantineColorScheme;
   model?: ModelType | string;
   id?: string | number | null;
   instance?: any;

package/lib/types/Tables.tsx

@@ -1,4 +1,5 @@
 import type { MantineStyleProp } from '@mantine/core';
+import type { AxiosInstance } from 'axios';
 import type {
   DataTableCellClickHandler,
   DataTableRowExpansionProps
@@ -219,3 +220,13 @@ export type InvenTreeTableProps<T = any> = {
   minHeight?: number;
   noHeader?: boolean;
 };
+
+export type InvenTreeTableRenderProps<T extends Record<string, any>> = {
+  url?: string;
+  tableState: TableState;
+  tableData?: T[];
+  columns: TableColumn<T>[];
+  props: InvenTreeTableProps<T>;
+  api: AxiosInstance;
+  navigate: NavigateFunction;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@inventreedb/ui",
     "description": "UI components for the InvenTree project",
-    "version": "0.10.0",
+    "version": "0.11.0",
     "private": false,
     "type": "module",
     "license": "MIT",
@@ -130,7 +130,7 @@
         "rollup": "^4.59.0",
         "rollup-plugin-license": "^3.7.0",
         "typescript": "^5.9.3",
-        "vite": "7.1.11",
+        "vite": "7.3.2",
         "vite-plugin-babel-macros": "^1.0.6",
         "vite-plugin-dts": "^4.5.4",
         "vite-plugin-externals": "^0.6.2",