@opalkelly/frontpanel-react-components 0.1.0

package/src/primitives/DigitEntry/DigitEntry.props.ts

@@ -0,0 +1,62 @@
+/**
+ * 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";
+
+export type DigitEntryVariant = "standard" | "compact";
+export type DigitEntrySize = 1 | 2 | 3;
+export type DigitEntryValueChangeEventHandler = (value: number, isKeyDown: boolean) => void;
+
+/**
+ * Interface for the properties of the `DigitEntry` component.
+ */
+interface DigitEntryProps {
+    /**
+     * The current value of the digit entry
+     */
+    value: number;
+
+    /**
+     * Optional CSS class to apply to the digit entry
+     */
+    className?: string;
+
+    /**
+     * The maximum value that the digit entry can have
+     */
+    maximum?: number;
+
+    /**
+     * The minimum value that the digit entry can have
+     */
+    minimum?: number;
+
+    /**
+     * The numeral system for the digit entry
+     * @default Decimal
+     */
+    numeralSystem?: NumeralSystem;
+
+    /**
+     * Size of the digit entry
+     * @default 1
+     */
+    size?: DigitEntrySize;
+
+    /**
+     * Variant of the digit entry
+     * @default standard
+     */
+    variant?: DigitEntryVariant;
+
+    /**
+     * Optional event handler for the value changed event
+     */
+    onValueChanged?: DigitEntryValueChangeEventHandler;
+}
+
+export default DigitEntryProps;

package/src/primitives/DigitEntry/DigitEntry.stories.tsx

