@classic-homes/charts-svelte 0.2.0 → 0.3.0

package/dist/lib/components/extended/GaugeChart.svelte

@@ -1,18 +1,24 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { GaugeChart as EChartsGaugeChart } from 'echarts/charts';
-  import { TitleComponent, TooltipComponent } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { TooltipComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
   import type { GaugeChartProps } from '@classic-homes/charts-core';
-  import { buildTooltip, getChartColors, mergeChartOption } from '@classic-homes/charts-core';
+  import {
+    buildTooltip,
+    formatValue as formatChartValue,
+    getChartColors,
+    mergeChartOption,
+    resolveValueFormatter,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents, toDataPointParams } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
-  echarts.use([EChartsGaugeChart, TitleComponent, TooltipComponent, CanvasRenderer]);
+  echarts.use([EChartsGaugeChart, TooltipComponent]);
 
   interface Props extends Omit<GaugeChartProps, 'class'> {
     class?: string;
@@ -25,33 +31,57 @@
     min = 0,
     max = 100,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
     splitNumber = 10,
     showProgress = true,
     formatValue,
+    valueFormat,
+    locale,
     showTooltip = true,
     tooltipFormatter,
     tooltipValueFormatter,
     option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
     class: className,
   }: Props = $props();
 
+  // A missing or non-numeric value has nothing to point at
+  const isEmpty = $derived(typeof value !== 'number' || !Number.isFinite(value));
+
+  const valueFormatter = $derived(formatValue ?? resolveValueFormatter(valueFormat, locale));
+
   // Manage ECharts instance lifecycle (init, theme, resize, option updates)
   const chart = useChart({
     option: () => option,
     theme: () => theme,
     animation: () => animation,
+    isEmpty: () => isEmpty,
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click: onClick && ((params) => onClick(toDataPointParams(params, 'click'))),
+      }),
+    onCreated: () => onReady,
   });
 
   // Per-element colours that follow the resolved chart theme
   const chartColors = $derived.by(() => getChartColors(chart.theme));
 
-  const option: EChartsOption = $derived.by(() =>
-    mergeChartOption(
+  const option: EChartsOption = $derived.by(() => {
+    if (isEmpty) return {};
+    return mergeChartOption(
       {
         // No tooltip by default; one appears only when a formatter is set
         tooltip:
@@ -94,18 +124,30 @@
               fontSize: 28,
               fontWeight: 'bold',
               offsetCenter: [0, '40%'],
-              formatter: formatValue || '{value}',
+              formatter: valueFormatter || '{value}',
             },
             data: [{ value, name: title }],
           },
         ],
       } as EChartsOption,
       optionOverride
-    )
-  );
+    );
+  });
 
   const accessibilityDescription = $derived(
-    description || `${title}. Gauge showing value ${value} on scale from ${min} to ${max}.`
+    description ||
+      (isEmpty
+        ? undefined
+        : `${title}. Gauge showing value ${formatChartValue(value, valueFormatter)} on scale from ${formatChartValue(min, valueFormatter)} to ${formatChartValue(max, valueFormatter)}.`)
+  );
+
+  const dataTable = $derived(
+    isEmpty
+      ? undefined
+      : {
+          headers: ['Metric', 'Value', 'Minimum', 'Maximum'],
+          rows: [[title, value, min, max]],
+        }
   );
 </script>
 
@@ -113,10 +155,19 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
+  empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  format={valueFormatter}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/extended/HeatmapChart.svelte

@@ -1,13 +1,7 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { HeatmapChart as EChartsHeatmapChart } from 'echarts/charts';
-  import {
-    GridComponent,
-    TooltipComponent,
-    TitleComponent,
-    VisualMapComponent,
-  } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { GridComponent, TooltipComponent, VisualMapComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
   import type { HeatmapChartProps, HeatmapEventParams } from '@classic-homes/charts-core';
@@ -15,23 +9,21 @@
     buildAxis,
     buildDataLabel,
     buildTooltip,
+    colorWithAlpha,
     escapeHtml,
     formatTooltipValue,
+    getChartColors,
+    heatmapTable,
     mergeChartOption,
+    resolveValueFormatter,
   } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
