@classic-homes/charts-core 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.cjs CHANGED
@@ -806,6 +806,66 @@ function mergeChartOption(generated, override) {
806
806
  return merged;
807
807
  }
808
808
 
809
+ // src/utils/ghost.ts
810
+ var GHOST_LINE_OPACITY = 0.6;
811
+ var GHOST_BAR_OPACITY = 0.35;
812
+ var GHOST_STACK = "\0ghost";
813
+ function isGhostSeries(source) {
814
+ return source?.variant === "ghost";
815
+ }
816
+ function hasGhostSeries(series) {
817
+ return !!series?.some(isGhostSeries);
818
+ }
819
+ function withoutGhostSeries(series) {
820
+ return series.filter((s) => !isGhostSeries(s));
821
+ }
822
+ function ghostStackId(stack, source) {
823
+ if (stack === void 0 || !isGhostSeries(source) || stack.endsWith(GHOST_STACK)) return stack;
824
+ return `${stack}${GHOST_STACK}`;
825
+ }
826
+ var isPlainObject3 = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
827
+ function withoutItemLabels(data) {
828
+ if (!Array.isArray(data)) return data;
829
+ return data.map(
830
+ (item) => isPlainObject3(item) && item.label ? { ...item, label: { ...item.label, show: false } } : item
831
+ );
832
+ }
833
+ function withGhostSeries(series, sources) {
834
+ if (!hasGhostSeries(sources)) return series;
835
+ return series.map((s, index) => {
836
+ const source = sources[index];
837
+ if (!isGhostSeries(source)) return s;
838
+ const common = {
839
+ ...s,
840
+ stack: ghostStackId(s.stack, source),
841
+ data: withoutItemLabels(s.data),
842
+ label: { ...s.label, show: false }
843
+ };
844
+ if (s.type === "bar") {
845
+ return {
846
+ ...common,
847
+ itemStyle: { ...s.itemStyle, opacity: GHOST_BAR_OPACITY },
848
+ emphasis: {
849
+ ...s.emphasis,
850
+ itemStyle: { ...s.emphasis?.itemStyle, opacity: GHOST_BAR_OPACITY + 0.2 }
851
+ }
852
+ };
853
+ }
854
+ return {
855
+ ...common,
856
+ showSymbol: false,
857
+ areaStyle: void 0,
858
+ lineStyle: { ...s.lineStyle, type: "dashed", opacity: GHOST_LINE_OPACITY },
859
+ itemStyle: { ...s.itemStyle, opacity: GHOST_LINE_OPACITY },
860
+ emphasis: {
861
+ ...s.emphasis,
862
+ areaStyle: void 0
863
+ },
864
+ z: (s.z ?? 2) - 1
865
+ };
866
+ });
867
+ }
868
+
809
869
  // src/utils/stats.ts
810
870
  var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
811
871
  var clean = (value) => Number(value.toPrecision(12));
@@ -958,20 +1018,26 @@ function waterfallLayout(steps) {
958
1018
  }
