Gauge

package.json

@@ -118,7 +118,7 @@
     "chalk": "4.1.2",
     "clean-webpack-plugin": "^4.0.0",
     "concurrently": "^8.0.0",
-    "cross-env": "^7.0.3",
+    "cross-env": "^10.1.0",
     "css-loader": "^7.1.2",
     "eslint": "^8.29.0",
     "eslint-config-prettier": "^9.0.0",
@@ -175,5 +175,6 @@
     "React",
     "Spectrum",
     "Charts"
-  ]
+  ],
+  "dependencies": {}
 }

packages/constants/constants.ts

@@ -18,6 +18,7 @@ export const DEFAULT_AXIS_ANNOTATION_COLOR = 'gray-600';
 export const DEFAULT_AXIS_ANNOTATION_OFFSET = 80;
 export const DEFAULT_BACKGROUND_COLOR = 'transparent';
 export const DEFAULT_BULLET_DIRECTION = 'column';
+export const DEFAULT_GAUGE_DIRECTION = 'column';
 export const DEFAULT_CATEGORICAL_DIMENSION = 'category';
 export const DEFAULT_COLOR = 'series';
 export const DEFAULT_COLOR_SCHEME = 'light';
@@ -35,6 +36,8 @@ export const DEFAULT_LINE_WIDTHS = ['M'];
 export const DEFAULT_LINEAR_DIMENSION = 'x';
 export const DEFAULT_LOCALE = 'en-US';
 export const DEFAULT_METRIC = 'value';
+export const DEFAULT_MAX_ARC_VALUE = 100;
+export const DEFAULT_MIN_ARC_VALUE = 0;
 export const DEFAULT_SCALE_TYPE = 'normal';
 export const DEFAULT_SCALE_VALUE = 100;
 export const DEFAULT_SECONDARY_COLOR = 'subSeries';

packages/docs/docs/api/visualizations/Gauge.md

@@ -0,0 +1,62 @@
+## ALPHA RELEASE 
+
+Gauge is currently in alpha. This means that the component, behavior and API are all subject to change. 
+
+```
+import { Chart, ChartProps } from '@adobe/react-spectrum-charts';
+import { Gauge, GaugeSummary, SegmentLabel } from '@adobe/react-spectrum-charts/rc';
+```
+
+# Gauge
+
+The `Gauge` component is used to display data in a dashboard gauge style. 
+
+## Data visualization 
+
+Unlike many other chart types, `Gauge` draws two marks (arcs) for a given series, and a mark needle for progression measurement and data tracking. The two arcs shown are the backgrounds arc and the filling color arc, showing the progress based on the current value.
+
+
+## Props
+
+<table>
+    <thead>
+        <tr>
+            <th>name</th>
+            <th>type</th>
+            <th>default</th>
+            <th>description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>color</td>
+            <td>string</td>
+            <td>'series'</td>
+            <td>Key in the data that is used as the color to current value.</td>
+        </tr>
+        <tr>
+            <td>currVal</td>
+            <td>number</td>
+            <td>75</td>
+            <td>The current value tracked and its progress in the gauge. Set to 75 out of 100 by default.</td>
+        </tr>
+        <tr>
+            <td>metric</td>
+            <td>number</td>
+            <td>'value'</td>
+            <td>The key in the data that is used for the current value.</td>
+        </tr>
+        <tr>
+            <td>maxArcValue</td>
+            <td>number</td>
+            <td>100</td>
+            <td>The maximum value of the arc in the gauge. Set to 100 by default.</td>
+        </tr>
+                <tr>
+            <td>minArcValue</td>
+            <td>number</td>
+            <td>0</td>
+            <td>The minimum value of the arc in the gauge. Set to 0 by default.</td>
+        </tr>
+   </tbody>
+</table>

