@classic-homes/charts-svelte 0.2.0 → 0.3.0

package/dist/lib/components/core/DonutChart.svelte

@@ -1,11 +1,10 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { PieChart as EChartsPieChart } from 'echarts/charts';
-  import { TooltipComponent, LegendComponent, TitleComponent } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { TooltipComponent, LegendComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
-  import type { DonutChartProps, SliceEventParams } from '@classic-homes/charts-core';
+  import type { DonutChartProps } from '@classic-homes/charts-core';
   import {
     buildDataLabel,
     buildLegend,
@@ -19,9 +18,12 @@
     legendCenter,
     mergeChartOption,
     pointLabel,
+    resolveValueFormatter,
+    sliceTable,
   } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents, toSliceParams } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import {
     useChartLegend,
@@ -30,7 +32,7 @@
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
-  echarts.use([EChartsPieChart, TooltipComponent, LegendComponent, TitleComponent, CanvasRenderer]);
+  echarts.use([EChartsPieChart, TooltipComponent, LegendComponent]);
 
   interface Props extends Omit<DonutChartProps, 'class'>, CustomLegendProps {
     class?: string;
@@ -41,8 +43,11 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -53,6 +58,8 @@
     innerRadius = '50%',
     centerLabel,
     centerValue,
+    valueFormat,
+    locale,
     labelFormatter,
     tooltipFormatter,
     tooltipValueFormatter,
@@ -60,12 +67,22 @@
     renderLegend,
     onLegendChange,
     option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
     onClick,
     class: className,
   }: Props = $props();
 
   const isEmpty = $derived(!data?.length);
 
+  // Slice labels show shares; `valueFormat` writes the values in tooltips and the data table
+  const valueFormatter = $derived(
+    tooltipValueFormatter ?? resolveValueFormatter(valueFormat, locale)
+  );
+
   // Per-element colours that follow the resolved chart theme
   const chartColors = $derived.by(() => getChartColors(chart.theme));
 
@@ -131,7 +148,7 @@
             trigger: 'item',
             // A string template ignores valueFormatter, so format the value here
             formatter:
-              tooltipValueFormatter && !tooltipFormatter
+              valueFormatter && !tooltipFormatter
                 ? (params: unknown) => {
                     const p = params as {
                       seriesName?: string;
@@ -139,14 +156,14 @@
                       value?: unknown;
                       percent?: number;
                     };
-                    return `${escapeHtml(p.seriesName)} <br/>${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, tooltipValueFormatter))} (${p.percent}%)`;
+                    return `${escapeHtml(p.seriesName)} <br/>${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, valueFormatter))} (${p.percent}%)`;
                   }
                 : '{a} <br/>{b}: {c} ({d}%)',
           },
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter,
             getLabel,
           }
         ),
@@ -200,6 +217,8 @@
     description || (!isEmpty ? generatePieChartDescription(title, data, true) : undefined)
   );
 
+  const dataTable = $derived(isEmpty ? undefined : sliceTable(data));
+
   // Legend selection state, shared with a custom legend
   const legend = useChartLegend({
     names: () => data?.map((d) => d.name) ?? [],
@@ -216,21 +235,13 @@
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      legend.attach(instance);
-      if (onClick) {
-        instance.on('click', (params) => {
-          onClick({
-            type: params.type || 'click',
-            componentType: params.componentType || 'series',
-            name: params.name || '',
-            value: params.value as number,
-            percent: params.percent,
-            color: params.color as string,
-          } as SliceEventParams);
-        });
-      }
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click: onClick && ((params) => onClick(toSliceParams(params, 'click'))),
+      }),
+    onReady: (instance) => legend.attach(instance),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -242,13 +253,21 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
   legend={renderLegend ? customLegend : undefined}
   legendPosition={legendConfig?.position}
+  {dataTable}
+  {showDataTable}
+  format={resolveValueFormatter(valueFormat, locale)}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/core/LineChart.svelte

