@opalkelly/frontpanel-react-components 0.1.0

package/src/primitives/Label/Label.props.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 type LabelVerticalPosition = "top" | "bottom";
+export type LabelHorizontalPosition = "left" | "right";
+
+/**
+ * Interface for the properties of the `Label` component.
+ */
+interface LabelProps extends React.PropsWithChildren<NonNullable<unknown>> {
+    /**
+     * Text to be displayed on the label
+     */
+    text: string;
+
+    /**
+     * Optional CSS class to apply to the label
+     */
+    className?: string;
+
+    /**
+     * Optional horizontal position of the label, defined in LabelHorizontalPosition
+     * @default "left"
+     */
+    horizontalPosition?: LabelHorizontalPosition;
+
+    /**
+     * Optional vertical position of the label, defined in LabelVerticalPosition
+     * @default "top"
+     */
+    verticalPosition?: LabelVerticalPosition;
+}
+
+export default LabelProps;

package/src/primitives/Label/Label.stories.tsx

@@ -0,0 +1,53 @@
+/**
+ * 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 Label from "./Label";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/Label",
+    component: Label,
+    parameters: {
+        layout: "centered" // Center the component in the Canvas
+    },
+    tags: ["autodocs"], // Automatically generate documentation
+    argTypes: {
+        horizontalPosition: {
+            control: "radio",
+            options: ["left", "right"]
+        },
+        verticalPosition: {
+            control: "radio",
+            options: ["top", "bottom"]
+        }
+    }
+} satisfies Meta<typeof Label>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    render: ({ ...args }) => {
+        return (
+            <Label {...args}>
+                <input type="text" />
+            </Label>
+        );
+    },
+    args: {
+        text: "Label Text",
+        // Optional Properties
+        horizontalPosition: "left",
+        verticalPosition: "top"
+    }
+};

package/src/primitives/Label/Label.tsx

@@ -0,0 +1,66 @@
+/**
+ * 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 LabelProps from "./Label.props";
+
+import "../../index.css";
+
+import "./Label.css";
+
+type LabelElement = React.ElementRef<"div">;
+
+/**
+ * `Label` is a React component that renders a label with optional positioning.
+ *
+ * @component
+ * @param {object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the indicator
+ *
+ * @returns {ReactNode} The rendered Label component
+ *
+ * @example
+ * ```jsx
+ * <Label
+ *     text="Label"
+ *     horizontalPosition="left"
+ *     verticalPosition="top">
+ *     <input type="text" />
+ * </Label>
+ * ```
+ */
+const Label = React.forwardRef<LabelElement, LabelProps>((props, forwardedRef) => {
+    const {
+        className,
+        text,
+        horizontalPosition = "left",
+        verticalPosition = "top",
+        children,
+        ...labelProps
+    } = props;
+
+    return (
+        <div
+            {...labelProps}
+            ref={forwardedRef}
+            className={classNames(
+                "okLabel",
+                className,
+                "ok-pos-" + horizontalPosition + "-" + verticalPosition
+            )}>
+            <span className={classNames("okLabelText")}>{text}</span>
+            {children}
+        </div>
+    );
+});
+
+Label.displayName = "Label";
+
+export default Label;

package/src/primitives/Label/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 "./Label";
+
+export { default as LabelProps } from "./Label.props";
+export { LabelHorizontalPosition, LabelVerticalPosition } from "./Label.props";