packages/react-spectrum-charts/src/alpha/components/Gauge/Gauge.tsx

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { FC } from 'react';
+
+import {
+  DEFAULT_MAX_ARC_VALUE,
+  DEFAULT_MIN_ARC_VALUE,
+} from '@spectrum-charts/constants';
+
+import { GaugeProps } from '../../../types';
+
+// I assume this houses all the props for all variations of a Gauge chart?
+const Gauge: FC<GaugeProps> = ({
+  name = 'gauge0',
+  metric = 'currentAmount', // CurrVal
+  minArcValue = DEFAULT_MIN_ARC_VALUE, // Min Arc Value
+  maxArcValue = DEFAULT_MAX_ARC_VALUE, // Max Arc Value
+}) => {
+  return null;
+};
+
+// displayName is used to validate the component type in the spec builder
+Gauge.displayName = 'Gauge';
+
+export { Gauge };

packages/react-spectrum-charts/src/alpha/components/Gauge/index.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export * from './Gauge';

packages/react-spectrum-charts/src/alpha/components/index.ts

@@ -13,3 +13,4 @@
 export * from './Bullet';
 export * from './Combo';
 export * from './Venn';
+export * from './Gauge/Gauge';

packages/react-spectrum-charts/src/rscToSbAdapter/childrenAdapter.ts

