@classic-homes/charts-svelte 0.1.38 → 0.3.0

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

@@ -1,33 +1,47 @@
 <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 { AreaChartProps, DataPointEventParams } from '@classic-homes/charts-core';
-  import { colorWithAlpha, getChartColors } from '@classic-homes/charts-core';
+  import type { AreaChartProps } from '@classic-homes/charts-core';
+  import {
+    allSeriesEmpty,
+    buildAxis,
+    buildDataLabel,
+    buildDataZoom,
+    buildLegend,
+    buildTooltip,
+    categoryTable,
+    chartFormatters,
+    colorWithAlpha,
+    generateAreaChartDescription,
+    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,
+    type CustomLegendProps,
+  } from '../../composables/useChartLegend.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
-  echarts.use([
-    EChartsLineChart,
-    GridComponent,
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-    CanvasRenderer,
-  ]);
-
-  interface Props extends Omit<AreaChartProps, 'class'> {
+  echarts.use([EChartsLineChart, GridComponent, TooltipComponent, LegendComponent]);
+
+  interface Props extends Omit<AreaChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -36,8 +50,11 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -47,29 +64,112 @@
     smooth = false,
     stacked = false,
     gradient = true,
+    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 {};
 
-    return {
-      grid: {
-        left: '3%',
-        right: '4%',
-        bottom: '3%',
-        containLabel: true,
-      },
-      tooltip: showTooltip
-        ? {
+    const plotted = isPercent ? toPercentStack(data.series) : data.series;
+    const getLabel = seriesLabelLookup(data.series);
+    // ECharts hides line labels along with the symbol
+    const showSymbol = showLabels || hasPointLabels(data.series);
+    const legendBottom = builtInLegend && (legendConfig?.position ?? 'bottom') === 'bottom';
+
+    const series = data.series.map((source, index) => {
+      // Fade the series colour (theme palette unless overridden) downwards
+      const base = source.color || chartColors.series[index % chartColors.series.length];
+      return {
+        name: source.name,
+        type: 'line',
+        data: withPointLabels(
+          pairWithCategories(data.categories, plotted[index].data, xAxisConfig?.type),
+          source.labels,
+          formatters.label,
+          { position: 'top' }
+        ),
+        smooth,
+        connectNulls,
+        stack: source.stack ?? (stacked ? 'Total' : undefined),
+        areaStyle: gradient
+          ? {
+              opacity: 0.8,
+              color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
+                { offset: 0, color: colorWithAlpha(base, 0.8) },
+                { offset: 1, color: colorWithAlpha(base, 0.1) },
+              ]),
+            }
+          : { opacity: 0.5 },
+        itemStyle: source.color ? { color: source.color } : undefined,
+        label: buildDataLabel({ show: true, position: 'top' }, undefined, {
+          show: showLabels,
+          formatter: formatters.label,
+          getLabel,
+        }),
+        emphasis: {
+          focus: 'series',
+        },
+        showSymbol,
+      };
+    });
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...withZoomInset(
+            gridInset(legendConfig, builtInLegend, xAxisConfig, yAxisConfig),
+            dataZoom,
+            'x'
+          ),
+        },
+        tooltip: buildTooltip(
+          {
             trigger: 'axis',
             axisPointer: {
               type: 'cross',
@@ -77,94 +177,106 @@
                 backgroundColor: chartColors.axisPointerLabel,
               },
             },
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: formatters.tooltip,
+            getLabel,
           }
-        : undefined,
-      legend: showLegend
-        ? {
-            data: data.series.map((s) => s.name),
-            bottom: 0,
-          }
-        : undefined,
-      xAxis: {
-        type: 'category',
-        boundaryGap: false,
-        data: data.categories,
-      },
-      yAxis: {
-        type: 'value',
-        splitLine: {
-          show: showGrid,
-        },
-      },
-      series: data.series.map((series, index) => {
-        // Fade the series colour (theme palette unless overridden) downwards
-        const base = series.color || chartColors.series[index % chartColors.series.length];
-        return {
-          name: series.name,
-          type: 'line',
-          data: series.data,
-          smooth,
-          stack: stacked ? 'Total' : undefined,
-          areaStyle: gradient
-            ? {
-                opacity: 0.8,
-                color: new echarts.graphic.LinearGradient(0, 0, 0, 1, [
-                  { offset: 0, color: colorWithAlpha(base, 0.8) },
-                  { offset: 1, color: colorWithAlpha(base, 0.1) },
-                ]),
-              }
-            : { opacity: 0.5 },
-          itemStyle: series.color ? { color: series.color } : undefined,
-          emphasis: {
-            focus: 'series',
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        dataZoom: buildDataZoom(dataZoom, 'x', legendBottom ? 36 : 0),
+        xAxis: buildAxis(
+          {
+            type: 'category',
+            boundaryGap: false,
+            data: data.categories,
           },
-          showSymbol: false,
-        };
-      }),
-    };
+          xAxisConfig
+        ),
+        yAxis: buildAxis(
+          {
+            type: 'value',
+            ...(isPercent && { max: 100 }),
+            splitLine: {
+              show: showGrid,
+            },
+          },
+          formatters.axis(yAxisConfig)
+        ),
+        series: withReferenceMarks(series, referenceLines, referenceBands, {
+          valueAxis: 'y',
+          format: formatters.format,
+          color: chartColors.reference,
+          bandColor: chartColors.referenceBand,
+        }),
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description ||
-      (!isEmpty
-        ? `${title}. Area chart with ${data.categories.length} data points across ${data.series.length} series.`
-        : undefined)
+      (!isEmpty ? generateAreaChartDescription(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) ?? [],
+    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) => {
-      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);
-        });
-      }
-    },
+    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>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {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/AreaChart.svelte.d.ts

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