@adcops/autocore-react 3.0.19 → 3.0.21

package/src/components/ValueInput.tsx

@@ -2,18 +2,65 @@
  * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
  * Created Date: 2024-03-20 13:05:42
  * -----
- * Last Modified: 2024-04-25 16:40:53
+ * Last Modified: 2024-04-30 08:33:37
  * -----
  * 
  */
 
+/** @file
+ * `ValueInput` is a React component for number input that encapsulates various features
+ * such as custom numeric formatting, optional currency formatting, increment and decrement
+ * buttons, and validation. This component uses the PrimeReact `InputNumber` control
+ * to provide a rich input experience, including handling both decimal and currency modes,
+ * with configurable precision and optional prefix/suffix text.
+ *
+ * Properties:
+ * - `label`: Label text displayed on the input field.
+ * - `value`: Current numeric value of the input field.
+ * - `min`: Minimum allowable value.
+ * - `max`: Maximum allowable value.
+ * - `minPrecision`: Minimum number of decimal places to display.
+ * - `maxPrecision`: Maximum number of decimal places allowed.
+ * - `mode`: Determines whether the input is treated as a plain decimal or currency. Defaults to "decimal".
+ * - `currency`: ISO 4217 currency code for formatting the value as currency.
+ * - `prefix`: String to display before the value.
+ * - `suffix`: String to display after the value.
+ * - `showButtons`: Whether to display increment and decrement buttons.
+ * - `step`: The amount by which the value should be incremented or decremented.
+ * - `locale`: Locale code for formatting the value.
+ * - `description`: Additional descriptive text to display below the input.
+ * - `disabled`: Whether the input is disabled.
+ * - `dispatchTopic`: Event topic to dispatch on value change.
+ * - `placeholder`: Placeholder text when the input is empty.
+ * - `onValueChanged`: Callback function that is called when the user accepts a new value.
+ *
+ * Example Usage:
+ * ```tsx
+ * <ValueInput
+ *   label="Quantity"
+ *   value={10}
+ *   min={1}
+ *   max={100}
+ *   minPrecision={0}
+ *   maxPrecision={2}
+ *   mode="decimal"
+ *   showButtons={true}
+ *   step={1}
+ *   locale="en-US"
+ *   onValueChanged={(newValue) => console.log("New Value:", newValue)}
+ * />
+ * ```
+ *
+ * This example creates a `ValueInput` component for entering quantities, with values ranging from 1 to 100,
+ * allowing up to 2 decimal places. Increment and decrement buttons are visible, and the new value is logged
+ * to the console when accepted.
+ */
 
-import React, { createRef } from "react";
 
+import React, { useState, useRef, useEffect, useContext } from 'react';
 import { InputNumber } from 'primereact/inputnumber';
-import { Button } from "primereact/button";
-
 import { EventEmitterContext } from "../core/EventEmitterContext";
+import { Button } from 'primereact/button';
 
 /**
  * Properties of the ValueInput component.
@@ -34,12 +81,12 @@ interface ValueInputProps {
     /**
      * Minimum value for the field.
      */
-    min: number | undefined;
+    min?: number | undefined;
 
     /**
      * Minimum value for the field.
      */
-    max: number | undefined;
+    max?: number | undefined;
 
     /**
      * Minimum number of decimal points. The user will not
@@ -49,7 +96,7 @@ interface ValueInputProps {
      * the component will throw an error.
      * @default 0
      */
-    minPrecision: number | undefined;
+    minPrecision?: number | undefined;
 
 
     /**
@@ -58,7 +105,7 @@ interface ValueInputProps {
      * the component will throw an error.
      * @default 3
      */
-    maxPrecision: number | undefined;
+    maxPrecision?: number | undefined;
 
 
     /**
@@ -67,7 +114,7 @@ interface ValueInputProps {
      * currency type using the currency property.
      * @default "decimal"
      */
-    mode: "currency" | "decimal" | undefined;
+    mode?: "currency" | "decimal" | undefined;
 
 
     /**
@@ -78,19 +125,19 @@ interface ValueInputProps {
      * 
      * @default "USD"
      */