@@ -1,31 +1,35 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { LineChart as EChartsLineChart } from 'echarts/charts';
-  import {
-    GridComponent,
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-  } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { GridComponent, TooltipComponent, LegendComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
-  import type { LineChartProps, DataPointEventParams } from '@classic-homes/charts-core';
+  import type { LineChartProps } from '@classic-homes/charts-core';
   import {
+    allSeriesEmpty,
     buildAxis,
     buildDataLabel,
+    buildDataZoom,
     buildLegend,
     buildTooltip,
+    categoryTable,
+    chartFormatters,
     generateLineChartDescription,
     getChartColors,
     hasPointLabels,
     gridInset,
     mergeChartOption,
+    pairWithCategories,
+    resolveValueFormatter,
     seriesLabelLookup,
+    toPercentStack,
     withPointLabels,
+    withReferenceMarks,
+    withZoomInset,
   } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents, toDataPointParams } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import {
     useChartLegend,
@@ -34,14 +38,7 @@
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
-  echarts.use([
-    EChartsLineChart,
-    GridComponent,
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-    CanvasRenderer,
-  ]);
+  echarts.use([EChartsLineChart, GridComponent, TooltipComponent, LegendComponent]);
 
   interface Props extends Omit<LineChartProps, 'class'>, CustomLegendProps {
     class?: string;
@@ -52,8 +49,11 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -64,34 +64,85 @@
     areaFilled = false,
     showDataPoints = false,
     stacked = false,
+    connectNulls = false,
     showLabels = false,
+    valueFormat,
+    locale,
     labelFormatter,
     xAxisConfig,
     yAxisConfig,
+    referenceLines,
+    referenceBands,
+    dataZoom,
     tooltipFormatter,
     tooltipValueFormatter,
     legend: legendConfig,
     renderLegend,
     onLegendChange,
     option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
     onClick,
     onHover,
     class: className,
   }: Props = $props();
 
-  const isEmpty = $derived(
-    !data?.categories?.length || !data?.series?.length || data.series.every((s) => !s.data?.length)
+  const isEmpty = $derived(!data?.categories?.length || allSeriesEmpty(data?.series));
+
+  const isPercent = $derived(stacked === 'percent');
+
+  // Percent stacks plot shares, so they always read as percentages
+  const formatters = $derived(
+    chartFormatters({
+      valueFormat: isPercent ? 'percentValue' : valueFormat,
+      locale,
+      tooltipValueFormatter,
+      labelFormatter,
+    })
   );
 
   // Per-element colours that follow the resolved chart theme
   const chartColors = $derived.by(() => getChartColors(chart.theme));
 
+  const builtInLegend = $derived(showLegend && !renderLegend);
+
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
+    const plotted = isPercent ? toPercentStack(data.series) : data.series;
     const getLabel = seriesLabelLookup(data.series);
     // ECharts hides line labels along with the symbol
     const showSymbol = showDataPoints || showLabels || hasPointLabels(data.series);
+    const legendBottom = builtInLegend && (legendConfig?.position ?? 'bottom') === 'bottom';
+
+    const series = data.series.map((source, index) => ({
+      name: source.name,
+      type: 'line',
+      data: withPointLabels(
+        pairWithCategories(data.categories, plotted[index].data, xAxisConfig?.type),
+        source.labels,
+        formatters.label,
+        { position: 'top' }
+      ),
+      smooth,
+      showSymbol,
+      symbolSize: showDataPoints ? 6 : 0,
+      connectNulls,
+      stack: source.stack ?? (stacked ? 'Total' : undefined),
+      areaStyle: areaFilled ? { opacity: 0.3 } : undefined,
+      itemStyle: source.color ? { color: source.color } : undefined,
+      label: buildDataLabel({ show: true, position: 'top' }, undefined, {
+        show: showLabels,
+        formatter: formatters.label,
+        getLabel,
+      }),
+      emphasis: {
+        focus: 'series',
+      },
+    }));
 
     return mergeChartOption(
       {
@@ -100,7 +151,11 @@
           right: '4%',
           bottom: '3%',
           containLabel: true,
-          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+          ...withZoomInset(
+            gridInset(legendConfig, builtInLegend, xAxisConfig, yAxisConfig),
+            dataZoom,
+            'x'
+          ),
         },
         tooltip: buildTooltip(
           {
@@ -115,7 +170,7 @@
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter: formatters.tooltip,
             getLabel,
           }
         ),
@@ -124,6 +179,7 @@
           legendConfig,
           { show: showLegend, custom: !!renderLegend }
         ),
+        dataZoom: buildDataZoom(dataZoom, 'x', legendBottom ? 36 : 0),
         xAxis: buildAxis(
           {
             type: 'category',
@@ -138,40 +194,31 @@
         yAxis: buildAxis(
           {
             type: 'value',
+            ...(isPercent && { max: 100 }),
             splitLine: {
               show: showGrid,
             },
           },
-          yAxisConfig
+          formatters.axis(yAxisConfig)
         ),
-        series: data.series.map((series) => ({
-          name: series.name,
-          type: 'line',
-          data: withPointLabels(series.data, series.labels, labelFormatter, { position: 'top' }),
-          smooth,
-          showSymbol,
-          symbolSize: showDataPoints ? 6 : 0,
-          stack: stacked ? 'Total' : undefined,
-          areaStyle: areaFilled ? { opacity: 0.3 } : undefined,
-          itemStyle: series.color ? { color: series.color } : undefined,
-          label: buildDataLabel({ show: true, position: 'top' }, undefined, {
-            show: showLabels,
-            formatter: labelFormatter,
-            getLabel,
-          }),
-          emphasis: {
-            focus: 'series',
-          },
-        })),
+        series: withReferenceMarks(series, referenceLines, referenceBands, {
+          valueAxis: 'y',
+          format: formatters.format,
+          color: chartColors.reference,
+          bandColor: chartColors.referenceBand,
+        }),
       } as EChartsOption,
       optionOverride
     );
   });
 
   const accessibilityDescription = $derived(
-    description || (!isEmpty ? generateLineChartDescription(title, data) : undefined)
+    description ||
+      (!isEmpty ? generateLineChartDescription(title, data, formatters.format) : undefined)
   );
 