@@ -0,0 +1,84 @@
+/**
+ * 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 DigitEntry from "./DigitEntry";
+
+import { NumeralSystem } from "../../core";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/DigitEntry",
+    component: DigitEntry,
+    parameters: {
+        layout: "centered" // Center the component in the Canvas
+    },
+    tags: ["autodocs"], // Automatically generate documentation
+    argTypes: {
+        variant: {
+            control: "radio",
+            options: ["standard", "compact"]
+        },
+        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
+            }
+        },
+        value: {
+            control: { type: "number", step: 1 }
+        },
+        maximum: {
+            control: { type: "number", step: 1 }
+        },
+        minimum: {
+            control: { type: "number", step: 1 }
+        },
+        // Disable event callback arguments
+        onValueChanged: {
+            control: { disable: true }
+        }
+    }
+} satisfies Meta<typeof DigitEntry>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    render: (args) => {
+        const [{ value }, updateArgs] = useArgs();
+
+        function onValueChanged(value: number, _isKeyDown: boolean): void {
+            updateArgs({ value: value });
+        }
+
+        return <DigitEntry {...args} value={value} onValueChanged={onValueChanged} />;
+    },
+    args: {
+        value: 8,
+        // Optional Properties
+        size: 1,
+        numeralSystem: NumeralSystem.Decimal,
+        variant: "standard",
+        maximum: undefined,
+        minimum: undefined
+    }
+};

package/src/primitives/DigitEntry/DigitEntry.tsx

@@ -0,0 +1,226 @@
+/**
+ * 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 { IndicatorArrowIcon, IndicatorArrowDirection } from "../../components/Icons";
+import { IndicatorBarIcon } from "../../components/Icons";
+
+import DigitEntryProps from "./DigitEntry.props";
+
+import "../../index.css";
+
+import "./DigitEntry.css";
+
+import { NumeralSystem } from "../../core";
+
+type DigitEntryElement = React.ElementRef<"div">;
+
+/**
+ * `DigitEntry` is a React component that renders a digit entry field to allow setting the value of the digit represented
+ * in binary, octal, decimal, or hexadecimal number systems. The value of the digit can be entered by key or the current
+ * value can be incremented or decremented using the up and down arrow keys and or the mouse wheel. A maximum and minimum
+ * value can be specified to limit the range of values that the digit entry field can have. Indicators are displayed to
+ * show when the value can be incremented or decremented based on the maximum and minimum values.
+ *
+ * @component
+ * @param {Object} props - Properties passed to component
+ * @param {React.Ref<DigitEntryElement>} forwardedRef - Forwarded ref for the number display
+ *
+ * @returns {React.ReactElement} The rendered DigitEntry component
+ *
+ * @example
+ * ```jsx
+ * <DigitEntry
+ *     value={0}
+ *     maximum={5}
+ *     minimum={2} />
+ * ```
+ */
+const DigitEntry: React.FC<DigitEntryProps> = (props) => {
+    const digitEntryRef = React.useRef<DigitEntryElement>(null);
+
+    const {
+        className,
+        variant = "standard",
+        size = 1,
+        value,
+        maximum,
+        minimum,
+        numeralSystem = NumeralSystem.Decimal,
+        onValueChanged
+    } = props;
+
+    const valueRef = React.useRef(value);
+
+    valueRef.current = props.value;
+
+    const valueChangedRef = React.useRef(onValueChanged);
+
+    valueChangedRef.current = onValueChanged;
+
+    const onDigitKeyboardEventHandler = (event: React.KeyboardEvent<HTMLDivElement>) => {
+        let isHandled: boolean = false;
+
+        switch (event.key) {
+            case "ArrowUp":
+                onValueChanged?.(value + 1, false);
+                isHandled = true;
+                break;
+            case "ArrowDown":
+                onValueChanged?.(value - 1, false);
+                isHandled = true;
+                break;
+            case "ArrowRight":
+                {
+                    const nextElement: HTMLDivElement | null = event.currentTarget
+                        .nextElementSibling as HTMLDivElement;
+                    nextElement?.focus();
+                    isHandled = true;
+                }
+                break;
+            case "ArrowLeft":
+                {
+                    const previousElement: HTMLDivElement | null = event.currentTarget
+                        .previousElementSibling as HTMLDivElement;
+                    previousElement?.focus();
+                    isHandled = true;
+                }
+                break;
+            default:
+                isHandled = false;
+                break;
+        }
+
+        if (isHandled) {
+            event.stopPropagation();
+            event.preventDefault();
+        } else {
+            const numericValue: number = parseInt(event.key, numeralSystem);
+
+            if (!Number.isNaN(numericValue)) {
+                onValueChanged?.(numericValue, true);
+
+                const nextElement: HTMLDivElement | null = event.currentTarget
+                    .nextElementSibling as HTMLDivElement;
+
+                nextElement?.focus();
+            }
+        }
+    };
+
+    React.useEffect(() => {
+        const onDigitMouseWheelEventHandler = (event: WheelEvent) => {
+            if (event.deltaY < 0) {
+                valueChangedRef.current?.(valueRef.current + 1, false);
+
+                event.stopPropagation();
+                event.preventDefault();
+            } else if (event.deltaY > 0) {
+                valueChangedRef.current?.(valueRef.current - 1, false);
+
+                event.stopPropagation();
+                event.preventDefault();
+            }
+        };
+
+        digitEntryRef.current?.addEventListener("wheel", onDigitMouseWheelEventHandler, {
+            passive: false
+        });
+
+        return () => {
+            digitEntryRef.current?.removeEventListener("wheel", onDigitMouseWheelEventHandler);
+        };
+    }, [digitEntryRef]);
+
+    const canIncrement = maximum != null ? value < maximum : true;
+    const canDecrement = minimum != null ? value > minimum : true;
+
+    const DigitEntryIncrementIndicator = (): React.ReactNode => {
+        let indicator: React.ReactNode;
+
+        switch (variant) {
+            case "standard":
+                indicator = (
+                    <IndicatorArrowIcon
+                        className={classNames("okDigitEntryIncrementIndicator")}
+                        direction={IndicatorArrowDirection.Up}
+                        color="#343434"
+                        data-enabled={canIncrement}
+                    />
+                );
+                break;
+            case "compact":
+                indicator = (
+                    <IndicatorBarIcon
+                        className={classNames("okDigitEntryIncrementIndicator")}
+                        color="#343434"
+                        data-enabled={canIncrement}
+                    />
+                );
+                break;
+            default:
+                indicator = null;
+                break;
+        }
+
+        return indicator;
+    };
+
+    const DigitEntryDecrementIndicator = (): React.ReactNode => {
+        let indicator: React.ReactNode;
+
+        switch (variant) {
+            case "standard":
+                indicator = (
+                    <IndicatorArrowIcon
+                        className={classNames("okDigitEntryDecrementIndicator")}
+                        direction={IndicatorArrowDirection.Down}
+                        color="#343434"
+                        data-enabled={canDecrement}
+                    />
+                );
+                break;
+            case "compact":
+                indicator = (
+                    <IndicatorBarIcon
+                        className={classNames("okDigitEntryDecrementIndicator")}
+                        color="#343434"
+                        data-enabled={canDecrement}
+                    />
+                );
+                break;
+            default:
+                indicator = null;
+                break;
+        }
+
+        return indicator;
+    };
+
+    return (
+        <div
+            className={classNames("okDigitEntry", className, "ok-r-size-" + size)}
+            ref={digitEntryRef}
+            tabIndex={-1}
+            onMouseEnter={(e) => e.currentTarget.focus()}
+            onMouseLeave={(e) => e.currentTarget.blur()}
+            onKeyDown={onDigitKeyboardEventHandler}>
+            <DigitEntryIncrementIndicator />
+            <div className={classNames("okDigitEntryContent", "ok-r-size-" + size)}>
+                {Math.abs(value).toString(Number(numeralSystem))}
+            </div>
+            <DigitEntryDecrementIndicator />
+        </div>
+    );
+};
+
+DigitEntry.displayName = "DigitEntry";
+
+export default DigitEntry;

