@opalkelly/frontpanel-react-components 0.1.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@opalkelly/frontpanel-react-components",
+  "version": "0.1.0",
+  "description": "React Component Library for OpalKelly FrontPanel Alloy",
+  "keywords": [
+    "FPGA",
+    "FrontPanel",
+    "OpalKelly",
+    "Alloy",
+    "React",
+    "Component",
+    "Library"
+  ],
+  "author": "Opal Kelly <support@opalkelly.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opalkelly-opensource/design-resources.git"
+  },
+  "homepage": "https://opalkelly.com/",
+  "bugs": {
+    "url": "https://forums.opalkelly.com/"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^25.0.7",
+    "@rollup/plugin-eslint": "^9.0.5",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "@storybook/addon-essentials": "^7.6.6",
+    "@storybook/addon-interactions": "^7.6.6",
+    "@storybook/addon-links": "^7.6.6",
+    "@storybook/blocks": "^7.6.6",
+    "@storybook/manager-api": "^8.0.8",
+    "@storybook/react": "^7.6.6",
+    "@storybook/react-webpack5": "^7.6.6",
+    "@storybook/test": "^7.6.6",
+    "@storybook/theming": "^8.0.8",
+    "@types/react": "^18.2.45",
+    "@typescript-eslint/eslint-plugin": "^7.1.1",
+    "@typescript-eslint/parser": "^7.1.1",
+    "eslint": "^8.57.0",
+    "eslint-plugin-react": "^7.34.0",
+    "prettier": "^3.2.5",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.9.1",
+    "rollup-plugin-dts": "^6.1.0",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-postcss": "^4.0.2",
+    "storybook": "^7.6.6",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "@opalkelly/frontpanel-alloy-core": "^0.1.0",
+    "@radix-ui/react-scroll-area": "^1.0.5",
+    "@radix-ui/react-select": "^2.0.0",
+    "@radix-ui/react-slider": "^1.1.2",
+    "@radix-ui/react-tooltip": "^1.0.7",
+    "classnames": "^2.3.2",
+    "react": "^18.2.0"
+  },
+  "scripts": {
+    "rollup": "rollup -c",
+    "format-check": "prettier --check ./src/**",
+    "lint": "eslint ./src/**/*.{ts,tsx}",
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "storybook-docs": "storybook dev --docs",
+    "build-storybook-docs": "storybook build --docs"
+  },
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "types": "dist/index.d.ts"
+}

package/src/components/FrontPanel/FrontPanel.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 { IFrontPanel, IFrontPanelEventSource, WorkQueue } from "@opalkelly/frontpanel-alloy-core";
+
+interface FrontPanelProps extends React.PropsWithChildren<NonNullable<unknown>> {
+    /**
+     * The front panel device to be used
+     */
+    device?: IFrontPanel;
+    /**
+     * Optional work queue to be used
+     */
+    workQueue?: WorkQueue;
+    /**
+     * Optional event source to be used
+     */
+    eventSource?: IFrontPanelEventSource;
+}
+
+export { FrontPanelProps };

package/src/components/FrontPanel/FrontPanel.tsx

@@ -0,0 +1,33 @@
+/**
+ * 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 { FrontPanelPeriodicUpdateTimer, WorkQueue } from "@opalkelly/frontpanel-alloy-core";
+
+import { FrontPanelProps } from "./FrontPanel.props";
+
+import { FrontPanelContext } from "../../contexts";
+
+const FrontPanel: React.FC<FrontPanelProps> = (props) => {
+    const {
+        device = window.FrontPanel,
+        workQueue = new WorkQueue(),
+        eventSource = new FrontPanelPeriodicUpdateTimer(device, 10)
+    } = props;
+
+    return (
+        <FrontPanelContext.Provider
+            value={{ device: device, workQueue: workQueue, eventSource: eventSource }}>
+            {props.children}
+        </FrontPanelContext.Provider>
+    );
+};
+
+FrontPanel.displayName = "FrontPanel";
+
+export default FrontPanel;

package/src/components/FrontPanel/index.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 "./FrontPanel";

package/src/components/FrontPanelIndicator/FrontPanelIndicator.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 `FrontPanelIndicator` component.
+ */
+interface FrontPanelIndicatorProps {
+    /**
+     * Address of the frontpanel endpoint
+     */
+    fpEndpoint: EndpointAddressProps;
+}
+
+export default FrontPanelIndicatorProps;

