@opalkelly/frontpanel-react-components 0.1.0

package/src/components/FrontPanelNumberEntry/FrontPanelNumberEntry.stories.tsx

@@ -0,0 +1,104 @@
+/**
+ * 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, { useContext } from "react";
+
+import type { Meta, StoryObj } from "@storybook/react";
+
+import withApplication from "../../stories/decorators/Application.decorator";
+import withFrontPanel from "../../stories/decorators/FrontPanel.decorator";
+
+import FrontPanelNumberEntry from "./FrontPanelNumberEntry";
+
+import { FrontPanelContext } from "../../contexts";
+
+import { NumeralSystem } from "../../core";
+
+import { WireValue } from "@opalkelly/frontpanel-alloy-core";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/FrontPanel/FrontPanelNumberEntry",
+    component: FrontPanelNumberEntry,
+    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 }
+        },
+        decimalScale: {
+            control: { type: "range", min: 0, max: 20, step: 1 }
+        },
+        numeralSystem: {
+            control: "radio",
+            options: ["Decimal", "Hexadecimal", "Binary", "Octal"],
+            mapping: {
+                Decimal: NumeralSystem.Decimal,
+                Hexadecimal: NumeralSystem.Hexadecimal,
+                Binary: NumeralSystem.Binary,
+                Octal: NumeralSystem.Octal
+            }
+        },
+        maximumValue: { control: "text" },
+        minimumValue: { control: "text" }
+    }
+} satisfies Meta<typeof FrontPanelNumberEntry>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    render: (props) => {
+        const { device, workQueue } = useContext(FrontPanelContext);
+
+        const setWireInPromises: Promise<void>[] = [];
+
+        // Initialize the WireIns with unique values.
+        workQueue.Post(async (): Promise<void> => {
+            let byteId = 0;
+
+            for (let address = 0x0; address < 0x20; address++) {
+                let wireValue: WireValue = byteId++;
+                for (let byteIndex = 1; byteIndex < 4; byteIndex++) {
+                    wireValue |= byteId++ << (8 * byteIndex);
+                }
+                setWireInPromises.push(device.setWireInValue(address, wireValue, 0xffffffff));
+            }
+
+            await Promise.all(setWireInPromises);
+            await device.updateWireIns();
+        });
+
+        return <FrontPanelNumberEntry {...props} />;
+    },
+    decorators: [withApplication, withFrontPanel],
+    args: {
+        fpEndpoint: { epAddress: 0x00, bitOffset: 1 },
+        maximumValue: 0xffffffffn,
+        // Optional Properties
+        disabled: false,
+        variant: "standard",
+        numeralSystem: NumeralSystem.Decimal,
+        decimalScale: 0,
+        label: {
+            text: "Wire Value",
+            verticalPosition: "top",
+            horizontalPosition: "left"
+        },
+        size: 1,
+        tooltip: "Set the wire endpoint value"
+    }
+};

package/src/components/FrontPanelNumberEntry/FrontPanelNumberEntry.tsx

@@ -0,0 +1,195 @@
+/**
+ * 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 "./FrontPanelNumberEntry.css";
+
+import { NumberEntry } from "../../primitives";
+
+import FrontPanelNumberEntryProps from "./FrontPanelNumberEntry.props";
+
+import { FrontPanelContext } from "../../contexts";
+
+import { CalculateBitLength } from "../../core";
+
+import { IFrontPanel, WIREIN_ADDRESS_RANGE } from "@opalkelly/frontpanel-alloy-core";
+
+type FrontPanelNumberEntryElement = React.ElementRef<typeof NumberEntry>;
+
+interface FrontPanelNumberEntryCombinedProps
+    extends Omit<
+            React.ComponentPropsWithoutRef<typeof NumberEntry>,
+            "value" | "maximumValue" | "minimumValue" | "onValueChange"
+        >,
+        FrontPanelNumberEntryProps {}
+
+export type { FrontPanelNumberEntryCombinedProps };
+
+/**
+ * `FrontPanelNumberEntry` is a React component that renders a number entry field to allow setting the value of a WireIn endpoint
+ * 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 be incremented and decremented using the up and down arrow keys and or the mouse wheel.
+ *
+ * @component
+ * @param {Object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the number display
+ *
+ * @returns {React.Node} The rendered FrontPanelNumberDisplay component
+ *
+ * @example
+ * ```jsx
+ * <FrontPanelNumberEntry
+ *     fpEndpoint={{epAddress: 0x00, bitOffset: 1}}
+ *     maximumValue=0xffffffff />
+ * ```
+ */
+const FrontPanelNumberEntry = React.forwardRef<
+    FrontPanelNumberEntryElement,
+    FrontPanelNumberEntryCombinedProps
+>((props, forwardedRef) => {
+    const [value, setValue] = React.useState<bigint>(props.minimumValue ?? 0n);
+
+    const { device, workQueue } = React.useContext(FrontPanelContext);
+
+    const { maximumValue, minimumValue, fpEndpoint, ...rootProps } = props;
+
+    const clampedMinimumValue = React.useMemo(() => {
+        return typeof minimumValue !== "undefined"
+            ? ClampValue(minimumValue, maximumValue, 0n)
+            : 0n;
+    }, [minimumValue, maximumValue]);
+
+    const targetBitLength: number = React.useMemo(() => {
+        return CalculateBitLength(maximumValue);
+    }, [maximumValue]);
+
+    const targetWireSpanBitMask =
+        ((1n << BigInt(targetBitLength)) - 1n) << BigInt(fpEndpoint.bitOffset);
+
+    const onUpdateWireValue = React.useCallback(
+        async (sender: IFrontPanel): Promise<void> => {
+            await workQueue.Post(async () => {
+                // Get the wire value for the endpoint
+                let sourceWireValue = await sender.getWireInValue(fpEndpoint.epAddress);
+                let targetWireBitMask = targetWireSpanBitMask & 0xffffffffn;
+                let sourceSpanValue =
+                    (BigInt(sourceWireValue) & targetWireBitMask) >> BigInt(fpEndpoint.bitOffset);
+
+                if (targetWireSpanBitMask > 0xffffffffn) {
+                    // The operations spans multiple endpoints
+                    let currentWireSpanBitOffset = 32n - BigInt(fpEndpoint.bitOffset);
+                    let currentWireSpanBitMask = targetWireSpanBitMask >> 32n;
+
+                    for (
+                        let sourceWireAddress = fpEndpoint.epAddress + 1;
+                        sourceWireAddress <= WIREIN_ADDRESS_RANGE.Maximum &&
+                        currentWireSpanBitMask > 0n;
+                        sourceWireAddress++
+                    ) {
+                        // Get the wire value for the next endpoint
+                        sourceWireValue = await sender.getWireInValue(sourceWireAddress);
+                        targetWireBitMask = currentWireSpanBitMask & 0xffffffffn;
+                        sourceSpanValue |=
+                            (BigInt(sourceWireValue) & targetWireBitMask) <<
+                            currentWireSpanBitOffset;
+
+                        currentWireSpanBitOffset += 32n;
+                        currentWireSpanBitMask >>= 32n;
+                    }
+                }
+
+                setValue(sourceSpanValue);
+            });
+        },
+        [fpEndpoint, targetWireSpanBitMask]
+    );
+
+    React.useEffect(() => {
+        onUpdateWireValue(device);
+    }, [device, onUpdateWireValue]);
+
+    const onNumberEntryValueChange = React.useCallback(
+        async (value: bigint): Promise<void> => {
+            await workQueue.Post(async () => {
+                let targetWireBitMask = targetWireSpanBitMask & 0xffffffffn;
+                let targetWireValue = Number(
+                    (value << BigInt(fpEndpoint.bitOffset)) & targetWireBitMask
+                );
+
+                // Set the wire value for the endpoint
+                await device.setWireInValue(
+                    fpEndpoint.epAddress,
+                    targetWireValue,
+                    Number(targetWireBitMask)
+                );
+
+                if (targetWireSpanBitMask > 0xffffffffn) {
+                    // The operations spans multiple endpoints
+                    let currentWireSpanBitOffset = 32n - BigInt(fpEndpoint.bitOffset);
+                    let currentWireSpanBitMask = targetWireSpanBitMask >> 32n;
+
+                    for (
+                        let targetWireAddress = fpEndpoint.epAddress + 1;
+                        targetWireAddress <= WIREIN_ADDRESS_RANGE.Maximum &&
+                        currentWireSpanBitMask > 0n;
+                        targetWireAddress++
+                    ) {
+                        targetWireBitMask = currentWireSpanBitMask & 0xffffffffn;
+                        targetWireValue = Number(
+                            (value >> currentWireSpanBitOffset) & targetWireBitMask
+                        );
+
+                        // Set the wire value for the next endpoint
+                        await device.setWireInValue(
+                            targetWireAddress,
+                            targetWireValue,
+                            Number(targetWireBitMask)
+                        );
+
+                        currentWireSpanBitOffset += 32n;
+                        currentWireSpanBitMask >>= 32n;
+                    }
+                }
+
+                await device.updateWireIns();
+            });
+
+            onUpdateWireValue(device);
+        },
+        [device, workQueue, fpEndpoint, targetWireSpanBitMask, onUpdateWireValue]
+    );
+
+    return (
+        <NumberEntry
+            {...rootProps}
+            ref={forwardedRef}
+            maximumValue={maximumValue}
+            minimumValue={clampedMinimumValue}
+            value={value}
+            onValueChange={onNumberEntryValueChange}
+        />
+    );
+});
+
+FrontPanelNumberEntry.displayName = "FrontPanelNumberEntry";
+
+export default FrontPanelNumberEntry;
+
+function ClampValue(value: bigint, maximumLimit: bigint, minimumLimit: bigint): bigint {
+    let retval: bigint;
+
+    if (value < minimumLimit) {
+        retval = minimumLimit;
+    } else if (value > maximumLimit) {
+        retval = maximumLimit;
+    } else {
+        retval = value;
+    }
+
+    return retval;
+}

