@classic-homes/charts-svelte 0.1.38 → 0.2.0

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

@@ -6,9 +6,24 @@
   import type { EChartsOption } from 'echarts';
 
   import type { FunnelChartProps, SliceEventParams } from '@classic-homes/charts-core';
+  import {
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    escapeHtml,
+    formatTooltipValue,
+    getChartColors,
+    itemLabelLookup,
+    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';
 
   echarts.use([
@@ -19,7 +34,7 @@
     CanvasRenderer,
   ]);
 
-  interface Props extends Omit<FunnelChartProps, 'class'> {
+  interface Props extends Omit<FunnelChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -38,6 +53,13 @@
     sort = 'descending',
     orientation = 'vertical',
     showLabels = true,
+    labelFormatter,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -47,44 +69,84 @@
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
-    return {
-      tooltip: showTooltip ? { trigger: 'item', formatter: '{a} <br/>{b}: {c}' } : undefined,
-      legend: showLegend ? { data: data.map((d) => d.name), bottom: 0 } : undefined,
-      series: [
-        {
-          name: title,
-          type: 'funnel',
-          left: '10%',
-          top: 60,
-          bottom: 60,
-          width: '80%',
-          min: 0,
-          // reduce, not Math.max(...): spreading large arrays overflows the stack
-          max: data.reduce((m, d) => (d.value > m ? d.value : m), -Infinity),
-          minSize: '0%',
-          maxSize: '100%',
-          sort,
-          orient: orientation,
-          gap: 2,
-          label: showLabels
-            ? { show: true, position: 'inside', formatter: '{b}: {c}' }
-            : { show: false },
-          labelLine: { show: false },
-          emphasis: { label: { fontSize: 16 } },
-          data: data.map((item) => ({
-            name: item.name,
-            value: item.value,
-            itemStyle: item.color ? { color: item.color } : undefined,
-          })),
-        },
-      ],
-    };
+    const getLabel = itemLabelLookup(data);
+
+    return mergeChartOption(
+      {
+        tooltip: buildTooltip(
+          {
+            trigger: 'item',
+            // 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 };
+                    return `${escapeHtml(p.seriesName)} <br/>${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, tooltipValueFormatter))}`;
+                  }
+                : '{a} <br/>{b}: {c}',
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: tooltipValueFormatter,
+            getLabel,
+          }
+        ),
+        legend: buildLegend(
+          data.map((d) => d.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        series: [
+          {
+            name: title,
+            type: 'funnel',
+            left: '10%',
+            top: 60,
+            bottom: 60,
+            width: '80%',
+            min: 0,
+            // reduce, not Math.max(...): spreading large arrays overflows the stack
+            max: data.reduce((m, d) => (d.value > m ? d.value : m), -Infinity),
+            minSize: '0%',
+            maxSize: '100%',
+            sort,
+            orient: orientation,
+            gap: 2,
+            label: buildDataLabel(
+              { show: true, position: 'inside', formatter: '{b}: {c}' },
+              { show: false },
+              { show: showLabels, formatter: labelFormatter, getLabel }
+            ),
+            labelLine: { show: false },
+            emphasis: { label: { fontSize: 16 } },
+            data: data.map((item) => ({
+              name: item.name,
+              value: item.value,
+              itemStyle: item.color ? { color: item.color } : undefined,
+              label: pointLabel(item.label, labelFormatter, { position: 'inside' }),
+            })),
+          },
+        ],
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description || (!isEmpty ? `${title}. Funnel chart with ${data.length} stages.` : 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,
@@ -92,6 +154,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -107,6 +170,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -116,6 +183,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/extended/FunnelChart.svelte.d.ts

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

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

@@ -1,18 +1,18 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { GaugeChart as EChartsGaugeChart } from 'echarts/charts';
-  import { TitleComponent } from 'echarts/components';
+  import { TitleComponent, TooltipComponent } from 'echarts/components';
   import { CanvasRenderer } from 'echarts/renderers';
   import type { EChartsOption } from 'echarts';
 
   import type { GaugeChartProps } from '@classic-homes/charts-core';
-  import { getChartColors } from '@classic-homes/charts-core';
+  import { buildTooltip, getChartColors, mergeChartOption } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
-  echarts.use([EChartsGaugeChart, TitleComponent, CanvasRenderer]);
+  echarts.use([EChartsGaugeChart, TitleComponent, TooltipComponent, CanvasRenderer]);
 
   interface Props extends Omit<GaugeChartProps, 'class'> {
     class?: string;
@@ -33,6 +33,10 @@
     splitNumber = 10,
     showProgress = true,
     formatValue,
+    showTooltip = true,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
     class: className,
   }: Props = $props();
 
@@ -46,42 +50,59 @@
   // Per-element colours that follow the resolved chart theme
   const chartColors = $derived.by(() => getChartColors(chart.theme));
 
-  const option: EChartsOption = $derived({
-    series: [
+  const option: EChartsOption = $derived.by(() =>
+    mergeChartOption(
       {
-        type: 'gauge',
-        center: ['50%', '60%'],
-        radius: '80%',
-        min,
-        max,
-        splitNumber,
-        progress: showProgress ? { show: true, width: 18 } : undefined,
-        axisLine: { lineStyle: { width: 18 } },
-        axisTick: {
-          distance: -30,
-          splitNumber: 5,
-          lineStyle: { width: 2, color: chartColors.mutedForeground },
-        },
-        splitLine: {
-          distance: -32,
-          length: 10,
-          lineStyle: { width: 3, color: chartColors.mutedForeground },
-        },
-        axisLabel: { distance: -20, color: chartColors.mutedForeground, fontSize: 12 },
-        anchor: { show: true, size: 20, itemStyle: { borderWidth: 2 } },
-        pointer: { width: 6, length: '60%' },
-        title: { show: true, offsetCenter: [0, '70%'], fontSize: 14 },
-        detail: {
-          valueAnimation: animation && !chart.reducedMotion,
-          fontSize: 28,
-          fontWeight: 'bold',
-          offsetCenter: [0, '40%'],
-          formatter: formatValue || '{value}',
-        },
-        data: [{ value, name: title }],
-      },
-    ],
-  });
+        // No tooltip by default; one appears only when a formatter is set
+        tooltip:
+          tooltipFormatter || tooltipValueFormatter
+            ? buildTooltip(
+                { trigger: 'item' },
+                {
+                  show: showTooltip,
+                  formatter: tooltipFormatter,
+                  valueFormatter: tooltipValueFormatter,
+                }
+              )
+            : undefined,
+        series: [
+          {
+            type: 'gauge',
+            center: ['50%', '60%'],
+            radius: '80%',
+            min,
+            max,
+            splitNumber,
+            progress: showProgress ? { show: true, width: 18 } : undefined,
+            axisLine: { lineStyle: { width: 18 } },
+            axisTick: {
+              distance: -30,
+              splitNumber: 5,
+              lineStyle: { width: 2, color: chartColors.mutedForeground },
+            },
+            splitLine: {
+              distance: -32,
+              length: 10,
+              lineStyle: { width: 3, color: chartColors.mutedForeground },
+            },
+            axisLabel: { distance: -20, color: chartColors.mutedForeground, fontSize: 12 },
+            anchor: { show: true, size: 20, itemStyle: { borderWidth: 2 } },
+            pointer: { width: 6, length: '60%' },
+            title: { show: true, offsetCenter: [0, '70%'], fontSize: 14 },
+            detail: {
+              valueAnimation: animation && !chart.reducedMotion,
+              fontSize: 28,
+              fontWeight: 'bold',
+              offsetCenter: [0, '40%'],
+              formatter: formatValue || '{value}',
+            },
+            data: [{ value, name: title }],
+          },
+        ],
+      } as EChartsOption,
+      optionOverride
+    )
+  );
 
   const accessibilityDescription = $derived(
     description || `${title}. Gauge showing value ${value} on scale from ${min} to ${max}.`

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

@@ -11,7 +11,14 @@
   import type { EChartsOption } from 'echarts';
 
   import type { HeatmapChartProps, HeatmapEventParams } from '@classic-homes/charts-core';
-  import { escapeHtml } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildDataLabel,
+    buildTooltip,
+    escapeHtml,
+    formatTooltipValue,
+    mergeChartOption,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
   import { useChart } from '../../composables/useChart.svelte.js';
@@ -44,6 +51,12 @@
     animation = true,
     showTooltip = true,
     showValues = false,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -66,39 +79,46 @@
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
-    return {
-      tooltip: showTooltip
-        ? {
+    return mergeChartOption(
+      {
+        tooltip: buildTooltip(
+          {
             position: 'top' as const,
             formatter: (params: unknown) => {
               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(value)}`;
+              return `${escapeHtml(xAxis[xIdx])} / ${escapeHtml(yAxis[yIdx])}: ${escapeHtml(formatTooltipValue(value, tooltipValueFormatter))}`;
             },
-          }
-        : undefined,
-      grid: { left: '3%', right: '10%', bottom: '3%', containLabel: true },
-      xAxis: { type: 'category', data: xAxis, splitArea: { show: true } },
-      yAxis: { type: 'category', data: yAxis, splitArea: { show: true } },
-      visualMap: {
-        min: minValue,
-        max: maxValue,
-        calculable: true,
-        orient: 'vertical',
-        right: '0%',
-        top: 'center',
-      },
-      series: [
-        {
-          name: title,
-          type: 'heatmap',
-          data: data.data,
-          label: showValues ? { show: true } : undefined,
-          emphasis: { itemStyle: { shadowBlur: 10, shadowColor: 'rgba(0, 0, 0, 0.5)' } },
+          },
+          { show: showTooltip, formatter: tooltipFormatter, valueFormatter: tooltipValueFormatter }
+        ),
+        grid: { left: '3%', right: '10%', bottom: '3%', containLabel: true },
+        xAxis: buildAxis({ type: 'category', data: xAxis, splitArea: { show: true } }, xAxisConfig),
+        yAxis: buildAxis({ type: 'category', data: yAxis, splitArea: { show: true } }, yAxisConfig),
+        visualMap: {
+          min: minValue,
+          max: maxValue,
+          calculable: true,
+          orient: 'vertical',
+          right: '0%',
+          top: 'center',
         },
-      ],
-    };
+        series: [
+          {
+            name: title,
+            type: 'heatmap',
+            data: data.data,
+            label: buildDataLabel({ show: true }, undefined, {
+              show: showValues,
+              formatter: labelFormatter,
+            }),
+            emphasis: { itemStyle: { shadowBlur: 10, shadowColor: 'rgba(0, 0, 0, 0.5)' } },
+          },
+        ],
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(

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

@@ -11,9 +11,21 @@
   import type { EChartsOption } from 'echarts';
 
   import type { RadarChartProps } from '@classic-homes/charts-core';
+  import {
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    getChartColors,
+    legendCenter,
+    mergeChartOption,
+  } 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';
 
   echarts.use([
@@ -25,7 +37,7 @@
     CanvasRenderer,
   ]);
 
-  interface Props extends Omit<RadarChartProps, 'class'> {
+  interface Props extends Omit<RadarChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -43,6 +55,14 @@
     showLegend = true,
     showTooltip = true,
     shape = 'polygon',
+    showLabels = false,
+    labelFormatter,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     class: className,
   }: Props = $props();
 
@@ -53,29 +73,44 @@
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
-    return {
-      tooltip: showTooltip ? { trigger: 'item' } : undefined,
-      legend: showLegend ? { data: data.series.map((s) => s.name), bottom: 0 } : undefined,
-      radar: {
-        indicator: indicators.map((ind) => ({
-          name: ind.name,
-          max: ind.max,
-          min: ind.min,
-        })),
-        shape,
-      },
-      series: [
-        {
-          type: 'radar',
-          data: data.series.map((series) => ({
-            name: series.name,
-            value: series.data,
-            itemStyle: series.color ? { color: series.color } : undefined,
-            areaStyle: { opacity: 0.2 },
+    return mergeChartOption(
+      {
+        tooltip: buildTooltip(
+          { trigger: 'item' },
+          { show: showTooltip, formatter: tooltipFormatter, valueFormatter: tooltipValueFormatter }
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        radar: {
+          center: legendCenter(legendConfig, showLegend && !renderLegend, ['50%', '50%']),
+          indicator: indicators.map((ind) => ({
+            name: ind.name,
+            max: ind.max,
+            min: ind.min,
           })),
+          shape,
         },
-      ],
-    };
+        series: [
+          {
+            type: 'radar',
+            label: buildDataLabel({ show: true }, undefined, {
+              show: showLabels,
+              formatter: labelFormatter,
+            }),
+            data: data.series.map((series) => ({
+              name: series.name,
+              value: series.data,
+              itemStyle: series.color ? { color: series.color } : undefined,
+              areaStyle: { opacity: 0.2 },
+            })),
+          },
+        ],
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
@@ -85,15 +120,32 @@
         : 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,
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
+    onReady: (instance) => {
+      legend.attach(instance);
+    },
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -103,6 +155,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/extended/RadarChart.svelte.d.ts

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