@opalkelly/frontpanel-react-components 0.1.0

package/src/core/Numeric.ts

@@ -0,0 +1,168 @@
+/**
+ * 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 "./Types";
+
+/**
+ * Class representing numeric digits in various numeral systems.
+ */
+export class NumericDigits {
+    /**
+     * Maximum number of digits.
+     */
+    static readonly MAX_DIGITS: number = 1024;
+
+    /**
+     * Binary digit values.
+     */
+    static readonly BINARY_DIGITVALUES = ["0", "1"];
+
+    /**
+     * Octal digit values.
+     */
+    static readonly OCTAL_DIGITVALUES = ["0", "1", "2", "3", "4", "5", "6", "7"];
+
+    /**
+     * Decimal digit values.
+     */
+    static readonly DECIMAL_DIGITVALUES = [...NumericDigits.OCTAL_DIGITVALUES, "8", "9"];
+
+    /**
+     * Hexadecimal digit values.
+     */
+    static readonly HEXADECIMAL_DIGITVALUES = [
+        ...NumericDigits.DECIMAL_DIGITVALUES,
+        "A",
+        "B",
+        "C",
+        "D",
+        "E",
+        "F"
+    ];
+
+    private readonly _DigitCount: bigint;
+    private readonly _NumeralSystem: NumeralSystem;
+    private readonly _DigitChars: string[];
+
+    /**
+     * Gets the count of digits.
+     */
+    public get DigitCount() {
+        return this._DigitCount;
+    }
+
+    /**
+     * Gets the numeral system.
+     */
+    public get NumeralSystem() {
+        return this._NumeralSystem;
+    }
+
+    /**
+     * Gets the digit characters.
+     */
+    public get DigitChars() {
+        return this._DigitChars;
+    }
+
+    /**
+     * Creates a new instance of NumericDigits.
+     * @param digitCount - The count of digits.
+     * @param numeralSystem - The numeral system.
+     */
+    constructor(digitCount: bigint, numeralSystem: NumeralSystem) {
+        this._DigitCount = digitCount;
+        this._NumeralSystem = numeralSystem;
+        this._DigitChars = NumericDigits.GetDigitChars(numeralSystem);
+    }
+
+    /**
+     * Gets the character representation of the digit corresponding
+     * to the value specified.
+     * @param value - The value.
+     * @returns {string} - The digit as represented in the numeral system.
+     */
+    public GetDigitFromValue(value: number): string {
+        let targetDigitValue: number = value % this._NumeralSystem;
+
+        if (targetDigitValue < 0) {
+            targetDigitValue += this._NumeralSystem;
+        }
+
+        return targetDigitValue.toString(this._NumeralSystem);
+    }
+
+    /**
+     * Gets the digit characters from the numeral.
+     * @param numeral - The numeral system.
+     * @returns {string[]} - The digit characters.
+     */
+    public static GetDigitChars(numeral: NumeralSystem): string[] {
+        let retval: string[];
+
+        switch (numeral) {
+            case NumeralSystem.Binary:
+                retval = NumericDigits.BINARY_DIGITVALUES;
+                break;
+            case NumeralSystem.Octal:
+                retval = NumericDigits.OCTAL_DIGITVALUES;
+                break;
+            case NumeralSystem.Decimal:
+                retval = NumericDigits.DECIMAL_DIGITVALUES;
+                break;
+            case NumeralSystem.Hexadecimal:
+                retval = NumericDigits.HEXADECIMAL_DIGITVALUES;
+                break;
+            default:
+                retval = [];
+                break;
+        }
+
+        return retval;
+    }
+
+    /**
+     * Computes the digit count from the bits.
+     * @param bitcount - The bit count.
+     * @param numeral - The numeral.
+     * @returns {bigint} - The digit count.
+     */
+    public static ComputeDigitCountFromBits(bitcount: number, numeral: NumeralSystem) {
+        const maxValue: bigint = (1n << BigInt(bitcount)) - 1n;
+
+        return this.ComputeDigitCountFromValue(maxValue, numeral);
+    }
+
+    /**
+     * Computes the digit count from the value.
+     * @param value - The value.
+     * @param numeral - The numeral.
+     * @returns {bigint} - The digit count.
+     */
+    public static ComputeDigitCountFromValue(value: bigint, numeral: NumeralSystem): bigint {
+        // The following equation computes the number of digits necessary to represent the value
+        // given the radix. However, an iterative solution is used because Math.log operates on
+        // the number type and therefore limits the value to 52 bits. This solution should allow
+        // value to be any number of bits.
+        //
+        // d = ceiling(log[radix](value))
+        // v = value
+        // d = digits
+
+        const radix: bigint = BigInt(numeral);
+
+        let val: bigint = value;
+
+        let digitIndex: bigint;
+
+        for (digitIndex = 0n; digitIndex < NumericDigits.MAX_DIGITS && val !== 0n; digitIndex++) {
+            val = val / radix;
+        }
+
+        return digitIndex > 0n ? digitIndex : 1n;
+    }
+}

