@opalkelly/frontpanel-react-components 0.1.0

package/src/primitives/NumberEntry/NumberEntry.props.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2024 Opal Kelly Incorporated
+ *
+ * This source code is licensed under the FrontPanel license.
+ * See the LICENSE file found in the root directory of this project.
+ */
+
+import { NumeralSystem } from "../../core";
+
+import { LabelProps } from "../Label";
+
+import { DigitEntryVariant } from "../DigitEntry";
+
+export type NumberEntrySize = 1 | 2 | 3;
+export type NumberEntryValueChangeEventHandler = (value: bigint) => void;
+
+/**
+ * Interface for the properties of the `NumberEntry` component.
+ */
+interface NumberEntryProps {
+    /**
+     * Current value of the number entry
+     */
+    value: bigint;
+
+    /**
+     * Maximum value that can be entered
+     */
+    maximumValue: bigint;
+
+    /**
+     * Minimum value that can be entered
+     */
+    minimumValue: bigint;
+
+    /**
+     * Optional CSS class to apply to the number entry
+     */
+    className?: string;
+
+    /**
+     * Optional decimal scale for the number entry (Only used when numeral system is NumeralSystem.Decimal)
+     */
+    decimalScale?: number;
+
+    /**
+     * Optional disable the number entry
+     * @default false
+     */
+    disabled?: boolean;
+
+    /**
+     * Optional label properties for the number entry
+     */
+    label?: LabelProps;
+
+    /**
+     * Optional numeral system to be used for the number entry, defined in NumeralSystem
+     * @default Decimal
+     */
+    numeralSystem?: NumeralSystem;
+
+    /**
+     * Optional Size of the number entry
+     * @default 1
+     */
+    size?: NumberEntrySize;
+
+    /**
+     * Optional tooltip text to be displayed on hover
+     */
+    tooltip?: string;
+
+    /**
+     * Optional variant of the digit entry
+     * @default standard
+     */
+    variant?: DigitEntryVariant;
+
+    /**
+     * Optional event handler for the value changed event
+     */
+    onValueChange?: NumberEntryValueChangeEventHandler;
+}
+
+export default NumberEntryProps;

package/src/primitives/NumberEntry/NumberEntry.stories.tsx

@@ -0,0 +1,129 @@
+/**
+ * Copyright (c) 2024 Opal Kelly Incorporated
+ *
+ * This source code is licensed under the FrontPanel license.
+ * See the LICENSE file found in the root directory of this project.
+ */
+
+import React from "react";
+
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { useArgs } from "@storybook/preview-api";
+
+import withApplication from "../../stories/decorators/Application.decorator";
+
+import NumberEntry from "./NumberEntry";
+
+import { NumeralSystem } from "../../core";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/NumberEntry",
+    component: NumberEntry,
+    parameters: {
+        layout: "centered" // Center the component in the Canvas
+    },
+    tags: ["autodocs"], // Automatically generate documentation
+    argTypes: {
+        variant: {
+            control: "radio",
+            options: ["standard", "compact"]
+        },
+        disabled: { control: "boolean" },
+        size: {
+            control: { type: "range", min: 1, max: 3, step: 1 }
+        },
+        numeralSystem: {
+            control: "radio",
+            options: ["Decimal", "Hexadecimal", "Binary", "Octal"],
+            mapping: {
+                Decimal: NumeralSystem.Decimal,
+                Hexadecimal: NumeralSystem.Hexadecimal,
+                Binary: NumeralSystem.Binary,
+                Octal: NumeralSystem.Octal
+            }
+        },
+        valueString: { control: "text" },
+        maximumValueString: { control: "text" },
+        minimumValueString: { control: "text" },
+        // Disable event callback arguments
+        onValueChange: {
+            control: { disable: true }
+        }
+    }
+} satisfies Meta<typeof NumberEntry>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const convertToBigInt = (value: string) => {
+    return BigInt(value);
+};
+
+// Template for Stories
+const ComponentTemplate: Story = {
+    render: (args) => {
+        const [{ valueString }, updateArgs] = useArgs();
+
+        const { maximumValueString, minimumValueString } = args;
+
+        const value = convertToBigInt(valueString);
+        const maximum = convertToBigInt(maximumValueString);
+        const minimum = convertToBigInt(minimumValueString);
+
+        function onValueChange(value: bigint): void {
+            updateArgs({ valueString: value.toString() });
+        }
+
+        return (
+            <NumberEntry
+                {...args}
+                value={value}
+                maximumValue={maximum}
+                minimumValue={minimum}
+                onValueChange={onValueChange}
+            />
+        );
+    },
+    decorators: [withApplication],
+    args: {
+        variant: "standard",
+        disabled: false,
+        label: {
+            text: "Value",
+            verticalPosition: "top",
+            horizontalPosition: "left"
+        },
+        size: 1,
+        tooltip: "Set the value",
+        numeralSystem: NumeralSystem.Decimal,
+        decimalScale: 3,
+        valueString: "8000",
+        maximumValueString: "1000000",
+        minimumValueString: "-1000000"
+    }
+};
+
+// Primary Story
+export const Decimal: Story = {
+    ...ComponentTemplate,
+    args: {
+        valueString: "8000",
+        maximumValueString: "1000000",
+        minimumValueString: "-1000000",
+        // Optional Properties
+        disabled: false,
+        variant: "standard",
+        numeralSystem: NumeralSystem.Decimal,
+        decimalScale: 3,
+        size: 1,
+        label: {
+            text: "Decimal Value",
+            verticalPosition: "top",
+            horizontalPosition: "left"
+        },
+        tooltip: "Set the decimal value"
+    }
+};