package/src/primitives/DigitEntry/index.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 "./DigitEntry";
+
+export { default as DigitEntryProps } from "./DigitEntry.props";
+export {
+    DigitEntryVariant,
+    DigitEntrySize,
+    DigitEntryValueChangeEventHandler
+} from "./DigitEntry.props";

package/src/primitives/Indicator/Indicator.css

@@ -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.
+ */
+
+.okIndicator {
+    /* Layout */
+    display: inline-flex;
+    padding: var(--indicator-padding, 6px 12px);
+    justify-content: flex-start;
+    align-items: baseline;
+    gap: 4px;
+
+    /* Style */
+    border-radius: 4px;
+    border: 1px solid var(--Gray-2, #d0d7df);
+    background: var(--Light, #fff);
+
+    /* Indicator Icon Style */
+    svg.okIndicatorIcon {
+        width: var(--indicator-icon-width, 9px);
+        height: var(--indicator-icon-height, 9px);
+    }
+
+    /* Label Style */
+    .okIndicatorLabel {
+        /* Typography */
+        color: var(--Dark, #343434);
+        text-align: center;
+        /* TODO: Determine how to get Inter font */
+        font-family: Inter, "Nunito Sans", sans-serif, ui-sans-serif;
+        font-size: var(--indicator-font-size, 12px);
+        font-style: normal;
+        font-weight: 500;
+        line-height: var(--indicator-line-height, 12px); /* 100% */
+    }
+
+    /* Size 1 */
+    &:where(.ok-r-size-1) {
+        --indicator-padding: 6px 12px;
+        --indicator-font-size: 12px;
+        --indicator-line-height: 12px;
+        --indicator-icon-width: 9px;
+        --indicator-icon-height: 9px;
+    }
+
+    /* Sizes 2 */
+    &:where(.ok-r-size-2) {
+        --indicator-padding: 10px 18px;
+        --indicator-font-size: 14px;
+        --indicator-line-height: 14px;
+        --indicator-icon-width: 10px;
+        --indicator-icon-height: 10px;
+    }
+
+    /* Sizes 3 */
+    &:where(.ok-r-size-3) {
+        --indicator-padding: 18px 22px;
+        --indicator-font-size: 20px;
+        --indicator-line-height: 20px;
+        --indicator-icon-width: 15px;
+        --indicator-icon-height: 15px;
+    }
+}

package/src/primitives/Indicator/Indicator.props.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 IndicatorSize = 1 | 2 | 3;
+export type IndicatorState = boolean;
+
+/**
+ * Interface for the properties of the `Indicator` component.
+ */
+interface IndicatorProps {
+    /**
+     * Label to be displayed on the indicator
+     */
+    label: string;
+
+    /**
+     * Current state of the indicator
+     */
+    state: IndicatorState;
+
+    /**
+     * Optional CSS class to apply to the indicator
+     */
+    className?: string;
+
+    /**
+     * Optional size of the indicator
+     * @default 1
+     */
+    size?: IndicatorSize;
+
+    /**
+     * Optional tooltip text to be displayed on hover
+     */
+    tooltip?: string;
+}
+
+export default IndicatorProps;

package/src/primitives/Indicator/Indicator.stories.tsx

@@ -0,0 +1,44 @@
+/**
+ * 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 type { Meta, StoryObj } from "@storybook/react";
+
+import withApplication from "../../stories/decorators/Application.decorator";
+
+import Indicator from "./Indicator";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/Indicator",
+    component: Indicator,
+    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 }
+        },
+        state: { control: { type: "boolean" } }
+    }
+} satisfies Meta<typeof Indicator>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    decorators: [withApplication],
+    args: {
+        label: "Indicator",
+        state: true,
+        // Optional Properties
+        size: 1,
+        tooltip: "Indicator tooltip"
+    }
+};

package/src/primitives/Indicator/Indicator.tsx

@@ -0,0 +1,64 @@
+/**
+ * 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 IndicatorProps from "./Indicator.props";
+
+import "../../index.css";
+
+import "./Indicator.css";
+
+import { withTooltip } from "../TooltipUtility";
+
+import { ToggleState } from "../../core";
+
+import { IndicatorStateIcon } from "../../components/Icons";
+
+type IndicatorElement = React.ElementRef<"span">;
+
+/**
+ * `Indicator` is a React component that renders an indicator that represents the state of a boolean value with an
+ * optional tooltip.
+ *
+ * @component
+ * @param {object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the indicator
+ *
+ * @returns {React.Node} The rendered Indicator component
+ *
+ * @example
+ * ```jsx
+ * <Indicator
+ *     label="Indicator"
+ *     state={true} />
+ * ```
+ */
+const Indicator = React.forwardRef<IndicatorElement, IndicatorProps>((props, forwardedRef) => {
+    const { className, label, size = 1, state, ...indicatorProps } = props;
+
+    const IndicatorWithTooltip = withTooltip(
+        <span
+            {...indicatorProps}
+            ref={forwardedRef}
+            className={classnames("okIndicator", className, "ok-r-size-" + size)}>
+            <IndicatorStateIcon
+                className="okIndicatorIcon"
+                state={state ? ToggleState.On : ToggleState.Off}
+            />
+            <span className={classnames("okIndicatorLabel")}>{label}</span>
+        </span>
+    );
+
+    return <IndicatorWithTooltip {...props} />;
+});
+
+Indicator.displayName = "Indicator";
+
+export default Indicator;

package/src/primitives/Indicator/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 "./Indicator";
+
+export { default as IndicatorProps } from "./Indicator.props";
+export { IndicatorSize, IndicatorState } from "./Indicator.props";

package/src/primitives/Label/Label.css

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+
+.okLabel {
+    /* Layout */
+    display: inline-flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 4px;
+
+    /* Text Style */
+    .okLabelText {
+        /* Typography */
+        color: var(--Dark, #343434);
+        font-family: Inter, "Nunito Sans", sans-serif, ui-sans-serif;
+        font-size: 12px;
+        font-style: normal;
+        font-weight: 400;
+        line-height: 12px; /* 100% */
+    }
+
+    /* Label Position Left Top*/
+    &:where(.ok-pos-left-top) {
+        flex-direction: column;
+        align-items: flex-start;
+    }
+
+    /* Label Position Left Bottom*/
+    &:where(.ok-pos-left-bottom) {
+        flex-direction: column-reverse;
+        align-items: flex-start;
+    }
+
+    /* Label Position Right Top*/
+    &:where(.ok-pos-right-top) {
+        flex-direction: column;
+        align-items: flex-end;
+    }
+
+    /* Label Position Right Bottom*/
+    &:where(.ok-pos-right-bottom) {
+        flex-direction: column-reverse;
+        align-items: flex-end;
+    }
+}