+  const dataTable = $derived(isEmpty ? undefined : categoryTable(data));
+
   // Legend selection state, shared with a custom legend
   const legend = useChartLegend({
     names: () => data?.series?.map((s) => s.name) ?? [],
@@ -188,38 +235,14 @@
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      legend.attach(instance);
-      if (onClick) {
-        instance.on('click', (params) => {
-          onClick({
-            type: params.type || 'click',
-            componentType: params.componentType || 'series',
-            seriesIndex: params.seriesIndex,
-            seriesName: params.seriesName || '',
-            dataIndex: params.dataIndex || 0,
-            name: params.name || '',
-            value: params.value as number,
-            color: params.color as string,
-          } as DataPointEventParams);
-        });
-      }
-
-      if (onHover) {
-        instance.on('mouseover', (params) => {
-          onHover({
-            type: params.type || 'mouseover',
-            componentType: params.componentType || 'series',
-            seriesIndex: params.seriesIndex,
-            seriesName: params.seriesName || '',
-            dataIndex: params.dataIndex || 0,
-            name: params.name || '',
-            value: params.value as number,
-            color: params.color as string,
-          } as DataPointEventParams);
-        });
-      }
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click: onClick && ((params) => onClick(toDataPointParams(params, 'click'))),
+        mouseover: onHover && ((params) => onHover(toDataPointParams(params, 'mouseover'))),
+      }),
+    onReady: (instance) => legend.attach(instance),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -231,13 +254,21 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
   legend={renderLegend ? customLegend : undefined}
   legendPosition={legendConfig?.position}
