Merge pull request #658 from adobe/scatterAnnotation

feat: add scatter annotations

Author: marshallpete

packages/docs/docs/api/visualizations/Scatter.md

@@ -136,7 +136,7 @@ The `Trendline` component is fully supported by `Scatter`. To plot a trendline,
     <tbody>
         <tr>
             <td>children</td>
-            <td>ChartTooltip | ChartPopover | Trendline</td>
+            <td>ChartTooltip | ChartPopover | Trendline | ScatterAnnotation</td>
             <td>–</td>
             <td>Optional elements that can be rendered within the chart.</td>
         </tr>
@@ -198,6 +198,56 @@ The `Trendline` component is fully supported by `Scatter`. To plot a trendline,
     </tbody>
 </table>
 
+### ScatterAnnotation
+
+The `ScatterAnnotation` component can be passed into `Scatter` as a child. This allows you to add text labels directly on scatter plot points, making it easier to identify specific data points or highlight important information.
+
+The component supports an `anchor` prop to define where annotations should be placed relative to their corresponding points. You can pass a single position or an array of positions. When an array is provided, each position is tried in order until one fits within the chart bounds without overlapping other annotations or points. **If a label cannot be placed without overlapping, it will not be displayed. This means scatter annotations should be considered "nice to have" supplemental information.**
+
+#### Example
+
+```jsx
+<Chart data={data}>
+  <Axis baseline grid position="bottom" ticks title="Speed (normal)" />
+  <Axis baseline grid position="left" ticks title="Handling (normal)" />
+  <Scatter dimension="speedNormal" metric="handlingNormal" color="weightClass">
+    <ScatterAnnotation textKey="character" anchor={['right', 'top', 'bottom', 'left']} />
+  </Scatter>
+  <Legend highlight position="right" title="Weight class" />
+  <Title text="Mario Kart 8 Character Data" />
+</Chart>
+```
+
+![Scatter plot with text annotations for each point](/img/scatterAnnotation_light.png#gh-light-mode-only)
+![Scatter plot with text annotations for each point](/img/scatterAnnotation_dark.png#gh-dark-mode-only)
+
+#### Props
+
+<table>
+    <thead>
+        <tr>
+            <th>name</th>
+            <th>type</th>
+            <th>default</th>
+            <th>description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>anchor</td>
+            <td>LabelAnchor | LabelAnchor[]</td>
+            <td>['right', 'top', 'bottom', 'left']</td>
+            <td>Specifies where to position the annotation relative to the data point. Possible values include 'top', 'bottom', 'left', 'right', 'top-left', 'top-right', 'bottom-left', and 'bottom-right'.<br/>When an array is provided, each position is tried in order until one fits within the chart bounds and doesn't overlap with other annotations or points. If no position fits, the annotation is not displayed. This is true even if only one position is supplied.</td>
+        </tr>
+        <tr>
+            <td>textKey</td>
+            <td>string</td>
+            <td>'annotation'</td>
+            <td>The key in the data that contains the text to display for each annotation.</td>
+        </tr>
+    </tbody>
+</table>
+
 ## Advanced
 
 ### ScatterPath

packages/docs/static/img/scatterAnnotation_dark.png

@@ -65,9 +65,6 @@
     "clean": "rm -rf dist",
     "g": "plop component",
     "generate": "plop component",
-    "lint": "eslint src --ext .ts,.tsx,.js,.jsx",
-    "ts": "yarn tsc",
-    "tsc": "tsc --noEmit --skipLibCheck",
     "pack-test": "yarn clean && yarn build && cross-env NODE_ENV=development npm pack",
     "pack": "cross-env NODE_ENV=production npm pack",
     "sonar": "node ./scripts/runSonarOnBranch.js",

packages/docs/static/img/scatterAnnotation_light.png

@@ -0,0 +1,28 @@
+/*
+ * 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 { ScatterAnnotationProps } from '../../types';
+
+// destructure props here and set defaults so that storybook can pick them up
+const ScatterAnnotation: FC<ScatterAnnotationProps> = ({
+  anchor = ['right', 'top', 'bottom', 'left'],
+  textKey = 'annotation',
+}) => {
+  return null;
+};
+
+// displayName is used to validate the component type in the spec builder
+ScatterAnnotation.displayName = 'ScatterAnnotation';
+export { ScatterAnnotation };

packages/react-spectrum-charts/package.json

@@ -0,0 +1,12 @@
+/*
+ * 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 './ScatterAnnotation';

packages/react-spectrum-charts/src/components/ScatterAnnotation/ScatterAnnotation.tsx

@@ -24,7 +24,8 @@ export * from './Line';
 export * from './ScatterPath';
 export * from './MetricRange';
 export * from './ReferenceLine';
+export * from './Scatter';
+export * from './ScatterAnnotation';
 export * from './Title';
 export * from './Trendline';
 export * from './TrendlineAnnotation';
-export * from './Scatter';

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

@@ -330,6 +330,7 @@ describe('rscPropsToSpecBuilderOptions()', () => {
             markType: 'scatter',
             metric: 'countAvg',
             opacity: 'period',
+            scatterAnnotations: [],
             scatterPaths: [{ groupBy: ['event', 'segment'], opacity: 0.2, pathWidth: 'pathWidth' }],
             trendlines: [
               {

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

@@ -23,6 +23,7 @@ import {
   MarkOptions,
   MetricRangeOptions,
   ReferenceLineOptions,
+  ScatterAnnotationOptions,
   ScatterPathOptions,
   SegmentLabelOptions,
   TitleOptions,
@@ -44,6 +45,7 @@ import { Line } from '../components/Line';
 import { MetricRange } from '../components/MetricRange';
 import { ReferenceLine } from '../components/ReferenceLine';
 import { Scatter } from '../components/Scatter';
+import { ScatterAnnotation } from '../components/ScatterAnnotation';
 import { ScatterPath } from '../components/ScatterPath';
 import { Title } from '../components/Title';
 import { Trendline } from '../components/Trendline';
@@ -63,6 +65,7 @@ import {
   LegendProps,
   LineProps,
   ReferenceLineProps,
+  ScatterAnnotationProps,
   ScatterPathProps,
   ScatterProps,
   SegmentLabelProps,
@@ -100,6 +103,7 @@ export const childrenToOptions = (
   marks: MarkOptions[];
   metricRanges: MetricRangeOptions[];
   referenceLines: ReferenceLineOptions[];
+  scatterAnnotations: ScatterAnnotationOptions[];
   scatterPaths: ScatterPathOptions[];
   segmentLabels: SegmentLabelOptions[];
   titles: TitleOptions[];
@@ -119,6 +123,7 @@ export const childrenToOptions = (
   const metricRanges: MetricRangeOptions[] = [];
   const referenceLines: ReferenceLineOptions[] = [];
   const segmentLabels: SegmentLabelOptions[] = [];
+  const scatterAnnotations: ScatterAnnotationOptions[] = [];
   const scatterPaths: ScatterPathOptions[] = [];
   const titles: TitleOptions[] = [];
   const trendlineAnnotations: TrendlineAnnotationOptions[] = [];
@@ -199,6 +204,10 @@ export const childrenToOptions = (
         marks.push(getScatterOptions(child.props as ScatterProps));
         break;
 
+      case ScatterAnnotation.displayName:
+        scatterAnnotations.push(child.props as ScatterAnnotationProps);
+        break;
+
       case ScatterPath.displayName:
         scatterPaths.push(child.props as ScatterPathProps);
         break;
@@ -241,6 +250,7 @@ export const childrenToOptions = (
     marks,
     metricRanges,
     referenceLines,
+    scatterAnnotations,
     scatterPaths,
     segmentLabels,
     titles,

packages/react-spectrum-charts/src/rscToSbAdapter/chartAdapter.test.ts

@@ -15,12 +15,13 @@ import { ScatterProps } from '../types';
 import { childrenToOptions } from './childrenAdapter';
 
 export const getScatterOptions = ({ children, ...scatterProps }: ScatterProps): ScatterOptions => {
-  const { chartPopovers, chartTooltips, scatterPaths, trendlines } = childrenToOptions(children);
+  const { chartPopovers, chartTooltips, scatterAnnotations, scatterPaths, trendlines } = childrenToOptions(children);
   return {
     ...scatterProps,
     chartPopovers,
     chartTooltips,
     markType: 'scatter',
+    scatterAnnotations,
     scatterPaths,
     trendlines,
   };