package/src/core/Types.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+
+/**
+ * Enumeration representing numeral systems.
+ */
+export enum NumeralSystem {
+    /**
+     * Binary numeral system (base 2).
+     */
+    Binary = 2,
+
+    /**
+     * Octal numeral system (base 8).
+     */
+    Octal = 8,
+
+    /**
+     * Decimal numeral system (base 10).
+     */
+    Decimal = 10,
+
+    /**
+     * Hexadecimal numeral system (base 16).
+     */
+    Hexadecimal = 16
+}
+
+/**
+ * Enumeration representing toggle states.
+ */
+export enum ToggleState {
+    Off,
+    On
+}

package/src/core/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 * from "./Types";
+
+export * from "./Numeric";
+export * from "./Binary";

package/src/index.css

@@ -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.
+ */
+
+@font-face {
+    font-family: "Inter";
+    src: url("./fonts/Inter-VariableFont_slnt\,wght.ttf") format("truetype");
+}

package/src/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 * from "./core";
+export * from "./components";
+export * from "./contexts";
+export * from "./primitives";

package/src/primitives/Application/Application.props.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+interface ApplicationProps extends React.PropsWithChildren<NonNullable<unknown>> {}
+
+export { ApplicationProps };

package/src/primitives/Application/Application.tsx