package/src/primitives/NumberEntry/NumberEntry.tsx

@@ -0,0 +1,249 @@
+/**
+ * Copyright (c) 2024 Opal Kelly Incorporated
+ *
+ * This source code is licensed under the FrontPanel license.
+ * See the LICENSE file found in the root directory of this project.
+ */
+
+import React from "react";
+
+import classnames from "classnames";
+
+import NumberEntryProps, { NumberEntrySize } from "./NumberEntry.props";
+
+import "../../index.css";
+
+import "./NumberEntry.css";
+
+import NumberEntryDigits from "./NumberEntryDigits";
+
+import { DigitEntryState } from "./NumberEntryDigits.props";
+
+import { NumeralSystem, NumericDigits } from "../../core";
+
+import Label from "../Label";
+import Tooltip from "../Tooltip";
+
+type NumberEntryElement = React.ElementRef<"div">;
+
+/**
+ * `NumberEntry` is a React component that renders a number entry field to allow setting the value of a number
+ * represented in binary, octal, decimal, or hexadecimal numeral systems. The values of the individual digits of
+ * the number can be entered by key or they can incremented and decremented using the up and down arrow keys and or
+ * the mouse wheel. The maximum and minimum values of the number can be specified to limit the range of values that
+ * that can be set. Each individual digit shows an indicator to show if the value of that digit can be incremented
+ * or decremented based on the maximum and minimum values.
+ *
+ * @component
+ * @param {Object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the number display
+ *
+ * @returns {React.Node} The rendered NumberEntry component.
+ *
+ * @example
+ * ```jsx
+ * <NumberEntry
+ *     value={0}
+ *     maximumValue={65535}
+ *     minimumValue={0} />
+ * ```
+ */
+const NumberEntry = React.forwardRef<NumberEntryElement, NumberEntryProps>(
+    (props, forwardedRef) => {
+        const { label, tooltip, ...sliderProps } = props;
+
+        const showLabel = label != null;
+        const showTooltip = tooltip != null;
+
+        if (showLabel && showTooltip) {
+            return (
+                <Label {...label}>
+                    <Tooltip content={tooltip}>
+                        <div style={{ width: "100%" }}>
+                            <NumberEntryImpl ref={forwardedRef} {...sliderProps} />
+                        </div>
+                    </Tooltip>
+                </Label>
+            );
+        } else if (showLabel) {
+            return (
+                <Label {...label}>
+                    <div style={{ width: "100%" }}>
+                        <NumberEntryImpl ref={forwardedRef} {...sliderProps} />
+                    </div>
+                </Label>
+            );
+        } else if (showTooltip) {
+            return (
+                <Tooltip content={tooltip}>
+                    <div>
+                        <NumberEntryImpl ref={forwardedRef} {...sliderProps} />
+                    </div>
+                </Tooltip>
+            );
+        } else {
+            return <NumberEntryImpl ref={forwardedRef} {...sliderProps} />;
+        }
+    }
+);
+
+NumberEntry.displayName = "NumberEntry";
+
+export default NumberEntry;
+
+interface NumberEntryImplProps
+    extends Omit<React.ComponentPropsWithoutRef<typeof NumberEntry>, "label" | "tooltip"> {}
+
+const NumberEntryImpl = React.forwardRef<NumberEntryElement, NumberEntryImplProps>(
+    (props, forwardedRef) => {
+        const {
+            className,
+            variant = "standard",
+            size = 1,
+            disabled = false,
+            numeralSystem = NumeralSystem.Decimal,
+            decimalScale = 0,
+            maximumValue,
+            minimumValue,
+            value,
+            onValueChange
+        } = props;
+
+        const digitCount: number = React.useMemo(() => {
+            const maximumValueDigitCount: bigint = NumericDigits.ComputeDigitCountFromValue(
+                maximumValue,
+                numeralSystem
+            );
+            const minimumValueDigitCount: bigint = NumericDigits.ComputeDigitCountFromValue(
+                minimumValue,
+                numeralSystem
+            );
+
+            const maximumDigitCount: bigint =
+                maximumValueDigitCount > minimumValueDigitCount
+                    ? maximumValueDigitCount
+                    : minimumValueDigitCount;
+
+            return Number(maximumDigitCount);
+        }, [maximumValue, minimumValue, numeralSystem]);
+
+        const radix: bigint = BigInt(numeralSystem);
+
+        const digitStates: DigitEntryState[] = ComputeDigitStatesFromValue(
+            value,
+            maximumValue,
+            minimumValue,
+            radix,
+            digitCount
+        );
+
+        const onDigitStatesChange = (
+            newDigitStates: readonly DigitEntryState[],
+            _isKeyDown: boolean
+        ) => {
+            let newValue: bigint = ComputeValueFromDigitStates(newDigitStates, radix);
+
+            const crossedZero: boolean = newValue >= 0n !== value >= 0n && newValue !== 0n;
+
+            if (crossedZero) {
+                newValue += 2n * -value;
+            }
+
+            //console.log("onDigitStatesChange: Value:" + value + "=>" + newValue);
+
+            if (newValue <= maximumValue && newValue >= minimumValue) {
+                onValueChange?.(newValue);
+            }
+        };
+
+        const NegativeSign = (size: NumberEntrySize): JSX.Element => (
+            <span className={classnames("okNumberEntryText", "ok-r-size-" + size)}>-</span>
+        );
+
+        return (
+            <div
+                ref={forwardedRef}
+                className={classnames("okNumberEntry", className, "ok-r-size-" + size)}
+                data-disabled={disabled || undefined}>
+                <div className="okNumberEntryContent">
+                    {value < 0n && NegativeSign(size)}
+                    <NumberEntryDigits
+                        variant={variant}
+                        size={size}
+                        numeralSystem={numeralSystem}
+                        decimalScale={decimalScale}
+                        digitStates={digitStates}
+                        onDigitStatesChange={onDigitStatesChange}
+                    />
+                </div>
+            </div>
+        );
+    }
+);
+
+NumberEntryImpl.displayName = "NumberEntryImpl";
+
+const ComputeValueFromDigitStates = (
+    digitStates: readonly DigitEntryState[],
+    radix: bigint
+): bigint => {
+    const digitCount: number = digitStates.length;
+
+    const startDigitIndex: number = digitCount - 1;
+
+    let numericValue: bigint = BigInt(digitStates[startDigitIndex].value);
+
+    for (let digitIndex: number = startDigitIndex - 1; digitIndex >= 0; digitIndex--) {
+        numericValue = numericValue * radix + BigInt(digitStates[digitIndex].value);
+    }
+
+    return numericValue;
+};
+
+const ComputeDigitStatesFromValue = (
+    value: bigint,
+    maximum: bigint,
+    minimum: bigint,
+    radix: bigint,
+    digitCount: number
+): DigitEntryState[] => {
+    const retval: DigitEntryState[] = [];
+
+    let currentValue: bigint = value;
+    let currentMaxDifference: bigint = maximum - value;
+    let currentMinDifference: bigint = minimum - value;
+
+    for (let digitIndex: number = 0; digitIndex < digitCount; digitIndex++) {
+        const digitValue: number = Number(currentValue % radix);
+        const digitMaximum: number = Math.floor(Number(currentMaxDifference + BigInt(digitValue)));
+        const digitMinimum: number = Math.ceil(Number(currentMinDifference + BigInt(digitValue)));
+
+        retval[digitIndex] = {
+            id: digitIndex,
+            value: digitValue,
+            maximum: ComputeDigitLimitValue(digitMaximum, Number(radix)),
+            minimum: ComputeDigitLimitValue(digitMinimum, Number(radix))
+        };
+
+        currentValue = currentValue / radix;
+        currentMaxDifference = currentMaxDifference / radix;
+        currentMinDifference = currentMinDifference / radix;
+    }
+
+    return retval;
+};
+
+const ComputeDigitLimitValue = (
+    digitValueDifference: number,
+    radix: number
+): number | undefined => {
+    let retval: number | undefined;
+
+    if (digitValueDifference >= 0) {
+        retval = digitValueDifference < radix ? digitValueDifference : undefined;
+    } else {
+        retval = digitValueDifference > -radix ? digitValueDifference : undefined;
+    }
+
+    return retval;
+};

