@adcops/autocore-react 3.3.84 → 3.3.87

package/src/components/ValueInput.tsx

@@ -2,387 +2,202 @@
  * 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.
+ * `ValueInput` is a React component for numeric entry built on top of
+ * `react-number-format`. It wraps a PrimeReact `InputText` so the field
+ * inherits the standard inputgroup styling and integrates with the
+ * accept/cancel button row below.
  *
- * 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)}
- * />
- * ```
+ * Why react-number-format and not PrimeReact's `InputNumber`:
+ *   - `InputNumber` handles the `-` key via `onKeyDown` (sign-toggle action).
+ *     On Wayland on-screen keyboards (Ubuntu 24 virtual keyboard) keydown is
+ *     not always delivered, so negative entry was broken on touch HMIs.
+ *   - `NumericFormat` treats the input as text and validates it against a
+ *     numeric format. The user can simply type `-`, `2`, `0`, `0` to get
+ *     `-200` on every input device.
  *
- * 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.
+ * Properties:
+ * - `label`: Optional label addon shown before the field.
+ * - `value`: Externally controlled value.
+ * - `min` / `max`: Range validation, applied on accept.
+ * - `minPrecision` / `maxPrecision`: Decimal precision. (Aliases
+ *   `minFractionDigits` / `maxFractionDigits` are also accepted for
+ *   compatibility with older call sites.)
+ * - `prefix` / `suffix`: Inline string before/after the number.
+ * - `description`: Small advisory text below the field.
+ * - `disabled`: Disable all interaction.
+ * - `dispatchTopic`: Topic dispatched on accept via the EventEmitter context.
+ * - `placeholder`: Placeholder when empty.
+ * - `onValueChanged`: Called with the new numeric value when the user accepts.
+ * - `size`: Field width — small (30mm), normal (55mm), large (70mm).
  */
 
-
-import React, { useState, useRef, useEffect, useContext } from 'react';
+import React, { useState, useEffect, useContext } from 'react';
 import clsx from 'clsx';
-import { InputNumber, type InputNumberProps } from 'primereact/inputnumber';
-import { EventEmitterContext } from "../core/EventEmitterContext";
+import { NumericFormat, type NumberFormatValues, type SourceInfo } from 'react-number-format';
+import { InputText } from 'primereact/inputtext';
 import { Button } from 'primereact/button';
+import { EventEmitterContext } from '../core/EventEmitterContext';
 
-import "./ValueInput.css";
+import './ValueInput.css';
 
 export type ValueInputSize = 'small' | 'normal' | 'large';
 
-/**
- * Properties of the ValueInput component.
- */
-interface ValueInputProps extends Omit<InputNumberProps, 'value' | 'size'>  {
-
-    /**
-     * The label for the ValueInput field.
-     */
-    label: React.ReactNode | undefined | null;
-
-
-    /**
-     * The value for the field.
-     */
+export interface ValueInputProps {
+    label?: React.ReactNode | null;
     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.
-     */
+    min?: number;
+    max?: number;
+
+    /** Minimum decimal places displayed. @default 0 */
+    minPrecision?: number;
+    /** Maximum decimal places allowed. @default 3 */
+    maxPrecision?: number;
+
+    /** Alias for `minPrecision` (compat with older call sites). */
+    minFractionDigits?: number;
+    /** Alias for `maxPrecision` (compat with older call sites). */
+    maxFractionDigits?: number;
+
+    prefix?: string;
+    suffix?: string;
+    description?: React.ReactNode;
+    disabled?: boolean;
+    dispatchTopic?: string;
+    placeholder?: string;
     onValueChanged?(newValue: number): void;
-
-    /**
-     * Width of the InputNumber field. The label addon and accept/cancel buttons
-     * keep their natural size; only the numeric input is constrained.
-     * Widths: small=30mm, normal=55mm, large=70mm.
-     * @default 'normal'
-     */
     size?: ValueInputSize;
+    className?: string;
 }
 
-/**
- * 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 = undefined,
+    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,
+    min,
+    max,
+    minPrecision,
+    maxPrecision,
+    minFractionDigits,
+    maxFractionDigits,
+    prefix,
+    suffix,
+    description,
     disabled = false,
-    dispatchTopic = undefined,
-    placeholder = undefined,
-    onValueChanged = undefined,
+    dispatchTopic,
+    placeholder,
+    onValueChanged,
     size = 'normal',
-    ...restProps
+    className,
 }) => {
+    const minDecimals = minPrecision ?? minFractionDigits ?? 0;
+    const maxDecimals = maxPrecision ?? maxFractionDigits ?? 3;
+
     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 [editing, setEditing] = useState(false);
+    const [invalid, setInvalid] = useState(false);
     const eventEmitter = useContext(EventEmitterContext);
 
+    // Sync external value into entryValue when not editing. While editing,
+    // ignore prop updates so we don't yank the rug out from under the user.
     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;
-            }
+            setEntryValue(value);
+            setInvalid(false);
         }
+    }, [value, editing]);
 
+    const validate = (val: number | null): boolean => {
+        if (val === null || Number.isNaN(val)) return false;
+        if (min !== undefined && val < min) return false;
+        if (max !== undefined && val > max) return false;
         return true;
-    }
+    };
 
-    /**
-     * The user has elected to accept the input value. Validate and store, if valid.
-     */
-    const handleAcceptValue = () => {
-        if (editing && entryValue !== null ) {
+    const handleChange = (values: NumberFormatValues, sourceInfo: SourceInfo) => {
+        // NumericFormat fires onValueChange both from user interaction and from
+        // prop-driven re-renders. Only treat user interaction as editing —
+        // otherwise external value changes would falsely flip editing=true.
+        if (sourceInfo.source !== 'event') return;
 
-            if (validateValue(entryValue)) {
-                setCurrentValue(entryValue);
-                setEditing(false);
-                onValueChanged?.(entryValue);
-                setInvalidValue(false);
-    
-                if (dispatchTopic) {
-                    eventEmitter.dispatch({ topic: dispatchTopic, payload: entryValue });
-                }    
-            }
-            else {
-                setInvalidValue(true);
-            }
+        setEntryValue(values.floatValue ?? null);
+        setEditing(true);
+        setInvalid(false);
+    };
 
+    const handleAccept = () => {
+        if (!editing) return;
+        if (!validate(entryValue)) {
+            setInvalid(true);
+            return;
+        }
+        const v = entryValue as number;
+        onValueChanged?.(v);
+        if (dispatchTopic) {
+            eventEmitter.dispatch({ topic: dispatchTopic, payload: v });
         }
+        setEditing(false);
+        setInvalid(false);
     };
 
-    /**
-     * The user wishes to cancel/reset to the previous value.
-     */
-    const handleResetValue = () => {
-        if (editing) {
-            setEntryValue(null);
-            setCurrentValue(null);
-            setEditing(false);
-            setInvalidValue(false);    
-        }        
+    const handleCancel = () => {
+        setEntryValue(value);
+        setEditing(false);
+        setInvalid(false);
     };
 
-    const isLabelDefined = () => {
-        return label !== undefined && label !== null && label !== '';
-    }
+    const isLabelDefined = label !== undefined && label !== null && label !== '';
+    const allowNegative = min === undefined || min < 0;
 
     return (
         <div>
             <div className="p-inputgroup">
-                { isLabelDefined() && 
+                {isLabelDefined && (
                     <span className="p-inputgroup-addon">{label}</span>
-                }                
-                <InputNumber
-                    {...restProps}
-                    ref={inputRef}
-                    className={clsx('value-input-field', `size-${size}`, restProps.className)}
-                    invalid={invalidValue}
-                    min={min}
-                    max={max}                    
-                    minFractionDigits={minPrecision}
-                    maxFractionDigits={maxPrecision}
-                    mode={mode}
+                )}
+                <NumericFormat
+                    value={entryValue ?? ''}
+                    onValueChange={handleChange}
+                    decimalScale={maxDecimals}
+                    fixedDecimalScale={minDecimals > 0 && !editing}
+                    allowNegative={allowNegative}
+                    decimalSeparator="."
+                    thousandSeparator={false}
                     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}
+                    customInput={InputText}
+                    className={clsx(
+                        'value-input-field',
+                        `size-${size}`,
+                        className,
+                    )}
+                    invalid={invalid || undefined}
+                    onKeyDown={(e: React.KeyboardEvent<HTMLInputElement>) => {
+                        if (e.key === 'Enter') handleAccept();
+                        else if (e.key === 'Escape') handleCancel();
+                    }}
                 />
-
                 <Button
                     icon="pi pi-check"
                     disabled={disabled || !editing}
                     className="p-button-success"
-                    onClick={() => handleAcceptValue()}
-                    visible={true}
+                    onClick={handleAccept}
                     autoFocus={false}
                 />
-
                 <Button
                     icon="pi pi-times"
                     disabled={disabled || !editing}
                     className="p-button-danger"
-                    onClickCapture={() => handleResetValue()}
-                    visible={true}
+                    onClick={handleCancel}
                     autoFocus={false}
                 />
-
-
             </div>
             {description && <small>{description}</small>}
         </div>
     );
 };
 
-export default ValueInput;
+export default ValueInput;