@classic-homes/charts-core 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -806,6 +806,133 @@ 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/selection.ts
+var UNSELECTED_OPACITY = 0.3;
+function selectionSet(selected) {
+  if (selected == null) return void 0;
+  const names = typeof selected === "string" ? [selected] : selected;
+  const set = new Set(names.filter((name) => name !== ""));
+  return set.size ? set : void 0;
+}
+var isPlainObject4 = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+function withItem2(item, extra) {
+  if (isPlainObject4(item) && "value" in item) {
+    return {
+      ...item,
+      ...extra,
+      itemStyle: { ...item.itemStyle, ...extra.itemStyle }
+    };
+  }
+  return { value: item, ...extra };
+}
+function opacityOf(item, seriesOpacity) {
+  const opacity = isPlainObject4(item) ? item.itemStyle?.opacity : void 0;
+  return typeof opacity === "number" ? opacity : seriesOpacity;
+}
+function withSelectedBars(data, categories, selected, seriesOpacity = 1) {
+  const set = selectionSet(selected);
+  if (!set) return [...data];
+  return data.map(
+    (item, index) => set.has(String(categories[index])) ? item : withItem2(item, {
+      itemStyle: { opacity: opacityOf(item, seriesOpacity) * UNSELECTED_OPACITY }
+    })
+  );
+}
+function withSelectedPoints(data, categories, selected, options = {}) {
+  const set = selectionSet(selected);
+  if (!set) return [...data];
+  const size = Math.max(options.pointSize ?? 0, 6) + 4;
+  return data.map(
+    (item, index) => set.has(String(categories[index])) ? withItem2(item, {
+      symbol: "circle",
+      symbolSize: size,
+      itemStyle: {
+        borderWidth: 2,
+        ...options.ringColor && { borderColor: options.ringColor }
+      }
+    }) : item
+  );
+}
+function selectionShowsSymbols(selected) {
+  return selectionSet(selected) !== void 0;
+}
+function withSelectedSlices(items, selected) {
+  const set = selectionSet(selected);
+  if (!set) return [...items];
+  return items.map(
+    (item) => set.has(item.name) ? item : { ...item, itemStyle: { ...item.itemStyle, opacity: UNSELECTED_OPACITY } }
+  );
+}
+function describeSelection(selected) {
+  const set = selectionSet(selected);
+  return set ? `Selected: ${[...set].join(", ")}` : void 0;
+}
+function withSelectionDescription(description, selected) {
+  const note = describeSelection(selected);
+  if (!note) return description;
+  return description ? `${description.replace(/\.?\s*$/, "")}. ${note}.` : `${note}.`;
+}
+
 // src/utils/stats.ts
 var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 var clean = (value) => Number(value.toPrecision(12));
@@ -958,20 +1085,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));
@@ -1750,8 +1883,11 @@ 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.UNSELECTED_OPACITY = UNSELECTED_OPACITY;
 exports.abbreviateNumber = abbreviateNumber;
 exports.allSeriesEmpty = allSeriesEmpty;
 exports.anchorCenterGraphic = anchorCenterGraphic;
@@ -1778,6 +1914,7 @@ exports.createTooltipFormatter = createTooltipFormatter;
 exports.darkChartColors = darkChartColors;
 exports.darkTheme = darkTheme;
 exports.describeForecast = describeForecast;
+exports.describeSelection = describeSelection;
 exports.downloadCsv = downloadCsv;
 exports.downloadFile = downloadFile;
 exports.escapeHtml = escapeHtml;
@@ -1808,11 +1945,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;
@@ -1828,6 +1968,8 @@ exports.resolveChartHeight = resolveChartHeight;
 exports.resolveValueFormatter = resolveValueFormatter;
 exports.sankeyTable = sankeyTable;
 exports.scatterTable = scatterTable;
+exports.selectionSet = selectionSet;
+exports.selectionShowsSymbols = selectionShowsSymbols;
 exports.seriesLabelLookup = seriesLabelLookup;
 exports.sliceTable = sliceTable;
 exports.stackTotals = stackTotals;
@@ -1844,6 +1986,12 @@ exports.withEndLabelInset = withEndLabelInset;
 exports.withForecastBars = withForecastBars;
 exports.withForecastLines = withForecastLines;
 exports.withForecastPoints = withForecastPoints;
