From 4b726a38e0a028b25070fda96e3cd8a2020b5f44 Mon Sep 17 00:00:00 2001 From: Guilherme de Freitas Date: Tue, 17 Nov 2026 11:56:48 +0000 Subject: [PATCH 1/3] Add data tag component --- .../datadisplay/DataCard/DataTag.test.tsx | 157 +++++++++ .../datadisplay/DataCard/DataTag.tsx | 162 ++++++++++ src/components/datadisplay/DataCard/index.ts | 1 + .../datadisplay/DataTag.stories.tsx | 301 ++++++++++++++++++ 4 files changed, 621 insertions(+) create mode 100644 src/components/datadisplay/DataCard/DataTag.test.tsx create mode 100644 src/components/datadisplay/DataCard/DataTag.tsx create mode 100644 src/components/datadisplay/DataTag.stories.tsx diff --git a/src/components/datadisplay/DataCard/DataTag.test.tsx b/src/components/datadisplay/DataCard/DataTag.test.tsx new file mode 100644 index 00000000..f5895b2a --- /dev/null +++ b/src/components/datadisplay/DataCard/DataTag.test.tsx @@ -0,0 +1,157 @@ +import { LucideStar } from "lucide-react"; +import { render, screen } from "@testing-library/react"; +import { DataTag, DataTagGrid } from "./DataTag"; + +describe("DataTag Component", () => { + it("renders the label and value correctly when strings provided", () => { + const value = "Test Value"; + render(); + expect(screen.getByText("Test Label")).toBeInTheDocument(); + expect(screen.getByText(value)).toBeInTheDocument(); + }); + + it("renders the label and value correctly when number provided", () => { + const value = 2; + render(); + expect(screen.getByText("Test number Label")).toBeInTheDocument(); + expect(screen.getByText(value)).toBeInTheDocument(); + }); + + it("renders '?' if value is undefined or empty and 'hideOnNullish' is set to false", () => { + render( + , + ); + const dataElement = screen.getByRole("data"); + + expect(screen.getByText("?")).toBeInTheDocument(); + expect(dataElement).toHaveAttribute( + "aria-details", + "data-tag-textDisabled", + ); + }); + + it("renders an icon if provided", () => { + render(); + expect(screen.getByTitle("datafield-icon")).toBeInTheDocument(); + }); + + it("applies the default aria-details if no indicatorFn is provided", () => { + render(); + const dataElement = screen.getByRole("data"); + expect(dataElement).toHaveAttribute("aria-details", "data-tag"); + }); + + describe("String matching", () => { + it("applies the correct aria-details for matched string values", () => { + render( + + value === "hello" ? "success" : "error" + } + />, + ); + const dataElement = screen.getByRole("data"); + expect(dataElement).toHaveAttribute("aria-details", "data-tag-success"); + }); + + it("applies the correct aria-details for non-matched string values", () => { + render( + + value === "hello" ? "success" : "error" + } + />, + ); + const dataElement = screen.getByRole("data"); + expect(dataElement).toHaveAttribute("aria-details", "data-tag-error"); + }); + }); + + describe("Number matching", () => { + it("applies the correct aria-details for numeric value success", () => { + render( + (value > 0 ? "success" : "error")} + />, + ); + const dataElement = screen.getByRole("data"); + expect(dataElement).toHaveAttribute("aria-details", "data-tag-success"); + }); + + it("applies the correct aria-details for numeric value error", () => { + render( + (value > 10 ? "success" : "error")} + />, + ); + const dataElement = screen.getByRole("data"); + expect(dataElement).toHaveAttribute("aria-details", "data-tag-error"); + }); + + it("renders an optional provided suffix when using number", () => { + const value = 2; + render(); + + expect(screen.getByText("Test")).toBeInTheDocument(); + expect(screen.getByText(`${value}s`)).toBeInTheDocument(); + }); + + it("renders numbers converted to fixed decimal places when provided", () => { + const value = 0.12345678; + const valueToFixed = value.toFixed(2); + + render(); + + expect(screen.getByText("Test")).toBeInTheDocument(); + expect(screen.getByText(valueToFixed)).toBeInTheDocument(); + }); + + it("should hide data field if value is null or undefined", () => { + render( + , + ); + + expect(screen.getByText("Test")).not.toBeVisible(); + }); + + it("should hide data field if value is falsy", () => { + render(); + + expect(screen.getByText("Test")).not.toBeVisible(); + }); + }); + + describe("DataTagGrid Component", () => { + it("renders a collection of DataTags correctly", () => { + render( + + + + + + , + ); + + const collection = screen.getByRole("grid"); + + expect(collection).toBeInTheDocument(); + expect(screen.getAllByRole("data").length).toEqual(4); + + expect(screen.getByText("Sensor 1")).toBeInTheDocument(); + expect(screen.getByText(/156.2356°/)).toBeInTheDocument(); + }); + }); +}); diff --git a/src/components/datadisplay/DataCard/DataTag.tsx b/src/components/datadisplay/DataCard/DataTag.tsx new file mode 100644 index 00000000..b65cc9f1 --- /dev/null +++ b/src/components/datadisplay/DataCard/DataTag.tsx @@ -0,0 +1,162 @@ +"use client"; + +import { + Box, + Divider, + Grid, + GridProps, + Stack, + Typography, + TypographyProps, +} from "@mui/material"; +import { ReactElement } from "react"; +import type { LucideIcon } from "lucide-react"; + +const defaultTextColour: TypographyProps["color"] = "inherit"; + +interface DataDisplayProps { + label: string; + icon?: LucideIcon; + value?: T; + setColourCallback?: (value: T) => TypographyProps["color"]; +} + +// This is to preserve the T typeguard, so numbers and strings are only allowed certain props +export type DataTagProps = DataDisplayProps & + (T extends number ? { suffix?: string; toFixed?: number } : object) & { + size?: number | "full"; + /** When to hide data field. Null or undefined only hides if value is null or undefined, falsy hides it if the value is 0, false or any other falsy value */ + hideIf?: "nullOrUndefined" | "falsy" | "never"; + /** Shrink width of data tag, as opposed to taking up whole column */ + shrinkWidth?: boolean; + }; + +export const DataTag = ({ + label, + value, + hideIf = "nullOrUndefined", + shrinkWidth = false, + size = 1, + setColourCallback = () => defaultTextColour, + ...props +}: DataTagProps) => { + const colVal: TypographyProps["color"] = value + ? setColourCallback(value) + : "textDisabled"; + + let formattedValue: string | undefined; + + if (typeof value === "number") { + const numericProps = props as DataTagProps; + formattedValue = value.toString(); + if (numericProps.toFixed) + formattedValue = value.toFixed(numericProps.toFixed); + if (numericProps.suffix) + formattedValue = `${formattedValue}${numericProps.suffix}`; + } else { + formattedValue = value; + } + + const handleCopy = () => { + if (formattedValue) { + navigator.clipboard.writeText(formattedValue); + } + }; + + const hideField = () => { + switch (hideIf) { + // This is a switch case in case we want to add more conditions in the future + case "falsy": + return !value; + case "nullOrUndefined": + return formattedValue === null || formattedValue === undefined; + default: + return false; + } + }; + + const gridColumn = + size === "full" ? "1 / -1" : size > 1 ? `span ${size}` : "auto"; + + const contentFitProps = shrinkWidth + ? { + maxWidth: "fit-content", + minHeight: "fit-content", + maxHeight: "fit-content", + } + : {}; + + const Icon = props.icon; + return ( + + + {Icon && } + {label} + + + {formattedValue ?? "?"} + + + + ); +}; + +export interface ResponsiveColumnGridProps extends Pick { + children: ReactElement>[]; +} + +export const DataTagGrid = ({ + children, + spacing = "0.2rem", + ...rest +}: ResponsiveColumnGridProps) => { + return ( + + + {children} + + + ); +}; diff --git a/src/components/datadisplay/DataCard/index.ts b/src/components/datadisplay/DataCard/index.ts index abfa3470..4e91b84e 100644 --- a/src/components/datadisplay/DataCard/index.ts +++ b/src/components/datadisplay/DataCard/index.ts @@ -1,4 +1,5 @@ export { DataCard } from "./DataCard"; export type { DataCardProps } from "./DataCard"; export { DataGroup } from "./DataGroup"; +export { DataTag, DataTagGrid, type DataTagProps } from "./DataTag"; export type { DecoratedValue, DataObjectProps } from "./types"; diff --git a/src/components/datadisplay/DataTag.stories.tsx b/src/components/datadisplay/DataTag.stories.tsx new file mode 100644 index 00000000..7a07898c --- /dev/null +++ b/src/components/datadisplay/DataTag.stories.tsx @@ -0,0 +1,301 @@ +import { Meta, StoryObj } from "@storybook/react-webpack5"; +import { DataTag, DataTagGrid, type DataTagProps } from "./DataCard"; +import { Box, Stack, Typography } from "../MUI/MuiWrapped"; +import { LucideStar } from "lucide-react"; + +const meta = { + title: "Components/Data Display/DataTag", + component: DataTag, + tags: ["autodocs"], + parameters: { + docs: { + description: { + component: + "An extremely compact component to display data in high-density scientific views. Clicking a tag copies its formatted value to the clipboard.", + }, + }, + }, +} satisfies Meta; + +export default meta; +type Story = StoryObj; +type StringStory = StoryObj>; +type NumberStory = StoryObj>; + +const standardStringProps: DataTagProps = { + label: "Label", + value: "Value", + icon: LucideStar, +}; + +const standardNumberProps: DataTagProps = { + label: "Label", + value: 123, + icon: LucideStar, +}; + +export const StandardStringTag: StringStory = { + name: "Standard data tag (with string value)", + args: standardStringProps, + render: (args) => ( + + + + ), + parameters: { + docs: { + description: { + story: + "A tag consists of a label and a value separated by a divider, with an optional Lucide icon. Click the tag to copy the value.", + }, + }, + }, +}; + +export const StandardNumberTag: NumberStory = { + name: "Standard data tag (with number value)", + args: standardNumberProps, + render: (args) => ( + + + + ), + parameters: { + docs: { + description: { + story: "Numeric tags additionally accept `suffix` and `toFixed` props.", + }, + }, + }, +}; + +export const WithoutIcon: Story = { + name: "Without icon", + args: { label: "Label", value: "Value" }, + render: (args) => ( + + + + ), + parameters: { + docs: { + description: { story: "The icon is optional." }, + }, + }, +}; + +export const NumberFormatting: Story = { + name: "Number formatting (suffix and toFixed)", + args: { label: "Label" }, + render: () => ( + + + + + + + ), + parameters: { + docs: { + description: { + story: + "`toFixed` sets the number of decimal places and `suffix` appends a unit. These props are only available when the value is a number. The copied text includes the suffix.", + }, + }, + }, +}; + +export const ColourCallback: Story = { + name: "Colour from value", + args: { label: "Label" }, + render: () => { + const thresholdColour = (value: number) => + value > 90 ? "error" : value > 70 ? "warning" : "success"; + + const statusColour = (value: string) => + value === "Open" ? "success" : "error"; + + return ( + + + + + + + + ); + }, + parameters: { + docs: { + description: { + story: + "`setColourCallback` receives the value and returns a theme colour for the tag's left border. Without it the default colour is used.", + }, + }, + }, +}; + +export const MissingValues: Story = { + name: "Missing and falsy values", + args: { label: "Label" }, + render: () => ( + + Undefined value: + + Zero: + + Empty string: + + + ), + parameters: { + docs: { + description: { + story: + "A missing value is displayed as `?`. Falsy values (including `0` and an empty string) are shown with a disabled border colour and do not invoke `setColourCallback`.", + }, + }, + }, +}; + +export const ShrinkWidth: Story = { + name: "Shrink width", + args: { label: "Label" }, + render: () => ( + + + Default (grows to fill the column): + + + + + + shrinkWidth: + + + + + + ), + parameters: { + docs: { + description: { + story: + "By default a tag takes up the whole column. Set `shrinkWidth` to fit the tag to its content instead.", + }, + }, + }, +}; + +const gridTags = ( + <> + + + + + + + +); + +export const Grid: Story = { + name: "DataTagGrid", + args: { label: "Label" }, + render: () => ( + + Default spacing: + + + + + + + + + + Custom spacing (1rem): + + + + + + + + ), + parameters: { + docs: { + description: { + story: + "`DataTagGrid` lays tags out in a responsive grid: one column on small screens, two on large and three on extra-large. Resize the viewport to see it reflow. `spacing` sets the gap between tags.", + }, + }, + }, +}; + +export const GridSizes: Story = { + name: "Tag size within a grid", + args: { label: "Label" }, + render: () => ( + + + + + + + + + ), + parameters: { + docs: { + description: { + story: + 'Inside a `DataTagGrid`, `size` sets how many columns a tag spans. Use a number for a fixed span, or `"full"` to take the entire row. Best viewed at a wide viewport so the extra columns are visible.', + }, + }, + }, +}; + +export const GridWithHiddenTags: Story = { + name: "Grid with hidden tags", + args: { label: "Label" }, + render: () => ( + + + + + + {gridTags} + + ), + parameters: { + docs: { + description: { + story: + "Hidden tags use `display: none`, so they leave no gap in the grid.", + }, + }, + }, +}; From c07138adf81e17adf07841219540408207cfeb80 Mon Sep 17 00:00:00 2001 From: Guilherme de Freitas Date: Tue, 17 Nov 2026 12:03:34 +0000 Subject: [PATCH 2/3] Update stories to add more features on grid --- .../datadisplay/DataTag.stories.tsx | 26 +++++++++++++++---- 1 file changed, 21 insertions(+), 5 deletions(-) diff --git a/src/components/datadisplay/DataTag.stories.tsx b/src/components/datadisplay/DataTag.stories.tsx index 7a07898c..1495ff1c 100644 --- a/src/components/datadisplay/DataTag.stories.tsx +++ b/src/components/datadisplay/DataTag.stories.tsx @@ -228,12 +228,28 @@ export const Grid: Story = { Default spacing: - - - + + + (v > 90 ? "success" : "error")} + /> - - + "primary"} + /> + "info"} /> Custom spacing (1rem): From 48e282fdeecab11f3dce2ba48d59eee60f6248dd Mon Sep 17 00:00:00 2001 From: Guilherme de Freitas Date: Tue, 17 Nov 2026 12:03:45 +0000 Subject: [PATCH 3/3] Update data tag grid to showcase colours --- src/components/datadisplay/DataTag.stories.tsx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/components/datadisplay/DataTag.stories.tsx b/src/components/datadisplay/DataTag.stories.tsx index 1495ff1c..bda50f42 100644 --- a/src/components/datadisplay/DataTag.stories.tsx +++ b/src/components/datadisplay/DataTag.stories.tsx @@ -243,7 +243,11 @@ export const Grid: Story = { icon={LucideStar} setColourCallback={(v) => (v > 90 ? "success" : "error")} /> - + (v > 1 ? "error" : "success")} + />