-  echarts.use([
-    EChartsHeatmapChart,
-    GridComponent,
-    TooltipComponent,
-    TitleComponent,
-    VisualMapComponent,
-    CanvasRenderer,
-  ]);
+  echarts.use([EChartsHeatmapChart, GridComponent, TooltipComponent, VisualMapComponent]);
 
   interface Props extends Omit<HeatmapChartProps, 'class'> {
     class?: string;
@@ -44,8 +36,11 @@
     xAxis,
     yAxis,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -57,10 +52,25 @@
     tooltipFormatter,
     tooltipValueFormatter,
     option: optionOverride,
+    valueFormat,
+    locale,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
     onClick,
     class: className,
   }: Props = $props();
 
+  // `valueFormat` writes 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));
+
   const isEmpty = $derived(!data?.data?.length || !xAxis?.length || !yAxis?.length);
 
   // A loop: spreading large arrays into Math.min/max overflows the call stack
@@ -88,10 +98,10 @@
               const p = params as { value?: [number, number, number] };
               if (!p.value) return '';
               const [xIdx, yIdx, value] = p.value;
-              return `${escapeHtml(xAxis[xIdx])} / ${escapeHtml(yAxis[yIdx])}: ${escapeHtml(formatTooltipValue(value, tooltipValueFormatter))}`;
+              return `${escapeHtml(xAxis[xIdx])} / ${escapeHtml(yAxis[yIdx])}: ${escapeHtml(formatTooltipValue(value, valueFormatter))}`;
             },
           },
-          { show: showTooltip, formatter: tooltipFormatter, valueFormatter: tooltipValueFormatter }
+          { show: showTooltip, formatter: tooltipFormatter, valueFormatter }
         ),
         grid: { left: '3%', right: '10%', bottom: '3%', containLabel: true },
         xAxis: buildAxis({ type: 'category', data: xAxis, splitArea: { show: true } }, xAxisConfig),
@@ -103,6 +113,12 @@
           orient: 'vertical',
           right: '0%',
           top: 'center',
+          // Shade from a faint to a full first series colour, matching the theme
+          inRange: {
+            color: [colorWithAlpha(chartColors.series[0], 0.08), chartColors.series[0]],
+          },
+          textStyle: { color: chartColors.mutedForeground },
+          formatter: valueFormatter ? (value: number) => valueFormatter(value) : undefined,
         },
         series: [
           {
@@ -128,28 +144,33 @@
         : undefined)
   );
 
+  const dataTable = $derived(isEmpty ? undefined : heatmapTable(data, xAxis, yAxis));
+
   // Manage ECharts instance lifecycle (init, theme, resize, option updates)
   const chart = useChart({
     option: () => option,
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      if (onClick) {
-        instance.on('click', (params) => {
-          const [xIdx, yIdx, value] = (params.value as [number, number, number]) || [0, 0, 0];
-          onClick({
-            type: params.type || 'click',
-            componentType: params.componentType || 'series',
-            xIndex: xIdx,
-            yIndex: yIdx,
-            xLabel: xAxis[xIdx],
-            yLabel: yAxis[yIdx],
-            value,
-          } as HeatmapEventParams);
-        });
-      }
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click:
+          onClick &&
+          ((params) => {
+            const [xIdx, yIdx, value] = (params.value as [number, number, number]) || [0, 0, 0];
+            onClick({
+              type: params.type || 'click',
+              componentType: params.componentType || 'series',
+              xIndex: xIdx,
+              yIndex: yIdx,
+              xLabel: xAxis[xIdx],
+              yLabel: yAxis[yIdx],
+              value,
+            } as HeatmapEventParams);
+          }),
+      }),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -157,11 +178,19 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  format={valueFormatter}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/extended/RadarChart.svelte

@@ -1,13 +1,7 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { RadarChart as EChartsRadarChart } from 'echarts/charts';
-  import {
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-    RadarComponent,
-  } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { TooltipComponent, LegendComponent, RadarComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
   import type { RadarChartProps } from '@classic-homes/charts-core';
@@ -18,9 +12,12 @@
     getChartColors,
     legendCenter,
     mergeChartOption,
+    radarTable,
+    resolveValueFormatter,
   } 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,
@@ -28,14 +25,7 @@
   } from '../../composables/useChartLegend.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
-  echarts.use([
-    EChartsRadarChart,
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-    RadarComponent,
-    CanvasRenderer,
-  ]);
+  echarts.use([EChartsRadarChart, TooltipComponent, LegendComponent, RadarComponent]);
 
   interface Props extends Omit<RadarChartProps, 'class'>, CustomLegendProps {
     class?: string;
@@ -47,8 +37,11 @@
     data,
     indicators,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -63,9 +56,22 @@
     renderLegend,
     onLegendChange,
     option: optionOverride,
+    valueFormat,
+    locale,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
     class: className,
   }: Props = $props();
 