package/src/primitives/NumberEntry/NumberEntryDigits.props.ts

@@ -0,0 +1,57 @@
+/**
+ * Copyright (c) 2024 Opal Kelly Incorporated
+ *
+ * This source code is licensed under the FrontPanel license.
+ * See the LICENSE file found in the root directory of this project.
+ */
+
+import { NumeralSystem } from "../../core";
+
+import { DigitEntryVariant } from "../DigitEntry";
+
+export type DigitEntrySize = 1 | 2 | 3;
+export type DigitEntryStatesChangeEventHandler = (
+    digitStates: readonly DigitEntryState[],
+    isKeyDown: boolean
+) => void;
+
+export type DigitEntryState = {
+    id: number;
+    value: number;
+    maximum?: number;
+    minimum?: number;
+};
+
+interface NumberEntryDigitsProps {
+    /**
+     * Variant of the digit entry
+     */
+    variant?: DigitEntryVariant;
+
+    /**
+     * Size of the digit entry
+     */
+    size: DigitEntrySize;
+
+    /**
+     * Numeral system to be used for the number entry, defined in NumeralSystem enum
+     */
+    numeralSystem: NumeralSystem;
+
+    /**
+     * Current value of the number entry
+     */
+    digitStates: DigitEntryState[];
+
+    /**
+     * Optional decimal scale for the number entry (Only used when numeral system is NumeralSystem.Decimal)
+     */
+    decimalScale?: number;
+
+    /**
+     * Event handler for the number entries state change event
+     */
+    onDigitStatesChange?: DigitEntryStatesChangeEventHandler;
+}
+
+export default NumberEntryDigitsProps;

