Merge pull request #810 from adobe/feat/s2-line-forecast

feat: create s2 LineForecast component

Author: madelineluke

packages/docs/docs/spectrum2/line.md

@@ -192,6 +192,61 @@ The transition between segments is seamless — the line connects solid and dott
 
 ---
 
+## Forecast (LineForecast)
+
+The `LineForecast` component is an S2-exclusive child of `Line`. It visually distinguishes a forecast region from historical data: the line transitions from solid to dotted at the forecast boundary, a vertical rule marks the start of the forecast, and an optional label appears above the rule.
+
+```jsx
+<Chart data={data}>
+  <Axis position="bottom" labelFormat="time" ticks baseline />
+  <Axis position="left" grid />
+  <Line color="series" metric="value" dimension="datetime" scaleType="time">
+    <LineForecast metric="forecastValue" start={1725148800000} label="Forecast" />
+  </Line>
+</Chart>
+```
+
+The `start` value must be a dimension value that exists in the data (for time axes, epoch milliseconds). Rows at or after `start` are rendered as the forecast segment. Rows before `start` use the `metric` field on `Line`; rows in the forecast region use the `metric` field on `LineForecast`.
+
+When `gradient` is set on the parent `Line`, the gradient is also rendered in the forecast region at a reduced opacity (40% of the historical gradient) to reinforce the uncertainty of the forecast.
+
+### LineForecast props
+
+<table>
+    <thead>
+        <tr>
+            <th>name</th>
+            <th>type</th>
+            <th>default</th>
+            <th>description</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>metric *</td>
+            <td>string</td>
+            <td>–</td>
+            <td>Key in the data containing the forecast values.</td>
+        </tr>
+        <tr>
+            <td>start *</td>
+            <td>number | string</td>
+            <td>–</td>
+            <td>Dimension value at which the forecast begins. For time axes, provide epoch milliseconds. Rows at or after this value are rendered as the forecast segment.</td>
+        </tr>
+        <tr>
+            <td>label</td>
+            <td>string</td>
+            <td>'Forecast'</td>
+            <td>Text shown above the boundary rule. Hidden automatically when fewer than 80px remain between the boundary and the right edge of the chart.</td>
+        </tr>
+    </tbody>
+</table>
+
+_* required_
+
+---
+
 ## Line props (S2)
 
 :::note Not all base Line props are supported