@@ -0,0 +1,24 @@
+/**
+ * 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 * as React from "react";
+
+import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+
+import { ApplicationProps } from "./Application.props";
+
+type ApplicationElement = React.ElementRef<"div">;
+
+const Application = React.forwardRef<ApplicationElement, ApplicationProps>(
+    (props, _forwardedRef) => {
+        return <TooltipPrimitive.Provider>{props.children}</TooltipPrimitive.Provider>;
+    }
+);
+
+Application.displayName = "Application";
+
+export default Application;

package/src/primitives/Application/index.ts

@@ -0,0 +1 @@
+export { default } from "./Application";

package/src/primitives/Button/Button.css

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+
+.okButton {
+    /* Layout */
+    display: inline-flex;
+    padding: var(--button-padding, 6px 12px);
+    justify-content: center;
+    align-items: center;
+    gap: 8px;
+
+    /* Style */
+    border-width: 0px;
+    border-radius: 4px;
+    background: var(--brand-12, #44bd84);
+
+    /* Typography */
+    color: var(--Base-White, #fff);
+    text-align: center;
+    font-family: Inter, "Nunito Sans", sans-serif, ui-sans-serif;
+    font-size: var(--button-font-size, 12px);
+    font-style: normal;
+    font-weight: 600;
+    line-height: var(--button-line-height, 12px); /* 100% */
+
+    /* State Pressed */
+    &:is(:active) {
+        background: #329466;
+    }
+
+    /* State Disabled */
+    &:is(:disabled) {
+        background: var(--Gray-2, #d0d7df);
+    }
+
+    /* Size 1 */
+    &:where(.ok-r-size-1) {
+        --button-padding: 6px 12px;
+        --button-font-size: 12px;
+        --button-line-height: 12px;
+    }
+
+    /* Sizes 2*/
+    &:where(.ok-r-size-2) {
+        --button-padding: 10px 18px;
+        --button-font-size: 14px;
+        --button-line-height: 14px;
+    }
+
+    /* Sizes 3*/
+    &:where(.ok-r-size-3) {
+        --button-padding: 18px 22px;
+        --button-font-size: 20px;
+        --button-line-height: 20px;
+    }
+}

package/src/primitives/Button/Button.props.ts

@@ -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.
+ */
+
+export type ButtonSize = 1 | 2 | 3;
+export type ButtonStateChangeEventHandler = () => void;
+export type ButtonClickEventHandler = () => void;
+
+/**
+ * Interface for the properties of the `Button` component.
+ */
+interface ButtonProps {
+    /**
+     * Label text to be displayed in the button
+     */
+    label: string;
+
+    /**
+     * Optional CSS class to apply to the button
+     */
+    className?: string;
+
+    /**
+     * Optional size of the button
+     * @default 1
+     */
+    size?: ButtonSize;
+
+    /**
+     * Optional tooltip text to be displayed on hover
+     */
+    tooltip?: string;
+
+    /**
+     * Optional event handler for the button down event
+     */
+    onButtonDown?: ButtonStateChangeEventHandler;
+
+    /**
+     * Optional event handler for the button up event
+     */
+    onButtonUp?: ButtonStateChangeEventHandler;
+
+    /**
+     * Optional event handler for the button click event
+     */
+    onButtonClick?: ButtonClickEventHandler;
+}
+
+export default ButtonProps;

package/src/primitives/Button/Button.stories.tsx

@@ -0,0 +1,54 @@
+/**
+ * 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 Button from "./Button";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/Button",
+    component: Button,
+    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 }
+        },
+        disabled: { control: "boolean" },
+        // Disable event callback arguments
+        onButtonClick: {
+            control: { disable: true }
+        },
+        onButtonDown: {
+            control: { disable: true }
+        },
+        onButtonUp: {
+            control: { disable: true }
+        }
+    }
+} satisfies Meta<typeof Button>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    decorators: [withApplication],
+    args: {
+        label: "Button",
+        // Optional Properties
+        size: 1,
+        disabled: false,
+        tooltip: "Button tooltip"
+    }
+};

package/src/primitives/Button/Button.tsx

@@ -0,0 +1,75 @@
+/**
+ * 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 ButtonProps from "./Button.props";
+
+import "../../index.css";
+
+import "./Button.css";
+
+//import { Slot } from "@radix-ui/react-slot";
+
+import { withTooltip } from "../TooltipUtility";
+
+type ButtonElement = React.ElementRef<"button">;
+
+interface ButtonCombinedProps extends React.ComponentPropsWithoutRef<"button">, ButtonProps {}
+
+export type { ButtonCombinedProps };
+
+/**
+ * `Button` is a React component that renders a button with an optional label and optional tooltip.
+ * The button event handlers provide notification when the button is clicked, pressed, or released
+ * and can be used to perform actions in response to these events.
+ *
+ * @component
+ * @param {object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the button
+ *
+ * @returns {React.Node} The rendered Button component
+ *
+ * @example
+ * ```jsx
+ * <Button
+ *     label="Button"
+ *     onButtonClick={() => console.log("Button clicked")} />
+ * ```
+ */
+const Button = React.forwardRef<ButtonElement, ButtonCombinedProps>((props, forwardedRef) => {
+    const {
+        className,
+        label,
+        size = 1,
+        onButtonUp,
+        onButtonDown,
+        onButtonClick,
+        ...buttonProps
+    } = props;
+
+    const ButtonWithTooltip = withTooltip(
+        <button
+            data-disabled={buttonProps.disabled || undefined}
+            {...buttonProps}
+            ref={forwardedRef}
+            className={classNames("okButton", className, "ok-r-size-" + size)}
+            onMouseDown={onButtonDown}
+            onMouseUp={onButtonUp}
+            onClick={onButtonClick}>
+            {label}
+        </button>
+    );
+
+    return <ButtonWithTooltip {...props} />;
+});
+
+Button.displayName = "Button";
+
+export default Button;

package/src/primitives/Button/index.ts

@@ -0,0 +1,4 @@
+export { default } from "./Button";
+
+export { default as ButtonProps } from "./Button.props";
+export { ButtonSize, ButtonStateChangeEventHandler, ButtonClickEventHandler } from "./Button.props";

package/src/primitives/DigitEntry/DigitEntry.css

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+
+.okDigitEntry {
+    /* Layout */
+    display: inline-flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    gap: 1px;
+
+    /* Content Style */
+    .okDigitEntryContent {
+        /* Layout */
+        display: flex;
+        padding: var(--spacing-xxs, 2px);
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+
+        /* Style */
+        border-radius: 1px;
+
+        /* Typography */
+        color: var(--Dark, #343434);
+        text-align: center;
+        font-family: Monaco;
+        font-size: var(--digit-font-size, 12px);
+        font-style: normal;
+        font-weight: 400;
+        line-height: var(--digit-line-height, 12px); /* 200% */
+        letter-spacing: 1.26px;
+        text-transform: uppercase;
+    }
+
+    /* Increment Indicator Style */
+    .okDigitEntryIncrementIndicator {
+        visibility: hidden;
+    }
+
+    /* Decrement Indicator Style */
+    .okDigitEntryDecrementIndicator {
+        visibility: hidden;
+    }
+
+    /* Size 1 */
+    &:where(.ok-r-size-1) {
+        --digit-font-size: 12px;
+        --digit-line-height: 12px;
+    }
+
+    /* Sizes 2 */
+    &:where(.ok-r-size-2) {
+        --digit-font-size: 14px;
+        --digit-line-height: 14px;
+    }
+
+    /* Sizes 3 */
+    &:where(.ok-r-size-3) {
+        --digit-font-size: 20px;
+        --digit-line-height: 20px;
+    }
+}
+
+div.okDigitEntry:focus {
+    /* Layout */
+    display: inline-flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    gap: 1px;
+
+    /* Style */
+    outline: none;
+    overscroll-behavior: none;
+
+    /* Content Style */
+    .okDigitEntryContent {
+        /* Layout */
+        display: flex;
+        padding: var(--spacing-xxs, 2px);
+        flex-direction: column;
+        justify-content: center;
+        align-items: center;
+
+        /* Style */
+        border-radius: 1px;
+        background: var(--brand-12, #44bd84);
+
+        /* Typography */
+        color: var(--Light, #fff);
+        text-align: center;
+        font-family: Monaco;
+        font-size: var(--digit-font-size, 12px);
+        font-style: normal;
+        font-weight: 400;
+        line-height: var(--digit-line-height, 12px); /* 200% */
+        letter-spacing: 1.26px;
+    }
+
+    .okDigitEntryIncrementIndicator {
+        visibility: visible;
+    }
+
+    .okDigitEntryDecrementIndicator {
+        visibility: visible;
+    }
+
+    .okDigitEntryIncrementIndicator[data-enabled="false"] {
+        opacity: 0.25;
+    }
+
+    .okDigitEntryDecrementIndicator[data-enabled="false"] {
+        opacity: 0.25;
+    }
+}