useMMAppSetting

A hook for configuring widget settings in the MachineMetrics platform. This hook allows you to define various types of settings that can be configured by users.

Usage

import { useMMAppSetting } from '@machinemetrics/mm-react-tools';

function MyWidget() {
  const { threshold } = useMMAppContext();

  // Define a numeric threshold setting
  useMMAppSetting("threshold", {
    label: "Threshold",
    type: "input",
    isRequired: true,
    helperText: "Enter the maximum value",
    validate: ({ value }) => {
      if (isNaN(value)) {
        return { message: "Must be a number" };
      }
    },
  });

  return (
    <Box>
        <Text>Current threshold: {threshold}</Text>
    </div>
  );
}

Arguments

The hook takes three arguments:

1. Property Name (string)

   • The identifier for the setting
   • Used to access the setting's value through useMMAppContext
   • Example: "threshold", "metric", "timeRange"

2. Setting Configuration (object)

   • Required properties:
     • label: The display label for the setting
     • type: The type of setting (one of: "input", "select", "radio", "thresholds", "custom")
   • Optional properties:
     • isRequired: Boolean indicating if the setting is required
     • helperText: Help text displayed below the setting
     • validate: Function to validate the setting value
     • default: Default value for the setting
     • Type-specific properties (e.g., options for select/radio, fields for thresholds)

3. State Triggers (array, optional)

   • Array of dependencies that trigger re-renders when they change
   • Used to ensure the setting updates when related state changes
   • Example: [thresholdEnabled, utilization]

Complete Example

useMMAppSetting(
  'utilization', // Property name
  {
    // Setting configuration
    type: 'thresholds',
    visible: thresholdEnabled === 'custom',
    fields: [
      {
        name: 'goal',
        label: 'Goal %',
        color: Palette.Green600,
        description: `At or above ${utilization?.warning || '-'}% in-cycle`,
        value: utilization?.warning,
      },
      // ... other fields
    ],
  },
  [thresholdEnabled, utilization], // State triggers
);

Setting Types

The hook supports various setting types:

• input: Text input field
• select: Dropdown selection
• thresholds: Multiple threshold values with colors
• custom: Custom component for complex settings
• radio: Radio button selection