@adcops/autocore-react 3.0.19 → 3.0.21

package/src/hooks/useScaledValue.tsx

@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2024-04-30 11:41:59
+ * -----
+ * Last Modified: 2024-04-30 21:33:42
+ * -----
+ * 
+ */
+
+
+
+import { useCallback, useState } from 'react';
+
+
+export const kMillimeters2Inches: number = 1 / 25.4;
+
+
+type UseScaledValueReturn = [number, (newValue: number) => void];
+
+/**
+ * A custom React hook for converting values between different scales,
+ * with support for dynamically updating the scale and offset. This hook manages values
+ * in a base unit and allows for easy conversion to a display unit, updating
+ * reactively to changes in the conversion factors.
+ *
+ * @param initialValue - The initial value in the base unit.
+ * @param scale - The dynamic scale factor used for conversion to the display unit.
+ * @param offset - An optional offset applied after scaling (default is 0).
+ * @returns A tuple containing the display value and a setter function for updating
+ * the value in the display unit.
+ *
+ * @example
+ * Here's how to use `useScaledValue` in a component that fetches a scale factor from a backend
+ * and allows the user to input values in a converted scale, which are then handled in a base unit:
+ *
+ * ```tsx
+ * import React, { useState, useEffect } from 'react';
+ * import { useScaledValue } from './hooks/useScaledValue';
+ *
+ * const MeasurementInput: React.FC = () => {
+ *   const [units, setUnits] = useState<number>(1); // Start with a default scale of 1
+ *   const [xPosition, setXPosition] = useScaledValue(0, units);
+ *
+ *   useEffect(() => {
+ *     async function fetchScale() {
+ *       try {
+ *         // Simulate fetching scale factor from a backend
+ *         const res = await invoke("GNV", "read_value", { group: "ux", key: "kSelectedUnits" });
+ *         setUnits(res.data); // Update scale based on backend response
+ *       } catch (error) {
+ *         console.error('Failed to fetch units', error);
+ *       }
+ *     }
+ *     fetchScale();
+ *   }, []);
+ *
+ *   return (
+ *     <input
+ *       type="number"
+ *       value={xPosition.toFixed(2)} // Display the value formatted to 2 decimal places
+ *       onChange={(e) => setXPosition(parseFloat(e.target.value))}
+ *     />
+ *   );
+ * };
+ *
+ * export default MeasurementInput;
+ * ```
+ *
+ * In this example, `useScaledValue` is used to manage a measurement input in a dynamic unit system.
+ * The component fetches the conversion scale from the backend upon component mounting and updates the
+ * input display accordingly. The user's input is converted back to the base unit before being processed.
+ */
+export function useScaledValue(initialValue: number, scale: number, offset: number = 0): UseScaledValueReturn {
+
+    const [displayValue, setDisplayValue] = useState<number>(initialValue * scale + offset);
+
+    const handleSetDisplayValue = useCallback((newValue: number) => {
+
+        // In autocore-react, we multiple to scale incoming values,
+        // divide to scale outgoing values.
+        // This is an INCOMING value, so we multiply.
+
+        const newDisplayValue = newValue * scale + offset;
+        setDisplayValue(newDisplayValue);
+
+    }, [scale, offset]);
+
+    return [displayValue, handleSetDisplayValue];
+}