package/src/components/FrontPanelNumberEntry/index.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.
+ */
+
+export { default } from "./FrontPanelNumberEntry";
+
+export { default as FrontPanelNumberEntryProps } from "./FrontPanelNumberEntry.props";

package/src/components/FrontPanelPushButton/FrontPanelPushButton.props.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { EndpointAddressProps } from "../types";
+
+/**
+ * Interface for the properties of the `FrontPanelToggleButton` component.
+ */
+interface FrontPanelPushButtonProps {
+    /**
+     * Address of the frontpanel endpoint
+     */
+    fpEndpoint: EndpointAddressProps;
+}
+
+export default FrontPanelPushButtonProps;

package/src/components/FrontPanelPushButton/FrontPanelPushButton.stories.tsx

@@ -0,0 +1,46 @@
+/**
+ * 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 withFrontPanel from "../../stories/decorators/FrontPanel.decorator";
+
+import FrontPanelPushButton from "./FrontPanelPushButton";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/FrontPanel/FrontPanelPushButton",
+    component: FrontPanelPushButton,
+    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" }
+    }
+} satisfies Meta<typeof FrontPanelPushButton>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    decorators: [withApplication, withFrontPanel],
+    args: {
+        label: "Pushbutton",
+        fpEndpoint: { epAddress: 0x00, bitOffset: 1 },
+        // Optional Properties
+        disabled: false,
+        size: 1,
+        tooltip: "Wire endpoint assert button"
+    }
+};

package/src/components/FrontPanelPushButton/FrontPanelPushButton.tsx

@@ -0,0 +1,80 @@
+/**
+ * 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 { Button } from "../../primitives";
+
+import FrontPanelPushButtonProps from "./FrontPanelPushButton.props";
+
+import { FrontPanelContext } from "../../contexts";
+
+type FrontPanelPushButtonElement = React.ElementRef<typeof Button>;
+
+interface FrontPanelPushButtonCombinedProps
+    extends Omit<
+            React.ComponentPropsWithoutRef<typeof Button>,
+            "asChild" | "onButtonClick" | "onButtonDown" | "onButtonUp"
+        >,
+        FrontPanelPushButtonProps {}
+
+export type { FrontPanelPushButtonCombinedProps };
+
+/**
+ * `FrontPanelPushButton` is a React component that renders a push button that asserts a WireIn endpoint
+ * when pressed and deasserts it when released.
+ *
+ * @component
+ * @param {object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the button
+ *
+ * @returns {React.Node} The rendered FrontPanelPushButton component
+ *
+ * @example
+ * ```jsx
+ * <FrontPanelPushButton
+ *     label="Pushbutton"
+ *     fpEndpoint={{epAddress: 0x00, bitOffset: 1}} />
+ * ```
+ */
+const FrontPanelPushButton = React.forwardRef<
+    FrontPanelPushButtonElement,
+    FrontPanelPushButtonCombinedProps
+>((props, forwardedRef) => {
+    const { device, workQueue } = React.useContext(FrontPanelContext);
+
+    const { fpEndpoint, ...buttonProps } = props;
+
+    const targetWireBitMask = 1 << fpEndpoint.bitOffset;
+
+    const onButtonUp = React.useCallback(async (): Promise<void> => {
+        await workQueue.Post(async () => {
+            await device.setWireInValue(fpEndpoint.epAddress, 0, targetWireBitMask);
+            await device.updateWireIns();
+        });
+    }, [device, fpEndpoint, targetWireBitMask, workQueue]);
+
+    const onButtonDown = React.useCallback(async (): Promise<void> => {
+        await workQueue.Post(async () => {
+            await device.setWireInValue(fpEndpoint.epAddress, 0xffffffff, targetWireBitMask);
+            await device.updateWireIns();
+        });
+    }, [device, fpEndpoint, targetWireBitMask, workQueue]);
+
+    return (
+        <Button
+            {...buttonProps}
+            ref={forwardedRef}
+            onButtonUp={onButtonUp}
+            onButtonDown={onButtonDown}
+        />
+    );
+});
+
+FrontPanelPushButton.displayName = "FrontPanelPushButton";
+
+export default FrontPanelPushButton;

