@adcops/autocore-react 3.3.8 → 3.3.10

package/src/components/ValueInput.tsx

@@ -1,369 +1,369 @@
-/*
- * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
- * Created Date: 2024-03-20 13:05:42
- * -----
- * Last Modified: 2025-09-05 14:50:52
- * -----
- * 
- */
-
-/** @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, { useState, useRef, useEffect, useContext } from 'react';
-import { InputNumber, type InputNumberProps } from 'primereact/inputnumber';
-import { EventEmitterContext } from "../core/EventEmitterContext";
-import { Button } from 'primereact/button';
-
-/**
- * Properties of the ValueInput component.
- */
-interface ValueInputProps extends Omit<InputNumberProps, 'value'>  {
-
-    /**
-     * The label for the ValueInput field.
-     */
-    label: React.ReactNode | undefined;
-
-
-    /**
-     * The value for the field.
-     */
-    value: number | null;
-
-    /**
-     * Minimum value for the field.
-     */
-    min?: number | undefined;
-
-    /**
-     * Minimum value for the field.
-     */
-    max?: number | undefined;
-
-    /**
-     * Minimum number of decimal points. The user will not
-     * be required to type the decimal values, but this minimum
-     * precision will always be displayed.
-     * Must be less than or equal to maxPrecision, or
-     * the component will throw an error.
-     * @default 0
-     */
-    minPrecision?: number | undefined;
-
-
-    /**
-     * Maximum number of decimal points.
-     * Set to 0 for integer-only. Must be greater or equal to than minPrecision, or
-     * the component will throw an error.
-     * @default 3
-     */
-    maxPrecision?: number | undefined;
-
-
-    /**
-     * Defines the behavior of the component. 
-     * If set to "currency", then you need to specify the
-     * currency type using the currency property.
-     * @default "decimal"
-     */
-    mode?: "currency" | "decimal" | undefined;
-
-
-    /**
-     * The currency to use in currency formatting. Possible values are the 
-     * [ISO 4217 currency codes](https://www.six-group.com/en/products-services/financial-information/data-standards.html#scrollTo=maintenance-agency), 
-     * such as "USD" for the US dollar, "EUR" for the euro, or "CNY" for the Chinese RMB.
-     * If the mode is "currency", the currency property must be provided.
-     * 
-     * @default "USD"
-     */
-    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;
-
-    /**
-     * An optional suffix after the value of the field.
-     * Unlike the TextInput control, this prefix is internal to the field.
-     */
-    suffix?: string | undefined;
-
-    /**
-     * Set true to display buttons to increment/decrement the value.
-     * Use the step property to adjust the amount that the value will change.
-     * 
-     * @default false
-     */
-    showButtons?: boolean;
-
-    /**
-     * The amount clicking an increment/decrement buttion will change the value.
-     */
-    step?: number | undefined;
-
-
-    /**
-     * Locale to be used in formatting. Changes how the numbers/separators are displayed
-     * for international users. The typical locale codes are used.
-     * 
-     * @default "en-US"
-     */
-    locale?: string | undefined;
-
-    /**
-     * A small, advisory text below the field.
-     */
-    description?: React.ReactNode | undefined;
-
-    /**
-     * If true, all functions of the field will be disabled.
-     */
-    disabled?: boolean | undefined;
-
-    /** Topic on which the value will be dispatched through the user interfave on successful data entry. */
-    dispatchTopic?: string | undefined;
-
-    /**
-     * Placeholder string to display if the value is empty.
-     */
-    placeholder?: string | undefined;
-
-    /**
-     * The user has accepted a new value.
-     * @param newValue New value accepted by the user.
-     */
-    onValueChanged?(newValue: number): void;
-}
-
-/**
- * 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 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,
-    ...restProps
-}) => {
-    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);
-        }
-        
-
-    }, [value, currentValue]);
-
-    /**
-     * Buffers the original value, if editing just starting,
-     * and updates the entry value.
-     * 
-     * @param val New value being entered.
-     */
-    const handleBufferValue = (val: number | null) => {
-        if (!editing) {
-            setBufferedValue(currentValue);            
-            setEditing(true);            
-        }        
-        setEntryValue(val);        
-    };
-
-    /**
-     * Returns true if the new value falls within specified parameters.
-     * @param val The new value.
-     * @returns 
-     */
-    const validateValue = (val : number) : boolean => {
-        
-        if (max !== undefined) {
-            if (val > max) {
-                return false;
-            }
-        }
-        if (min !== undefined) {
-            if (val < min) {
-                return false;
-            }
-        }
-
-        return true;
-    }
-
-    /**
-     * The user has elected to accept the input value. Validate and store, if valid.
-     */
-    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 cancel/reset to the previous value.
-     */
-    const handleResetValue = () => {
-        if (editing) {
-            setEntryValue(null);
-            setCurrentValue(null);
-            setEditing(false);
-            setInvalidValue(false);    
-        }        
-    };
-
-    return (
-        <div>
-            <div className="p-inputgroup flex-1">
-                <span className="p-inputgroup-addon">{label}</span>
-                <InputNumber
-                    {...restProps}
-                    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>
-    );
-};
-
+/*
+ * Copyright (C) 2024 Automated Design Corp.. All Rights Reserved.
+ * Created Date: 2024-03-20 13:05:42
+ * -----
+ * Last Modified: 2025-09-05 14:50:52
+ * -----
+ * 
+ */
+
+/** @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, { useState, useRef, useEffect, useContext } from 'react';
+import { InputNumber, type InputNumberProps } from 'primereact/inputnumber';
+import { EventEmitterContext } from "../core/EventEmitterContext";
+import { Button } from 'primereact/button';
+
+/**
+ * Properties of the ValueInput component.
+ */
+interface ValueInputProps extends Omit<InputNumberProps, 'value'>  {
+
+    /**
+     * The label for the ValueInput field.
+     */
+    label: React.ReactNode | undefined;
+
+
+    /**
+     * The value for the field.
+     */
+    value: number | null;
+
+    /**
+     * Minimum value for the field.
+     */
+    min?: number | undefined;
+
+    /**
+     * Minimum value for the field.
+     */
+    max?: number | undefined;
+
+    /**
+     * Minimum number of decimal points. The user will not
+     * be required to type the decimal values, but this minimum
+     * precision will always be displayed.
+     * Must be less than or equal to maxPrecision, or
+     * the component will throw an error.
+     * @default 0
+     */
+    minPrecision?: number | undefined;
+
+
+    /**
+     * Maximum number of decimal points.
+     * Set to 0 for integer-only. Must be greater or equal to than minPrecision, or
+     * the component will throw an error.
+     * @default 3
+     */
+    maxPrecision?: number | undefined;
+
+
+    /**
+     * Defines the behavior of the component. 
+     * If set to "currency", then you need to specify the
+     * currency type using the currency property.
+     * @default "decimal"
+     */
+    mode?: "currency" | "decimal" | undefined;
+
+
+    /**
+     * The currency to use in currency formatting. Possible values are the 
+     * [ISO 4217 currency codes](https://www.six-group.com/en/products-services/financial-information/data-standards.html#scrollTo=maintenance-agency), 
+     * such as "USD" for the US dollar, "EUR" for the euro, or "CNY" for the Chinese RMB.
+     * If the mode is "currency", the currency property must be provided.
+     * 
+     * @default "USD"
+     */
+    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;
+
+    /**
+     * An optional suffix after the value of the field.
+     * Unlike the TextInput control, this prefix is internal to the field.
+     */
+    suffix?: string | undefined;
+
+    /**
+     * Set true to display buttons to increment/decrement the value.
+     * Use the step property to adjust the amount that the value will change.
+     * 
+     * @default false
+     */
+    showButtons?: boolean;
+
+    /**
+     * The amount clicking an increment/decrement buttion will change the value.
+     */
+    step?: number | undefined;
+
+
+    /**
+     * Locale to be used in formatting. Changes how the numbers/separators are displayed
+     * for international users. The typical locale codes are used.
+     * 
+     * @default "en-US"
+     */
+    locale?: string | undefined;
+
+    /**
+     * A small, advisory text below the field.
+     */
+    description?: React.ReactNode | undefined;
+
+    /**
+     * If true, all functions of the field will be disabled.
+     */
+    disabled?: boolean | undefined;
+
+    /** Topic on which the value will be dispatched through the user interfave on successful data entry. */
+    dispatchTopic?: string | undefined;
+
+    /**
+     * Placeholder string to display if the value is empty.
+     */
+    placeholder?: string | undefined;
+
+    /**
+     * The user has accepted a new value.
+     * @param newValue New value accepted by the user.
+     */
+    onValueChanged?(newValue: number): void;
+}
+
+/**
+ * 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 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,
+    ...restProps
+}) => {
+    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);
+        }
+        
+
+    }, [value, currentValue]);
+
+    /**
+     * Buffers the original value, if editing just starting,
+     * and updates the entry value.
+     * 
+     * @param val New value being entered.
+     */
+    const handleBufferValue = (val: number | null) => {
+        if (!editing) {
+            setBufferedValue(currentValue);            
+            setEditing(true);            
+        }        
+        setEntryValue(val);        
+    };
+
+    /**
+     * Returns true if the new value falls within specified parameters.
+     * @param val The new value.
+     * @returns 
+     */
+    const validateValue = (val : number) : boolean => {
+        
+        if (max !== undefined) {
+            if (val > max) {
+                return false;
+            }
+        }
+        if (min !== undefined) {
+            if (val < min) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * The user has elected to accept the input value. Validate and store, if valid.
+     */
+    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 cancel/reset to the previous value.
+     */
+    const handleResetValue = () => {
+        if (editing) {
+            setEntryValue(null);
+            setCurrentValue(null);
+            setEditing(false);
+            setInvalidValue(false);    
+        }        
+    };
+
+    return (
+        <div>
+            <div className="p-inputgroup flex-1">
+                <span className="p-inputgroup-addon">{label}</span>
+                <InputNumber
+                    {...restProps}
+                    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;