@inventreedb/ui 0.2.3 → 0.3.0

package/lib/components/RowActions.tsx

@@ -0,0 +1,157 @@
+import { t } from '@lingui/core/macro';
+import { ActionIcon, Menu, Tooltip } from '@mantine/core';
+import {
+  IconArrowRight,
+  IconCircleX,
+  IconCopy,
+  IconDots,
+  IconEdit,
+  IconTrash
+} from '@tabler/icons-react';
+import { type ReactNode, useMemo, useState } from 'react';
+import { cancelEvent } from '../functions/Events';
+import { getDetailUrl } from '../functions/Navigation';
+import { navigateToLink } from '../functions/Navigation';
+import type { RowAction, RowViewProps } from '../types/Tables';
+
+export type { RowAction, RowViewProps } from '../types/Tables';
+
+// Component for viewing a row in a table
+export function RowViewAction(props: RowViewProps): RowAction {
+  return {
+    ...props,
+    color: undefined,
+    icon: <IconArrowRight />,
+    onClick: (event: any) => {
+      const url = getDetailUrl(props.modelType, props.modelId);
+      navigateToLink(url, props.navigate, event);
+    }
+  };
+}
+
+// Component for duplicating a row in a table
+export function RowDuplicateAction(props: RowAction): RowAction {
+  return {
+    ...props,
+    title: t`Duplicate`,
+    color: 'green',
+    icon: <IconCopy />
+  };
+}
+
+// Component for editing a row in a table
+export function RowEditAction(props: RowAction): RowAction {
+  return {
+    ...props,
+    title: t`Edit`,
+    color: 'blue',
+    icon: <IconEdit />
+  };
+}
+
+// Component for deleting a row in a table
+export function RowDeleteAction(props: RowAction): RowAction {
+  return {
+    ...props,
+    title: t`Delete`,
+    color: 'red',
+    icon: <IconTrash />
+  };
+}
+
+// Component for cancelling a row in a table
+export function RowCancelAction(props: RowAction): RowAction {
+  return {
+    ...props,
+    title: t`Cancel`,
+    color: 'red',
+    icon: <IconCircleX />
+  };
+}
+
+/**
+ * Component for displaying actions for a row in a table.
+ * Displays a simple dropdown menu with a list of actions.
+ */
+export function RowActions({
+  title,
+  actions,
+  disabled = false,
+  index
+}: {
+  title?: string;
+  disabled?: boolean;
+  actions: RowAction[];
+  index?: number;
+}): ReactNode {
+  // Prevent default event handling
+  // Ref: https://icflorescu.github.io/mantine-datatable/examples/links-or-buttons-inside-clickable-rows-or-cells
+  function openMenu(event: any) {
+    cancelEvent(event);
+    setOpened(!opened);
+  }
+
+  const [opened, setOpened] = useState(false);
+
+  const visibleActions = useMemo(() => {
+    return actions.filter((action) => !action.hidden);
+  }, [actions]);
+
+  // Render a single action icon
+  function RowActionIcon(action: Readonly<RowAction>) {
+    return (
+      <Tooltip
+        withinPortal={true}
+        label={action.tooltip ?? action.title}
+        key={action.title}
+        position='left'
+      >
+        <Menu.Item
+          color={action.color}
+          leftSection={action.icon}
+          onClick={(event) => {
+            // Prevent clicking on the action from selecting the row itself
+            cancelEvent(event);
+            action.onClick?.(event);
+            setOpened(false);
+          }}
+          disabled={action.disabled || false}
+        >
+          {action.title}
+        </Menu.Item>
+      </Tooltip>
+    );
+  }
+
+  return (
+    visibleActions.length > 0 && (
+      <Menu
+        withinPortal={true}
+        disabled={disabled}
+        position='bottom-end'
+        opened={opened}
+        onChange={setOpened}
+      >
+        <Menu.Target>
+          <Tooltip withinPortal={true} label={title || t`Actions`}>
+            <ActionIcon
+              key={`row-action-menu-${index ?? ''}`}
+              aria-label={`row-action-menu-${index ?? ''}`}
+              onClick={openMenu}
+              disabled={disabled}
+              variant='subtle'
+              color='gray'
+            >
+              <IconDots />
+            </ActionIcon>
+          </Tooltip>
+        </Menu.Target>
+        <Menu.Dropdown>
+          {visibleActions.map((action) => (
+            <RowActionIcon key={action.title} {...action} />
+          ))}
+        </Menu.Dropdown>
+      </Menu>
+    )
+  );
+}