@@ -210,9 +265,9 @@ The S2 `Line` component does not yet support `onMouseOver`, `onMouseOut`, `Metri
     <tbody>
         <tr>
             <td>children</td>
-            <td>ChartInspect | ChartPopover | LineDirectLabel</td>
+            <td>ChartInspect | ChartPopover | LineDirectLabel | LineForecast</td>
             <td>–</td>
-            <td>Optional child components for tooltips, popovers, and inline direct labels.</td>
+            <td>Optional child components for tooltips, popovers, inline direct labels, and forecast regions.</td>
         </tr>
         <tr>
             <td>color</td>

packages/react-spectrum-charts-s2/src/components/LineForecast/LineForecast.tsx

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2026 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 { LineForecastProps } from '../../types';
+
+const LineForecast: FC<LineForecastProps> = ({ metric, start, label }: LineForecastProps) => {
+  return null;
+};
+
+LineForecast.displayName = 'LineForecast';
+
+export { LineForecast };

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

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2026 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 { LineForecast } from './LineForecast';

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

@@ -20,6 +20,7 @@ export * from './EmptyState';
 export * from './Legend';
 export * from './Line';
 export * from './LineDirectLabel';
+export * from './LineForecast';
 export * from './LoadingState';
 export * from './ReferenceLine';
 export * from './Title';

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

@@ -255,6 +255,7 @@ describe('rscPropsToSpecBuilderOptions()', () => {
             chartInspects: [],
             color: 'series',
             dimension: 'datetime',
+            forecasts: [],
             hasOnClick: false,
             hasOnContextMenu: false,
             lineDirectLabels: [],

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

@@ -18,6 +18,7 @@ import {
   ChartPopoverOptions,
   DonutSummaryOptions,
   LegendOptions,
+  LineForecastOptions,
   LineDirectLabelOptions,
   LineOptions,
   MarkOptions,
@@ -35,6 +36,7 @@ import { ChartPopover } from '../components/ChartPopover';
 import { Legend } from '../components/Legend';
 import { Line } from '../components/Line';
 import { LineDirectLabel } from '../components/LineDirectLabel';
+import { LineForecast } from '../components/LineForecast';
 import { ReferenceLine } from '../components/ReferenceLine';
 import { Title } from '../components/Title';
 import { Donut, DonutSummary, SegmentLabel } from '../rc';
@@ -48,6 +50,7 @@ import {
   DonutProps,
   DonutSummaryProps,
   LegendProps,
+  LineForecastProps,
   LineDirectLabelProps,
   LineProps,
   ReferenceLineProps,
@@ -73,6 +76,7 @@ export const childrenToOptions = (
   chartInspects: ChartInspectOptions[];
   chartPopovers: ChartPopoverOptions[];
   donutSummaries: DonutSummaryOptions[];
+  forecasts: LineForecastOptions[];
   legends: LegendOptions[];
   lineDirectLabels: LineDirectLabelOptions[];
   lines: LineOptions[];
@@ -88,6 +92,7 @@ export const childrenToOptions = (
   const chartInspects: ChartInspectOptions[] = [];
   const chartPopovers: ChartPopoverOptions[] = [];
   const donutSummaries: DonutSummaryOptions[] = [];
+  const forecasts: LineForecastOptions[] = [];
   const legends: LegendOptions[] = [];
   const lineDirectLabels: LineDirectLabelOptions[] = [];
   const lines: LineOptions[] = [];
@@ -138,6 +143,10 @@ export const childrenToOptions = (
         legends.push(getLegendOptions(child.props as LegendProps));
         break;
 
+      case LineForecast.displayName:
+        forecasts.push(child.props as LineForecastProps);
+        break;
+
       case LineDirectLabel.displayName:
         lineDirectLabels.push(child.props as LineDirectLabelProps);
         break;
@@ -172,6 +181,7 @@ export const childrenToOptions = (
     chartInspects,
     chartPopovers,
     donutSummaries,
+    forecasts,
     legends,
     lineDirectLabels,
     lines,

packages/react-spectrum-charts-s2/src/rscToSbAdapter/lineAdapter.test.ts

@@ -15,6 +15,7 @@ import { DEFAULT_COLOR } from '@spectrum-charts/constants';
 
 import { ChartPopover } from '../components/ChartPopover';
 import { ChartInspect } from '../components/ChartInspect';
+import { LineForecast } from '../components/LineForecast';
 import { getLineOptions } from './lineAdapter';
 
 describe('getLineOptions()', () => {
@@ -41,6 +42,18 @@ describe('getLineOptions()', () => {
     expect(getLineOptions({ onContextMenu: () => {} }).hasOnContextMenu).toBe(true);
     expect(getLineOptions({ onContextMenu: undefined }).hasOnContextMenu).toBe(false);
   });
+  it('should convert LineForecast children to forecasts array', () => {
+    const options = getLineOptions({
+      children: [createElement(LineForecast, { metric: 'forecastValue', start: 1725148800000 })],
+    });
+    expect(options.forecasts).toHaveLength(1);
+    expect(options.forecasts?.[0]).toHaveProperty('metric', 'forecastValue');
+    expect(options.forecasts?.[0]).toHaveProperty('start', 1725148800000);
+  });
+  it('should return empty forecasts array when no LineForecast children', () => {
+    const options = getLineOptions({});
+    expect(options.forecasts).toHaveLength(0);
+  });
   it('should pass through included props', () => {
     const options = getLineOptions({ color: DEFAULT_COLOR });
     expect(options).toHaveProperty('color', DEFAULT_COLOR);

packages/react-spectrum-charts-s2/src/rscToSbAdapter/lineAdapter.ts

@@ -15,11 +15,12 @@ import { LineProps } from '../types';
 import { childrenToOptions } from './childrenAdapter';
 
 export const getLineOptions = ({ children, onClick, onContextMenu, contextMenuMode: _contextMenuMode, ...lineProps }: LineProps): LineOptions => {
-  const { chartInspects, chartPopovers, lineDirectLabels } = childrenToOptions(children);
+  const { chartInspects, chartPopovers, forecasts, lineDirectLabels } = childrenToOptions(children);
   return {
     ...lineProps,
     chartInspects,
     chartPopovers,
+    forecasts,
     hasOnClick: Boolean(onClick),
     hasOnContextMenu: Boolean(onContextMenu),
     lineDirectLabels,