@classic-homes/charts-svelte 0.2.0 → 0.3.0

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

@@ -1,31 +1,36 @@
 <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 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,
@@ -34,14 +39,7 @@
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
-  echarts.use([
-    EChartsLineChart,
-    GridComponent,
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-    CanvasRenderer,
-  ]);
+  echarts.use([EChartsLineChart, GridComponent, TooltipComponent, LegendComponent]);
 
   interface Props extends Omit<AreaChartProps, 'class'>, CustomLegendProps {
     class?: string;
@@ -52,8 +50,11 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -63,33 +64,96 @@
     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 {};
 
+    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(
       {
@@ -98,7 +162,11 @@
           right: '4%',
           bottom: '3%',
           containLabel: true,
-          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+          ...withZoomInset(
+            gridInset(legendConfig, builtInLegend, xAxisConfig, yAxisConfig),
+            dataZoom,
+            'x'
+          ),
         },
         tooltip: buildTooltip(
           {
@@ -113,7 +181,7 @@
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter: formatters.tooltip,
             getLabel,
           }
         ),
@@ -122,6 +190,7 @@
           legendConfig,
           { show: showLegend, custom: !!renderLegend }
         ),
+        dataZoom: buildDataZoom(dataZoom, 'x', legendBottom ? 36 : 0),
         xAxis: buildAxis(
           {
             type: 'category',
@@ -133,41 +202,18 @@
         yAxis: buildAxis(
           {
             type: 'value',
+            ...(isPercent && { max: 100 }),
             splitLine: {
               show: showGrid,
             },
           },
-          yAxisConfig
+          formatters.axis(yAxisConfig)
         ),
-        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: withPointLabels(series.data, series.labels, labelFormatter, { position: 'top' }),
-            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,
-            label: buildDataLabel({ show: true, position: 'top' }, undefined, {
-              show: showLabels,
-              formatter: labelFormatter,
-              getLabel,
-            }),
-            emphasis: {
-              focus: 'series',
-            },
-            showSymbol,
-          };
+        series: withReferenceMarks(series, referenceLines, referenceBands, {
+          valueAxis: 'y',
+          format: formatters.format,
+          color: chartColors.reference,
+          bandColor: chartColors.referenceBand,
         }),
       } as EChartsOption,
       optionOverride
@@ -176,11 +222,11 @@
 
   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) ?? [],