+exports.withGhostSeries = withGhostSeries;
 exports.withPointLabels = withPointLabels;
 exports.withReferenceMarks = withReferenceMarks;
+exports.withSelectedBars = withSelectedBars;
+exports.withSelectedPoints = withSelectedPoints;
+exports.withSelectedSlices = withSelectedSlices;
+exports.withSelectionDescription = withSelectionDescription;
 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, SelectableChartProps, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.cjs';
 import 'echarts';
 import 'echarts/core';
 
@@ -157,7 +157,7 @@ declare function mergeChartOption<T extends object>(generated: T, override: obje
  * with hollow points, bars draw it faded with a dashed outline, and the
  * tooltip tags its values.
  */
-type AnyObject$1 = Record<string, any>;
+type AnyObject$3 = Record<string, any>;
 declare const DEFAULT_FORECAST_LABEL = "Forecast";
 /** The forecast fields a series may carry */
 interface ForecastSource {
@@ -214,7 +214,97 @@ interface ForecastLineOptions {
  * 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[];
+declare function withForecastLines<S extends AnyObject$3>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$3[];
+
+/**
+ * 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$2 = 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$2>(series: S[], sources: readonly (GhostSource | undefined)[]): S[];
+
+/**
+ * Selected categories (or pie slices): the rest of the chart recedes so the
+ * chosen ones stand out — the visual half of cross-filtering, where clicking
+ * a bar filters the other charts on a page and highlights it in its own.
+ *
+ * Selection is controlled: the chart shows what the `selected` prop says and
+ * never toggles on its own. Everything is per data item, so changing the
+ * selection only changes series values and the chart animates in place.
+ */
+type AnyObject$1 = Record<string, any>;
+/** What a chart's `selected` prop accepts: one name, several, or none */
+type ChartSelection = string | readonly string[] | null | undefined;
+/** Opacity of items outside the selection */
+declare const UNSELECTED_OPACITY = 0.3;
+/** The selected names, or `undefined` when nothing is selected */
+declare function selectionSet(selected: ChartSelection): ReadonlySet<string> | undefined;
+/**
+ * Bars outside the selection fade. `data` lines up with `categories` by
+ * index (as `pairWithCategories` leaves it); unchanged without a selection.
+ * `seriesOpacity` is the series' own opacity (a ghost series is already
+ * faded), which an item opacity would otherwise replace.
+ */
+declare function withSelectedBars(data: readonly unknown[], categories: readonly string[], selected: ChartSelection, seriesOpacity?: number): unknown[];
+interface SelectedPointOptions {
+    /** The series' own point size (0 when its points are hidden) */
+    pointSize?: number;
+    /** Ring colour around a selected point (the chart surface) */
+    ringColor?: string;
+}
+/**
+ * Line / area points at selected categories: shown even when the series
+ * hides its points, larger, and ringed in the surface colour. The series
+ * must set `showSymbol: true` (see `selectionShowsSymbols`) for points it
+ * otherwise hides; `symbolSize` 0 keeps the rest hidden.
+ */
+declare function withSelectedPoints(data: readonly unknown[], categories: readonly string[], selected: ChartSelection, options?: SelectedPointOptions): unknown[];
+/** Whether a line / area series must turn its symbols on to show selected points */
+declare function selectionShowsSymbols(selected: ChartSelection): boolean;
+/** Pie / donut slices outside the selection fade; `items` are ECharts pie data items */
+declare function withSelectedSlices<T extends {
+    name: string;
+    itemStyle?: AnyObject$1;
+}>(items: readonly T[], selected: ChartSelection): T[];
+/** Accessible description of the selection ("Selected: Aspen, Birch"), or undefined */
+declare function describeSelection(selected: ChartSelection): string | undefined;
+/** A chart description with the selection appended, for screen readers */
+declare function withSelectionDescription(description: string | undefined, selected: ChartSelection): string | undefined;
 
 /**
  * Builders for the label, axis, tooltip and legend parts of a chart option.
@@ -515,10 +605,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
@@ -744,4 +836,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, 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 };
+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 ChartSelection, 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 SelectedPointOptions, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, UNSELECTED_OPACITY, 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, describeSelection, 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, selectionSet, selectionShowsSymbols, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withSelectedBars, withSelectedPoints, withSelectedSlices, withSelectionDescription, 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, SelectableChartProps, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.js';
 import 'echarts';
 import 'echarts/core';
 
@@ -157,7 +157,7 @@ declare function mergeChartOption<T extends object>(generated: T, override: obje
  * with hollow points, bars draw it faded with a dashed outline, and the
  * tooltip tags its values.
  */
-type AnyObject$1 = Record<string, any>;
+type AnyObject$3 = Record<string, any>;
 declare const DEFAULT_FORECAST_LABEL = "Forecast";
 /** The forecast fields a series may carry */
 interface ForecastSource {
@@ -214,7 +214,97 @@ interface ForecastLineOptions {
  * 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[];
+declare function withForecastLines<S extends AnyObject$3>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$3[];
+
+/**
+ * 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$2 = 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$2>(series: S[], sources: readonly (GhostSource | undefined)[]): S[];
+
+/**
+ * Selected categories (or pie slices): the rest of the chart recedes so the
+ * chosen ones stand out — the visual half of cross-filtering, where clicking
+ * a bar filters the other charts on a page and highlights it in its own.
+ *
+ * Selection is controlled: the chart shows what the `selected` prop says and
+ * never toggles on its own. Everything is per data item, so changing the
+ * selection only changes series values and the chart animates in place.
+ */
+type AnyObject$1 = Record<string, any>;
+/** What a chart's `selected` prop accepts: one name, several, or none */
+type ChartSelection = string | readonly string[] | null | undefined;
+/** Opacity of items outside the selection */
+declare const UNSELECTED_OPACITY = 0.3;
+/** The selected names, or `undefined` when nothing is selected */
+declare function selectionSet(selected: ChartSelection): ReadonlySet<string> | undefined;
+/**
+ * Bars outside the selection fade. `data` lines up with `categories` by
+ * index (as `pairWithCategories` leaves it); unchanged without a selection.
+ * `seriesOpacity` is the series' own opacity (a ghost series is already
+ * faded), which an item opacity would otherwise replace.
+ */
+declare function withSelectedBars(data: readonly unknown[], categories: readonly string[], selected: ChartSelection, seriesOpacity?: number): unknown[];
+interface SelectedPointOptions {
+    /** The series' own point size (0 when its points are hidden) */
+    pointSize?: number;
+    /** Ring colour around a selected point (the chart surface) */
+    ringColor?: string;
+}
+/**
+ * Line / area points at selected categories: shown even when the series
+ * hides its points, larger, and ringed in the surface colour. The series
+ * must set `showSymbol: true` (see `selectionShowsSymbols`) for points it
+ * otherwise hides; `symbolSize` 0 keeps the rest hidden.
+ */
+declare function withSelectedPoints(data: readonly unknown[], categories: readonly string[], selected: ChartSelection, options?: SelectedPointOptions): unknown[];
+/** Whether a line / area series must turn its symbols on to show selected points */
+declare function selectionShowsSymbols(selected: ChartSelection): boolean;
+/** Pie / donut slices outside the selection fade; `items` are ECharts pie data items */
+declare function withSelectedSlices<T extends {
+    name: string;
+    itemStyle?: AnyObject$1;
+}>(items: readonly T[], selected: ChartSelection): T[];
+/** Accessible description of the selection ("Selected: Aspen, Birch"), or undefined */
+declare function describeSelection(selected: ChartSelection): string | undefined;
+/** A chart description with the selection appended, for screen readers */
+declare function withSelectionDescription(description: string | undefined, selected: ChartSelection): string | undefined;
 
 /**
  * Builders for the label, axis, tooltip and legend parts of a chart option.
@@ -515,10 +605,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
@@ -744,4 +836,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, 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 };
+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 ChartSelection, 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 SelectedPointOptions, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, UNSELECTED_OPACITY, 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, describeSelection, 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, selectionSet, selectionShowsSymbols, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withSelectedBars, withSelectedPoints, withSelectedSlices, withSelectionDescription, withZoomInset, withoutGhostSeries };

package/dist/index.js

@@ -485,6 +485,133 @@ 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/selection.ts
+var UNSELECTED_OPACITY = 0.3;
+function selectionSet(selected) {
+  if (selected == null) return void 0;
+  const names = typeof selected === "string" ? [selected] : selected;
+  const set = new Set(names.filter((name) => name !== ""));
+  return set.size ? set : void 0;
+}
+var isPlainObject4 = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
+function withItem2(item, extra) {
+  if (isPlainObject4(item) && "value" in item) {
+    return {
+      ...item,
+      ...extra,
+      itemStyle: { ...item.itemStyle, ...extra.itemStyle }
+    };
+  }
+  return { value: item, ...extra };
+}
+function opacityOf(item, seriesOpacity) {
+  const opacity = isPlainObject4(item) ? item.itemStyle?.opacity : void 0;
+  return typeof opacity === "number" ? opacity : seriesOpacity;
+}
+function withSelectedBars(data, categories, selected, seriesOpacity = 1) {
+  const set = selectionSet(selected);
+  if (!set) return [...data];
+  return data.map(
+    (item, index) => set.has(String(categories[index])) ? item : withItem2(item, {
+      itemStyle: { opacity: opacityOf(item, seriesOpacity) * UNSELECTED_OPACITY }
+    })
+  );
+}
+function withSelectedPoints(data, categories, selected, options = {}) {
+  const set = selectionSet(selected);
+  if (!set) return [...data];
+  const size = Math.max(options.pointSize ?? 0, 6) + 4;
+  return data.map(
+    (item, index) => set.has(String(categories[index])) ? withItem2(item, {
+      symbol: "circle",
+      symbolSize: size,
+      itemStyle: {
+        borderWidth: 2,
+        ...options.ringColor && { borderColor: options.ringColor }
+      }
+    }) : item
+  );
+}
+function selectionShowsSymbols(selected) {
+  return selectionSet(selected) !== void 0;
+}
+function withSelectedSlices(items, selected) {
+  const set = selectionSet(selected);
+  if (!set) return [...items];
+  return items.map(
+    (item) => set.has(item.name) ? item : { ...item, itemStyle: { ...item.itemStyle, opacity: UNSELECTED_OPACITY } }
+  );
+}
+function describeSelection(selected) {
+  const set = selectionSet(selected);
+  return set ? `Selected: ${[...set].join(", ")}` : void 0;
+}
+function withSelectionDescription(description, selected) {
+  const note = describeSelection(selected);
+  if (!note) return description;
+  return description ? `${description.replace(/\.?\s*$/, "")}. ${note}.` : `${note}.`;
+}
+
 // src/utils/stats.ts
 var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
 var clean = (value) => Number(value.toPrecision(12));
@@ -637,20 +764,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));
@@ -1428,4 +1561,4 @@ function downloadCsv(table, filename) {
   );
 }
 
-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 };
+export { DEFAULT_FORECAST_LABEL, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, UNSELECTED_OPACITY, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, describeSelection, 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, selectionSet, selectionShowsSymbols, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withSelectedBars, withSelectedPoints, withSelectedSlices, withSelectionDescription, withZoomInset, withoutGhostSeries };

package/dist/types/index.d.cts

@@ -33,6 +33,13 @@ interface LineSeriesData {
     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 */
@@ -63,6 +70,13 @@ interface BarSeriesData {
     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) */
@@ -103,6 +117,13 @@ interface AreaSeriesData {
     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 */
@@ -252,6 +273,13 @@ interface CategorySeriesData {
     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 */
@@ -814,10 +842,19 @@ interface RowHeightProps {
     /** Height per category row for `height="auto"` (defaults to 28) */
     rowHeight?: number;
 }
+/**
+ * Controlled selection: the named categories (bar / line / area) or slices
+ * (pie / donut) stand out and the rest recede. The chart never changes it on
+ * its own — set it from `onClick` to cross-filter.
+ */
+interface SelectableChartProps {
+    /** Selected category or slice names; empty / undefined = nothing selected */
+    selected?: string | readonly string[] | null;
+}
 /**
  * Line chart specific props
  */
-interface LineChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
+interface LineChartProps extends BaseChartProps, SelectableChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
     /** Show data labels */
     showLabels?: boolean;
     /** Chart data */
@@ -840,7 +877,7 @@ interface LineChartProps extends BaseChartProps, LegendChartProps, LabelChartPro
 /**
  * Bar chart specific props
  */
-interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps, RowHeightProps {
+interface BarChartProps extends BaseChartProps, SelectableChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps, RowHeightProps {
     /** Chart data */
     data: BarChartData;
     /**
@@ -866,7 +903,7 @@ interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProp
 /**
  * Pie chart specific props
  */
-interface PieChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
+interface PieChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, SelectableChartProps {
     /** Chart data */
     data: PieSliceData[];
     /** Show slice labels */
@@ -892,7 +929,7 @@ interface DonutChartProps extends Omit<PieChartProps, 'innerRadius'> {
 /**
  * Area chart specific props
  */
-interface AreaChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
+interface AreaChartProps extends BaseChartProps, SelectableChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
     /** Show data labels */
     showLabels?: boolean;
     /** Chart data */
@@ -905,6 +942,8 @@ interface AreaChartProps extends BaseChartProps, LegendChartProps, LabelChartPro
     connectNulls?: boolean;
     /** Use gradient fill */
     gradient?: boolean;
+    /** Show data points on the area's line (needed for clicks on a point) */
+    showDataPoints?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
     /** Hover event handler */
@@ -1198,6 +1237,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
  */
@@ -1232,4 +1299,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, SelectableChartProps, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };

package/dist/types/index.d.ts

@@ -33,6 +33,13 @@ interface LineSeriesData {
     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 */
@@ -63,6 +70,13 @@ interface BarSeriesData {
     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) */
@@ -103,6 +117,13 @@ interface AreaSeriesData {
     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 */
@@ -252,6 +273,13 @@ interface CategorySeriesData {
     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 */
@@ -814,10 +842,19 @@ interface RowHeightProps {
     /** Height per category row for `height="auto"` (defaults to 28) */
     rowHeight?: number;
 }
+/**
+ * Controlled selection: the named categories (bar / line / area) or slices
+ * (pie / donut) stand out and the rest recede. The chart never changes it on
+ * its own — set it from `onClick` to cross-filter.
+ */
+interface SelectableChartProps {
+    /** Selected category or slice names; empty / undefined = nothing selected */
+    selected?: string | readonly string[] | null;
+}
 /**
  * Line chart specific props
  */
-interface LineChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
+interface LineChartProps extends BaseChartProps, SelectableChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
     /** Show data labels */
     showLabels?: boolean;
     /** Chart data */
@@ -840,7 +877,7 @@ interface LineChartProps extends BaseChartProps, LegendChartProps, LabelChartPro
 /**
  * Bar chart specific props
  */
-interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps, RowHeightProps {
+interface BarChartProps extends BaseChartProps, SelectableChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps, RowHeightProps {
     /** Chart data */
     data: BarChartData;
     /**
@@ -866,7 +903,7 @@ interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProp
 /**
  * Pie chart specific props
  */
-interface PieChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
+interface PieChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, SelectableChartProps {
     /** Chart data */
     data: PieSliceData[];
     /** Show slice labels */
@@ -892,7 +929,7 @@ interface DonutChartProps extends Omit<PieChartProps, 'innerRadius'> {
 /**
  * Area chart specific props
  */
-interface AreaChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
+interface AreaChartProps extends BaseChartProps, SelectableChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
     /** Show data labels */
     showLabels?: boolean;
     /** Chart data */
@@ -905,6 +942,8 @@ interface AreaChartProps extends BaseChartProps, LegendChartProps, LabelChartPro
     connectNulls?: boolean;
     /** Use gradient fill */
     gradient?: boolean;
+    /** Show data points on the area's line (needed for clicks on a point) */
+    showDataPoints?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
     /** Hover event handler */
@@ -1198,6 +1237,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
  */
@@ -1232,4 +1299,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, SelectableChartProps, 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.5.0",
+  "version": "0.7.0",
   "description": "Core utilities and theme for Classic Theme charts",
   "type": "module",
   "main": "dist/index.cjs",