package/lib/components/SearchInput.tsx

@@ -0,0 +1,49 @@
+import { t } from '@lingui/core/macro';
+import { CloseButton, TextInput } from '@mantine/core';
+import { useDebouncedValue } from '@mantine/hooks';
+import { IconSearch } from '@tabler/icons-react';
+import { useEffect, useState } from 'react';
+
+/**
+ * A search input component that debounces user input
+ */
+export function SearchInput({
+  disabled,
+  debounce,
+  placeholder,
+  searchCallback
+}: Readonly<{
+  disabled?: boolean;
+  debounce?: number;
+  placeholder?: string;
+  searchCallback: (searchTerm: string) => void;
+}>) {
+  const [value, setValue] = useState<string>('');
+  const [searchText] = useDebouncedValue(value, debounce ?? 500);
+
+  useEffect(() => {
+    searchCallback(searchText);
+  }, [searchText]);
+
+  return (
+    <TextInput
+      value={value}
+      disabled={disabled}
+      aria-label='table-search-input'
+      leftSection={<IconSearch />}
+      placeholder={placeholder ?? t`Search`}
+      onChange={(event) => setValue(event.target.value)}
+      rightSection={
+        value.length > 0 ? (
+          <CloseButton
+            size='xs'
+            onClick={() => {
+              setValue('');
+              searchCallback('');
+            }}
+          />
+        ) : null
+      }
+    />
+  );
+}

package/lib/components/YesNoButton.tsx

@@ -0,0 +1,42 @@
+import { t } from '@lingui/core/macro';
+import { Badge, Skeleton } from '@mantine/core';
+
+import { isTrue } from '../functions/Conversion';
+
+export function PassFailButton({
+  value,
+  passText,
+  failText
+}: Readonly<{
+  value: any;
+  passText?: string;
+  failText?: string;
+}>) {
+  const v = isTrue(value);
+  const pass = passText ?? t`Pass`;
+  const fail = failText ?? t`Fail`;
+
+  return (
+    <Badge
+      color={v ? 'green' : 'red'}
+      variant='filled'
+      radius='lg'
+      size='sm'
+      style={{ maxWidth: '50px' }}
+    >
+      {v ? pass : fail}
+    </Badge>
+  );
+}
+
+export function YesNoButton({ value }: Readonly<{ value: any }>) {
+  return <PassFailButton value={value} passText={t`Yes`} failText={t`No`} />;
+}
+
+export function YesNoUndefinedButton({ value }: Readonly<{ value?: boolean }>) {
+  if (value === undefined) {
+    return <Skeleton height={15} width={32} />;
+  } else {
+    return <YesNoButton value={value} />;
+  }
+}

package/lib/enums/ApiEndpoints.tsx

@@ -235,5 +235,8 @@ export enum ApiEndpoints {
   error_report_list = 'error-report/',
   project_code_list = 'project-code/',
   custom_unit_list = 'units/',
-  notes_image_upload = 'notes-image-upload/'
+  notes_image_upload = 'notes-image-upload/',
+  email_list = 'admin/email/',
+  email_test = 'admin/email/test/',
+  config_list = 'admin/config/'
 }

package/lib/enums/ModelInformation.tsx

