@classic-homes/charts-core 0.1.37 → 0.2.0

package/dist/types/index.d.ts

@@ -1,3 +1,5 @@
+import { EChartsOption } from 'echarts';
+
 /**
  * Data structure types for all chart components
  */
@@ -14,6 +16,8 @@ interface LineSeriesData {
     data: number[];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
 }
 interface BarChartData {
     /** Category labels */
@@ -28,6 +32,8 @@ interface BarSeriesData {
     data: number[];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
 }
 interface PieSliceData {
     /** Slice name (shown in legend/tooltip) */
@@ -36,6 +42,8 @@ interface PieSliceData {
     value: number;
     /** Override theme color for this slice */
     color?: string;
+    /** Label text shown for this slice instead of the default (templates allowed) */
+    label?: string;
 }
 interface AreaChartData {
     /** X-axis category labels */
@@ -50,6 +58,8 @@ interface AreaSeriesData {
     data: number[];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
 }
 interface ScatterChartData {
     /** Data series */
@@ -62,6 +72,8 @@ interface ScatterSeriesData {
     data: [number, number][];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
 }
 interface RadarChartData {
     /** Data series */
@@ -90,6 +102,8 @@ interface FunnelSliceData {
     value: number;
     /** Override theme color for this slice */
     color?: string;
+    /** Label text shown for this stage instead of the default (templates allowed) */
+    label?: string;
 }
 interface HeatmapData {
     /** Data points as [xIndex, yIndex, value] */
@@ -108,6 +122,8 @@ interface TreemapNode {
     children?: TreemapNode[];
     /** Override theme color for this node */
     color?: string;
+    /** Label text shown for this node instead of the default (templates allowed) */
+    label?: string;
 }
 interface TreemapLevel {
     /** Level index (0 = root) */
@@ -153,6 +169,8 @@ interface SankeyNode {
     name: string;
     /** Override theme color for this node */
     color?: string;
+    /** Label text shown for this node instead of the default (templates allowed) */
+    label?: string;
 }
 interface SankeyLink {
     /** Source node name */
@@ -272,6 +290,119 @@ interface SankeyEventParams extends BaseEventParams {
     target?: string;
 }
 
+/**
+ * Types for customising chart labels, axes, tooltips and legends
+ */
+/**
+ * A formatter: either an ECharts string template (e.g. `'{b}: {c}'`) or a
+ * function returning the text to show.
+ */
+type ChartFormatter<P> = string | ((params: P) => string);
+/**
+ * Normalised parameters passed to label and tooltip formatter functions
+ */
+interface LabelFormatterParams {
+    /** Category, slice or node name */
+    name: string;
+    /** Data value ([x, y] for scatter, [x, y, value] for heatmap) */
+    value: number | number[];
+    /** Series name */
+    seriesName: string;
+    /** Series index */
+    seriesIndex: number;
+    /** Data index within the series */
+    dataIndex: number;
+    /** Share of the total, for pie, donut and funnel slices */
+    percent?: number;
+    /** Colour of the data point */
+    color?: string;
+    /** Per-point label text supplied in the chart data, if any */
+    label?: string;
+}
+/**
+ * Parameters passed to a tooltip formatter function, one entry per series
+ * under the pointer (a single entry for item tooltips)
+ */
+interface TooltipFormatterParams extends LabelFormatterParams {
+    /** HTML for the coloured dot ECharts draws before each series */
+    marker: string;
+    /** Axis value under the pointer, for axis tooltips */
+    axisValue?: string | number;
+}
+/**
+ * Axis customisation for charts with cartesian axes. Refers to the visual
+ * axis: `xAxisConfig` is always the horizontal one.
+ */
+interface AxisConfig {
+    /** Show the axis (defaults to true) */
+    show?: boolean;
+    /** Axis title */
+    name?: string;
+    /** Where the axis title sits (defaults to 'middle') */
+    nameLocation?: 'start' | 'middle' | 'end';
+    /** Distance between the axis title and the axis line, in pixels */
+    nameGap?: number;
+    /** Tick label formatter: a template such as `'{value} kg'` or a function */
+    formatter?: string | ((value: string | number, index: number) => string);
+    /** Tick label rotation in degrees */
+    rotate?: number;
+    /** Axis minimum */
+    min?: number | 'dataMin';
+    /** Axis maximum */
+    max?: number | 'dataMax';
+    /** Fixed interval between ticks (value axes) */
+    interval?: number;
+}
+/** Where the legend is placed */
+type ChartLegendPosition = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Built-in legend customisation
+ */
+interface ChartLegendConfig {
+    /** Legend placement (defaults to 'bottom') */
+    position?: ChartLegendPosition;
+    /** Alignment along the legend's edge (defaults to 'center') */
+    align?: 'start' | 'center' | 'end';
+    /** Item flow; defaults to horizontal for top/bottom, vertical for left/right */
+    orient?: 'horizontal' | 'vertical';
+    /** Legend marker shape */
+    icon?: 'circle' | 'rect' | 'roundRect' | 'line' | 'none';
+    /** Item text: a template such as `'{name}'` or a function of the series name */
+    formatter?: ChartFormatter<string>;
+    /** Page the legend when items overflow instead of wrapping */
+    scroll?: boolean;
+}
+/**
+ * One entry of a chart legend
+ */
+interface LegendItem {
+    /** Series, slice or indicator name */
+    name: string;
+    /** Colour the chart draws the item in */
+    color: string;
+    /** Whether the item is currently shown */
+    visible: boolean;
+}
+/**
+ * State and actions handed to a custom legend renderer
+ */
+interface LegendRenderProps {
+    /** Legend entries in chart order */
+    items: LegendItem[];
+    /** Requested legend placement */
+    position: ChartLegendPosition;
+    /** Chart title, for labelling the legend */
+    chartTitle: string;
+    /** Show or hide an item */
+    toggle: (name: string) => void;
+    /** Set an item's visibility */
+    setVisible: (name: string, visible: boolean) => void;
+    /** Show only this item */
+    showOnly: (name: string) => void;
+    /** Show every item */
+    showAll: () => void;
+}
+
 /**
  * Base chart props shared across all chart components
  */
@@ -302,13 +433,53 @@ interface BaseChartProps {
     showTooltip?: boolean;
     /** Show grid lines (where applicable) */
     showGrid?: boolean;
+    /**
+     * Custom tooltip content: an ECharts template or a function returning HTML.
+     * The function always receives an array (one entry for item tooltips).
+     * Escape any data you interpolate (see `escapeHtml`).
+     */
+    tooltipFormatter?: ChartFormatter<TooltipFormatterParams[]>;
+    /** Format the values in the default tooltip, e.g. as currency */
+    tooltipValueFormatter?: (value: number) => string;
+    /**
+     * Raw ECharts option deep-merged over the generated one, for anything the
+     * props do not cover. Arrays such as `series` merge by index.
+     */
+    option?: EChartsOption;
     /** Custom CSS class */
     class?: string;
 }
+/**
+ * Props for charts with a legend
+ */
+interface LegendChartProps {
+    /** Built-in legend placement and formatting */
+    legend?: ChartLegendConfig;
+    /** Called when legend items are shown or hidden, with every item's visibility */
+    onLegendChange?: (visible: Record<string, boolean>) => void;
+}
+/**
+ * Props for charts with data labels
+ */
+interface LabelChartProps {
+    /** Data label text: an ECharts template or a function */
+    labelFormatter?: ChartFormatter<LabelFormatterParams>;
+}
+/**
+ * Props for charts with cartesian axes
+ */
+interface AxisChartProps {
+    /** Horizontal axis customisation */
+    xAxisConfig?: AxisConfig;
+    /** Vertical axis customisation */
+    yAxisConfig?: AxisConfig;
+}
 /**
  * Line chart specific props
  */
-interface LineChartProps extends BaseChartProps {
+interface LineChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: LineChartData;
     /** Use smooth curved lines */
@@ -327,7 +498,7 @@ interface LineChartProps extends BaseChartProps {
 /**
  * Bar chart specific props
  */
-interface BarChartProps extends BaseChartProps {
+interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps {
     /** Chart data */
     data: BarChartData;
     /** Bar orientation */
@@ -342,7 +513,7 @@ interface BarChartProps extends BaseChartProps {
 /**
  * Pie chart specific props
  */
-interface PieChartProps extends BaseChartProps {
+interface PieChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
     /** Chart data */
     data: PieSliceData[];
     /** Show slice labels */
@@ -368,7 +539,9 @@ interface DonutChartProps extends Omit<PieChartProps, 'innerRadius'> {
 /**
  * Area chart specific props
  */
-interface AreaChartProps extends BaseChartProps {
+interface AreaChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: AreaChartData;
     /** Use smooth curved lines */
@@ -383,7 +556,9 @@ interface AreaChartProps extends BaseChartProps {
 /**
  * Scatter chart specific props
  */
-interface ScatterChartProps extends BaseChartProps {
+interface ScatterChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: ScatterChartData;
     /** Show trend/regression line */
@@ -396,7 +571,9 @@ interface ScatterChartProps extends BaseChartProps {
 /**
  * Radar chart specific props
  */
-interface RadarChartProps extends BaseChartProps {
+interface RadarChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: RadarChartData;
     /** Radar indicators/dimensions */
@@ -407,7 +584,7 @@ interface RadarChartProps extends BaseChartProps {
 /**
  * Funnel chart specific props
  */
-interface FunnelChartProps extends BaseChartProps {
+interface FunnelChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
     /** Chart data */
     data: FunnelSliceData[];
     /** Sort order */
@@ -439,7 +616,7 @@ interface GaugeChartProps extends BaseChartProps {
 /**
  * Heatmap chart specific props
  */
-interface HeatmapChartProps extends BaseChartProps {
+interface HeatmapChartProps extends BaseChartProps, LabelChartProps, AxisChartProps {
     /** Chart data */
     data: HeatmapData;
     /** X-axis labels */
@@ -454,7 +631,7 @@ interface HeatmapChartProps extends BaseChartProps {
 /**
  * Treemap chart specific props
  */
-interface TreemapChartProps extends BaseChartProps {
+interface TreemapChartProps extends BaseChartProps, LabelChartProps {
     /** Hierarchical data */
     data: TreemapNode[];
     /** Level configurations */
@@ -465,7 +642,7 @@ interface TreemapChartProps extends BaseChartProps {
 /**
  * Candlestick chart specific props
  */
-interface CandlestickChartProps extends BaseChartProps {
+interface CandlestickChartProps extends BaseChartProps, AxisChartProps {
     /** Chart data */
     data: CandlestickData;
     /** Show volume bars */
@@ -476,7 +653,7 @@ interface CandlestickChartProps extends BaseChartProps {
 /**
  * Sankey chart specific props
  */
-interface SankeyChartProps extends BaseChartProps {
+interface SankeyChartProps extends BaseChartProps, LabelChartProps {
     /** Chart data with nodes and links */
     data: SankeyData;
     /** Flow orientation */
@@ -485,4 +662,4 @@ interface SankeyChartProps extends BaseChartProps {
     onClick?: (params: SankeyEventParams) => void;
 }
 
-export type { AreaChartData, AreaChartProps, AreaSeriesData, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode };
+export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartFormatter, ChartLegendConfig, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode };

package/package.json

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