package/src/components/FrontPanelPushButton/index.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.
+ */
+
+export { default } from "./FrontPanelPushButton";
+
+export { default as FrontPanelPushButtonProps } from "./FrontPanelPushButton.props";

package/src/components/FrontPanelRangeSlider/FrontPanelRangeSlider.props.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 { EndpointAddressProps } from "../types";
+
+/**
+ * Interface for the properties of the `FrontPanelRangeSlider` component.
+ */
+interface FrontPanelRangeSliderProps {
+    /**
+     * Address of the frontpanel endpoint
+     */
+    fpEndpoint: EndpointAddressProps;
+
+    /**
+     * Maximum value that the range slider will allow
+     */
+    maximumValue: number;
+}
+
+export default FrontPanelRangeSliderProps;

package/src/components/FrontPanelRangeSlider/FrontPanelRangeSlider.stories.tsx

@@ -0,0 +1,92 @@
+/**
+ * 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, { useContext } from "react";
+
+import type { Meta, StoryObj, Decorator } from "@storybook/react";
+
+import withApplication from "../../stories/decorators/Application.decorator";
+import withFrontPanel from "../../stories/decorators/FrontPanel.decorator";
+
+import FrontPanelRangeSlider from "./FrontPanelRangeSlider";
+
+import { FrontPanelContext } from "../../contexts";
+
+import { WireValue } from "@opalkelly/frontpanel-alloy-core";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/FrontPanel/FrontPanelRangeSlider",
+    component: FrontPanelRangeSlider,
+    parameters: {
+        layout: "centered" // Center the component in the Canvas
+    },
+    tags: ["autodocs"], // Automatically generate documentation
+    argTypes: {
+        maximumValue: {
+            control: { type: "number", step: 1 }
+        },
+        minimumValue: {
+            control: { type: "number", step: 1 }
+        },
+        valueStep: {
+            control: { type: "number", step: 1 }
+        },
+        disabled: { control: "boolean" },
+        showThumbLabel: { type: "boolean" },
+        showTrackLabels: { type: "boolean" }
+    }
+} satisfies Meta<typeof FrontPanelRangeSlider>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const withContainer: Decorator = (Story) => (
+    <div style={{ width: "200px" }}>
+        <Story />
+    </div>
+);
+
+// Primary Story
+export const Primary: Story = {
+    render: (props) => {
+        const { device, workQueue } = useContext(FrontPanelContext);
+
+        const setWireInPromises: Promise<void>[] = [];
+
+        workQueue.Post(async (): Promise<void> => {
+            let byteId = 0;
+
+            for (let address = 0x0; address < 0x20; address++) {
+                let wireValue: WireValue = byteId++;
+                for (let byteIndex = 1; byteIndex < 4; byteIndex++) {
+                    wireValue |= byteId++ << (8 * byteIndex);
+                }
+                setWireInPromises.push(device.setWireInValue(address, wireValue, 0xffffffff));
+            }
+
+            await Promise.all(setWireInPromises);
+            await device.updateWireIns();
+        });
+
+        return <FrontPanelRangeSlider {...props} />;
+    },
+    decorators: [withApplication, withFrontPanel, withContainer],
+    args: {
+        fpEndpoint: { epAddress: 0x00, bitOffset: 1 },
+        // Optional Properties
+        maximumValue: 100,
+        minimumValue: 0,
+        valueStep: 1,
+        showTrackLabels: true,
+        showThumbLabel: true,
+        disabled: false,
+        label: { text: "RangeSlider" },
+        tooltip: "Wire endpoint Range slider tooltip"
+    }
+};