@classic-homes/charts-core 0.4.2 → 0.5.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]);
@@ -1038,12 +1195,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 +1749,7 @@ function downloadCsv(table, filename) {
   );
 }
 
+exports.DEFAULT_FORECAST_LABEL = DEFAULT_FORECAST_LABEL;
 exports.THEME_DARK = THEME_DARK;
 exports.THEME_LIGHT = THEME_LIGHT;
 exports.abbreviateNumber = abbreviateNumber;
@@ -1614,9 +1777,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;
@@ -1643,6 +1809,7 @@ exports.getChartColors = getChartColors;
 exports.getLegendItems = getLegendItems;
 exports.getReplaceMerge = getReplaceMerge;
 exports.gridInset = gridInset;
+exports.hasForecast = hasForecast;
 exports.hasPointLabels = hasPointLabels;
 exports.heatmapTable = heatmapTable;
 exports.histogramTable = histogramTable;
@@ -1674,6 +1841,9 @@ exports.valueLabelFormatter = valueLabelFormatter;
 exports.waterfallLayout = waterfallLayout;
 exports.waterfallTable = waterfallTable;
 exports.withEndLabelInset = withEndLabelInset;
+exports.withForecastBars = withForecastBars;
+exports.withForecastLines = withForecastLines;
+exports.withForecastPoints = withForecastPoints;
 exports.withPointLabels = withPointLabels;
 exports.withReferenceMarks = withReferenceMarks;
 exports.withZoomInset = withZoomInset;

package/dist/index.d.cts

@@ -151,6 +151,71 @@ 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$1 = 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$1>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$1[];
+
 /**
  * Builders for the label, axis, tooltip and legend parts of a chart option.
  *
@@ -268,11 +333,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)
@@ -677,4 +744,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, 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, gridInset, hasForecast, 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, withForecastBars, withForecastLines, withForecastPoints, withPointLabels, withReferenceMarks, withZoomInset };

package/dist/index.d.ts

@@ -151,6 +151,71 @@ 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$1 = 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$1>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$1[];
+
 /**
  * Builders for the label, axis, tooltip and legend parts of a chart option.
  *
@@ -268,11 +333,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)
@@ -677,4 +744,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, 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, gridInset, hasForecast, 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, withForecastBars, withForecastLines, withForecastPoints, withPointLabels, withReferenceMarks, withZoomInset };

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]);
@@ -717,12 +874,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 +1428,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, 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, gridInset, hasForecast, 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, withForecastBars, withForecastLines, withForecastPoints, withPointLabels, withReferenceMarks, withZoomInset };

package/dist/types/index.d.cts

@@ -24,6 +24,15 @@ 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;
 }
 interface BarChartData {
     /** Category labels */
@@ -45,6 +54,15 @@ 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;
 }
 interface PieSliceData {
     /** Slice name (shown in legend/tooltip) */
@@ -76,6 +94,15 @@ 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;
 }
 interface ScatterChartData {
     /** Data series */
@@ -216,6 +243,15 @@ 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;
 }
 interface ComboChartData {
     /** Category labels */

package/dist/types/index.d.ts

@@ -24,6 +24,15 @@ 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;
 }
 interface BarChartData {
     /** Category labels */
@@ -45,6 +54,15 @@ 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;
 }
 interface PieSliceData {
     /** Slice name (shown in legend/tooltip) */
@@ -76,6 +94,15 @@ 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;
 }
 interface ScatterChartData {
     /** Data series */
@@ -216,6 +243,15 @@ 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;
 }
 interface ComboChartData {
     /** Category labels */

package/package.json

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