@classic-homes/charts-svelte 0.1.38 → 0.2.0

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

@@ -6,16 +6,32 @@
   import type { EChartsOption } from 'echarts';
 
   import type { PieChartProps, SliceEventParams } from '@classic-homes/charts-core';
-  import { generatePieChartDescription } from '@classic-homes/charts-core';
+  import {
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    escapeHtml,
+    formatTooltipValue,
+    generatePieChartDescription,
+    getChartColors,
+    itemLabelLookup,
+    legendCenter,
+    mergeChartOption,
+    pointLabel,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
   import { useChart } from '../../composables/useChart.svelte.js';
+  import {
+    useChartLegend,
+    type CustomLegendProps,
+  } from '../../composables/useChartLegend.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
   echarts.use([EChartsPieChart, TooltipComponent, LegendComponent, TitleComponent, CanvasRenderer]);
 
-  interface Props extends Omit<PieChartProps, 'class'> {
+  interface Props extends Omit<PieChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -34,6 +50,13 @@
     showLabels = true,
     labelPosition = 'outside',
     innerRadius = 0,
+    labelFormatter,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -43,56 +66,88 @@
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
-    return {
-      tooltip: showTooltip
-        ? {
+    const getLabel = itemLabelLookup(data);
+
+    return mergeChartOption(
+      {
+        tooltip: buildTooltip(
+          {
             trigger: 'item',
-            formatter: '{a} <br/>{b}: {c} ({d}%)',
-          }
-        : undefined,
-      legend: showLegend
-        ? {
-            orient: 'horizontal',
-            bottom: 0,
-            data: data.map((d) => d.name),
+            // A string template ignores valueFormatter, so format the value here
+            formatter:
+              tooltipValueFormatter && !tooltipFormatter
+                ? (params: unknown) => {
+                    const p = params as {
+                      seriesName?: string;
+                      name?: string;
+                      value?: unknown;
+                      percent?: number;
+                    };
+                    return `${escapeHtml(p.seriesName)} <br/>${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, tooltipValueFormatter))} (${p.percent}%)`;
+                  }
+                : '{a} <br/>{b}: {c} ({d}%)',
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: tooltipValueFormatter,
+            getLabel,
           }
-        : undefined,
-      series: [
-        {
-          name: title,
-          type: 'pie',
-          radius: innerRadius ? [innerRadius, '70%'] : '70%',
-          center: ['50%', '45%'],
-          data: data.map((item) => ({
-            name: item.name,
-            value: item.value,
-            itemStyle: item.color ? { color: item.color } : undefined,
-          })),
-          label: showLabels
-            ? {
+        ),
+        legend: buildLegend(
+          data.map((d) => d.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend, defaults: { orient: 'horizontal' } }
+        ),
+        series: [
+          {
+            name: title,
+            type: 'pie',
+            radius: innerRadius ? [innerRadius, '70%'] : '70%',
+            center: legendCenter(legendConfig, showLegend && !renderLegend, ['50%', '45%']),
+            data: data.map((item) => ({
+              name: item.name,
+              value: item.value,
+              itemStyle: item.color ? { color: item.color } : undefined,
+              label: pointLabel(item.label, labelFormatter, { position: labelPosition }),
+            })),
+            label: buildDataLabel(
+              {
                 show: true,
                 position: labelPosition,
                 formatter: labelPosition === 'inside' ? '{d}%' : '{b}: {d}%',
-              }
-            : {
-                show: false,
               },
-          emphasis: {
-            itemStyle: {
-              shadowBlur: 10,
-              shadowOffsetX: 0,
-              shadowColor: 'rgba(0, 0, 0, 0.5)',
+              { show: false },
+              { show: showLabels, formatter: labelFormatter, getLabel }
+            ),
+            emphasis: {
+              itemStyle: {
+                shadowBlur: 10,
+                shadowOffsetX: 0,
+                shadowColor: 'rgba(0, 0, 0, 0.5)',
+              },
             },
           },
-        },
-      ],
-    };
+        ],
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description || (!isEmpty ? generatePieChartDescription(title, data, false) : undefined)
   );
 
+  // Legend selection state, shared with a custom legend
+  const legend = useChartLegend({
+    names: () => data?.map((d) => d.name) ?? [],
+    colors: () => data?.map((d) => d.color) ?? [],
+    palette: () => getChartColors(chart.theme).series,
+    config: () => legendConfig,
+    title: () => title,
+    onLegendChange: () => onLegendChange,
+  });
+
   // Manage ECharts instance lifecycle (init, theme, resize, option updates)
   const chart = useChart({
     option: () => option,
@@ -100,6 +155,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -116,6 +172,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -125,6 +185,8 @@
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  legend={renderLegend ? customLegend : undefined}
+  legendPosition={legendConfig?.position}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

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

@@ -1,5 +1,6 @@
 import type { PieChartProps } from '@classic-homes/charts-core';
-interface Props extends Omit<PieChartProps, 'class'> {
+import { type CustomLegendProps } from '../../composables/useChartLegend.svelte.js';
+interface Props extends Omit<PieChartProps, 'class'>, CustomLegendProps {
     class?: string;
 }
 declare const PieChart: import("svelte").Component<Props, {}, "">;

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

@@ -14,10 +14,27 @@
   import type { EChartsOption } from 'echarts';
 
   import type { ScatterChartProps, DataPointEventParams } from '@classic-homes/charts-core';
-  import { escapeHtml, generateScatterChartDescription } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    escapeHtml,
+    formatTooltipValue,
+    generateScatterChartDescription,
+    getChartColors,
+    gridInset,
+    mergeChartOption,
+    seriesLabelLookup,
+    withPointLabels,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
   import { useChart } from '../../composables/useChart.svelte.js';
+  import {
+    useChartLegend,
+    type CustomLegendProps,
+  } from '../../composables/useChartLegend.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
@@ -32,7 +49,7 @@
     CanvasRenderer,
   ]);
 
-  interface Props extends Omit<ScatterChartProps, 'class'> {
+  interface Props extends Omit<ScatterChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -51,6 +68,16 @@
     showGrid = true,
     showTrendLine = false,
     symbolSize = 10,
+    showLabels = false,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -60,12 +87,19 @@
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
+    const getLabel = seriesLabelLookup(data.series);
+
     const series: EChartsOption['series'] = data.series.map((s) => ({
       name: s.name,
       type: 'scatter',
-      data: s.data,
+      data: withPointLabels(s.data, s.labels, labelFormatter, { position: 'top' }),
       symbolSize: typeof symbolSize === 'function' ? symbolSize : symbolSize,
       itemStyle: s.color ? { color: s.color } : undefined,
+      label: buildDataLabel({ show: true, position: 'top' }, undefined, {
+        show: showLabels,
+        formatter: labelFormatter,
+        getLabel,
+      }),
       emphasis: {
         focus: 'series',
         itemStyle: {
@@ -125,49 +159,76 @@
       });
     }
 
-    return {
-      grid: {
-        left: '3%',
-        right: '4%',
-        bottom: '3%',
-        containLabel: true,
-      },
-      tooltip: showTooltip
-        ? {
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
             trigger: 'item' as const,
             formatter: (params: unknown) => {
               const p = params as { seriesName?: string; value?: number[] };
               if (!p.value) return '';
-              return `${escapeHtml(p.seriesName)}<br/>X: ${escapeHtml(p.value[0])}<br/>Y: ${escapeHtml(p.value[1])}`;
+              const x = formatTooltipValue(p.value[0], tooltipValueFormatter);
+              const y = formatTooltipValue(p.value[1], tooltipValueFormatter);
+              return `${escapeHtml(p.seriesName)}<br/>X: ${escapeHtml(x)}<br/>Y: ${escapeHtml(y)}`;
             },
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: tooltipValueFormatter,
+            getLabel,
           }
-        : undefined,
-      legend: showLegend
-        ? {
-            data: data.series.map((s) => s.name),
-            bottom: 0,
-          }
-        : undefined,
-      xAxis: {
-        type: 'value',
-        splitLine: {
-          show: showGrid,
-        },
-      },
-      yAxis: {
-        type: 'value',
-        splitLine: {
-          show: showGrid,
-        },
-      },
-      series,
-    };
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        xAxis: buildAxis(
+          {
+            type: 'value',
+            splitLine: {
+              show: showGrid,
+            },
+          },
+          xAxisConfig
+        ),
+        yAxis: buildAxis(
+          {
+            type: 'value',
+            splitLine: {
+              show: showGrid,
+            },
+          },
+          yAxisConfig
+        ),
+        series,
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description || (!isEmpty ? generateScatterChartDescription(title, data) : undefined)
   );
 
+  // Legend selection state, shared with a custom legend
+  const legend = useChartLegend({
+    names: () => data?.series?.map((s) => s.name) ?? [],
+    colors: () => data?.series?.map((s) => s.color) ?? [],
+    palette: () => getChartColors(chart.theme).series,
+    config: () => legendConfig,
+    title: () => title,
+    onLegendChange: () => onLegendChange,
+  });
+
   // Manage ECharts instance lifecycle (init, theme, resize, option updates)
   const chart = useChart({
     option: () => option,
@@ -175,6 +236,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -193,6 +255,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -202,6 +268,8 @@
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  legend={renderLegend ? customLegend : undefined}
+  legendPosition={legendConfig?.position}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/core/ScatterChart.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { ScatterChartProps } from '@classic-homes/charts-core';
-interface Props extends Omit<ScatterChartProps, 'class'> {
+import { type CustomLegendProps } from '../../composables/useChartLegend.svelte.js';
+interface Props extends Omit<ScatterChartProps, 'class'>, CustomLegendProps {
     class?: string;
 }
 declare const ScatterChart: import("svelte").Component<Props, {}, "">;

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

@@ -14,7 +14,12 @@
   import type { EChartsOption } from 'echarts';
 
   import type { CandlestickChartProps, CandlestickEventParams } from '@classic-homes/charts-core';
-  import { getChartColors } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildTooltip,
+    getChartColors,
+    mergeChartOption,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
   import { useChart } from '../../composables/useChart.svelte.js';
@@ -46,6 +51,11 @@
     animation = true,
     showTooltip = true,
     showVolume = false,
+    xAxisConfig,
+    yAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -77,18 +87,24 @@
     const gridArr: { left: string; right: string; top: number | string; height: string }[] = [
       { left: '10%', right: '10%', top: 60, height: showVolume ? '50%' : '70%' },
     ];
+    // Axis customisation applies to the main (price) axes only
     const xAxisArr: unknown[] = [
-      {
-        type: 'category',
-        data: data.dates,
-        boundaryGap: false,
-        axisLine: { onZero: false },
-        splitLine: { show: false },
-        min: 'dataMin',
-        max: 'dataMax',
-      },
+      buildAxis(
+        {
+          type: 'category',
+          data: data.dates,
+          boundaryGap: false,
+          axisLine: { onZero: false },
+          splitLine: { show: false },
+          min: 'dataMin',
+          max: 'dataMax',
+        },
+        xAxisConfig
+      ),
+    ];
+    const yAxisArr: unknown[] = [
+      buildAxis({ scale: true, splitArea: { show: true } }, yAxisConfig),
     ];
-    const yAxisArr: unknown[] = [{ scale: true, splitArea: { show: true } }];
 
     if (showVolume && data.volume) {
       gridArr.push({ left: '10%', right: '10%', top: '73%', height: '12%' });
@@ -123,17 +139,23 @@
       });
     }
 
-    return {
-      tooltip: showTooltip ? { trigger: 'axis', axisPointer: { type: 'cross' } } : undefined,
-      grid: gridArr,
-      xAxis: xAxisArr as EChartsOption['xAxis'],
-      yAxis: yAxisArr as EChartsOption['yAxis'],
-      dataZoom: [
-        { type: 'inside', start: 80, end: 100 },
-        { show: true, type: 'slider', top: '90%', start: 80, end: 100 },
-      ],
-      series: seriesArr,
-    };
+    return mergeChartOption(
+      {
+        tooltip: buildTooltip(
+          { trigger: 'axis', axisPointer: { type: 'cross' } },
+          { show: showTooltip, formatter: tooltipFormatter, valueFormatter: tooltipValueFormatter }
+        ),
+        grid: gridArr,
+        xAxis: xAxisArr as EChartsOption['xAxis'],
+        yAxis: yAxisArr as EChartsOption['yAxis'],
+        dataZoom: [
+          { type: 'inside', start: 80, end: 100 },
+          { show: true, type: 'slider', top: '90%', start: 80, end: 100 },
+        ],
+        series: seriesArr,
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(