+  {dataTable}
+  {showDataTable}
+  format={resolveValueFormatter(valueFormat, locale)}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/core/PieChart.svelte

@@ -1,11 +1,10 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { PieChart as EChartsPieChart } from 'echarts/charts';
-  import { TooltipComponent, LegendComponent, TitleComponent } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { TooltipComponent, LegendComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
-  import type { PieChartProps, SliceEventParams } from '@classic-homes/charts-core';
+  import type { PieChartProps } from '@classic-homes/charts-core';
   import {
     buildDataLabel,
     buildLegend,
@@ -18,9 +17,12 @@
     legendCenter,
     mergeChartOption,
     pointLabel,
+    resolveValueFormatter,
+    sliceTable,
   } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents, toSliceParams } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import {
     useChartLegend,
@@ -29,7 +31,7 @@
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
-  echarts.use([EChartsPieChart, TooltipComponent, LegendComponent, TitleComponent, CanvasRenderer]);
+  echarts.use([EChartsPieChart, TooltipComponent, LegendComponent]);
 
   interface Props extends Omit<PieChartProps, 'class'>, CustomLegendProps {
     class?: string;
@@ -40,8 +42,11 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -50,6 +55,8 @@
     showLabels = true,
     labelPosition = 'outside',
     innerRadius = 0,
+    valueFormat,
+    locale,
     labelFormatter,
     tooltipFormatter,
     tooltipValueFormatter,
@@ -57,12 +64,22 @@
     renderLegend,
     onLegendChange,
     option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
     onClick,
     class: className,
   }: Props = $props();
 
   const isEmpty = $derived(!data?.length);
 
+  // Slice labels show shares; `valueFormat` writes the values in tooltips and the data table
+  const valueFormatter = $derived(
+    tooltipValueFormatter ?? resolveValueFormatter(valueFormat, locale)
+  );
+
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
@@ -75,7 +92,7 @@
             trigger: 'item',
             // A string template ignores valueFormatter, so format the value here
             formatter:
-              tooltipValueFormatter && !tooltipFormatter
+              valueFormatter && !tooltipFormatter
                 ? (params: unknown) => {
                     const p = params as {
                       seriesName?: string;
@@ -83,14 +100,14 @@
                       value?: unknown;
                       percent?: number;
                     };
-                    return `${escapeHtml(p.seriesName)} <br/>${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, tooltipValueFormatter))} (${p.percent}%)`;
+                    return `${escapeHtml(p.seriesName)} <br/>${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, valueFormatter))} (${p.percent}%)`;
                   }
                 : '{a} <br/>{b}: {c} ({d}%)',
           },
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter,
             getLabel,
           }
         ),
@@ -138,6 +155,8 @@
     description || (!isEmpty ? generatePieChartDescription(title, data, false) : undefined)
   );
 
+  const dataTable = $derived(isEmpty ? undefined : sliceTable(data));
+
   // Legend selection state, shared with a custom legend
   const legend = useChartLegend({
     names: () => data?.map((d) => d.name) ?? [],
@@ -154,21 +173,13 @@
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      legend.attach(instance);
-      if (onClick) {
-        instance.on('click', (params) => {
-          onClick({
-            type: params.type || 'click',
-            componentType: params.componentType || 'series',
-            name: params.name || '',
-            value: params.value as number,
-            percent: params.percent,
-            color: params.color as string,
-          } as SliceEventParams);
-        });
-      }
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click: onClick && ((params) => onClick(toSliceParams(params, 'click'))),
+      }),
+    onReady: (instance) => legend.attach(instance),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -180,13 +191,21 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
   legend={renderLegend ? customLegend : undefined}
   legendPosition={legendConfig?.position}
+  {dataTable}
+  {showDataTable}
+  format={resolveValueFormatter(valueFormat, locale)}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>