959
1019
  function toPercentStack(series) {
960
1020
  const length = Math.max(0, ...series.map((s) => s.data.length));
961
- const totals = Array.from(
1021
+ const sumOf = (ghost) => Array.from(
962
1022
  { length },
963
1023
  (_, index) => series.reduce((sum, s) => {
1024
+ if (s.variant === "ghost" !== ghost) return sum;
964
1025
  const value = s.data[index];
965
1026
  return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
966
1027
  }, 0)
967
1028
  );
968
- return series.map((s) => ({
969
- ...s,
970
- data: s.data.map((value, index) => {
971
- if (!isFiniteNumber(value)) return null;
972
- return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
973
- })
974
- }));
1029
+ const totals = sumOf(false);
1030
+ const ghostTotals = sumOf(true);
1031
+ return series.map((s) => {
1032
+ const sums = s.variant === "ghost" ? ghostTotals : totals;
1033
+ return {
1034
+ ...s,
1035
+ data: s.data.map((value, index) => {
1036
+ if (!isFiniteNumber(value)) return null;
1037
+ return sums[index] === 0 ? 0 : clean(value / sums[index] * 100);
1038
+ })
1039
+ };
1040
+ });
975
1041
  }
976
1042
  function stackTotals(series, stacked) {
977
1043
  const length = Math.max(0, ...series.map((s) => s.data.length));
@@ -1750,6 +1816,8 @@ function downloadCsv(table, filename) {
1750
1816
  }
1751
1817
 
1752
1818
  exports.DEFAULT_FORECAST_LABEL = DEFAULT_FORECAST_LABEL;
1819
+ exports.GHOST_BAR_OPACITY = GHOST_BAR_OPACITY;
1820
+ exports.GHOST_LINE_OPACITY = GHOST_LINE_OPACITY;
1753
1821
  exports.THEME_DARK = THEME_DARK;
1754
1822
  exports.THEME_LIGHT = THEME_LIGHT;
1755
1823
  exports.abbreviateNumber = abbreviateNumber;
@@ -1808,11 +1876,14 @@ exports.generateWaterfallDescription = generateWaterfallDescription;
1808
1876
  exports.getChartColors = getChartColors;
1809
1877
  exports.getLegendItems = getLegendItems;
1810
1878
  exports.getReplaceMerge = getReplaceMerge;
1879
+ exports.ghostStackId = ghostStackId;
1811
1880
  exports.gridInset = gridInset;
1812
1881
  exports.hasForecast = hasForecast;
1882
+ exports.hasGhostSeries = hasGhostSeries;
1813
1883
  exports.hasPointLabels = hasPointLabels;
1814
1884
  exports.heatmapTable = heatmapTable;
1815
1885
  exports.histogramTable = histogramTable;
1886
+ exports.isGhostSeries = isGhostSeries;
1816
1887
  exports.itemLabelLookup = itemLabelLookup;
1817
1888
  exports.legendCenter = legendCenter;
1818
1889
  exports.lightChartColors = lightChartColors;
@@ -1844,6 +1915,8 @@ exports.withEndLabelInset = withEndLabelInset;
1844
1915
  exports.withForecastBars = withForecastBars;
1845
1916
  exports.withForecastLines = withForecastLines;
1846
1917
  exports.withForecastPoints = withForecastPoints;
1918
+ exports.withGhostSeries = withGhostSeries;
1847
1919
  exports.withPointLabels = withPointLabels;
1848
1920
  exports.withReferenceMarks = withReferenceMarks;
1849
1921
  exports.withZoomInset = withZoomInset;
1922
+ exports.withoutGhostSeries = withoutGhostSeries;
package/dist/index.d.cts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.cjs';
2
2
  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';
3
- 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';
3
+ export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.cjs';
4
4
  import 'echarts';
5
5
  import 'echarts/core';
6
6
 
@@ -157,7 +157,7 @@ declare function mergeChartOption<T extends object>(generated: T, override: obje
157
157
  * with hollow points, bars draw it faded with a dashed outline, and the
158
158
  * tooltip tags its values.
159
159
  */
160
- type AnyObject$1 = Record<string, any>;
160
+ type AnyObject$2 = Record<string, any>;
161
161
  declare const DEFAULT_FORECAST_LABEL = "Forecast";
162
162
  /** The forecast fields a series may carry */
163
163
  interface ForecastSource {
@@ -214,7 +214,49 @@ interface ForecastLineOptions {
214
214
  * the series unchanged when none has a forecast. Apply reference marks
215
215
  * before this, so they attach to the series rather than the companions.
216
216
  */
217
- declare function withForecastLines<S extends AnyObject$1>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$1[];
217
+ declare function withForecastLines<S extends AnyObject$2>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$2[];
218
+
219
+ /**
220
+ * Ghost series: a faded reference drawn beside the real data, such as the
221
+ * prior period in a period-over-period comparison. Lines and areas draw
222
+ * dashed and faded with no fill or points; bars draw faded beside the solid
223
+ * ones (in a parallel stack group) rather than stacked onto them. Ghost
224
+ * series carry no value labels and are left out of bar totals.
225
+ */
226
+ type AnyObject$1 = Record<string, any>;
227
+ /** The variant field a series may carry */
228
+ interface GhostSource {
229
+ variant?: 'ghost';
230
+ }
231
+ /** Opacity of a ghost line, its points and its legend icon */
232
+ declare const GHOST_LINE_OPACITY = 0.6;
233
+ /** Opacity of ghost bars */
234
+ declare const GHOST_BAR_OPACITY = 0.35;
235
+ /** Whether a series is a ghost (faded reference) series */
236
+ declare function isGhostSeries(source: GhostSource | undefined): boolean;
237
+ /** Whether any series is a ghost series */
238
+ declare function hasGhostSeries(series: readonly GhostSource[] | undefined): boolean;
239
+ /** The series that are not ghosts (for totals and value labels) */
240
+ declare function withoutGhostSeries<S extends GhostSource>(series: readonly S[]): S[];
241
+ /**
242
+ * A series' stack id, moved into a parallel group for ghost series so they
243
+ * stack among themselves (side by side with the real stack) and never onto
244
+ * real series. Unstacked series stay unstacked.
245
+ */
246
+ declare function ghostStackId(stack: string | undefined, source: GhostSource | undefined): string | undefined;
247
+ /**
248
+ * Restyle the ECharts series built for ghost sources (matched by index):
249
+ *
250
+ * - line (and area) series: dashed, faded line and points, no area fill,
251
+ * no points by default, drawn under the real series
252
+ * - bar series: same colour at {@link GHOST_BAR_OPACITY}, in a parallel
253
+ * stack group so they pair side by side with the real bars
254
+ *
255
+ * Ghost series lose their value labels (series and per-point). Series
256
+ * without a ghost source are returned unchanged. Apply after building the
257
+ * series and before reference marks, forecast lines or totals are added.
258
+ */
259
+ declare function withGhostSeries<S extends AnyObject$1>(series: S[], sources: readonly (GhostSource | undefined)[]): S[];
218
260
 
219
261
  /**
220
262
  * Builders for the label, axis, tooltip and legend parts of a chart option.
@@ -515,10 +557,12 @@ interface WaterfallBar {
515
557
  declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
516
558
  /**
517
559
  * Convert stacked series to each category's share of 100%. Missing values
518
- * stay missing; a category whose values sum to zero gets zeros.
560
+ * stay missing; a category whose values sum to zero gets zeros. Ghost
561
+ * series (`variant: 'ghost'`) share their own 100%, apart from the rest.
519
562
  */
520
563
  declare function toPercentStack<S extends {
521
564
  data: (number | null)[];
565
+ variant?: 'ghost';
522
566
  }>(series: S[]): S[];
523
567
  /**
524
568
  * Each stack's total by category, keyed by stack id. A series stacks under
@@ -744,4 +788,4 @@ declare function downloadFile(content: string, filename: string, mimeType?: stri
744
788
  */
745
789
  declare function downloadCsv(table: ChartDataTable, filename: string): void;
746
790
 
747
- 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 };
791
+ export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, DEFAULT_FORECAST_LABEL, type Delta, type ForecastLineOptions, type ForecastSource, type FromRecordsOptions, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, type GhostSource, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, downloadCsv, downloadFile, escapeHtml, forecastStart, forecastTagLookup, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, ghostStackId, gridInset, hasForecast, hasGhostSeries, hasPointLabels, heatmapTable, histogramTable, isGhostSeries, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withZoomInset, withoutGhostSeries };
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.js';
2
2
  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';
3
- 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';
3
+ export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.js';
4
4
  import 'echarts';
5
5
  import 'echarts/core';
6
6
 
@@ -157,7 +157,7 @@ declare function mergeChartOption<T extends object>(generated: T, override: obje
157
157
  * with hollow points, bars draw it faded with a dashed outline, and the
158
158
  * tooltip tags its values.
159
159
  */
160
- type AnyObject$1 = Record<string, any>;
160
+ type AnyObject$2 = Record<string, any>;
161
161
  declare const DEFAULT_FORECAST_LABEL = "Forecast";
162
162
  /** The forecast fields a series may carry */
163
163
  interface ForecastSource {
@@ -214,7 +214,49 @@ interface ForecastLineOptions {
214
214
  * the series unchanged when none has a forecast. Apply reference marks
215
215
  * before this, so they attach to the series rather than the companions.
216
216
  */
217
- declare function withForecastLines<S extends AnyObject$1>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$1[];
217
+ declare function withForecastLines<S extends AnyObject$2>(series: S[], sources: readonly ForecastSource[], { colors }: ForecastLineOptions): AnyObject$2[];
218
+
219
+ /**
220
+ * Ghost series: a faded reference drawn beside the real data, such as the
221
+ * prior period in a period-over-period comparison. Lines and areas draw
222
+ * dashed and faded with no fill or points; bars draw faded beside the solid
223
+ * ones (in a parallel stack group) rather than stacked onto them. Ghost
224
+ * series carry no value labels and are left out of bar totals.
225
+ */
226
+ type AnyObject$1 = Record<string, any>;
227
+ /** The variant field a series may carry */
228
+ interface GhostSource {
229
+ variant?: 'ghost';
230
+ }
231
+ /** Opacity of a ghost line, its points and its legend icon */
232
+ declare const GHOST_LINE_OPACITY = 0.6;
233
+ /** Opacity of ghost bars */
234
+ declare const GHOST_BAR_OPACITY = 0.35;
235
+ /** Whether a series is a ghost (faded reference) series */
236
+ declare function isGhostSeries(source: GhostSource | undefined): boolean;
237
+ /** Whether any series is a ghost series */
238
+ declare function hasGhostSeries(series: readonly GhostSource[] | undefined): boolean;
239
+ /** The series that are not ghosts (for totals and value labels) */
240
+ declare function withoutGhostSeries<S extends GhostSource>(series: readonly S[]): S[];
241
+ /**
242
+ * A series' stack id, moved into a parallel group for ghost series so they
243
+ * stack among themselves (side by side with the real stack) and never onto
244
+ * real series. Unstacked series stay unstacked.
245
+ */
246
+ declare function ghostStackId(stack: string | undefined, source: GhostSource | undefined): string | undefined;
247
+ /**
248
+ * Restyle the ECharts series built for ghost sources (matched by index):
249
+ *
250
+ * - line (and area) series: dashed, faded line and points, no area fill,
251
+ * no points by default, drawn under the real series
252
+ * - bar series: same colour at {@link GHOST_BAR_OPACITY}, in a parallel
253
+ * stack group so they pair side by side with the real bars
254
+ *
255
+ * Ghost series lose their value labels (series and per-point). Series
256
+ * without a ghost source are returned unchanged. Apply after building the
257
+ * series and before reference marks, forecast lines or totals are added.
258
+ */
259
+ declare function withGhostSeries<S extends AnyObject$1>(series: S[], sources: readonly (GhostSource | undefined)[]): S[];
218
260
 
219
261
  /**
220
262
  * Builders for the label, axis, tooltip and legend parts of a chart option.
@@ -515,10 +557,12 @@ interface WaterfallBar {
515
557
  declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
516
558
  /**
517
559
  * Convert stacked series to each category's share of 100%. Missing values
518
- * stay missing; a category whose values sum to zero gets zeros.
560
+ * stay missing; a category whose values sum to zero gets zeros. Ghost
561
+ * series (`variant: 'ghost'`) share their own 100%, apart from the rest.
519
562
  */
520
563
  declare function toPercentStack<S extends {
521
564
  data: (number | null)[];
565
+ variant?: 'ghost';
522
566
  }>(series: S[]): S[];
523
567
  /**
524
568
  * Each stack's total by category, keyed by stack id. A series stacks under
@@ -744,4 +788,4 @@ declare function downloadFile(content: string, filename: string, mimeType?: stri
744
788
  */
745
789
  declare function downloadCsv(table: ChartDataTable, filename: string): void;
746
790
 
747
- 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 };
791
+ export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, DEFAULT_FORECAST_LABEL, type Delta, type ForecastLineOptions, type ForecastSource, type FromRecordsOptions, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, type GhostSource, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type StackTotalOptions, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, downloadCsv, downloadFile, escapeHtml, forecastStart, forecastTagLookup, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, ghostStackId, gridInset, hasForecast, hasGhostSeries, hasPointLabels, heatmapTable, histogramTable, isGhostSeries, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withZoomInset, withoutGhostSeries };
package/dist/index.js CHANGED
@@ -485,6 +485,66 @@ function mergeChartOption(generated, override) {
485
485
  return merged;
486
486
  }
487
487
 
488
+ // src/utils/ghost.ts
489
+ var GHOST_LINE_OPACITY = 0.6;
490
+ var GHOST_BAR_OPACITY = 0.35;
491
+ var GHOST_STACK = "\0ghost";
492
+ function isGhostSeries(source) {
493
+ return source?.variant === "ghost";
494
+ }
495
+ function hasGhostSeries(series) {
496
+ return !!series?.some(isGhostSeries);
497
+ }
498
+ function withoutGhostSeries(series) {
499
+ return series.filter((s) => !isGhostSeries(s));
500
+ }
501
+ function ghostStackId(stack, source) {
502
+ if (stack === void 0 || !isGhostSeries(source) || stack.endsWith(GHOST_STACK)) return stack;
503
+ return `${stack}${GHOST_STACK}`;
504
+ }
505
+ var isPlainObject3 = (item) => typeof item === "object" && item !== null && !Array.isArray(item);
506
+ function withoutItemLabels(data) {
507
+ if (!Array.isArray(data)) return data;
508
+ return data.map(
509
+ (item) => isPlainObject3(item) && item.label ? { ...item, label: { ...item.label, show: false } } : item
510
+ );
511
+ }
512
+ function withGhostSeries(series, sources) {
513
+ if (!hasGhostSeries(sources)) return series;
514
+ return series.map((s, index) => {
515
+ const source = sources[index];
516
+ if (!isGhostSeries(source)) return s;
517
+ const common = {
518
+ ...s,
519
+ stack: ghostStackId(s.stack, source),
520
+ data: withoutItemLabels(s.data),
521
+ label: { ...s.label, show: false }
522
+ };
523
+ if (s.type === "bar") {
524
+ return {
525
+ ...common,
526
+ itemStyle: { ...s.itemStyle, opacity: GHOST_BAR_OPACITY },
527
+ emphasis: {
528
+ ...s.emphasis,
529
+ itemStyle: { ...s.emphasis?.itemStyle, opacity: GHOST_BAR_OPACITY + 0.2 }
530
+ }
531
+ };
532
+ }
533
+ return {
534
+ ...common,
535
+ showSymbol: false,
536
+ areaStyle: void 0,
537
+ lineStyle: { ...s.lineStyle, type: "dashed", opacity: GHOST_LINE_OPACITY },
538
+ itemStyle: { ...s.itemStyle, opacity: GHOST_LINE_OPACITY },
539
+ emphasis: {
540
+ ...s.emphasis,
541
+ areaStyle: void 0
542
+ },
543
+ z: (s.z ?? 2) - 1
544
+ };
545
+ });
546
+ }
547
+
488
548
  // src/utils/stats.ts
489
549
  var isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
490
550
  var clean = (value) => Number(value.toPrecision(12));
@@ -637,20 +697,26 @@ function waterfallLayout(steps) {
637
697
  }
638
698
  function toPercentStack(series) {
639
699
  const length = Math.max(0, ...series.map((s) => s.data.length));
640
- const totals = Array.from(
700
+ const sumOf = (ghost) => Array.from(
641
701
  { length },
642
702
  (_, index) => series.reduce((sum, s) => {
703
+ if (s.variant === "ghost" !== ghost) return sum;
643
704
  const value = s.data[index];
644
705
  return sum + (isFiniteNumber(value) ? Math.abs(value) : 0);
645
706
  }, 0)
646
707
  );
647
- return series.map((s) => ({
648
- ...s,
649
- data: s.data.map((value, index) => {
650
- if (!isFiniteNumber(value)) return null;
651
- return totals[index] === 0 ? 0 : clean(value / totals[index] * 100);
652
- })
653
- }));
708
+ const totals = sumOf(false);
709
+ const ghostTotals = sumOf(true);
710
+ return series.map((s) => {
711
+ const sums = s.variant === "ghost" ? ghostTotals : totals;
712
+ return {
713
+ ...s,
714
+ data: s.data.map((value, index) => {
715
+ if (!isFiniteNumber(value)) return null;
716
+ return sums[index] === 0 ? 0 : clean(value / sums[index] * 100);
717
+ })
718
+ };
719
+ });
654
720
  }
655
721
  function stackTotals(series, stacked) {
656
722
  const length = Math.max(0, ...series.map((s) => s.data.length));
@@ -1428,4 +1494,4 @@ function downloadCsv(table, filename) {
1428
1494
  );
1429
1495
  }
1430
1496
 
1431
- 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 };
1497
+ export { DEFAULT_FORECAST_LABEL, GHOST_BAR_OPACITY, GHOST_LINE_OPACITY, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, barCornerRadius, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildStackTotalSeries, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, describeForecast, downloadCsv, downloadFile, escapeHtml, forecastStart, forecastTagLookup, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, ghostStackId, gridInset, hasForecast, hasGhostSeries, hasPointLabels, heatmapTable, histogramTable, isGhostSeries, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, stackTotals, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withEndLabelInset, withForecastBars, withForecastLines, withForecastPoints, withGhostSeries, withPointLabels, withReferenceMarks, withZoomInset, withoutGhostSeries };
@@ -33,6 +33,13 @@ interface LineSeriesData {
33
33
  forecastFrom?: number;
34
34
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
35
35
  forecastLabel?: string;
36
+ /**
37
+ * Draw the series as a faded reference (e.g. the prior period beside the
38
+ * current one): lines and areas dashed and faded with no fill or points,
39
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
40
+ * series carry no value labels and are left out of bar totals.
41
+ */
42
+ variant?: 'ghost';
36
43
  }
37
44
  interface BarChartData {
38
45
  /** Category labels */
@@ -63,6 +70,13 @@ interface BarSeriesData {
63
70
  forecastFrom?: number;
64
71
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
65
72
  forecastLabel?: string;
73
+ /**
74
+ * Draw the series as a faded reference (e.g. the prior period beside the
75
+ * current one): lines and areas dashed and faded with no fill or points,
76
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
77
+ * series carry no value labels and are left out of bar totals.
78
+ */
79
+ variant?: 'ghost';
66
80
  }
67
81
  interface PieSliceData {
68
82
  /** Slice name (shown in legend/tooltip) */
@@ -103,6 +117,13 @@ interface AreaSeriesData {
103
117
  forecastFrom?: number;
104
118
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
105
119
  forecastLabel?: string;
120
+ /**
121
+ * Draw the series as a faded reference (e.g. the prior period beside the
122
+ * current one): lines and areas dashed and faded with no fill or points,
123
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
124
+ * series carry no value labels and are left out of bar totals.
125
+ */
126
+ variant?: 'ghost';
106
127
  }
107
128
  interface ScatterChartData {
108
129
  /** Data series */
@@ -252,6 +273,13 @@ interface CategorySeriesData {
252
273
  forecastFrom?: number;
253
274
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
254
275
  forecastLabel?: string;
276
+ /**
277
+ * Draw the series as a faded reference (e.g. the prior period beside the
278
+ * current one): lines and areas dashed and faded with no fill or points,
279
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
280
+ * series carry no value labels and are left out of bar totals.
281
+ */
282
+ variant?: 'ghost';
255
283
  }
256
284
  interface ComboChartData {
257
285
  /** Category labels */
@@ -1198,6 +1226,34 @@ interface StatDelta {
1198
1226
  /** Text after the change, e.g. 'vs last year' */
1199
1227
  label?: string;
1200
1228
  }
1229
+ /**
1230
+ * Delta text: the change between two values as a coloured ▲/▼ with the
1231
+ * change and a "vs previous" label (the change line of `StatCard`, for KPI
1232
+ * rows, table cells and other inline use). Renders nothing when either value
1233
+ * is missing.
1234
+ */
1235
+ interface DeltaTextProps {
1236
+ /** The current value */
1237
+ current: number | null | undefined;
1238
+ /** The value being compared against (e.g. last year's) */
1239
+ previous: number | null | undefined;
1240
+ /**
1241
+ * How the change is shown: 'percent' (+12%), 'absolute' (+12, using
1242
+ * `valueFormat`) or 'both' (defaults to 'percent'). A change from zero
1243
+ * has no percentage, so it shows the absolute change.
1244
+ */
1245
+ display?: 'percent' | 'absolute' | 'both';
1246
+ /** Which direction is good, for colouring (defaults to 'up'); 'none' stays neutral */
1247
+ goodWhen?: 'up' | 'down' | 'none';
1248
+ /** How absolute changes and the previous value are written */
1249
+ valueFormat?: ValueFormat;
1250
+ /** Locale for `valueFormat` and the percentage (defaults to 'en-US') */
1251
+ locale?: string;
1252
+ /** Text after the change (defaults to 'vs <previous>'; '' hides it) */
1253
+ label?: string;
1254
+ /** Custom CSS class */
1255
+ class?: string;
1256
+ }
1201
1257
  /**
1202
1258
  * Stat card: a headline metric with its change and trend
1203
1259
  */
@@ -1232,4 +1288,4 @@ interface StatCardProps {
1232
1288
  class?: string;
1233
1289
  }
1234
1290
 
1235
- 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 };
1291
+ export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };
@@ -33,6 +33,13 @@ interface LineSeriesData {
33
33
  forecastFrom?: number;
34
34
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
35
35
  forecastLabel?: string;
36
+ /**
37
+ * Draw the series as a faded reference (e.g. the prior period beside the
38
+ * current one): lines and areas dashed and faded with no fill or points,
39
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
40
+ * series carry no value labels and are left out of bar totals.
41
+ */
42
+ variant?: 'ghost';
36
43
  }
37
44
  interface BarChartData {
38
45
  /** Category labels */
@@ -63,6 +70,13 @@ interface BarSeriesData {
63
70
  forecastFrom?: number;
64
71
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
65
72
  forecastLabel?: string;
73
+ /**
74
+ * Draw the series as a faded reference (e.g. the prior period beside the
75
+ * current one): lines and areas dashed and faded with no fill or points,
76
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
77
+ * series carry no value labels and are left out of bar totals.
78
+ */
79
+ variant?: 'ghost';
66
80
  }
67
81
  interface PieSliceData {
68
82
  /** Slice name (shown in legend/tooltip) */
@@ -103,6 +117,13 @@ interface AreaSeriesData {
103
117
  forecastFrom?: number;
104
118
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
105
119
  forecastLabel?: string;
120
+ /**
121
+ * Draw the series as a faded reference (e.g. the prior period beside the
122
+ * current one): lines and areas dashed and faded with no fill or points,
123
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
124
+ * series carry no value labels and are left out of bar totals.
125
+ */
126
+ variant?: 'ghost';
106
127
  }
107
128
  interface ScatterChartData {
108
129
  /** Data series */
@@ -252,6 +273,13 @@ interface CategorySeriesData {
252
273
  forecastFrom?: number;
253
274
  /** Tooltip tag for forecast values (defaults to 'Forecast') */
254
275
  forecastLabel?: string;
276
+ /**
277
+ * Draw the series as a faded reference (e.g. the prior period beside the
278
+ * current one): lines and areas dashed and faded with no fill or points,
279
+ * bars faded beside the solid ones rather than stacked onto them. Ghost
280
+ * series carry no value labels and are left out of bar totals.
281
+ */
282
+ variant?: 'ghost';
255
283
  }
256
284
  interface ComboChartData {
257
285
  /** Category labels */
@@ -1198,6 +1226,34 @@ interface StatDelta {
1198
1226
  /** Text after the change, e.g. 'vs last year' */
1199
1227
  label?: string;
1200
1228
  }
1229
+ /**
1230
+ * Delta text: the change between two values as a coloured ▲/▼ with the
1231
+ * change and a "vs previous" label (the change line of `StatCard`, for KPI
1232
+ * rows, table cells and other inline use). Renders nothing when either value
1233
+ * is missing.
1234
+ */
1235
+ interface DeltaTextProps {
1236
+ /** The current value */
1237
+ current: number | null | undefined;
1238
+ /** The value being compared against (e.g. last year's) */
1239
+ previous: number | null | undefined;
1240
+ /**
1241
+ * How the change is shown: 'percent' (+12%), 'absolute' (+12, using
1242
+ * `valueFormat`) or 'both' (defaults to 'percent'). A change from zero
1243
+ * has no percentage, so it shows the absolute change.
1244
+ */
1245
+ display?: 'percent' | 'absolute' | 'both';
1246
+ /** Which direction is good, for colouring (defaults to 'up'); 'none' stays neutral */
1247
+ goodWhen?: 'up' | 'down' | 'none';
1248
+ /** How absolute changes and the previous value are written */
1249
+ valueFormat?: ValueFormat;
1250
+ /** Locale for `valueFormat` and the percentage (defaults to 'en-US') */
1251
+ locale?: string;
1252
+ /** Text after the change (defaults to 'vs <previous>'; '' hides it) */
1253
+ label?: string;
1254
+ /** Custom CSS class */
1255
+ class?: string;
1256
+ }
1201
1257
  /**
1202
1258
  * Stat card: a headline metric with its change and trend
1203
1259
  */
@@ -1232,4 +1288,4 @@ interface StatCardProps {
1232
1288
  class?: string;
1233
1289
  }
1234
1290
 
1235
- 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 };
1291
+ export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DeltaTextProps, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@classic-homes/charts-core",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Core utilities and theme for Classic Theme charts",
5
5
  "type": "module",
6
6
  "main": "dist/index.cjs",