+  // `valueFormat` writes values in tooltips and the data table
+  const valueFormatter = $derived(
+    tooltipValueFormatter ?? resolveValueFormatter(valueFormat, locale)
+  );
+
   const isEmpty = $derived(
     !data?.series?.length || !indicators?.length || data.series.every((s) => !s.data?.length)
   );
@@ -77,7 +83,7 @@
       {
         tooltip: buildTooltip(
           { trigger: 'item' },
-          { show: showTooltip, formatter: tooltipFormatter, valueFormatter: tooltipValueFormatter }
+          { show: showTooltip, formatter: tooltipFormatter, valueFormatter }
         ),
         legend: buildLegend(
           data.series.map((s) => s.name),
@@ -130,15 +136,21 @@
     onLegendChange: () => onLegendChange,
   });
 
+  const dataTable = $derived(isEmpty ? undefined : radarTable(data, indicators));
+
   // Manage ECharts instance lifecycle (init, theme, resize, option updates)
   const chart = useChart({
     option: () => option,
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      legend.attach(instance);
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click: onClick && ((params) => onClick(toDataPointParams(params, 'click'))),
+      }),
+    onReady: (instance) => legend.attach(instance),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -150,13 +162,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={valueFormatter}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/extended/SankeyChart.svelte

@@ -1,8 +1,7 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { SankeyChart as EChartsSankeyChart } from 'echarts/charts';
-  import { TooltipComponent, TitleComponent } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { TooltipComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
   import type { SankeyChartProps, SankeyEventParams } from '@classic-homes/charts-core';
@@ -12,13 +11,16 @@
     mergeChartOption,
     nameLabelLookup,
     pointLabel,
+    resolveValueFormatter,
+    sankeyTable,
   } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
-  echarts.use([EChartsSankeyChart, TooltipComponent, TitleComponent, CanvasRenderer]);
+  echarts.use([EChartsSankeyChart, TooltipComponent]);
 
   interface Props extends Omit<SankeyChartProps, 'class'> {
     class?: string;
@@ -29,8 +31,11 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -40,10 +45,22 @@
     tooltipFormatter,
     tooltipValueFormatter,
     option: optionOverride,
+    valueFormat,
+    locale,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
     onClick,
     class: className,
   }: Props = $props();
 
+  // `valueFormat` writes values in tooltips and the data table
+  const valueFormatter = $derived(
+    tooltipValueFormatter ?? resolveValueFormatter(valueFormat, locale)
+  );
+
   const isEmpty = $derived(!data?.nodes?.length || !data?.links?.length);
 
   const option: EChartsOption = $derived.by(() => {
@@ -58,7 +75,7 @@
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter,
             getLabel,
           }
         ),
@@ -97,28 +114,33 @@
         : undefined)
   );
 
+  const dataTable = $derived(isEmpty ? undefined : sankeyTable(data));
+
   // Manage ECharts instance lifecycle (init, theme, resize, option updates)
   const chart = useChart({
     option: () => option,
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      if (onClick) {
-        instance.on('click', (params) => {
-          const isEdge = params.dataType === 'edge';
-          onClick({
-            type: params.type || 'click',
-            componentType: params.componentType || 'series',
-            dataType: isEdge ? 'edge' : 'node',
-            name: params.name || '',
-            value: isEdge ? (params.value as number) : undefined,
-            source: isEdge ? (params.data as { source?: string })?.source : undefined,
-            target: isEdge ? (params.data as { target?: string })?.target : undefined,
-          } as SankeyEventParams);
-        });
-      }
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click:
+          onClick &&
+          ((params) => {
+            const isEdge = params.dataType === 'edge';
+            onClick({
+              type: params.type || 'click',
+              componentType: params.componentType || 'series',
+              dataType: isEdge ? 'edge' : 'node',
+              name: params.name || '',
+              value: isEdge ? (params.value as number) : undefined,
+              source: isEdge ? (params.data as { source?: string })?.source : undefined,
+              target: isEdge ? (params.data as { target?: string })?.target : undefined,
+            } as SankeyEventParams);
+          }),
+      }),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -126,11 +148,19 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  format={valueFormatter}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>