-    currency: string;
+    currency?: string;
 
     /**
      * An optional prefix before the value of the field.
      * Unlike the TextInput control, this prefix is internal to the field.
      */
-    prefix: string | undefined;
+    prefix?: string | undefined;
 
     /**
      * An optional suffix after the value of the field.
      * Unlike the TextInput control, this prefix is internal to the field.
      */
-    suffix: string | undefined;
+    suffix?: string | undefined;
 
     /**
      * Set true to display buttons to increment/decrement the value.
@@ -98,12 +145,12 @@ interface ValueInputProps {
      * 
      * @default false
      */
-    showButtons: boolean;
+    showButtons?: boolean;
 
     /**
      * The amount clicking an increment/decrement buttion will change the value.
      */
-    step: number | undefined;
+    step?: number | undefined;
 
 
     /**
@@ -112,25 +159,25 @@ interface ValueInputProps {
      * 
      * @default "en-US"
      */
-    locale: string | undefined;
+    locale?: string | undefined;
 
     /**
      * A small, advisory text below the field.
      */
-    description: React.ReactNode | undefined;
+    description?: React.ReactNode | undefined;
 
     /**
      * If true, all functions of the field will be disabled.
      */
-    disabled: boolean | undefined;
+    disabled?: boolean | undefined;
 
     /** Topic on which the value will be dispatched through the user interfave on successful data entry. */
-    dispatchTopic: string | undefined;
+    dispatchTopic?: string | undefined;
 
     /**
      * Placeholder string to display if the value is empty.
      */
-    placeholder: string | undefined;
+    placeholder?: string | undefined;
 
     /**
      * The user has accepted a new value.
@@ -139,229 +186,182 @@ interface ValueInputProps {
     onValueChanged?(newValue: number): void;
 }
 
-/**
- * State variables of the ValueInput component.
- */
-interface ValueInputState {
-
-    entryValue: number | null;
-    currentValue: number | null;
-    editing: boolean;
-}
-
-
 /**
  * A convenient field with all the usual features of inputing numbers. 
  * Wraps the common features of use of a InputNumber, p-inputgroup, some icon buttons,
  * accepting and rejecting values and keyboard management.
  */