package/src/primitives/NumberDisplay/NumberDisplay.css

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ */
+
+.okNumberDisplay {
+    /* Layout */
+    display: flex;
+    padding: var(--number-display-padding, 6px 12px);
+    justify-content: flex-end;
+    align-items: center;
+    gap: 4px;
+
+    /* Style */
+    border-radius: 4px;
+    border: 1px solid var(--Gray-2, #d0d7df);
+    background: #f5f5f5;
+
+    /* Content Style */
+    .okNumberDisplayContent {
+        display: flex;
+        padding: var(--spacing-0, 0px);
+        align-items: center;
+        justify-content: flex-end;
+        gap: 8px;
+        flex: 1 0 0;
+    }
+
+    /* Text Style */
+    .okNumberDisplayText {
+        /* Typography */
+        color: var(--Dark, #343434);
+        text-align: center;
+        font-family: Monaco;
+        font-size: var(--number-display-font-size, 12px);
+        font-style: normal;
+        font-weight: 400;
+        line-height: var(--number-display-line-height, 12px); /* 100% */
+    }
+
+    /* Size 1 */
+    &:where(.ok-r-size-1) {
+        --number-display-padding: 6px 6px;
+        --number-display-font-size: 12px;
+        --number-display-line-height: 12px;
+    }
+
+    /* Sizes 2 */
+    &:where(.ok-r-size-2) {
+        --number-display-padding: 6px 10px;
+        --number-display-font-size: 14px;
+        --number-display-line-height: 14px;
+    }
+
+    /* Sizes 3 */
+    &:where(.ok-r-size-3) {
+        --number-display-padding: 6px 18px;
+        --number-display-font-size: 20px;
+        --number-display-line-height: 20px;
+    }
+}

package/src/primitives/NumberDisplay/NumberDisplay.props.ts

@@ -0,0 +1,65 @@
+/**
+ * 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";
+
+export type NumberDisplaySize = 1 | 2 | 3;
+
+/**
+ * Interface for the properties of the `NumberDisplay` component.
+ */
+interface NumberDisplayProps {
+    /**
+     * Current value to be displayed
+     */
+    value: bigint;
+
+    /**
+     * Maximum value that can be displayed
+     */
+    maximumValue: bigint;
+
+    /**
+     * Minimum value that can be displayed
+     */
+    minimumValue: bigint;
+
+    /**
+     * Optional CSS class to apply to the number display
+     */
+    className?: string;
+
+    /**
+     * Optional label properties for the number display
+     */
+    label?: LabelProps;
+
+    /**
+     * Optional size of the number display
+     * @default 1
+     */
+    size?: NumberDisplaySize;
+
+    /**
+     * Optional tooltip text to be displayed on hover
+     */
+    tooltip?: string;
+
+    /**
+     * Optional numeral system to be used for the number display, defined in NumeralSystem
+     */
+    numeralSystem?: NumeralSystem;
+
+    /**
+     * Optional decimal scale for the number entry (Only used when numeral system is NumeralSystem.Decimal)
+     */
+    decimalScale?: number;
+}
+
+export default NumberDisplayProps;

package/src/primitives/NumberDisplay/NumberDisplay.stories.tsx

@@ -0,0 +1,83 @@
+/**
+ * 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 withApplication from "../../stories/decorators/Application.decorator";
+
+import NumberDisplay from "./NumberDisplay";
+
+import { NumeralSystem } from "../../core";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/NumberDisplay",
+    component: NumberDisplay,
+    parameters: {
+        layout: "centered" // Center the component in the Canvas
+    },
+    tags: ["autodocs"], // Automatically generate documentation
+    argTypes: {
+        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" }
+    }
+} satisfies Meta<typeof NumberDisplay>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const convertToBigInt = (value: string) => {
+    return BigInt(value);
+};
+
+// Primary Story
+export const Primary: Story = {
+    decorators: [withApplication],
+    render: (args) => {
+        const { valueString, maximumValueString, minimumValueString } = args;
+
+        const value = convertToBigInt(valueString);
+        const maximum = convertToBigInt(maximumValueString);
+        const minimum = convertToBigInt(minimumValueString);
+
+        return (
+            <NumberDisplay {...args} value={value} maximumValue={maximum} minimumValue={minimum} />
+        );
+    },
+    args: {
+        valueString: "8000",
+        maximumValueString: "1000000",
+        minimumValueString: "-1000000",
+        // Optional Properties
+        numeralSystem: NumeralSystem.Decimal,
+        decimalScale: 3,
+        label: {
+            text: "Decimal Value",
+            verticalPosition: "top",
+            horizontalPosition: "left"
+        },
+        size: 1,
+        tooltip: "Set the decimal value"
+    }
+};

package/src/primitives/NumberDisplay/NumberDisplay.tsx

@@ -0,0 +1,155 @@
+/**
+ * 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 NumberDisplayProps from "./NumberDisplay.props";
+
+import "../../index.css";
+
+import "./NumberDisplay.css";
+
+import Label from "../Label";
+
+import { withTooltip } from "../TooltipUtility";
+
+import { NumeralSystem, NumericDigits } from "../../core";
+
+function FormatValueString(
+    value: bigint | null,
+    digitCount: bigint,
+    numeralSystem: NumeralSystem,
+    decimalScale: number
+): string {
+    let retval: string;
+
+    if (value != null) {
+        const outputValue: bigint = value >= 0n ? value : -value;
+        const outputDigitCount: number = Number(digitCount);
+
+        const outputValueStr: string = outputValue
+            .toString(numeralSystem)
+            .padStart(outputDigitCount, "0");
+
+        if (numeralSystem === NumeralSystem.Decimal && decimalScale > 0) {
+            const integerDigitCount: number = outputDigitCount - decimalScale;
+
+            if (integerDigitCount > 0) {
+                retval =
+                    outputValueStr.slice(0, integerDigitCount) +
+                    "." +
+                    outputValueStr.slice(integerDigitCount);
+            } else {
+                const prefixString: string = "0.";
+                const paddedPrefixString = prefixString.padEnd(
+                    prefixString.length - integerDigitCount,
+                    "0"
+                );
+
+                retval = paddedPrefixString + outputValueStr;
+            }
+        } else {
+            retval = outputValueStr;
+        }
+    } else {
+        retval = "Error"; //ERROR: Value is null
+    }
+
+    return retval;
+}
+
+type NumberDisplayElement = React.ElementRef<"div">;
+
+/**
+ * `NumberDisplay` is a React component that renders a number represented in binary, octal,
+ * decimal, or hexadecimal numeral systems with optional tooltip. It also allows to
+ * optionally set the decimal scale of the number when using the decimal numeral system.
+ *
+ * @component
+ * @param {object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the NumberDisplay
+ * @returns {React.Node} The rendered NumberDisplay component
+ *
+ * @example
+ * ```jsx
+ * <NumberDisplay
+ *    label="Number Display"
+ *    value={23456}
+ *    maximumValue={65535}
+ *    minimumValue={0} />
+ * ```
+ */
+const NumberDisplay = React.forwardRef<NumberDisplayElement, NumberDisplayProps>(
+    (props, forwardedRef) => {
+        const {
+            className,
+            label,
+            size = 1,
+            numeralSystem = NumeralSystem.Decimal,
+            decimalScale = 0,
+            maximumValue,
+            minimumValue,
+            value
+        } = props;
+
+        const digitCount: bigint = React.useMemo(() => {
+            const maximumValueDigitCount: bigint = NumericDigits.ComputeDigitCountFromValue(
+                maximumValue,
+                numeralSystem
+            );
+            const minimumValueDigitCount: bigint = NumericDigits.ComputeDigitCountFromValue(
+                minimumValue,
+                numeralSystem
+            );
+
+            const maximumDigitCount: bigint =
+                maximumValueDigitCount > minimumValueDigitCount
+                    ? maximumValueDigitCount
+                    : minimumValueDigitCount;
+
+            return maximumDigitCount;
+        }, [maximumValue, minimumValue, numeralSystem]);
+
+        const negativeSign = React.useMemo(
+            () => <span className={classnames("okNumberDisplayText", "ok-r-size-" + size)}>-</span>,
+            [size]
+        );
+
+        const NumberDisplayWithTooltip = withTooltip(
+            <div
+                ref={forwardedRef}
+                className={classnames("okNumberDisplay", className, "ok-r-size-" + size)}>
+                <div className="okNumberDisplayContent">
+                    {value < 0n && negativeSign}
+                    <span className="okNumberDisplayText">
+                        {FormatValueString(value, digitCount, numeralSystem, decimalScale)}
+                    </span>
+                </div>
+            </div>
+        );
+
+        const showLabel = label != null;
+
+        if (showLabel) {
+            return (
+                <Label {...label}>
+                    <div style={{ width: "100%" }}>
+                        <NumberDisplayWithTooltip {...props} />
+                    </div>
+                </Label>
+            );
+        } else {
+            <NumberDisplayWithTooltip {...props} />;
+        }
+    }
+);
+
+NumberDisplay.displayName = "NumberDisplay";
+
+export default NumberDisplay;

package/src/primitives/NumberDisplay/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 "./NumberDisplay";
+
+export { default as NumberDisplayProps } from "./NumberDisplay.props";
+export { NumberDisplaySize } from "./NumberDisplay.props";

package/src/primitives/NumberEntry/NumberEntry.css

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+
+.okNumberEntry {
+    /* Layout */
+    display: flex;
+    padding: var(--number-entry-padding, 6px);
+    justify-content: flex-end;
+    align-items: center;
+
+    /* Style */
+    border-radius: 4px;
+    border: 1px solid var(--brand-12, #44bd84);
+    background: var(--Light, #fff);
+
+    /* Content Style */
+    .okNumberEntryContent {
+        display: flex;
+        height: auto; /*32px;*/
+        justify-content: flex-end;
+        align-items: center;
+        gap: var(--spacing-0, 0px);
+        align-self: stretch;
+    }
+
+    /* Text Style */
+    .okNumberEntryText {
+        /* Typography */
+        color: var(--Dark, #343434);
+        text-align: center;
+        font-family: Monaco;
+        font-size: var(--number-entry-font-size, 12px);
+        font-style: normal;
+        font-weight: 400;
+        line-height: var(--number-entry-line-height, 12px); /* 100% */
+        letter-spacing: 1.26px;
+    }
+
+    /* Size 1 */
+    &:where(.ok-r-size-1) {
+        --number-entry-padding: 1px 6px;
+        --number-entry-font-size: 12px;
+        --number-entry-line-height: 12px;
+    }
+
+    /* Sizes 2 */
+    &:where(.ok-r-size-2) {
+        --number-entry-padding: 1px 10px;
+        --number-entry-font-size: 14px;
+        --number-entry-line-height: 14px;
+    }
+
+    /* Sizes 3 */
+    &:where(.ok-r-size-3) {
+        --number-entry-padding: 1px 18px;
+        --number-entry-font-size: 20px;
+        --number-entry-line-height: 20px;
+    }
+}
+
+.okNumberEntry[data-disabled="true"] {
+    border: 1px solid var(--Gray-2, #d0d7df);
+    opacity: 0.5;
+    background: var(--Gray-3, #e7ebef);
+
+    pointer-events: none;
+}