@classic-homes/charts-core 0.4.2 → 0.6.0

package/dist/index.cjs

@@ -424,6 +424,159 @@ function createTooltipFormatter(options = {}) {
   };
 }
 
+// src/utils/forecast.ts
+var DEFAULT_FORECAST_LABEL = "Forecast";
+function forecastStart(source) {
+  const from = source.forecastFrom;
+  if (from == null || !Number.isFinite(from)) return void 0;
+  const index = Math.max(0, Math.floor(from));
+  return index < source.data.length ? index : void 0;
+}
+function hasForecast(series) {
+  return !!series?.some((s) => forecastStart(s) !== void 0);
+}
+function forecastTagLookup(series) {
+  if (!hasForecast(series)) return void 0;
+  return (dataIndex) => {
+    for (const s of series) {
+      const from = forecastStart(s);
+      if (from !== void 0 && dataIndex >= from) return s.forecastLabel || DEFAULT_FORECAST_LABEL;
+    }
+    return void 0;
+  };
+}
+function describeForecast(categories, series) {
+  let first;
+  for (const s of series) {
+    const from = forecastStart(s);
+    if (from === void 0 || first && first.index <= from) continue;
+    first = { index: from, label: s.forecastLabel || DEFAULT_FORECAST_LABEL };
+  }
+  if (!first) return void 0;
+  const category = categories[first.index] ?? "";
+  return `Values from ${category} onward are marked ${first.label.toLowerCase()}`;
+}
+var isPlainObject = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+function blank(item) {
+  if (Array.isArray(item)) return [item[0], null];
+  return null;
+}
+function bare(item) {
+  return isPlainObject(item) && "value" in item ? item.value : item;
+}
+function withItem(item, extra) {
+  if (isPlainObject(item) && "value" in item) {
+    return {
+      ...item,
+      ...extra,
+      itemStyle: { ...item.itemStyle, ...extra.itemStyle }
+    };
+  }
+  return { value: item, ...extra };
+}
+function withForecastPoints(data, source, pointSize = 0) {
+  const from = forecastStart(source);
+  if (from === void 0) return [...data];
+  const size = Math.max(pointSize, 6) + 1;
+  return data.map(
+    (item, index) => index >= from ? withItem(item, { symbol: "emptyCircle", symbolSize: size }) : item
+  );
+}
+function withForecastBars(data, source, color) {
+  const from = forecastStart(source);
+  if (from === void 0) return [...data];
+  return data.map(
+    (item, index) => index >= from ? withItem(item, {
+      itemStyle: {
+        opacity: 0.45,
+        borderColor: color,
+        borderWidth: 1.5,
+        borderType: "dashed"
+      }
+    }) : item
+  );
+}
+function withForecastLines(series, sources, { colors: colors3 }) {
+  if (!hasForecast(sources)) return series;
+  const stackFrom = /* @__PURE__ */ new Map();
+  series.forEach((s, index) => {
+    const from = forecastStart(sources[index]);
+    if (s.stack == null || from === void 0) return;
+    stackFrom.set(s.stack, Math.min(stackFrom.get(s.stack) ?? Infinity, from));
+  });
+  const mains = [];
+  const companions = [];
+  series.forEach((s, index) => {
+    const from = s.stack != null ? stackFrom.get(s.stack) : forecastStart(sources[index]);
+    if (from === void 0) {
+      mains.push(s);
+      return;
+    }
+    const color = colors3[index];
+    const itemStyle = { ...s.itemStyle, color };
+    if (from === 0) {
+      mains.push({
+        ...s,
+        itemStyle,
+        lineStyle: { ...s.lineStyle, type: "dashed" },
+        ...s.areaStyle && { areaStyle: fadedArea(s.areaStyle) }
+      });
+      return;
+    }
+    const data = s.data ?? [];
+    const common = {
+      name: s.name,
+      type: "line",
+      smooth: s.smooth,
+      connectNulls: s.connectNulls,
+      showSymbol: false,
+      symbol: "none",
+      silent: true,
+      legendHoverLink: false,
+      tooltip: { show: false },
+      emphasis: { disabled: true },
+      itemStyle,
+      z: s.z
+    };
+    companions.push(
+      {
+        ...common,
+        data: data.map((item, i) => i < from ? bare(item) : blank(item)),
+        stack: s.stack != null ? `${s.stack}\0actual` : void 0,
+        lineStyle: s.lineStyle,
+        areaStyle: s.areaStyle
+      },
+      {
+        ...common,
+        data: data.map((item, i) => i >= from - 1 ? bare(item) : blank(item)),
+        stack: s.stack != null ? `${s.stack}\0forecast` : void 0,
+        lineStyle: { ...s.lineStyle, type: "dashed" },
+        areaStyle: s.areaStyle ? fadedArea(s.areaStyle) : void 0
+      }
+    );
+    mains.push({
+      ...s,
+      itemStyle,
+      // Forecast points carry their own size; the rest keep theirs (none
+      // when the series hid its points)
+      showSymbol: true,
+      symbolSize: s.showSymbol === false ? 0 : s.symbolSize ?? 4,
+      lineStyle: { ...s.lineStyle, opacity: 0 },
+      areaStyle: void 0,
+      emphasis: {
+        ...s.emphasis,
+        focus: "none",
+        lineStyle: { ...s.emphasis?.lineStyle, opacity: 0 }
+      },
+      z: (s.z ?? 2) + 1
+    });
+  });
+  return [...mains, ...companions];
+}
+function fadedArea(areaStyle) {
+  return { ...areaStyle, opacity: (areaStyle.opacity ?? 0.7) * 0.5 };
+}
+
 // src/utils/accessibility.ts
 var isNumber = (value) => typeof value === "number" && Number.isFinite(value);
 function seriesList(names) {
@@ -449,6 +602,8 @@ function describeTrends(title, kind, data, format) {
     0
   );
   if (missing > 0) description += `. ${missing} values are missing`;
+  const forecast = describeForecast(data.categories, data.series);
+  if (forecast) description += `. ${forecast}`;
   return description;
 }
 function generateLineChartDescription(title, data, format) {
@@ -484,6 +639,8 @@ function generateBarChartDescription(title, data, format) {
   if (max && min) {
     description += `. Highest value is ${formatValue(max.value, format)} for ${max.category}. Lowest value is ${formatValue(min.value, format)} for ${min.category}`;
   }
+  const forecast = describeForecast(data.categories, data.series);
+  if (forecast) description += `. ${forecast}`;
   return description;
 }
 function generateDotPlotDescription(title, data, format) {
@@ -617,7 +774,7 @@ function getReplaceMerge(prev, next, isComponentType) {
   }
   return [...types].filter((type) => isComponentType(type));
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   if (value === null || typeof value !== "object") return false;
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
@@ -630,7 +787,7 @@ function mergeValue(base, override, topLevel = false) {
     const length = Math.max(from.length, to.length);
     return Array.from({ length }, (_, index) => mergeValue(from[index], to[index]));
   }
-  if (isPlainObject(base) && isPlainObject(override)) {
+  if (isPlainObject2(base) && isPlainObject2(override)) {
     const merged = { ...base };
     for (const key of Object.keys(override)) {
       merged[key] = mergeValue(base[key], override[key]);
@@ -649,6 +806,66 @@ function mergeChartOption(generated, override) {
   return merged;
 }
 
+// src/utils/ghost.ts
+var GHOST_LINE_OPACITY = 0.6;
+var GHOST_BAR_OPACITY = 0.35;
+var GHOST_STACK = "\0ghost";
+function isGhostSeries(source) {
+  return source?.variant === "ghost";
+}
+function hasGhostSeries(series) {
+  return !!series?.some(isGhostSeries);
+}
+function withoutGhostSeries(series) {
+  return series.filter((s) => !isGhostSeries(s));
+}
+function ghostStackId(stack, source) {
+  if (stack === void 0 || !isGhostSeries(source) || stack.endsWith(GHOST_STACK)) return stack;
+  return `${stack}${GHOST_STACK}`;
+}
+var isPlainObject3 = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+function withoutItemLabels(data) {
+  if (!Array.isArray(data)) return data;
+  return data.map(
+    (item) => isPlainObject3(item) && item.label ? { ...item, label: { ...item.label, show: false } } : item
+  );
+}
+function withGhostSeries(series, sources) {
+  if (!hasGhostSeries(sources)) return series;
+  return series.map((s, index) => {
+    const source = sources[index];
+    if (!isGhostSeries(source)) return s;
+    const common = {
+      ...s,
+      stack: ghostStackId(s.stack, source),
+      data: withoutItemLabels(s.data),
+      label: { ...s.label, show: false }
+    };
+    if (s.type === "bar") {
+      return {
+        ...common,
+        itemStyle: { ...s.itemStyle, opacity: GHOST_BAR_OPACITY },
+        emphasis: {
+          ...s.emphasis,
+          itemStyle: { ...s.emphasis?.itemStyle, opacity: GHOST_BAR_OPACITY + 0.2 }
+        }
+      };
+    }
+    return {
+      ...common,
+      showSymbol: false,
+      areaStyle: void 0,
+      lineStyle: { ...s.lineStyle, type: "dashed", opacity: GHOST_LINE_OPACITY },
+      itemStyle: { ...s.itemStyle, opacity: GHOST_LINE_OPACITY },
+      emphasis: {
+        ...s.emphasis,
+        areaStyle: void 0
+      },
+      z: (s.z ?? 2) - 1
+    };
+  });
+}
+
 // src/utils/stats.ts
 var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 var clean = (value) => Number(value.toPrecision(12));
@@ -801,20 +1018,26 @@ function waterfallLayout(steps) {
 }
 function toPercentStack(series) {
   const length = Math.max(0, ...series.map((s) => s.data.length));
-  const totals = Array.from(
+  const sumOf = (ghost) => Array.from(
     { length },
     (_, index) => series.reduce((sum, s) => {
+      if (s.variant === "ghost" !== ghost) return sum;
       const value = s.data[index];
       return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
     }, 0)
   );
-  return series.map((s) => ({
-    ...s,
-    data: s.data.map((value, index) => {
-      if (!isFiniteNumber(value)) return null;
-      return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
-    })
-  }));
+  const totals = sumOf(false);
+  const ghostTotals = sumOf(true);
+  return series.map((s) => {
+    const sums = s.variant === "ghost" ? ghostTotals : totals;
+    return {
+      ...s,
+      data: s.data.map((value, index) => {
+        if (!isFiniteNumber(value)) return null;
+        return sums[index] === 0 ? 0 : clean(value / sums[index] * 100);
+      })
+    };
+  });
 }
 function stackTotals(series, stacked) {
   const length = Math.max(0, ...series.map((s) => s.data.length));
@@ -1038,12 +1261,17 @@ function nameLabelLookup(nodes) {
 function hasPointLabels(series) {
   return series.some((s) => s.labels?.some((text) => text != null && text !== ""));
 }
-function buildTooltip(base, { show, formatter, valueFormatter, getLabel }) {
+function buildTooltip(base, { show, formatter, valueFormatter, getLabel, forecastTag }) {
   if (!show) return void 0;
-  if (formatter === void 0 && valueFormatter === void 0) return base;
+  if (formatter === void 0 && valueFormatter === void 0 && !forecastTag) return base;
   const tooltip = { ...base };
-  if (valueFormatter) {
-    tooltip.valueFormatter = (value) => typeof value === "number" ? valueFormatter(value) : String(value ?? "");
+  if (valueFormatter || forecastTag) {
+    const format = (value) => typeof value === "number" ? valueFormatter ? valueFormatter(value) : value.toLocaleString() : String(value ?? "");
+    tooltip.valueFormatter = (value, dataIndex) => {
+      const text = format(value);
+      const tag = dataIndex === void 0 ? void 0 : forecastTag?.(dataIndex);
+      return tag && value != null ? `${text} (${tag})` : text;
+    };
   }
   if (typeof formatter === "string") {
     tooltip.formatter = formatter;
@@ -1587,6 +1815,9 @@ function downloadCsv(table, filename) {
   );
 }
 
+exports.DEFAULT_FORECAST_LABEL = DEFAULT_FORECAST_LABEL;
+exports.GHOST_BAR_OPACITY = GHOST_BAR_OPACITY;
+exports.GHOST_LINE_OPACITY = GHOST_LINE_OPACITY;
 exports.THEME_DARK = THEME_DARK;
 exports.THEME_LIGHT = THEME_LIGHT;
 exports.abbreviateNumber = abbreviateNumber;
@@ -1614,9 +1845,12 @@ exports.computeDelta = computeDelta;
 exports.createTooltipFormatter = createTooltipFormatter;
 exports.darkChartColors = darkChartColors;
 exports.darkTheme = darkTheme;
+exports.describeForecast = describeForecast;
 exports.downloadCsv = downloadCsv;
 exports.downloadFile = downloadFile;
 exports.escapeHtml = escapeHtml;
+exports.forecastStart = forecastStart;
+exports.forecastTagLookup = forecastTagLookup;
 exports.formatCurrency = formatCurrency;
 exports.formatDate = formatDate;
 exports.formatNumber = formatNumber;
@@ -1642,10 +1876,14 @@ exports.generateWaterfallDescription = generateWaterfallDescription;
 exports.getChartColors = getChartColors;
 exports.getLegendItems = getLegendItems;
 exports.getReplaceMerge = getReplaceMerge;
+exports.ghostStackId = ghostStackId;
 exports.gridInset = gridInset;
+exports.hasForecast = hasForecast;
+exports.hasGhostSeries = hasGhostSeries;
 exports.hasPointLabels = hasPointLabels;
 exports.heatmapTable = heatmapTable;
 exports.histogramTable = histogramTable;
+exports.isGhostSeries = isGhostSeries;
 exports.itemLabelLookup = itemLabelLookup;
 exports.legendCenter = legendCenter;
 exports.lightChartColors = lightChartColors;
@@ -1674,6 +1912,11 @@ exports.valueLabelFormatter = valueLabelFormatter;
 exports.waterfallLayout = waterfallLayout;
 exports.waterfallTable = waterfallTable;
 exports.withEndLabelInset = withEndLabelInset;
+exports.withForecastBars = withForecastBars;
+exports.withForecastLines = withForecastLines;
+exports.withForecastPoints = withForecastPoints;
+exports.withGhostSeries = withGhostSeries;
 exports.withPointLabels = withPointLabels;
 exports.withReferenceMarks = withReferenceMarks;
 exports.withZoomInset = withZoomInset;
+exports.withoutGhostSeries = withoutGhostSeries;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.cjs';
 import { ValueFormat, CategoryChartData, BarChartData, BoxPlotStats, BulletItem, HistogramBucket, LineChartData, PieSliceData, ScatterChartData, WaterfallStep, ChartFormatter, LabelFormatterParams, TooltipFormatterParams, AxisConfig, ChartLegendConfig, ReferenceBand, ReferenceLine, LegendItem, HistogramBin, CategorySeriesData, ChartDataTable, CandlestickData, HeatmapData, RadarChartData, RadarIndicator, SankeyData, TreemapNode } from './types/index.cjs';
-export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.cjs';
+export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.cjs';
 import 'echarts';
 import 'echarts/core';
 
@@ -151,6 +151,113 @@ declare function getReplaceMerge(prev: object | null | undefined, next: object,
  */
 declare function mergeChartOption<T extends object>(generated: T, override: object | undefined): T;
 
+/**
+ * Forecast stretches: the tail of a series whose values are projections (or a
+ * period still in progress, such as the current month). Lines draw it dashed
+ * with hollow points, bars draw it faded with a dashed outline, and the
+ * tooltip tags its values.
+ */
+type AnyObject$2 = Record<string, any>;
+declare const DEFAULT_FORECAST_LABEL = "Forecast";
+/** The forecast fields a series may carry */
+interface ForecastSource {
+    data: readonly unknown[];
+    forecastFrom?: number;
+    forecastLabel?: string;
+}
+/**
+ * Index of a series' first forecast point, or `undefined` when it has none
+ * (no `forecastFrom`, or one past the end of the data).
+ */
+declare function forecastStart(source: ForecastSource): number | undefined;
+/** Whether any series has a forecast stretch */
+declare function hasForecast(series: readonly ForecastSource[] | undefined): boolean;
+/**
+ * Tooltip tag by data index: the label of the first series forecasting at
+ * that index. ECharts' `valueFormatter` only knows the index, so series that
+ * share an index share its tag.
+ */
+declare function forecastTagLookup(series: readonly ForecastSource[]): ((dataIndex: number) => string | undefined) | undefined;
+/**
+ * The first category where any series' forecast starts, for accessible
+ * descriptions
+ */
+declare function describeForecast(categories: readonly string[], series: readonly ForecastSource[]): string | undefined;
+/**
+ * Line forecast points: hollow, a little larger than the series' own points.
+ * Returns the data unchanged when the series has no forecast.
+ */
+declare function withForecastPoints(data: readonly unknown[], source: ForecastSource, 
+/** The series' own point size (0 when its points are hidden) */
+pointSize?: number): unknown[];
+/**
+ * Bar forecast items: faded, with a dashed outline in the series colour.
+ * Returns the data unchanged when the series has no forecast.
+ */
+declare function withForecastBars(data: readonly unknown[], source: ForecastSource, color: string): unknown[];
+interface ForecastLineOptions {
+    /** Resolved colour per series (explicit colour, else the theme palette) */
+    colors: readonly string[];
+}
+/**
+ * Draw line series' forecast stretches dashed.
+ *
+ * ECharts styles a line as a whole, so a series with a forecast keeps its
+ * full data for the tooltip, points and labels but hides its own line; two
+ * silent companions (same name, so the legend toggles them together) draw
+ * it: a solid one up to the last actual point, and a dashed one from there
+ * to the end. Series stacked together split at the same index (the earliest
+ * forecast in the stack) and stack in parallel groups, so the companions'
+ * totals match the series'.
+ *
+ * Series that forecast from their first point are simply dashed. Returns
+ * the series unchanged when none has a forecast. Apply reference marks
+ * before this, so they attach to the series rather than the companions.
+ */
+declare function withForecastLines<S extends AnyObject$2>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$2[];
+
+/**
+ * Ghost series: a faded reference drawn beside the real data, such as the
+ * prior period in a period-over-period comparison. Lines and areas draw
+ * dashed and faded with no fill or points; bars draw faded beside the solid
+ * ones (in a parallel stack group) rather than stacked onto them. Ghost
+ * series carry no value labels and are left out of bar totals.
+ */
+type AnyObject$1 = Record<string, any>;
+/** The variant field a series may carry */
+interface GhostSource {
+    variant?: 'ghost';
+}
+/** Opacity of a ghost line, its points and its legend icon */
+declare const GHOST_LINE_OPACITY = 0.6;
+/** Opacity of ghost bars */
+declare const GHOST_BAR_OPACITY = 0.35;
+/** Whether a series is a ghost (faded reference) series */
+declare function isGhostSeries(source: GhostSource | undefined): boolean;
+/** Whether any series is a ghost series */
+declare function hasGhostSeries(series: readonly GhostSource[] | undefined): boolean;
+/** The series that are not ghosts (for totals and value labels) */
+declare function withoutGhostSeries<S extends GhostSource>(series: readonly S[]): S[];
+/**
+ * A series' stack id, moved into a parallel group for ghost series so they
+ * stack among themselves (side by side with the real stack) and never onto
+ * real series. Unstacked series stay unstacked.
+ */
+declare function ghostStackId(stack: string | undefined, source: GhostSource | undefined): string | undefined;
+/**
+ * Restyle the ECharts series built for ghost sources (matched by index):
+ *
+ * - line (and area) series: dashed, faded line and points, no area fill,
+ *   no points by default, drawn under the real series
+ * - bar series: same colour at {@link GHOST_BAR_OPACITY}, in a parallel
+ *   stack group so they pair side by side with the real bars
+ *
+ * Ghost series lose their value labels (series and per-point). Series
+ * without a ghost source are returned unchanged. Apply after building the
+ * series and before reference marks, forecast lines or totals are added.
+ */
+declare function withGhostSeries<S extends AnyObject$1>(series: S[], sources: readonly (GhostSource | undefined)[]): S[];
+
 /**
  * Builders for the label, axis, tooltip and legend parts of a chart option.
  *
@@ -268,11 +375,13 @@ interface BuildTooltipOptions {
     valueFormatter?: (value: number) => string;
     /** Per-point label lookup, exposed to formatter functions as `label` */
     getLabel?: PointLabelLookup;
+    /** Tag for forecast values by data index (see `forecastTagLookup`) */
+    forecastTag?: (dataIndex: number) => string | undefined;
 }
 /**
  * Build the `tooltip` component. `base` is the chart's default tooltip.
  */
-declare function buildTooltip(base: AnyObject, { show, formatter, valueFormatter, getLabel }: BuildTooltipOptions): AnyObject | undefined;
+declare function buildTooltip(base: AnyObject, { show, formatter, valueFormatter, getLabel, forecastTag }: BuildTooltipOptions): AnyObject | undefined;
 /**
  * Format a value with `tooltipValueFormatter`, for charts whose default
  * tooltip is custom HTML (where ECharts' `valueFormatter` does not apply)
@@ -448,10 +557,12 @@ interface WaterfallBar {
 declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
 /**
  * Convert stacked series to each category's share of 100%. Missing values
- * stay missing; a category whose values sum to zero gets zeros.
+ * stay missing; a category whose values sum to zero gets zeros. Ghost
+ * series (`variant: 'ghost'`) share their own 100%, apart from the rest.
  */
 declare function toPercentStack<S extends {
     data: (number | null)[];
+    variant?: 'ghost';
 }>(series: S[]): S[];
 /**
  * Each stack's total by category, keyed by stack id. A series stacks under
@@ -677,4 +788,4 @@ declare function downloadFile(content: string, filename: string, mimeType?: stri
  */
 declare function downloadCsv(table: ChartDataTable, filename: string): void;
 
-export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withPointLabels, withReferenceMarks, withZoomInset };
+export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, DEFAULT_FORECAST_LABEL, type Delta, type ForecastLineOptions, type ForecastSource, type FromRecordsOptions, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, type GhostSource, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, downloadCsv, downloadFile, escapeHtml, forecastStart, forecastTagLookup, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, ghostStackId, gridInset, hasForecast, hasGhostSeries, hasPointLabels, heatmapTable, histogramTable, isGhostSeries, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withZoomInset, withoutGhostSeries };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.js';
 import { ValueFormat, CategoryChartData, BarChartData, BoxPlotStats, BulletItem, HistogramBucket, LineChartData, PieSliceData, ScatterChartData, WaterfallStep, ChartFormatter, LabelFormatterParams, TooltipFormatterParams, AxisConfig, ChartLegendConfig, ReferenceBand, ReferenceLine, LegendItem, HistogramBin, CategorySeriesData, ChartDataTable, CandlestickData, HeatmapData, RadarChartData, RadarIndicator, SankeyData, TreemapNode } from './types/index.js';
-export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.js';
+export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.js';
 import 'echarts';
 import 'echarts/core';
 
@@ -151,6 +151,113 @@ declare function getReplaceMerge(prev: object | null | undefined, next: object,
  */
 declare function mergeChartOption<T extends object>(generated: T, override: object | undefined): T;
 
+/**
+ * Forecast stretches: the tail of a series whose values are projections (or a
+ * period still in progress, such as the current month). Lines draw it dashed
+ * with hollow points, bars draw it faded with a dashed outline, and the
+ * tooltip tags its values.
+ */
+type AnyObject$2 = Record<string, any>;
+declare const DEFAULT_FORECAST_LABEL = "Forecast";
+/** The forecast fields a series may carry */
+interface ForecastSource {
+    data: readonly unknown[];
+    forecastFrom?: number;
+    forecastLabel?: string;
+}
+/**
+ * Index of a series' first forecast point, or `undefined` when it has none
+ * (no `forecastFrom`, or one past the end of the data).
+ */
+declare function forecastStart(source: ForecastSource): number | undefined;
+/** Whether any series has a forecast stretch */
+declare function hasForecast(series: readonly ForecastSource[] | undefined): boolean;
+/**
+ * Tooltip tag by data index: the label of the first series forecasting at
+ * that index. ECharts' `valueFormatter` only knows the index, so series that
+ * share an index share its tag.
+ */
+declare function forecastTagLookup(series: readonly ForecastSource[]): ((dataIndex: number) => string | undefined) | undefined;
+/**
+ * The first category where any series' forecast starts, for accessible
+ * descriptions
+ */
+declare function describeForecast(categories: readonly string[], series: readonly ForecastSource[]): string | undefined;
+/**
+ * Line forecast points: hollow, a little larger than the series' own points.
+ * Returns the data unchanged when the series has no forecast.
+ */
+declare function withForecastPoints(data: readonly unknown[], source: ForecastSource, 
+/** The series' own point size (0 when its points are hidden) */
+pointSize?: number): unknown[];
+/**
+ * Bar forecast items: faded, with a dashed outline in the series colour.
+ * Returns the data unchanged when the series has no forecast.
+ */
+declare function withForecastBars(data: readonly unknown[], source: ForecastSource, color: string): unknown[];
+interface ForecastLineOptions {
+    /** Resolved colour per series (explicit colour, else the theme palette) */
+    colors: readonly string[];
+}
+/**
+ * Draw line series' forecast stretches dashed.
+ *
+ * ECharts styles a line as a whole, so a series with a forecast keeps its
+ * full data for the tooltip, points and labels but hides its own line; two
+ * silent companions (same name, so the legend toggles them together) draw
+ * it: a solid one up to the last actual point, and a dashed one from there
+ * to the end. Series stacked together split at the same index (the earliest
+ * forecast in the stack) and stack in parallel groups, so the companions'
+ * totals match the series'.
+ *
+ * Series that forecast from their first point are simply dashed. Returns
+ * the series unchanged when none has a forecast. Apply reference marks
+ * before this, so they attach to the series rather than the companions.
+ */
+declare function withForecastLines<S extends AnyObject$2>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$2[];
+
+/**
+ * Ghost series: a faded reference drawn beside the real data, such as the
+ * prior period in a period-over-period comparison. Lines and areas draw
+ * dashed and faded with no fill or points; bars draw faded beside the solid
+ * ones (in a parallel stack group) rather than stacked onto them. Ghost
+ * series carry no value labels and are left out of bar totals.
+ */
+type AnyObject$1 = Record<string, any>;
+/** The variant field a series may carry */
+interface GhostSource {
+    variant?: 'ghost';
+}
+/** Opacity of a ghost line, its points and its legend icon */
+declare const GHOST_LINE_OPACITY = 0.6;
+/** Opacity of ghost bars */
+declare const GHOST_BAR_OPACITY = 0.35;
+/** Whether a series is a ghost (faded reference) series */
+declare function isGhostSeries(source: GhostSource | undefined): boolean;
+/** Whether any series is a ghost series */
+declare function hasGhostSeries(series: readonly GhostSource[] | undefined): boolean;
+/** The series that are not ghosts (for totals and value labels) */
+declare function withoutGhostSeries<S extends GhostSource>(series: readonly S[]): S[];
+/**
+ * A series' stack id, moved into a parallel group for ghost series so they
+ * stack among themselves (side by side with the real stack) and never onto
+ * real series. Unstacked series stay unstacked.
+ */
+declare function ghostStackId(stack: string | undefined, source: GhostSource | undefined): string | undefined;
+/**
+ * Restyle the ECharts series built for ghost sources (matched by index):
+ *
+ * - line (and area) series: dashed, faded line and points, no area fill,
+ *   no points by default, drawn under the real series
+ * - bar series: same colour at {@link GHOST_BAR_OPACITY}, in a parallel
+ *   stack group so they pair side by side with the real bars
+ *
+ * Ghost series lose their value labels (series and per-point). Series
+ * without a ghost source are returned unchanged. Apply after building the
+ * series and before reference marks, forecast lines or totals are added.
+ */
+declare function withGhostSeries<S extends AnyObject$1>(series: S[], sources: readonly (GhostSource | undefined)[]): S[];
+
 /**
  * Builders for the label, axis, tooltip and legend parts of a chart option.
  *
@@ -268,11 +375,13 @@ interface BuildTooltipOptions {
     valueFormatter?: (value: number) => string;
     /** Per-point label lookup, exposed to formatter functions as `label` */
     getLabel?: PointLabelLookup;
+    /** Tag for forecast values by data index (see `forecastTagLookup`) */
+    forecastTag?: (dataIndex: number) => string | undefined;
 }
 /**
  * Build the `tooltip` component. `base` is the chart's default tooltip.
  */
-declare function buildTooltip(base: AnyObject, { show, formatter, valueFormatter, getLabel }: BuildTooltipOptions): AnyObject | undefined;
+declare function buildTooltip(base: AnyObject, { show, formatter, valueFormatter, getLabel, forecastTag }: BuildTooltipOptions): AnyObject | undefined;
 /**
  * Format a value with `tooltipValueFormatter`, for charts whose default
  * tooltip is custom HTML (where ECharts' `valueFormatter` does not apply)
@@ -448,10 +557,12 @@ interface WaterfallBar {
 declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
 /**
  * Convert stacked series to each category's share of 100%. Missing values
- * stay missing; a category whose values sum to zero gets zeros.
+ * stay missing; a category whose values sum to zero gets zeros. Ghost
+ * series (`variant: 'ghost'`) share their own 100%, apart from the rest.
  */
 declare function toPercentStack<S extends {
     data: (number | null)[];
+    variant?: 'ghost';
 }>(series: S[]): S[];
 /**
  * Each stack's total by category, keyed by stack id. A series stacks under
@@ -677,4 +788,4 @@ declare function downloadFile(content: string, filename: string, mimeType?: stri
  */
 declare function downloadCsv(table: ChartDataTable, filename: string): void;
 
-export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withPointLabels, withReferenceMarks, withZoomInset };
+export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, DEFAULT_FORECAST_LABEL, type Delta, type ForecastLineOptions, type ForecastSource, type FromRecordsOptions, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, type GhostSource, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, downloadCsv, downloadFile, escapeHtml, forecastStart, forecastTagLookup, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, ghostStackId, gridInset, hasForecast, hasGhostSeries, hasPointLabels, heatmapTable, histogramTable, isGhostSeries, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withZoomInset, withoutGhostSeries };

package/dist/index.js

@@ -103,6 +103,159 @@ function createTooltipFormatter(options = {}) {
   };
 }
 
+// src/utils/forecast.ts
+var DEFAULT_FORECAST_LABEL = "Forecast";
+function forecastStart(source) {
+  const from = source.forecastFrom;
+  if (from == null || !Number.isFinite(from)) return void 0;
+  const index = Math.max(0, Math.floor(from));
+  return index < source.data.length ? index : void 0;
+}
+function hasForecast(series) {
+  return !!series?.some((s) => forecastStart(s) !== void 0);
+}
+function forecastTagLookup(series) {
+  if (!hasForecast(series)) return void 0;
+  return (dataIndex) => {
+    for (const s of series) {
+      const from = forecastStart(s);
+      if (from !== void 0 && dataIndex >= from) return s.forecastLabel || DEFAULT_FORECAST_LABEL;
+    }
+    return void 0;
+  };
+}
+function describeForecast(categories, series) {
+  let first;
+  for (const s of series) {
+    const from = forecastStart(s);
+    if (from === void 0 || first && first.index <= from) continue;
+    first = { index: from, label: s.forecastLabel || DEFAULT_FORECAST_LABEL };
+  }
+  if (!first) return void 0;
+  const category = categories[first.index] ?? "";
+  return `Values from ${category} onward are marked ${first.label.toLowerCase()}`;
+}
+var isPlainObject = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+function blank(item) {
+  if (Array.isArray(item)) return [item[0], null];
+  return null;
+}
+function bare(item) {
+  return isPlainObject(item) && "value" in item ? item.value : item;
+}
+function withItem(item, extra) {
+  if (isPlainObject(item) && "value" in item) {
+    return {
+      ...item,
+      ...extra,
+      itemStyle: { ...item.itemStyle, ...extra.itemStyle }
+    };
+  }
+  return { value: item, ...extra };
+}
+function withForecastPoints(data, source, pointSize = 0) {
+  const from = forecastStart(source);
+  if (from === void 0) return [...data];
+  const size = Math.max(pointSize, 6) + 1;
+  return data.map(
+    (item, index) => index >= from ? withItem(item, { symbol: "emptyCircle", symbolSize: size }) : item
+  );
+}
+function withForecastBars(data, source, color) {
+  const from = forecastStart(source);
+  if (from === void 0) return [...data];
+  return data.map(
+    (item, index) => index >= from ? withItem(item, {
+      itemStyle: {
+        opacity: 0.45,
+        borderColor: color,
+        borderWidth: 1.5,
+        borderType: "dashed"
+      }
+    }) : item
+  );
+}
+function withForecastLines(series, sources, { colors }) {
+  if (!hasForecast(sources)) return series;
+  const stackFrom = /* @__PURE__ */ new Map();
+  series.forEach((s, index) => {
+    const from = forecastStart(sources[index]);
+    if (s.stack == null || from === void 0) return;
+    stackFrom.set(s.stack, Math.min(stackFrom.get(s.stack) ?? Infinity, from));
+  });
+  const mains = [];
+  const companions = [];
+  series.forEach((s, index) => {
+    const from = s.stack != null ? stackFrom.get(s.stack) : forecastStart(sources[index]);
+    if (from === void 0) {
+      mains.push(s);
+      return;
+    }
+    const color = colors[index];
+    const itemStyle = { ...s.itemStyle, color };
+    if (from === 0) {
+      mains.push({
+        ...s,
+        itemStyle,
+        lineStyle: { ...s.lineStyle, type: "dashed" },
+        ...s.areaStyle && { areaStyle: fadedArea(s.areaStyle) }
+      });
+      return;
+    }
+    const data = s.data ?? [];
+    const common = {
+      name: s.name,
+      type: "line",
+      smooth: s.smooth,
+      connectNulls: s.connectNulls,
+      showSymbol: false,
+      symbol: "none",
+      silent: true,
+      legendHoverLink: false,
+      tooltip: { show: false },
+      emphasis: { disabled: true },
+      itemStyle,
+      z: s.z
+    };
+    companions.push(
+      {
+        ...common,
+        data: data.map((item, i) => i < from ? bare(item) : blank(item)),
+        stack: s.stack != null ? `${s.stack}\0actual` : void 0,
+        lineStyle: s.lineStyle,
+        areaStyle: s.areaStyle
+      },
+      {
+        ...common,
+        data: data.map((item, i) => i >= from - 1 ? bare(item) : blank(item)),
+        stack: s.stack != null ? `${s.stack}\0forecast` : void 0,
+        lineStyle: { ...s.lineStyle, type: "dashed" },
+        areaStyle: s.areaStyle ? fadedArea(s.areaStyle) : void 0
+      }
+    );
+    mains.push({
+      ...s,
+      itemStyle,
+      // Forecast points carry their own size; the rest keep theirs (none
+      // when the series hid its points)
+      showSymbol: true,
+      symbolSize: s.showSymbol === false ? 0 : s.symbolSize ?? 4,
+      lineStyle: { ...s.lineStyle, opacity: 0 },
+      areaStyle: void 0,
+      emphasis: {
+        ...s.emphasis,
+        focus: "none",
+        lineStyle: { ...s.emphasis?.lineStyle, opacity: 0 }
+      },
+      z: (s.z ?? 2) + 1
+    });
+  });
+  return [...mains, ...companions];
+}
+function fadedArea(areaStyle) {
+  return { ...areaStyle, opacity: (areaStyle.opacity ?? 0.7) * 0.5 };
+}
+
 // src/utils/accessibility.ts
 var isNumber = (value) => typeof value === "number" && Number.isFinite(value);
 function seriesList(names) {
@@ -128,6 +281,8 @@ function describeTrends(title, kind, data, format) {
     0
   );
   if (missing > 0) description += `. ${missing} values are missing`;
+  const forecast = describeForecast(data.categories, data.series);
+  if (forecast) description += `. ${forecast}`;
   return description;
 }
 function generateLineChartDescription(title, data, format) {
@@ -163,6 +318,8 @@ function generateBarChartDescription(title, data, format) {
   if (max && min) {
     description += `. Highest value is ${formatValue(max.value, format)} for ${max.category}. Lowest value is ${formatValue(min.value, format)} for ${min.category}`;
   }
+  const forecast = describeForecast(data.categories, data.series);
+  if (forecast) description += `. ${forecast}`;
   return description;
 }
 function generateDotPlotDescription(title, data, format) {
@@ -296,7 +453,7 @@ function getReplaceMerge(prev, next, isComponentType) {
   }
   return [...types].filter((type) => isComponentType(type));
 }
-function isPlainObject(value) {
+function isPlainObject2(value) {
   if (value === null || typeof value !== "object") return false;
   const proto = Object.getPrototypeOf(value);
   return proto === Object.prototype || proto === null;
@@ -309,7 +466,7 @@ function mergeValue(base, override, topLevel = false) {
     const length = Math.max(from.length, to.length);
     return Array.from({ length }, (_, index) => mergeValue(from[index], to[index]));
   }
-  if (isPlainObject(base) && isPlainObject(override)) {
+  if (isPlainObject2(base) && isPlainObject2(override)) {
     const merged = { ...base };
     for (const key of Object.keys(override)) {
       merged[key] = mergeValue(base[key], override[key]);
@@ -328,6 +485,66 @@ function mergeChartOption(generated, override) {
   return merged;
 }
 
+// src/utils/ghost.ts
+var GHOST_LINE_OPACITY = 0.6;
+var GHOST_BAR_OPACITY = 0.35;
+var GHOST_STACK = "\0ghost";
+function isGhostSeries(source) {
+  return source?.variant === "ghost";
+}
+function hasGhostSeries(series) {
+  return !!series?.some(isGhostSeries);
+}
+function withoutGhostSeries(series) {
+  return series.filter((s) => !isGhostSeries(s));
+}
+function ghostStackId(stack, source) {
+  if (stack === void 0 || !isGhostSeries(source) || stack.endsWith(GHOST_STACK)) return stack;
+  return `${stack}${GHOST_STACK}`;
+}
+var isPlainObject3 = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+function withoutItemLabels(data) {
+  if (!Array.isArray(data)) return data;
+  return data.map(
+    (item) => isPlainObject3(item) && item.label ? { ...item, label: { ...item.label, show: false } } : item
+  );
+}
+function withGhostSeries(series, sources) {
+  if (!hasGhostSeries(sources)) return series;
+  return series.map((s, index) => {
+    const source = sources[index];
+    if (!isGhostSeries(source)) return s;
+    const common = {
+      ...s,
+      stack: ghostStackId(s.stack, source),
+      data: withoutItemLabels(s.data),
+      label: { ...s.label, show: false }
+    };
+    if (s.type === "bar") {
+      return {
+        ...common,
+        itemStyle: { ...s.itemStyle, opacity: GHOST_BAR_OPACITY },
+        emphasis: {
+          ...s.emphasis,
+          itemStyle: { ...s.emphasis?.itemStyle, opacity: GHOST_BAR_OPACITY + 0.2 }
+        }
+      };
+    }
+    return {
+      ...common,
+      showSymbol: false,
+      areaStyle: void 0,
+      lineStyle: { ...s.lineStyle, type: "dashed", opacity: GHOST_LINE_OPACITY },
+      itemStyle: { ...s.itemStyle, opacity: GHOST_LINE_OPACITY },
+      emphasis: {
+        ...s.emphasis,
+        areaStyle: void 0
+      },
+      z: (s.z ?? 2) - 1
+    };
+  });
+}
+
 // src/utils/stats.ts
 var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 var clean = (value) => Number(value.toPrecision(12));
@@ -480,20 +697,26 @@ function waterfallLayout(steps) {
 }
 function toPercentStack(series) {
   const length = Math.max(0, ...series.map((s) => s.data.length));
-  const totals = Array.from(
+  const sumOf = (ghost) => Array.from(
     { length },
     (_, index) => series.reduce((sum, s) => {
+      if (s.variant === "ghost" !== ghost) return sum;
       const value = s.data[index];
       return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
     }, 0)
   );
-  return series.map((s) => ({
-    ...s,
-    data: s.data.map((value, index) => {
-      if (!isFiniteNumber(value)) return null;
-      return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
-    })
-  }));
+  const totals = sumOf(false);
+  const ghostTotals = sumOf(true);
+  return series.map((s) => {
+    const sums = s.variant === "ghost" ? ghostTotals : totals;
+    return {
+      ...s,
+      data: s.data.map((value, index) => {
+        if (!isFiniteNumber(value)) return null;
+        return sums[index] === 0 ? 0 : clean(value / sums[index] * 100);
+      })
+    };
+  });
 }
 function stackTotals(series, stacked) {
   const length = Math.max(0, ...series.map((s) => s.data.length));
@@ -717,12 +940,17 @@ function nameLabelLookup(nodes) {
 function hasPointLabels(series) {
   return series.some((s) => s.labels?.some((text) => text != null && text !== ""));
 }
-function buildTooltip(base, { show, formatter, valueFormatter, getLabel }) {
+function buildTooltip(base, { show, formatter, valueFormatter, getLabel, forecastTag }) {
   if (!show) return void 0;
-  if (formatter === void 0 && valueFormatter === void 0) return base;
+  if (formatter === void 0 && valueFormatter === void 0 && !forecastTag) return base;
   const tooltip = { ...base };
-  if (valueFormatter) {
-    tooltip.valueFormatter = (value) => typeof value === "number" ? valueFormatter(value) : String(value ?? "");
+  if (valueFormatter || forecastTag) {
+    const format = (value) => typeof value === "number" ? valueFormatter ? valueFormatter(value) : value.toLocaleString() : String(value ?? "");
+    tooltip.valueFormatter = (value, dataIndex) => {
+      const text = format(value);
+      const tag = dataIndex === void 0 ? void 0 : forecastTag?.(dataIndex);
+      return tag && value != null ? `${text} (${tag})` : text;
+    };
   }
   if (typeof formatter === "string") {
     tooltip.formatter = formatter;
@@ -1266,4 +1494,4 @@ function downloadCsv(table, filename) {
   );
 }
 
-export { abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withPointLabels, withReferenceMarks, withZoomInset };
+export { DEFAULT_FORECAST_LABEL, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, downloadCsv, downloadFile, escapeHtml, forecastStart, forecastTagLookup, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, ghostStackId, gridInset, hasForecast, hasGhostSeries, hasPointLabels, heatmapTable, histogramTable, isGhostSeries, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withZoomInset, withoutGhostSeries };

package/dist/types/index.d.cts

@@ -24,6 +24,22 @@ interface LineSeriesData {
      * chart's `stacked` prop for this series.
      */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface BarChartData {
     /** Category labels */
@@ -45,6 +61,22 @@ interface BarSeriesData {
      * chart's `stacked` prop for this series.
      */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface PieSliceData {
     /** Slice name (shown in legend/tooltip) */
@@ -76,6 +108,22 @@ interface AreaSeriesData {
      * chart's `stacked` prop for this series.
      */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface ScatterChartData {
     /** Data series */
@@ -216,6 +264,22 @@ interface CategorySeriesData {
     labels?: (string | null | undefined)[];
     /** Stack group id */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface ComboChartData {
     /** Category labels */
@@ -1162,6 +1226,34 @@ interface StatDelta {
     /** Text after the change, e.g. 'vs last year' */
     label?: string;
 }
+/**
+ * Delta text: the change between two values as a coloured ▲/▼ with the
+ * change and a "vs previous" label (the change line of `StatCard`, for KPI
+ * rows, table cells and other inline use). Renders nothing when either value
+ * is missing.
+ */
+interface DeltaTextProps {
+    /** The current value */
+    current: number | null | undefined;
+    /** The value being compared against (e.g. last year's) */
+    previous: number | null | undefined;
+    /**
+     * How the change is shown: 'percent' (+12%), 'absolute' (+12, using
+     * `valueFormat`) or 'both' (defaults to 'percent'). A change from zero
+     * has no percentage, so it shows the absolute change.
+     */
+    display?: 'percent' | 'absolute' | 'both';
+    /** Which direction is good, for colouring (defaults to 'up'); 'none' stays neutral */
+    goodWhen?: 'up' | 'down' | 'none';
+    /** How absolute changes and the previous value are written */
+    valueFormat?: ValueFormat;
+    /** Locale for `valueFormat` and the percentage (defaults to 'en-US') */
+    locale?: string;
+    /** Text after the change (defaults to 'vs <previous>'; '' hides it) */
+    label?: string;
+    /** Custom CSS class */
+    class?: string;
+}
 /**
  * Stat card: a headline metric with its change and trend
  */
@@ -1196,4 +1288,4 @@ interface StatCardProps {
     class?: string;
 }
 
-export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };
+export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };

package/dist/types/index.d.ts

@@ -24,6 +24,22 @@ interface LineSeriesData {
      * chart's `stacked` prop for this series.
      */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface BarChartData {
     /** Category labels */
@@ -45,6 +61,22 @@ interface BarSeriesData {
      * chart's `stacked` prop for this series.
      */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface PieSliceData {
     /** Slice name (shown in legend/tooltip) */
@@ -76,6 +108,22 @@ interface AreaSeriesData {
      * chart's `stacked` prop for this series.
      */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface ScatterChartData {
     /** Data series */
@@ -216,6 +264,22 @@ interface CategorySeriesData {
     labels?: (string | null | undefined)[];
     /** Stack group id */
     stack?: string;
+    /**
+     * Index of the first forecast point: from here to the end of the series the
+     * values are projections (or a period still in progress). Lines draw that
+     * stretch dashed with hollow points, bars draw those bars faded with a
+     * dashed outline, and the tooltip tags those values with `forecastLabel`.
+     */
+    forecastFrom?: number;
+    /** Tooltip tag for forecast values (defaults to 'Forecast') */
+    forecastLabel?: string;
+    /**
+     * Draw the series as a faded reference (e.g. the prior period beside the
+     * current one): lines and areas dashed and faded with no fill or points,
+     * bars faded beside the solid ones rather than stacked onto them. Ghost
+     * series carry no value labels and are left out of bar totals.
+     */
+    variant?: 'ghost';
 }
 interface ComboChartData {
     /** Category labels */
@@ -1162,6 +1226,34 @@ interface StatDelta {
     /** Text after the change, e.g. 'vs last year' */
     label?: string;
 }
+/**
+ * Delta text: the change between two values as a coloured ▲/▼ with the
+ * change and a "vs previous" label (the change line of `StatCard`, for KPI
+ * rows, table cells and other inline use). Renders nothing when either value
+ * is missing.
+ */
+interface DeltaTextProps {
+    /** The current value */
+    current: number | null | undefined;
+    /** The value being compared against (e.g. last year's) */
+    previous: number | null | undefined;
+    /**
+     * How the change is shown: 'percent' (+12%), 'absolute' (+12, using
+     * `valueFormat`) or 'both' (defaults to 'percent'). A change from zero
+     * has no percentage, so it shows the absolute change.
+     */
+    display?: 'percent' | 'absolute' | 'both';
+    /** Which direction is good, for colouring (defaults to 'up'); 'none' stays neutral */
+    goodWhen?: 'up' | 'down' | 'none';
+    /** How absolute changes and the previous value are written */
+    valueFormat?: ValueFormat;
+    /** Locale for `valueFormat` and the percentage (defaults to 'en-US') */
+    locale?: string;
+    /** Text after the change (defaults to 'vs <previous>'; '' hides it) */
+    label?: string;
+    /** Custom CSS class */
+    class?: string;
+}
 /**
  * Stat card: a headline metric with its change and trend
  */
@@ -1196,4 +1288,4 @@ interface StatCardProps {
     class?: string;
 }
 
-export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };
+export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/charts-core",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Core utilities and theme for Classic Theme charts",
   "type": "module",
   "main": "dist/index.cjs",