-export class ValueInput extends React.Component<ValueInputProps, ValueInputState> {
-
-    // Here's an example of using the Application-wide EventEmitter con
-    // Define the contextType for the class to access the context
-    static contextType = EventEmitterContext;
-    // After specifying contextType, you can declare the context's type for the TypeScript compiler.
-    // Basically, we're telling TypeScript the type of the context; this line doesn't
-    // actually do any linking linking to the EventEmitterContext.    
-    declare context: React.ContextType<typeof EventEmitterContext>;
-
-
-
+export const ValueInput: React.FC<ValueInputProps> = ({
+    label = '',
+    value = null,
+    min = undefined,
+    max = undefined,
+    minPrecision = 0,
+    maxPrecision = 3,
+    mode = "decimal",
+    currency = "USD",
+    prefix = undefined,
+    suffix = undefined,
+    showButtons = false,
+    step = 1,
+    locale = "en-US",
+    description = undefined,
+    disabled = false,
+    dispatchTopic = undefined,
+    placeholder = undefined,
+    onValueChanged = undefined
+}) => {
+    const [entryValue, setEntryValue] = useState<number | null>(value);
+    const [currentValue, setCurrentValue] = useState<number | null>(value);
+    const [bufferedValue, setBufferedValue] = useState<number | null>(value);
+    const [editing, setEditing] = useState<boolean>(false);
+    const [invalidValue, setInvalidValue] = useState<boolean>(false);
+    const inputRef = useRef<InputNumber>(null);
+    const eventEmitter = useContext(EventEmitterContext);
+
+    useEffect(() => {
+
+        if (bufferedValue !== null) {
+            setCurrentValue(bufferedValue);
+            setBufferedValue(null);
+            setInvalidValue(false);
+        }
+        else if (value !== currentValue) {
+            setCurrentValue(value);
+            setEntryValue(value);
+            setEditing(false);
+            setInvalidValue(false);
+        }
+        
 
-    /**
-     * Default properties for the component.
-     */
-    static defaultProps = {
-        label: '',
-        value: undefined,
-        keyFilter: undefined,
-        writeTopic: undefined,
-        onValueChanged: undefined,
-        description: undefined,
-        prefix: undefined,
-        suffix: undefined,
-        disabled: false,
-        dispatchTopic: undefined,
-        placeholder: undefined,
-        validator: undefined,
-        min: undefined,
-        max: undefined,
-        minPrecision: 0,
-        maxPrecision: 3,
-        mode: "decimal",
-        showButtons: false,
-        step: 1,
-        locale: "en-US",
-        currency: "USD"
-    };
-    inputRef: React.RefObject<HTMLInputElement>;
+    }, [value, currentValue]);
 
     /**
+     * Buffers the original value, if editing just starting,
+     * and updates the entry value.
      * 
-     * @param {FooterViewProps} props 
+     * @param val New value being entered.
      */
-    constructor(props: ValueInputProps) {
-        super(props);
-        this.state = {
-            entryValue: props.value,
-            currentValue: props.value,
-            editing: false
-        };
-
-        this.inputRef = createRef();
-    }
+    const handleBufferValue = (val: number | null) => {
+        if (!editing) {
+            setBufferedValue(currentValue);            
+            setEditing(true);            
+        }        
+        setEntryValue(val);        
+    };
 
     /**
-     * The component has been loaded into the DOM.
+     * Returns true if the new value falls within specified parameters.
+     * @param val The new value.
+     * @returns 
      */
-    componentDidMount() {
-    }
-
-    componentDidUpdate(prevProps: ValueInputProps) {
-        // Check if the value prop has changed
-        if (prevProps.value !== this.props.value) {
-            this.setState({
-                currentValue: this.props.value,
-                entryValue: this.props.value,
-                editing: false  // Consider whether you want to reset editing state here
-            });
-        }
-    }    
-
-
-    private onBufferValue(val: number | null) {
-        if (val === null)
-            return;
-
-        if (!this.state.editing) {
-            this.setState({
-                entryValue: val, //this.state.currentValue,
-                editing: true
-            }, () => {
-
-                setTimeout(() => {
-                    if (this.inputRef.current) {
-                      this.inputRef.current.focus();
-                    }
-
-                  }, 0);
-
+    const validateValue = (val : number) : boolean => {
+        
+        if (max !== undefined) {
+            if (val > max) {
+                return false;
             }
-            );
         }
-        else {
-            this.setState({
-                entryValue: val
-            });
+        if (min !== undefined) {
+            if (val < min) {
+                return false;
+            }
         }
+
+        return true;
     }
 
     /**
      * The user has elected to accept the input value. Validate and store, if valid.
      */
-    private onAcceptValue() {
-        if (this.state.entryValue !== null) {
-            this.setState({ editing: false, currentValue: this.state.entryValue });
-
-            if (this.props.onValueChanged)
-                this.props.onValueChanged(this.state.entryValue);
-
-            if (this.props.dispatchTopic !== undefined) {
-                this.context.dispatch({ topic: this.props.dispatchTopic, payload: this.state.entryValue });
+    const handleAcceptValue = () => {
+        if (editing && entryValue !== null ) {
+
+            if (validateValue(entryValue)) {
+                setCurrentValue(entryValue);
+                setEditing(false);
+                onValueChanged?.(entryValue);
+                setInvalidValue(false);
+    
+                if (dispatchTopic) {
+                    eventEmitter.dispatch({ topic: dispatchTopic, payload: entryValue });
+                }    
+            }
+            else {
+                setInvalidValue(true);
             }
 
         }
-    }
+    };
 
     /**
-     * The user wishes to reset/cancel the previous value.
+     * The user wishes to cancel/reset to the previous value.
      */
-    private onResetValue() {
-
-        if (this.state.editing) {
-
-            this.setState({
-                currentValue: this.state.currentValue,
-                entryValue: this.state.currentValue,
-                editing: false
-            });
-        }
-    }
-
+    const handleResetValue = () => {
+        if (editing) {
+            setEntryValue(null);
+            setCurrentValue(null);
+            setEditing(false);
+            setInvalidValue(false);    
+        }        
+    };
 
-    render() {
-
-        return (
-            <div>
-                <div className="p-inputgroup flex-1" >
-                    <span className="p-inputgroup-addon">
-                        {this.props.label}
-                    </span>
-                    <InputNumber
-                        inputRef={this.inputRef}
-                        key={this.state.editing ? "editing" : "not-editing"}
-                        min={this.props.min}
-                        max={this.props.max}
-                        minFractionDigits={this.props.minPrecision}
-                        maxFractionDigits={this.props.maxPrecision}
-                        mode={this.props.mode}
-                        prefix={this.props.prefix}
-                        suffix={this.props.suffix}
-                        showButtons={this.props.showButtons}
-                        step={this.props.step}
-                        placeholder={this.props.placeholder}
-                        value={this.state.currentValue}
-                        onChange={(e) => { this.onBufferValue(e.value) }}
-
-                        buttonLayout="horizontal"
-                        decrementButtonClassName="p-button-danger"
-                        incrementButtonClassName="p-button-success"
-                        incrementButtonIcon="pi pi-plus"
-                        decrementButtonIcon="pi pi-minus"
-
-                        locale="en-US"
-                        currency={this.props.currency}
-
-                        onKeyDown={(e) => {
-                            if (e.key === 'Enter') {
-                                this.onAcceptValue();
-                            }
-                            else if (e.key === 'Escape') {
-                                this.onResetValue();
-                            }
-                        }}
-                        disabled={this.props.disabled}
-                        autoFocus={false}
-                    />
-                    <Button
-                        icon="pi pi-check"
-                        disabled={this.props.disabled || !this.state.editing}
-                        className="p-button-success"
-                        onClick={() => this.onAcceptValue()}
-                        visible={this.state.editing}
-                        size="small"
-                        autoFocus={false}
-                    />
-
-                    <Button
-                        icon="pi pi-times"
-                        disabled={this.props.disabled || !this.state.editing}
-                        className="p-button-danger"
-                        onClickCapture={() => this.onResetValue()}
-                        visible={this.state.editing}
-                        size="small"
-                        autoFocus={false}
-                    />
-                </div>
-
-                {this.props.description !== undefined &&
-                    <small>{this.props.description}</small>
-                }
+    return (
+        <div>
+            <div className="p-inputgroup flex-1">
+                <span className="p-inputgroup-addon">{label}</span>
+                <InputNumber
+                    ref={inputRef}
+                    invalid={invalidValue}
+                    min={min}
+                    max={max}                    
+                    minFractionDigits={minPrecision}
+                    maxFractionDigits={maxPrecision}
+                    mode={mode}
+                    prefix={prefix}
+                    suffix={suffix}
+                    showButtons={showButtons}
+                    step={step}
+                    placeholder={placeholder}
+                    value={currentValue}
+                    onChange={(e) => handleBufferValue(e.value)}
+                    locale={locale}
+                    currency={currency}
+                    onKeyDown={(e) => {
+                        if (e.key === 'Enter') {
+                            handleAcceptValue();
+                        } else if (e.key === 'Escape') {
+                            handleResetValue();
+                        }
+                    }}
+                    disabled={disabled}
+                />
+
+                <Button
+                    icon="pi pi-check"
+                    disabled={disabled || !editing}
+                    className="p-button-success"
+                    onClick={() => handleAcceptValue()}
+                    visible={editing}
+                    size="small"
+                    autoFocus={false}
+                />
+
+                <Button
+                    icon="pi pi-times"
+                    disabled={disabled || !editing}
+                    className="p-button-danger"
+                    onClickCapture={() => handleResetValue()}
+                    visible={editing}
+                    size="small"
+                    autoFocus={false}
+                />
 
 
             </div>
+            {description && <small>{description}</small>}
+        </div>
+    );
+};
 
-        );
-    }
-
-}
+export default ValueInput;

package/src/hooks/adsHooks.tsx

@@ -2,14 +2,14 @@
  * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
  * Created Date: 2024-04-26 09:04:40
  * -----
- * Last Modified: 2024-04-28 20:07:12
+ * Last Modified: 2024-04-30 21:32:01
  * -----
  * 
  */
 
 
 
-import { useContext, useRef, useEffect } from 'react';
+import { useContext, useRef, useEffect, useCallback } from 'react';
 import { EventEmitterContext } from '../core/EventEmitterContext';
 
 
@@ -163,6 +163,80 @@ export function useAdsWriteValue(symbolName: string) {
 
 
 
+
+
+/**
+ * useAdsWriteScaledValue is a custom React hook that enables writing scaled numerical values to a backend system.
+ * It applies a specified scale and offset to a numeric value before sending it over an ADS connection.
+ * This hook is ideal for scenarios where numeric data needs to be adjusted according to dynamically configurable
+ * scale factors before being persisted or processed by a backend system.
+ *
+ * @param symbolName The symbol name in the backend system where the value will be written.
+ * @param scale The scale factor to be applied to the value.
+ * @param offset The offset to be applied after scaling the value.
+ * @returns A function that takes a numeric value, applies the scaling and offset, and sends the modified value to the backend.
+ *
+ * @example
+ * This example demonstrates how to use the `useAdsWriteScaledValue` hook within a component that allows users
+ * to input a value in inches, which is then automatically converted to millimeters (if the scale is set for such conversion)
+ * based on a dynamic scale factor managed in the component's state.
+ *
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import { useAdsWriteScaledValue } from './hooks';
+ *
+ * const MeasurementInput: React.FC = () => {
+ *     const [scale, setScale] = useState<number>(1 / 25.4); // Initial scale for converting inches to millimeters.
+ *     const [offset, setOffset] = useState<number>(0); // No offset by default.
+ *
+ *     // The hook is used here with the scale and offset state variables.
+ *     const writeMeasurement = useAdsWriteScaledValue("GIO.axisX.position", scale, offset);
+ *
+ *     // This function is called when the input field value changes.
+ *     const handleMeasurementChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+ *         const valueInInches = parseFloat(event.target.value);
+ *         writeMeasurement(valueInInches); // Write the scaled value (converted to millimeters).
+ *     };
+ *
+ *     return (
+ *         <div>
+ *             <label>Enter measurement in inches:</label>
+ *             <input type="number" onChange={handleMeasurementChange} />
+ *         </div>
+ *     );
+ * };
+ *
+ * export default MeasurementInput;
+ * ```
+ *
+ * In this component, `writeMeasurement` is a function returned by the `useAdsWriteScaledValue` hook that takes a value in inches,
+ * converts it to millimeters using the current `scale`, and writes the result to a backend symbol. The `scale` and `offset` can be adjusted
+ * dynamically if needed, for instance, based on user selection or other external configurations.
+ */
+export function useAdsWriteScaledValue(symbolName: string, scale: number, offset: number) {
+    const { invoke } = useContext(EventEmitterContext);
+    const domain = "ADS";
+    const fname = "write_value";
+    
+    return useCallback(async (value: number) => {
+
+        // In autocore-react, we multiple to scale incoming values,
+        // divide to scale outgoing values.
+        // This is an OUTGOING value, so we divide.
+
+        const scaledValue = (value - offset) / scale; 
+        try {
+            await invoke(domain, fname, { symbol_name: symbolName, value: scaledValue });
+        } catch (err) {
+            console.error(`Error writing scaled value to tag ${symbolName}: ${err}`);
+        }
+    }, [symbolName, scale, offset, invoke]);
+}
+
+
+
+
+
 /**
  * Custom hook to send a "tap" action, which sends true followed by false after a short delay,
  * to a specified symbol in the backend. This is used to simulate a button tap or momentary switch.

package/src/hooks/index.ts

@@ -0,0 +1,12 @@
+/*
+ * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2024-04-30 12:14:43
+ * -----
+ * Last Modified: 2024-04-30 12:15:46
+ * -----
+ * 
+ */
+
+
+export {useAdsRegisterSymbols, useAdsWriteValue, useAdsTapValue} from "./adsHooks";
+export {useScaledValue, kMillimeters2Inches } from './useScaledValue';