@@ -36,6 +36,7 @@ export const ModelInformationDict: ModelDict = {
   partparametertemplate: {
     label: () => t`Part Parameter Template`,
     label_multiple: () => t`Part Parameter Templates`,
+    url_overview: '/settings/admin/part-parameters',
     url_detail: '/partparametertemplate/:pk/',
     api_endpoint: ApiEndpoints.part_parameter_template_list,
     icon: 'test_templates'
@@ -265,6 +266,7 @@ export const ModelInformationDict: ModelDict = {
   selectionlist: {
     label: () => t`Selection List`,
     label_multiple: () => t`Selection Lists`,
+    url_overview: '/settings/admin/part-parameters',
     api_endpoint: ApiEndpoints.selectionlist_list,
     icon: 'list_details'
   },

package/lib/functions/Conversion.tsx

@@ -0,0 +1,42 @@
+/*
+ * Determine if the provided value is "true":
+ *
+ * Many settings stored on the server are true/false,
+ * but stored as string values, "true" / "false".
+ *
+ * This function provides a wrapper to ensure that the return type is boolean
+ */
+export function isTrue(value: any): boolean {
+  if (value === true) {
+    return true;
+  }
+
+  if (value === false) {
+    return false;
+  }
+
+  const s = String(value).trim().toLowerCase();
+
+  return ['true', 'yes', '1', 'on', 't', 'y'].includes(s);
+}
+
+/*
+ * Resolve a nested item in an object.
+ * Returns the resolved item, if it exists.
+ *
+ * e.g. resolveItem(data, "sub.key.accessor")
+ *
+ * Allows for retrieval of nested items in an object.
+ */
+export function resolveItem(obj: any, path: string): any {
+  const properties = path.split('.');
+  return properties.reduce((prev, curr) => prev?.[curr], obj);
+}
+
+export function identifierString(value: string): string {
+  // Convert an input string e.g. "Hello World" into a string that can be used as an identifier, e.g. "hello-world"
+
+  value = value || '-';
+
+  return value.toLowerCase().replace(/[^a-z0-9]/g, '-');
+}

package/lib/functions/Formatting.tsx

@@ -0,0 +1,88 @@
+export interface FormatDecmimalOptionsInterface {
+  digits?: number;
+  minDigits?: number;
+  locale?: string;
+}
+
+export interface FormatCurrencyOptionsInterface {
+  digits?: number;
+  minDigits?: number;
+  currency?: string;
+  locale?: string;
+  multiplier?: number;
+}
+
+export function formatDecimal(
+  value: number | null | undefined,
+  options: FormatDecmimalOptionsInterface = {}
+) {
+  const locale = options.locale || navigator.language || 'en-US';
+
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  const formatter = new Intl.NumberFormat(locale, {
+    style: 'decimal',
+    maximumFractionDigits: options.digits ?? 6,
+    minimumFractionDigits: options.minDigits ?? 0
+  });
+
+  return formatter.format(value);
+}
+
+/*
+ * format currency (money) value based on current settings
+ *
+ * Options:
+ * - currency: Currency code (uses default value if none provided)
+ * - locale: Locale specified (uses default value if none provided)
+ * - digits: Maximum number of significant digits (default = 10)
+ */
+export function formatCurrencyValue(
+  value: number | string | null | undefined,
+  options: FormatCurrencyOptionsInterface = {}
+) {
+  if (value == null || value == undefined) {
+    return null;
+  }
+
+  value = Number.parseFloat(value.toString());
+
+  if (Number.isNaN(value) || !Number.isFinite(value)) {
+    return null;
+  }
+
+  value *= options.multiplier ?? 1;
+
+  // Extract locale information
+  const locale = options.locale || navigator.language || 'en-US';
+
+  const minDigits = options.minDigits ?? 0;
+  const maxDigits = options.digits ?? 6;
+
+  const formatter = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency: options.currency,
+    maximumFractionDigits: Math.max(minDigits, maxDigits),
+    minimumFractionDigits: Math.min(minDigits, maxDigits)
+  });
+
+  return formatter.format(value);
+}
+
+/*
+ * Format a file size (in bytes) into a human-readable format
+ */
+export function formatFileSize(size: number) {
+  const suffixes: string[] = ['B', 'KB', 'MB', 'GB'];
+
+  let idx = 0;
+
+  while (size > 1024 && idx < suffixes.length) {
+    size /= 1024;
+    idx++;
+  }
+
+  return `${size.toFixed(2)} ${suffixes[idx]}`;
+}

package/lib/functions/Navigation.tsx

@@ -72,7 +72,7 @@ export const navigateToLink = (
 
   const base = `/${getBaseUrl()}`;
 
-  if (event?.ctrlKey || event?.shiftKey) {
+  if (eventModified(event)) {
     // Open the link in a new tab
     let url = link;
     if (link.startsWith('/') && !link.startsWith(base)) {
@@ -91,3 +91,14 @@ export const navigateToLink = (
     navigate(url);
   }
 };
+
+/**
+ * Check if the event is modified (e.g. ctrl, shift, or meta key pressed)
+ * @param event - The event to check
+ * @returns true if the event was modified
+ */
+export const eventModified = (
+  event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>
+) => {
+  return event?.ctrlKey || event?.shiftKey || event?.metaKey;
+};

package/lib/index.ts

@@ -13,6 +13,7 @@ export type { ModelDict } from './enums/ModelInformation';
 export { UserRoles, UserPermissions } from './enums/Roles';
 
 export type { InvenTreePluginContext } from './types/Plugins';
+export type { RowAction, RowViewProps } from './types/Tables';
 
 // Common utility functions
 export { apiUrl } from './functions/Api';
@@ -22,3 +23,24 @@ export {
   navigateToLink
 } from './functions/Navigation';
 export { checkPluginVersion } from './functions/Plugins';
+
+export {
+  formatCurrencyValue,
+  formatDecimal,
+  formatFileSize
+} from './functions/Formatting';
+
+// Common UI components
+export { ActionButton } from './components/ActionButton';
+export { ButtonMenu } from './components/ButtonMenu';
+export { ProgressBar } from './components/ProgressBar';
+export { PassFailButton, YesNoButton } from './components/YesNoButton';
+export { SearchInput } from './components/SearchInput';
+export {
+  RowViewAction,
+  RowDuplicateAction,
+  RowEditAction,
+  RowDeleteAction,
+  RowCancelAction,
+  RowActions
+} from './components/RowActions';

package/lib/types/Plugins.tsx

@@ -6,6 +6,7 @@ import type { ModelDict } from '../enums/ModelInformation';
 import type { ModelType } from '../enums/ModelType';
 import type { ApiFormModalProps, BulkEditApiFormModalProps } from './Forms';
 import type { UseModalReturn } from './Modals';
+import type { RenderInstanceProps } from './Rendering';
 import type { SettingsStateProps } from './Settings';
 import type { UserStateProps } from './User';
 
@@ -45,6 +46,7 @@ export type InvenTreeFormsContext = {
  * @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
@@ -59,6 +61,7 @@ export type InvenTreePluginContext = {
   userSettings: SettingsStateProps;
   globalSettings: SettingsStateProps;
   modelInformation: ModelDict;
+  renderInstance: (props: Readonly<RenderInstanceProps>) => React.ReactNode;
   host: string;
   locale: string;
   navigate: NavigateFunction;

package/lib/types/Rendering.tsx

@@ -0,0 +1,24 @@
+import type { ModelType } from '../enums/ModelType';
+
+/**
+ * Interface for rendering a model instance.
+ */
+export interface InstanceRenderInterface {
+  instance: any;
+  link?: boolean;
+  navigate?: any;
+  showSecondary?: boolean;
+}
+
+type EnumDictionary<T extends string | symbol | number, U> = {
+  [K in T]: U;
+};
+
+export type ModelRendererDict = EnumDictionary<
+  ModelType,
+  (props: Readonly<InstanceRenderInterface>) => React.ReactNode
+>;
+
+export type RenderInstanceProps = {
+  model: ModelType | undefined;
+} & InstanceRenderInterface;

package/lib/types/Settings.tsx

@@ -50,6 +50,7 @@ export interface SettingsStateProps {
   lookup: SettingsLookup;
   fetchSettings: () => Promise<boolean>;
   loaded: boolean;
+  isError: boolean;
   endpoint: ApiEndpoints;
   pathParams?: PathParams;
   getSetting: (key: string, default_value?: string) => string; // Return a raw setting value