package/src/primitives/NumberEntry/NumberEntryDigits.tsx

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) 2024 Opal Kelly Incorporated
+ *
+ * This source code is licensed under the FrontPanel license.
+ * See the LICENSE file found in the root directory of this project.
+ */
+
+import React from "react";
+
+import classnames from "classnames";
+
+import NumberEntryDigitsProps from "./NumberEntryDigits.props";
+
+import "../../index.css";
+
+import "./NumberEntry.css";
+
+import DigitEntry from "../DigitEntry";
+
+import { NumeralSystem } from "../../core";
+
+/**
+ * `NumberEntryDigits` is a React component that renders a list of `DigitEntry` components.
+ * Each `DigitEntry` represents a digit in a number entry field.
+ * The digits are displayed in the specified numeral system and can be incremented and decremented.
+ *
+ * @component
+ * @param {Object} props - The properties that define the `NumberEntryDigits` component.
+ * @param {number} props.size - The size of the digits in the number entry field. Default is 1.
+ * @param {number} props.numeralSystem - The numeral system to use for displaying the digits.
+ * @param {number} props.decimalScale - The scale of the decimal part of the number entry field. Default is 0.
+ * @param {Array} props.digitStates - An array of objects that represent the state of each digit in the number entry field.
+ * @param {function} props.onDigitStatesChange - Function to be called when the state of any digit in the number entry field changes.
+ *
+ * @returns {React.ReactElement} The `NumberEntryDigits` component.
+ */
+const NumberEntryDigits: React.FC<NumberEntryDigitsProps> = (props) => {
+    const {
+        variant = "standard",
+        size = 1,
+        numeralSystem,
+        decimalScale = 0,
+        digitStates,
+        onDigitStatesChange
+    } = props;
+
+    const digitListItems = (): JSX.Element[] => {
+        const digitEntries = digitStates.map((digitState, digitIndex) => {
+            const onDigitValueChanged = (value: number, isKeyDown: boolean) => {
+                //console.log("onDigitValueChanged: " + "[" + digitIndex + "], " + value + ", isKeyDown: " + isKeyDown);
+
+                //console.log("oldDigitStates: " + JSON.stringify(digitStates));
+
+                const newDigitStates = [...digitStates];
+                newDigitStates[digitIndex] = {
+                    ...digitStates[digitIndex],
+                    value: value
+                };
+
+                //console.log("newDigitStates: " + JSON.stringify(newDigitStates));
+
+                onDigitStatesChange?.(newDigitStates, isKeyDown);
+            };
+
+            return (
+                <DigitEntry
+                    key={"digit-" + digitState.id}
+                    variant={variant}
+                    size={size}
+                    numeralSystem={numeralSystem}
+                    value={digitState.value}
+                    maximum={digitState.maximum}
+                    minimum={digitState.minimum}
+                    onValueChanged={onDigitValueChanged}
+                />
+            );
+        });
+
+        if (numeralSystem === NumeralSystem.Decimal && decimalScale > 0) {
+            const excessDecimalScale: number = decimalScale - digitEntries.length;
+
+            if (excessDecimalScale < 0) {
+                digitEntries.splice(
+                    decimalScale,
+                    0,
+                    <span
+                        key={"digit-decimal-point"}
+                        className={classnames("okNumberEntryText", "ok-r-size-" + size)}>
+                        .
+                    </span>
+                );
+            } else {
+                const prefixString: string = "0.";
+                const paddedPrefixString = prefixString.padEnd(
+                    prefixString.length + excessDecimalScale,
+                    "0"
+                );
+
+                digitEntries.push(
+                    <span
+                        key={"digit-decimal-prefix"}
+                        className={classnames("okNumberEntryText", "ok-r-size-" + size)}>
+                        {paddedPrefixString}
+                    </span>
+                );
+            }
+        }
+
+        return digitEntries.reverse();
+    };
+
+    return <>{digitListItems()}</>;
+};
+
+NumberEntryDigits.displayName = "NumberEntryDigits";
+
+export default NumberEntryDigits;

package/src/primitives/NumberEntry/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2024 Opal Kelly Incorporated
+ *
+ * This source code is licensed under the FrontPanel license.
+ * See the LICENSE file found in the root directory of this project.
+ */
+
+export { default } from "./NumberEntry";
+
+export { default as NumberEntryProps } from "./NumberEntry.props";
+export { NumberEntrySize, NumberEntryValueChangeEventHandler } from "./NumberEntry.props";