package/src/components/FrontPanelIndicator/FrontPanelIndicator.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 withFrontPanel from "../../stories/decorators/FrontPanel.decorator";
+
+import FrontPanelIndicator from "./FrontPanelIndicator";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/FrontPanel/FrontPanelIndicator",
+    component: FrontPanelIndicator,
+    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 }
+        }
+    }
+} satisfies Meta<typeof FrontPanelIndicator>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    decorators: [withApplication, withFrontPanel],
+    args: {
+        label: "Wire Indicator",
+        fpEndpoint: { epAddress: 0x20, bitOffset: 1 },
+        // Optional Properties
+        size: 1,
+        tooltip: "Indicator for wire endpoint"
+    }
+};

package/src/components/FrontPanelIndicator/FrontPanelIndicator.tsx

@@ -0,0 +1,81 @@
+/**
+ * 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 { Indicator } from "../../primitives";
+
+import FrontPanelIndicatorProps from "./FrontPanelIndicator.props";
+
+import { FrontPanelContext } from "../../contexts";
+
+import { IFrontPanel } from "@opalkelly/frontpanel-alloy-core";
+
+type FrontPanelIndicatorElement = React.ElementRef<typeof Indicator>;
+
+interface FrontPanelIndicatorCombinedProps
+    extends Omit<React.ComponentPropsWithoutRef<typeof Indicator>, "state">,
+        FrontPanelIndicatorProps {}
+
+export type { FrontPanelIndicatorCombinedProps };
+
+/**
+ * `FrontPanelIndicator` is a React component that renders an indicator that represents the state of a WireOut endpoint.
+ *
+ * @component
+ * @param {object} props - Properties passed to component
+ * @param {React.Ref} forwardedRef - Forwarded ref for the indicator
+ *
+ * @returns {React.Node} The rendered FrontPanelIndicator component
+ *
+ * @example
+ * ```jsx
+ * <FrontPanelIndicator
+ *     label="Indicator"
+ *     fpEndpoint={{epAddress: 0x20, bitOffset: 1}} />
+ * ```
+ */
+const FrontPanelIndicator = React.forwardRef<
+    FrontPanelIndicatorElement,
+    FrontPanelIndicatorCombinedProps
+>((props, forwardedRef) => {
+    const [bitValue, setBitValue] = React.useState<boolean>(false);
+
+    const { device, workQueue, eventSource } = React.useContext(FrontPanelContext);
+
+    const { fpEndpoint, ...rootProps } = props;
+
+    const targetWireBitMask = 1 << fpEndpoint.bitOffset;
+
+    const onUpdateWireValue = React.useCallback(
+        async (sender: IFrontPanel): Promise<void> => {
+            await workQueue.Post(async () => {
+                const sourceWireValue = await sender.getWireOutValue(fpEndpoint.epAddress);
+                const sourceBitValue = (sourceWireValue & targetWireBitMask) === targetWireBitMask;
+                setBitValue(sourceBitValue);
+            });
+        },
+        [fpEndpoint, targetWireBitMask]
+    );
+
+    React.useEffect(() => {
+        onUpdateWireValue(device);
+
+        const subscription =
+            eventSource?.WireOutValuesChangedEvent.SubscribeAsync(onUpdateWireValue);
+
+        return () => {
+            subscription?.Cancel();
+        };
+    }, [device, eventSource, onUpdateWireValue]);
+
+    return <Indicator {...rootProps} ref={forwardedRef} state={bitValue} />;
+});
+
+FrontPanelIndicator.displayName = "FrontPanelIndicator";
+
+export default FrontPanelIndicator;

package/src/components/FrontPanelIndicator/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 "./FrontPanelIndicator";
+
+export { default as FrontPanelIndicatorProps } from "./FrontPanelIndicator.props";

package/src/components/FrontPanelNumberDisplay/FrontPanelNumberDisplay.props.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 `FrontPanelNumberDisplay` component.
+ *
+ * @interface
+ */
+interface FrontPanelNumberDisplayProps {
+    /**
+     * Address of the frontpanel endpoint
+     */
+    fpEndpoint: EndpointAddressProps;
+
+    /**
+     * Maximum value that the number display will allow
+     */
+    maximumValue: bigint;
+}
+
+export default FrontPanelNumberDisplayProps;

package/src/components/FrontPanelNumberDisplay/FrontPanelNumberDisplay.stories.tsx