@@ -18,6 +18,7 @@ import {
   ChartPopoverOptions,
   ChartTooltipOptions,
   DonutSummaryOptions,
+  GaugeOptions,
   LegendOptions,
   LineOptions,
   MarkOptions,
@@ -30,7 +31,7 @@ import {
   TrendlineOptions,
 } from '@spectrum-charts/vega-spec-builder';
 
-import { Bullet, Combo, Venn } from '../alpha';
+import { Bullet, Combo, Gauge, Venn } from '../alpha';
 import { Annotation } from '../components/Annotation';
 import { Area } from '../components/Area';
 import { Axis } from '../components/Axis';
@@ -158,6 +159,10 @@ export const childrenToOptions = (
         marks.push({ ...child.props, markType: 'bullet' } as BulletOptions);
         break;
 
+      case Gauge.displayName:
+        marks.push({ ...child.props, markType: 'gauge' } as GaugeOptions);
+        break;
+
       case ChartPopover.displayName:
         chartPopovers.push(getChartPopoverOptions(child.props as ChartPopoverProps));
         break;

packages/react-spectrum-charts/src/stories/components/Bullet/Bullet.story.tsx

@@ -39,7 +39,7 @@ const BulletStory: StoryFn<BulletProps & { width?: number; height?: number }> =
   const { width, height, ...bulletProps } = args;
   const chartProps = useChartProps({ ...defaultChartProps, width: width ?? 350, height: height ?? 350 });
   return (
-    <Chart {...chartProps}>
+    <Chart {...chartProps} debug>
       <Bullet {...bulletProps} />
     </Chart>
   );

packages/react-spectrum-charts/src/stories/components/Gauge/Gauge.story.tsx

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { ReactElement } from 'react';
+
+import { StoryFn } from '@storybook/react';
+
+import { Chart } from '../../../Chart';
+// Gauge chart component from alpha export
+import { Gauge } from '../../../alpha';
+import { Title } from '../../../components';
+import useChartProps from '../../../hooks/useChartProps';
+import { bindWithProps } from '../../../test-utils';
+import { GaugeProps, ChartProps } from '../../../types';
+import { basicGaugeData } from './data';
+
+export default {
+  title: 'RSC/Gauge (alpha)',
+  component: Gauge,
+};
+
+// Default chart properties
+const defaultChartProps: ChartProps = {
+  data: basicGaugeData,
+  width: 500,
+  height: 600,
+};
+
+// Basic Gauge chart story
+const GaugeStory: StoryFn<GaugeProps & { width?: number; height?: number }> = (args): ReactElement => {
+  const { width, height, ...gaugeProps } = args;
+  const chartProps = useChartProps({ ...defaultChartProps, width: width ?? 500, height: height ?? 500 });
+  return (
+    <Chart {...chartProps} debug>
+      <Gauge {...gaugeProps} />
+    </Chart>
+  );
+};
+
+// Gauge with Title
+const GaugeTitleStory: StoryFn<typeof Gauge> = (args): ReactElement => {
+  const chartProps = useChartProps({ ...defaultChartProps, width: 400 });
+  return (
+    <Chart {...chartProps}>
+      <Title text={'Title Gauge'} position={'start'} orient={'top'} />
+      <Gauge {...args} />
+    </Chart>
+  );
+};
+
+// Basic Gauge chart story. All the ones below it are variations of the Gauge chart. 
+const Basic = bindWithProps(GaugeStory);
+Basic.args = {
+  metric: 'currentAmount',
+  color: 'blue-900',
+};
+
+const GaugeVariation2 = bindWithProps(GaugeStory);
+GaugeVariation2.args = {
+  metric: 'currentAmount',
+  color: 'red-900',
+};
+
+const GaugeVariation3 = bindWithProps(GaugeStory);
+GaugeVariation3.args = {
+  metric: 'currentAmount',
+  color: 'fuchsia-900',
+};
+
+
+
+export { Basic, GaugeVariation2, GaugeVariation3 };

packages/react-spectrum-charts/src/stories/components/Gauge/Gauge.test.tsx

@@ -0,0 +1,36 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { Gauge } from '../../../alpha';
+import { findChart, findMarksByGroupName, render } from '../../../test-utils';
+import { Basic } from './Gauge.story';
+
+describe('Gauge', () => {
+  // Gauge is not a real React component. This test provides test coverage for sonarqube
+  test('Gauge pseudo element', () => {
+    render(<Gauge />);
+  });
+
+  test('Basic gauge renders properly', async () => {
+    render(<Basic {...Basic.args} />);
+    const chart = await findChart();
+    expect(chart).toBeInTheDocument();
+
+    const backgroundArc = await findMarksByGroupName(chart, 'BackgroundArcRounded');
+    expect(backgroundArc).toBeDefined();
+
+    const fillerArc = await findMarksByGroupName(chart, 'FillerArc');
+    expect(fillerArc).toBeDefined();
+
+    const needleRule = await findMarksByGroupName(chart, 'Needle', 'line');
+    expect(needleRule).toBeDefined();
+  });
+});

packages/react-spectrum-charts/src/stories/components/Gauge/data.ts

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+
+export const basicGaugeData = [
+  { graphLabel: 'Customers', currentAmount: 60, target: 80 },
+];
+
+

packages/react-spectrum-charts/src/types/chart.types.ts

@@ -36,6 +36,7 @@ import {
   ComboElement,
   DonutElement,
   DonutSummaryElement,
+  GaugeElement,
   LineElement,
   MetricRangeElement,
   ScatterElement,
@@ -54,6 +55,7 @@ export type ChartChildElement =
   | BigNumberElement
   | DonutElement
   | ComboElement
+  | GaugeElement
   | LegendElement
   | LineElement
   | ScatterElement

packages/react-spectrum-charts/src/types/marks/gauge.types.ts

@@ -0,0 +1,18 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { JSXElementConstructor, ReactElement } from 'react';
+
+import { GaugeOptions } from '@spectrum-charts/vega-spec-builder'; // TODO: update this when GaugeOptions is added
+
+export interface GaugeProps extends Omit<GaugeOptions, 'markType'> {}
+
+export type GaugeElement = ReactElement<GaugeProps, JSXElementConstructor<GaugeProps>>;

packages/react-spectrum-charts/src/types/marks/index.ts

@@ -16,6 +16,7 @@ export * from './bigNumber.types';
 export * from './bullet.types';
 export * from './combo.types';
 export * from './donut.types';
+export * from './gauge.types';
 export * from './line.types';
 export * from './scatter.types';
 export * from './venn.types';