@@ -197,23 +243,14 @@
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      legend.attach(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>
 
@@ -225,13 +262,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={resolveValueFormatter(valueFormat, locale)}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

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

@@ -1,30 +1,35 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { BarChart as EChartsBarChart } 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 { BarChartProps, DataPointEventParams } from '@classic-homes/charts-core';
+  import type { BarChartProps } from '@classic-homes/charts-core';
   import {
+    allSeriesEmpty,
     buildAxis,
     buildDataLabel,
+    buildDataZoom,
     buildLegend,
     buildTooltip,
+    categoryTable,
+    chartFormatters,
     generateBarChartDescription,
     getChartColors,
     gridInset,
     mergeChartOption,
+    pairWithCategories,
+    resolveChartHeight,
+    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,
@@ -33,14 +38,7 @@
   import ChartContainer from '../base/ChartContainer.svelte';
 
   // Register required ECharts modules
-  echarts.use([
-    EChartsBarChart,
-    GridComponent,
-    TooltipComponent,
-    LegendComponent,
-    TitleComponent,
-    CanvasRenderer,
-  ]);
+  echarts.use([EChartsBarChart, GridComponent, TooltipComponent, LegendComponent]);
 
   interface Props extends Omit<BarChartProps, 'class'>, CustomLegendProps {
     class?: string;
@@ -51,8 +49,12 @@
     description,
     data,
     height = 400,
+    minHeight,
+    maxHeight,
+    rowHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -62,31 +64,62 @@
     orientation = 'vertical',
     stacked = false,
     showValues = 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 isHorizontal = $derived(orientation === 'horizontal');
+  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 {};
 
+    const plotted = isPercent ? toPercentStack(data.series) : data.series;
+    // A time or value x-axis reads [x, y] points (vertical bars only)
+    const categoryAxisType = isHorizontal ? undefined : xAxisConfig?.type;
+
     const categoryAxis = {
       type: 'category' as const,
       data: data.categories,
+      // Horizontal bars list the first category at the top
+      inverse: isHorizontal,
       axisTick: {
         alignWithLabel: true,
       },
@@ -94,12 +127,37 @@
 
     const valueAxis = {
       type: 'value' as const,
+      ...(isPercent && { max: 100 }),
       splitLine: {
         show: showGrid,
       },
     };
 
     const getLabel = seriesLabelLookup(data.series);
+    const labelPosition = isHorizontal ? 'right' : 'top';
+    const zoomAxis = isHorizontal ? 'y' : 'x';
+    const legendBottom = builtInLegend && (legendConfig?.position ?? 'bottom') === 'bottom';
+
+    const series = data.series.map((source, index) => ({
+      name: source.name,
+      type: 'bar',
+      data: withPointLabels(
+        pairWithCategories(data.categories, plotted[index].data, categoryAxisType),
+        source.labels,
+        formatters.label,
+        { position: labelPosition }
+      ),
+      stack: source.stack ?? (stacked ? 'Total' : undefined),
+      itemStyle: source.color ? { color: source.color } : undefined,
+      label: buildDataLabel({ show: true, position: labelPosition }, undefined, {
+        show: showValues,
+        formatter: formatters.label,
+        getLabel,
+      }),
+      emphasis: {
+        focus: 'series',
+      },
+    }));
 
     return mergeChartOption(
       {
@@ -108,7 +166,11 @@
           right: '4%',
           bottom: '3%',
           containLabel: true,
-          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+          ...withZoomInset(
+            gridInset(legendConfig, builtInLegend, xAxisConfig, yAxisConfig),
+            dataZoom,
+            zoomAxis
+          ),
         },
         tooltip: buildTooltip(
           {
@@ -120,7 +182,7 @@
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter: formatters.tooltip,
             getLabel,
           }
         ),
@@ -129,35 +191,46 @@
           legendConfig,
           { show: showLegend, custom: !!renderLegend }
         ),
-        xAxis: buildAxis(isHorizontal ? valueAxis : categoryAxis, xAxisConfig),
-        yAxis: buildAxis(isHorizontal ? categoryAxis : valueAxis, yAxisConfig),
-        series: data.series.map((series) => ({
-          name: series.name,
-          type: 'bar',
-          data: withPointLabels(series.data, series.labels, labelFormatter, {
-            position: isHorizontal ? 'right' : 'top',
-          }),
-          stack: stacked ? 'Total' : undefined,
-          itemStyle: series.color ? { color: series.color } : undefined,
-          label: buildDataLabel(
-            {
-              show: true,
-              position: isHorizontal ? 'right' : 'top',
-            },
-            undefined,
-            { show: showValues, formatter: labelFormatter, getLabel }
-          ),
-          emphasis: {
-            focus: 'series',
-          },
-        })),
+        dataZoom: buildDataZoom(dataZoom, zoomAxis, legendBottom ? 36 : 0),
+        xAxis: buildAxis(
+          isHorizontal ? valueAxis : categoryAxis,
+          isHorizontal ? formatters.axis(xAxisConfig) : xAxisConfig
+        ),
+        yAxis: buildAxis(
+          isHorizontal ? categoryAxis : valueAxis,
+          isHorizontal ? yAxisConfig : formatters.axis(yAxisConfig)
+        ),
+        series: withReferenceMarks(series, referenceLines, referenceBands, {
+          valueAxis: isHorizontal ? 'x' : 'y',
+          inverse: isHorizontal,
+          format: formatters.format,
+          color: chartColors.reference,
+          bandColor: chartColors.referenceBand,
+        }),
       } as EChartsOption,
       optionOverride
     );
   });
 
   const accessibilityDescription = $derived(
-    description || (!isEmpty ? generateBarChartDescription(title, data) : undefined)
+    description ||
+      (!isEmpty ? generateBarChartDescription(title, data, formatters.format) : undefined)
+  );
+
+  const dataTable = $derived(isEmpty ? undefined : categoryTable(data));
+
+  // One row per category when horizontal; a bottom legend needs its own row
+  const resolvedHeight = $derived(
+    isHorizontal
+      ? resolveChartHeight(height, data?.categories?.length ?? 0, {
+          rowHeight,
+          minHeight,
+          maxHeight,
+          chrome: 56 + (builtInLegend ? 36 : 0) + (dataZoom ? 36 : 0),
+        })
+      : height === 'auto'
+        ? 400
+        : height
   );
 
   // Legend selection state, shared with a custom legend
@@ -176,23 +249,14 @@
     theme: () => theme,
     animation: () => animation,
     isEmpty: () => isEmpty,
-    onReady: (instance) => {
-      legend.attach(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>
 
@@ -203,14 +267,22 @@
 <ChartContainer
   {title}
   description={accessibilityDescription}
-  {height}
+  height={resolvedHeight}
+  {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>