@@ -0,0 +1,67 @@
+/**
+ * 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 FrontPanelNumberDisplay from "./FrontPanelNumberDisplay";
+
+import { NumeralSystem } from "../../core";
+
+// Configure Story metadata
+const meta = {
+    title: "Components/FrontPanel/FrontPanelNumberDisplay",
+    component: FrontPanelNumberDisplay,
+    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 }
+        },
+        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" }
+    }
+} satisfies Meta<typeof FrontPanelNumberDisplay>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// Primary Story
+export const Primary: Story = {
+    decorators: [withApplication, withFrontPanel],
+    args: {
+        fpEndpoint: { epAddress: 0x20, bitOffset: 1 },
+        maximumValue: 0xffffffffn,
+        // Optional Properties
+        numeralSystem: NumeralSystem.Decimal,
+        decimalScale: 0,
+        label: {
+            text: "Wire Value",
+            verticalPosition: "top",
+            horizontalPosition: "left"
+        },
+        size: 1,
+        tooltip: "The wire endpoint value"
+    }
+};

package/src/components/FrontPanelNumberDisplay/FrontPanelNumberDisplay.tsx

@@ -0,0 +1,130 @@
+/**
+ * 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 "./FrontPanelNumberDisplay.css";
+
+import { NumberDisplay } from "../../primitives";
+
+import FrontPanelNumberDisplayProps from "./FrontPanelNumberDisplay.props";
+
+import { FrontPanelContext } from "../../contexts";
+
+import { CalculateBitLength } from "../../core";
+
+import { IFrontPanel, WIREOUT_ADDRESS_RANGE } from "@opalkelly/frontpanel-alloy-core";
+
+type FrontPanelNumberDisplayElement = React.ElementRef<typeof NumberDisplay>;
+
+interface FrontPanelNumberDisplayCombinedProps
+    extends Omit<
+            React.ComponentPropsWithoutRef<typeof NumberDisplay>,
+            "value" | "maximumValue" | "minimumValue"
+        >,
+        FrontPanelNumberDisplayProps {}
+
+export type { FrontPanelNumberDisplayCombinedProps };
+
+/**
+ * `FrontPanelNumberDisplay` is a React component that renders a number display to represent the value of a WireOut endpoint using
+ * binary, octal, decimal, or hexadecimal numeral systems. 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 number display
+ *
+ * @returns {React.Node} The rendered FrontPanelNumberDisplay component
+ *
+ * @example
+ * ```jsx
+ * <FrontPanelNumberDisplay
+ *     fpEndpoint={{epAddress: 0x20, bitOffset: 1}}
+ *     maximumValue=0xffffffff />
+ * ```
+ */
+const FrontPanelNumberDisplay = React.forwardRef<
+    FrontPanelNumberDisplayElement,
+    FrontPanelNumberDisplayCombinedProps
+>((props, forwardedRef) => {
+    const [value, setValue] = React.useState<bigint>(0n);
+
+    const { device, workQueue, eventSource } = React.useContext(FrontPanelContext);
+
+    const { maximumValue, fpEndpoint, ...rootProps } = props;
+
+    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.getWireOutValue(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 <= WIREOUT_ADDRESS_RANGE.Maximum &&
+                        currentWireSpanBitMask > 0n;
+                        sourceWireAddress++
+                    ) {
+                        // Get the wire value for the next endpoint
+                        sourceWireValue = await sender.getWireOutValue(sourceWireAddress);
+                        targetWireBitMask = currentWireSpanBitMask & 0xffffffffn;
+                        sourceSpanValue |=
+                            (BigInt(sourceWireValue) & targetWireBitMask) <<
+                            currentWireSpanBitOffset;
+
+                        currentWireSpanBitOffset += 32n;
+                        currentWireSpanBitMask >>= 32n;
+                    }
+                }
+
+                setValue(sourceSpanValue);
+            });
+        },
+        [fpEndpoint, targetWireSpanBitMask]
+    );
+
+    React.useEffect(() => {
+        onUpdateWireValue(device);
+
+        const subscription =
+            eventSource?.WireOutValuesChangedEvent.SubscribeAsync(onUpdateWireValue);
+
+        return () => {
+            subscription?.Cancel();
+        };
+    }, [device, eventSource, onUpdateWireValue]);
+
+    return (
+        <NumberDisplay
+            {...rootProps}
+            ref={forwardedRef}
+            maximumValue={maximumValue}
+            minimumValue={0n}
+            value={value}
+        />
+    );
+});
+
+FrontPanelNumberDisplay.displayName = "FrontPanelNumberDisplay";
+
+export default FrontPanelNumberDisplay;

package/src/components/FrontPanelNumberDisplay/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 "./FrontPanelNumberDisplay";
+
+export { default as FrontPanelNumberDisplayProps } from "./FrontPanelNumberDisplay.props";

package/src/components/FrontPanelNumberEntry/FrontPanelNumberEntry.props.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 `FrontPanelNumberEntry` component.
+ *
+ * @interface
+ */
+interface FrontPanelNumberEntryProps {
+    /**
+     * Address of the frontpanel endpoint
+     */
+    fpEndpoint: EndpointAddressProps;
+
+    /**
+     * Maximum value that the number entry will allow.
+     */
+    maximumValue: bigint;
+
+    /**
+     * Optional minimum value that the number entry will allow.
+     */
+    minimumValue?: bigint;
+}
+
+export default FrontPanelNumberEntryProps;