@classic-homes/charts-svelte 0.1.37 → 0.2.0

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

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

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

@@ -6,16 +6,33 @@
   import type { EChartsOption } from 'echarts';
 
   import type { DonutChartProps, SliceEventParams } from '@classic-homes/charts-core';
-  import { generatePieChartDescription } from '@classic-homes/charts-core';
+  import {
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    escapeHtml,
+    formatTooltipValue,
+    generatePieChartDescription,
+    getChartColors,
+    itemLabelLookup,
+    anchorCenterGraphic,
+    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<DonutChartProps, 'class'> {
+  interface Props extends Omit<DonutChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -36,114 +53,163 @@
     innerRadius = '50%',
     centerLabel,
     centerValue,
+    labelFormatter,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
 
   const isEmpty = $derived(!data?.length);
 
+  // Per-element colours that follow the resolved chart theme
+  const chartColors = $derived.by(() => getChartColors(chart.theme));
+
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
+    const getLabel = itemLabelLookup(data);
+
+    const pieCenter = legendCenter(legendConfig, showLegend && !renderLegend, ['50%', '45%']);
     const graphicElements: unknown[] = [];
 
     if (centerLabel || centerValue) {
-      graphicElements.push({
-        type: 'group',
-        left: 'center',
-        top: '40%',
-        children: [
-          ...(centerValue !== undefined
-            ? [
-                {
-                  type: 'text',
-                  style: {
-                    text: String(centerValue),
-                    fontSize: 28,
-                    fontWeight: 'bold',
-                    fill: 'currentColor',
-                    align: 'center',
-                  },
-                  top: 0,
-                  left: 'center',
-                },
-              ]
-            : []),
-          ...(centerLabel
-            ? [
-                {
-                  type: 'text',
-                  style: {
-                    text: centerLabel,
-                    fontSize: 14,
-                    fill: '#888',
-                    align: 'center',
-                  },
-                  top: centerValue !== undefined ? 35 : 0,
-                  left: 'center',
-                },
-              ]
-            : []),
-        ],
-      });
+      graphicElements.push(
+        anchorCenterGraphic(
+          {
+            type: 'group',
+            left: 'center',
+            top: '40%',
+            children: [
+              ...(centerValue !== undefined
+                ? [
+                    {
+                      type: 'text',
+                      style: {
+                        text: String(centerValue),
+                        fontSize: 28,
+                        fontWeight: 'bold',
+                        fill: chartColors.foreground,
+                        align: 'center',
+                      },
+                      top: 0,
+                      left: 'center',
+                    },
+                  ]
+                : []),
+              ...(centerLabel
+                ? [
+                    {
+                      type: 'text',
+                      style: {
+                        text: centerLabel,
+                        fontSize: 14,
+                        fill: chartColors.mutedForeground,
+                        align: 'center',
+                      },
+                      top: centerValue !== undefined ? 35 : 0,
+                      left: 'center',
+                    },
+                  ]
+                : []),
+            ],
+          },
+          pieCenter,
+          ['50%', '45%']
+        )
+      );
     }
 
-    return {
-      tooltip: showTooltip
-        ? {
+    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,
-      graphic:
-        graphicElements.length > 0 ? (graphicElements as EChartsOption['graphic']) : undefined,
-      series: [
-        {
-          name: title,
-          type: 'pie',
-          radius: [innerRadius, '70%'],
-          center: ['50%', '45%'],
-          avoidLabelOverlap: true,
-          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' } }
+        ),
+        graphic:
+          graphicElements.length > 0 ? (graphicElements as EChartsOption['graphic']) : undefined,
+        series: [
+          {
+            name: title,
+            type: 'pie',
+            radius: [innerRadius, '70%'],
+            center: pieCenter,
+            avoidLabelOverlap: true,
+            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,
               },
-          labelLine: {
-            show: showLabels && labelPosition === 'outside',
-          },
-          emphasis: {
-            itemStyle: {
-              shadowBlur: 10,
-              shadowOffsetX: 0,
-              shadowColor: 'rgba(0, 0, 0, 0.5)',
+              { show: false },
+              { show: showLabels, formatter: labelFormatter, getLabel }
+            ),
+            labelLine: {
+              show: showLabels && labelPosition === 'outside',
+            },
+            emphasis: {
+              itemStyle: {
+                shadowBlur: 10,
+                shadowOffsetX: 0,
+                shadowColor: 'rgba(0, 0, 0, 0.5)',
+              },
             },
           },
-        },
-      ],
-    };
+        ],
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description || (!isEmpty ? generatePieChartDescription(title, data, true) : 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,
@@ -151,6 +217,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -167,6 +234,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -176,6 +247,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/DonutChart.svelte.d.ts

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

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

@@ -11,10 +11,26 @@
   import type { EChartsOption } from 'echarts';
 
   import type { LineChartProps, DataPointEventParams } from '@classic-homes/charts-core';
-  import { generateLineChartDescription } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    generateLineChartDescription,
+    getChartColors,
+    hasPointLabels,
+    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
@@ -27,7 +43,7 @@
     CanvasRenderer,
   ]);
 
-  interface Props extends Omit<LineChartProps, 'class'> {
+  interface Props extends Omit<LineChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -48,6 +64,16 @@
     areaFilled = false,
     showDataPoints = false,
     stacked = false,
+    showLabels = false,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     onHover,
     class: className,
@@ -57,68 +83,105 @@
     !data?.categories?.length || !data?.series?.length || data.series.every((s) => !s.data?.length)
   );
 
+  // Per-element colours that follow the resolved chart theme
+  const chartColors = $derived.by(() => getChartColors(chart.theme));
+
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
-    return {
-      grid: {
-        left: '3%',
-        right: '4%',
-        bottom: '3%',
-        containLabel: true,
-      },
-      tooltip: showTooltip
-        ? {
+    const getLabel = seriesLabelLookup(data.series);
+    // ECharts hides line labels along with the symbol
+    const showSymbol = showDataPoints || showLabels || hasPointLabels(data.series);
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
             trigger: 'axis',
             axisPointer: {
               type: 'cross',
               label: {
-                backgroundColor: '#6a7985',
+                backgroundColor: chartColors.axisPointerLabel,
               },
             },
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: tooltipValueFormatter,
+            getLabel,
           }
-        : undefined,
-      legend: showLegend
-        ? {
-            data: data.series.map((s) => s.name),
-            bottom: 0,
-          }
-        : undefined,
-      xAxis: {
-        type: 'category',
-        boundaryGap: false,
-        data: data.categories,
-        splitLine: {
-          show: showGrid,
-        },
-      },
-      yAxis: {
-        type: 'value',
-        splitLine: {
-          show: showGrid,
-        },
-      },
-      series: data.series.map((series) => ({
-        name: series.name,
-        type: 'line',
-        data: series.data,
-        smooth,
-        showSymbol: showDataPoints,
-        symbolSize: showDataPoints ? 6 : 0,
-        stack: stacked ? 'Total' : undefined,
-        areaStyle: areaFilled ? { opacity: 0.3 } : undefined,
-        itemStyle: series.color ? { color: series.color } : undefined,
-        emphasis: {
-          focus: 'series',
-        },
-      })),
-    };
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        xAxis: buildAxis(
+          {
+            type: 'category',
+            boundaryGap: false,
+            data: data.categories,
+            splitLine: {
+              show: showGrid,
+            },
+          },
+          xAxisConfig
+        ),
+        yAxis: buildAxis(
+          {
+            type: 'value',
+            splitLine: {
+              show: showGrid,
+            },
+          },
+          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',
+          },
+        })),
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description || (!isEmpty ? generateLineChartDescription(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,
@@ -126,6 +189,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -159,6 +223,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -168,6 +236,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/LineChart.svelte.d.ts

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