@classic-homes/charts-svelte 0.2.0 → 0.3.0

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

@@ -1,8 +1,7 @@
 <script lang="ts">
   import * as echarts from 'echarts/core';
   import { TreemapChart as EChartsTreemapChart } from 'echarts/charts';
-  import { TooltipComponent, TitleComponent } from 'echarts/components';
-  import { CanvasRenderer } from 'echarts/renderers';
+  import { TooltipComponent } from 'echarts/components';
   import type { EChartsOption } from 'echarts';
 
   import type {
@@ -19,13 +18,16 @@
     mergeChartOption,
     nameLabelLookup,
     pointLabel,
+    resolveValueFormatter,
+    treemapTable,
   } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.js';
+  import { chartEvents } from '../../events.js';
   import { useChart } from '../../composables/useChart.svelte.js';
   import ChartContainer from '../base/ChartContainer.svelte';
 
-  echarts.use([EChartsTreemapChart, TooltipComponent, TitleComponent, CanvasRenderer]);
+  echarts.use([EChartsTreemapChart, TooltipComponent]);
 
   interface Props extends Omit<TreemapChartProps, 'class'> {
     class?: string;
@@ -37,8 +39,11 @@
     data,
     levels,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
+    onRetry,
     emptyMessage,
     theme = 'auto',
     animation = true,
@@ -47,10 +52,22 @@
     tooltipFormatter,
     tooltipValueFormatter,
     option: optionOverride,
+    valueFormat,
+    locale,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
     onClick,
     class: className,
   }: Props = $props();
 
+  // `valueFormat` writes values in tooltips and the data table
+  const valueFormatter = $derived(
+    tooltipValueFormatter ?? resolveValueFormatter(valueFormat, locale)
+  );
+
   const isEmpty = $derived(!data?.length);
 
   // Per-element colours that follow the resolved chart theme
@@ -61,8 +78,10 @@
 
     const getLabel = nameLabelLookup(data);
     // ECharts expects a label object, so swap each node's label text for one
-    const toNode = (n: TreemapNode): Record<string, unknown> => ({
+    // and a colour for a node fill (a node's own `color` is a palette for its children)
+    const toNode = ({ color, ...n }: TreemapNode): Record<string, unknown> => ({
       ...n,
+      ...(color && { itemStyle: { color } }),
       children: n.children?.map(toNode),
       label: pointLabel(n.label, labelFormatter),
     });
@@ -73,13 +92,13 @@
           {
             formatter: (params: unknown) => {
               const p = params as { name?: string; value?: number };
-              return `${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, tooltipValueFormatter))}`;
+              return `${escapeHtml(p.name)}: ${escapeHtml(formatTooltipValue(p.value, valueFormatter))}`;
             },
           },
           {
             show: showTooltip,
             formatter: tooltipFormatter,
-            valueFormatter: tooltipValueFormatter,
+            valueFormatter,
             getLabel,
           }
         ),
@@ -118,27 +137,32 @@
     description || (!isEmpty ? `${title}. Treemap chart showing hierarchical data.` : undefined)
   );
 
+  const dataTable = $derived(isEmpty ? undefined : treemapTable(data));
+
   // 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) => {
-          const treePathInfo = params.treePathInfo || [];
-          onClick({
-            type: params.type || 'click',
-            componentType: params.componentType || 'series',
-            name: params.name || '',
-            value: params.value as number,
-            path: treePathInfo.map((item: { name?: string }) => item.name || ''),
-            depth: treePathInfo.length - 1,
-          } as TreemapEventParams);
-        });
-      }
-    },
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click:
+          onClick &&
+          ((params) => {
+            const treePathInfo = params.treePathInfo || [];
+            onClick({
+              type: params.type || 'click',
+              componentType: params.componentType || 'series',
+              name: params.name || '',
+              value: params.value as number,
+              path: treePathInfo.map((item: { name?: string }) => item.name || ''),
+              depth: treePathInfo.length - 1,
+            } as TreemapEventParams);
+          }),
+      }),
+    onCreated: () => onReady,
   });
 </script>
 
@@ -146,11 +170,19 @@
   {title}
   description={accessibilityDescription}
   {height}
+  {minHeight}
+  {maxHeight}
   {loading}
   {error}
+  {onRetry}
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  format={valueFormatter}
+  {exportable}
+  exportImage={chart.exportImage}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

package/dist/lib/components/index.d.ts

@@ -1,3 +1,4 @@
-export { ChartContainer, ChartSkeleton, ChartError, ChartEmpty, ChartLegend, type ChartContainerProps, type ChartLegendProps, type ChartSkeletonProps, type ChartErrorProps, type ChartEmptyProps, } from './base/index.js';
+export { ChartContainer, ChartSkeleton, ChartError, ChartEmpty, ChartLegend, type ChartContainerProps, type ChartLegendProps, type ChartSkeletonProps, type ChartErrorProps, type ChartEmptyProps, ChartDataTable, type ChartDataTableProps, } from './base/index.js';
 export { LineChart, BarChart, PieChart, AreaChart, ScatterChart, DonutChart, } from './core/index.js';
 export { RadarChart, FunnelChart, GaugeChart, HeatmapChart, TreemapChart, CandlestickChart, SankeyChart, } from './extended/index.js';
+export { ComboChart, DotPlotChart, BulletChart, HistogramChart, BoxPlotChart, WaterfallChart, Sparkline, StatCard, StatGroup, type StatGroupProps, } from './report/index.js';

package/dist/lib/components/index.js

@@ -1,6 +1,8 @@
 // Base components
-export { ChartContainer, ChartSkeleton, ChartError, ChartEmpty, ChartLegend, } from './base/index.js';
+export { ChartContainer, ChartSkeleton, ChartError, ChartEmpty, ChartLegend, ChartDataTable, } from './base/index.js';
 // Core charts
 export { LineChart, BarChart, PieChart, AreaChart, ScatterChart, DonutChart, } from './core/index.js';
 // Extended charts
 export { RadarChart, FunnelChart, GaugeChart, HeatmapChart, TreemapChart, CandlestickChart, SankeyChart, } from './extended/index.js';
+// Report charts and stats
+export { ComboChart, DotPlotChart, BulletChart, HistogramChart, BoxPlotChart, WaterfallChart, Sparkline, StatCard, StatGroup, } from './report/index.js';

package/dist/lib/components/report/BoxPlotChart.svelte

@@ -0,0 +1,253 @@
+<script lang="ts">
+  import * as echarts from 'echarts/core';
+  import {
+    BoxplotChart as EChartsBoxplotChart,
+    ScatterChart as EChartsScatterChart,
+  } from 'echarts/charts';
+  import { GridComponent, TooltipComponent } from 'echarts/components';
+  import type { EChartsOption } from 'echarts';
+
+  import type { BoxPlotChartProps } from '@classic-homes/charts-core';
+  import {
+    boxPlotTable,
+    boxplotStats,
+    buildAxis,
+    buildTooltip,
+    chartFormatters,
+    colorWithAlpha,
+    escapeHtml,
+    formatValue,
+    generateBoxPlotDescription,
+    getChartColors,
+    gridInset,
+    mergeChartOption,
+    quantile,
+    withReferenceMarks,
+  } from '@classic-homes/charts-core';
+
+  import { cn } from '../../utils.js';
+  import { chartEvents, toDataPointParams } from '../../events.js';
+  import { useChart } from '../../composables/useChart.svelte.js';
+  import ChartContainer from '../base/ChartContainer.svelte';
+
+  // Register required ECharts modules
+  echarts.use([EChartsBoxplotChart, EChartsScatterChart, GridComponent, TooltipComponent]);
+
+  interface Props extends Omit<BoxPlotChartProps, 'class'> {
+    class?: string;
+  }
+
+  let {
+    title,
+    description,
+    data,
+    orientation = 'vertical',
+    showOutliers = true,
+    color,
+    height = 400,
+    minHeight,
+    maxHeight,
+    loading,
+    error,
+    onRetry,
+    emptyMessage,
+    theme = 'auto',
+    animation = true,
+    showTooltip = true,
+    showGrid = true,
+    valueFormat,
+    locale,
+    xAxisConfig,
+    yAxisConfig,
+    referenceLines,
+    referenceBands,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
+    class: className,
+  }: Props = $props();
+
+  const groups = $derived(
+    (data ?? []).map((group) => ({ name: group.name, stats: boxplotStats(group.values) }))
+  );
+
+  const isEmpty = $derived(!groups.some((group) => group.stats));
+
+  // A statistic of every observation, for reference lines
+  const statistic = (kind: 'average' | 'median' | 'min' | 'max') => {
+    const all = (data ?? [])
+      .flatMap((group) => group.values)
+      .filter((value) => Number.isFinite(value))
+      .sort((a, b) => a - b);
+    if (!all.length) return 0;
+    if (kind === 'min') return all[0];
+    if (kind === 'max') return all[all.length - 1];
+    if (kind === 'median') return quantile(all, 0.5);
+    return all.reduce((sum, value) => sum + value, 0) / all.length;
+  };
+
+  const isHorizontal = $derived(orientation === 'horizontal');
+
+  const formatters = $derived(chartFormatters({ valueFormat, locale, tooltipValueFormatter }));
+
+  // 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 base = color ?? chartColors.series[0];
+    const point = (index: number, value: number) =>
+      isHorizontal ? [value, index] : [index, value];
+
+    const series: Record<string, unknown>[] = [
+      {
+        name: title,
+        type: 'boxplot',
+        data: groups.map(({ stats }) =>
+          stats ? [stats.low, stats.q1, stats.median, stats.q3, stats.high] : []
+        ),
+        itemStyle: { color: colorWithAlpha(base, 0.2), borderColor: base, borderWidth: 1.5 },
+        emphasis: { itemStyle: { borderWidth: 2.5 } },
+      },
+    ];
+
+    if (showOutliers) {
+      series.push({
+        name: 'Outliers',
+        type: 'scatter',
+        symbolSize: 6,
+        itemStyle: { color: 'transparent', borderColor: base, borderWidth: 1.5 },
+        data: groups.flatMap(({ stats }, index) =>
+          (stats?.outliers ?? []).map((value) => point(index, value))
+        ),
+      });
+    }
+
+    const categoryAxis = {
+      type: 'category' as const,
+      data: groups.map((group) => group.name),
+      // Horizontal boxes list the first group at the top
+      inverse: isHorizontal,
+      axisTick: { alignWithLabel: true },
+    };
+    const valueAxis = { type: 'value' as const, scale: true, splitLine: { show: showGrid } };
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...gridInset(undefined, false, xAxisConfig, yAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
+            trigger: 'item',
+            formatter: (params: unknown) => {
+              const p = params as { seriesType?: string; dataIndex?: number; value?: number[] };
+              const fmt = (value: number) => escapeHtml(formatValue(value, formatters.tooltip));
+              if (p.seriesType === 'scatter') {
+                const [x, y] = p.value ?? [];
+                const index = isHorizontal ? y : x;
+                return `${escapeHtml(groups[index]?.name ?? '')}<br/>Outlier: <strong>${fmt(isHorizontal ? x : y)}</strong>`;
+              }
+              const group = groups[p.dataIndex ?? 0];
+              if (!group?.stats) return '';
+              const { stats } = group;
+              return [
+                `<strong>${escapeHtml(group.name)}</strong> (n = ${stats.count})`,
+                `High: ${fmt(stats.high)}`,
+                `Q3: ${fmt(stats.q3)}`,
+                `Median: <strong>${fmt(stats.median)}</strong>`,
+                `Q1: ${fmt(stats.q1)}`,
+                `Low: ${fmt(stats.low)}`,
+              ].join('<br/>');
+            },
+          },
+          { show: showTooltip, formatter: tooltipFormatter }
+        ),
+        xAxis: buildAxis(
+          isHorizontal ? valueAxis : categoryAxis,
+          isHorizontal ? formatters.axis(xAxisConfig) : xAxisConfig
+        ),
+        yAxis: buildAxis(
+          isHorizontal ? categoryAxis : valueAxis,
+          isHorizontal ? yAxisConfig : formatters.axis(yAxisConfig)
+        ),
+        series: withReferenceMarks(
+          series,
+          // ECharts would compute statistics from the box series' five-number
+          // rows, so resolve them from the raw observations instead
+          referenceLines?.map((line) =>
+            typeof line.value === 'number' ? line : { ...line, value: statistic(line.value) }
+          ),
+          referenceBands,
+          {
+            valueAxis: isHorizontal ? 'x' : 'y',
+            inverse: isHorizontal,
+            format: formatters.format,
+            color: chartColors.reference,
+            bandColor: chartColors.referenceBand,
+          }
+        ),
+      } as EChartsOption,
+      optionOverride
+    );
+  });
+
+  const accessibilityDescription = $derived(
+    description ||
+      (!isEmpty ? generateBoxPlotDescription(title, groups, formatters.format) : undefined)
+  );
+
+  const dataTable = $derived(isEmpty ? undefined : boxPlotTable(groups));
+
+  // Manage ECharts instance lifecycle (init, theme, resize, option updates)
+  const chart = useChart({
+    option: () => option,
+    theme: () => theme,
+    animation: () => animation,
+    isEmpty: () => isEmpty,
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click:
+          onClick &&
+          ((params) => {
+            const mapped = toDataPointParams(params, 'click');
+            if ((params as { seriesType?: string }).seriesType !== 'boxplot') return;
+            onClick({ ...mapped, name: groups[mapped.dataIndex]?.name ?? mapped.name });
+          }),
+      }),
+    onCreated: () => onReady,
+  });
+</script>
+
+<ChartContainer
+  {title}
+  description={accessibilityDescription}
+  {height}
+  {minHeight}
+  {maxHeight}
+  {loading}
+  {error}
+  {onRetry}
+  empty={isEmpty}
+  {emptyMessage}
+  class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  format={formatters.format}
+  {exportable}
+  exportImage={chart.exportImage}
+>
+  <div bind:this={chart.container} class="h-full w-full"></div>
+</ChartContainer>

package/dist/lib/components/report/BoxPlotChart.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { BoxPlotChartProps } from '@classic-homes/charts-core';
+interface Props extends Omit<BoxPlotChartProps, 'class'> {
+    class?: string;
+}
+declare const BoxPlotChart: import("svelte").Component<Props, {}, "">;
+type BoxPlotChart = ReturnType<typeof BoxPlotChart>;
+export default BoxPlotChart;

package/dist/lib/components/report/BulletChart.svelte

@@ -0,0 +1,231 @@
+<script lang="ts">
+  import * as echarts from 'echarts/core';
+  import { BarChart as EChartsBarChart, ScatterChart as EChartsScatterChart } from 'echarts/charts';
+  import { GridComponent, TooltipComponent } from 'echarts/components';
+  import type { EChartsOption } from 'echarts';
+
+  import type { BulletChartProps } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildDataLabel,
+    buildTooltip,
+    bulletTable,
+    chartFormatters,
+    escapeHtml,
+    formatValue,
+    generateBulletDescription,
+    getChartColors,
+    mergeChartOption,
+    pointLabel,
+    resolveChartHeight,
+  } from '@classic-homes/charts-core';
+
+  import { cn } from '../../utils.js';
+  import { chartEvents, toDataPointParams } from '../../events.js';
+  import { useChart } from '../../composables/useChart.svelte.js';
+  import ChartContainer from '../base/ChartContainer.svelte';
+
+  // Register required ECharts modules
+  echarts.use([EChartsBarChart, EChartsScatterChart, GridComponent, TooltipComponent]);
+
+  interface Props extends Omit<BulletChartProps, 'class'> {
+    class?: string;
+  }
+
+  let {
+    title,
+    description,
+    data,
+    height = 'auto',
+    minHeight,
+    maxHeight,
+    rowHeight = 36,
+    loading,
+    error,
+    onRetry,
+    emptyMessage,
+    theme = 'auto',
+    animation = true,
+    showTooltip = true,
+    showGrid = false,
+    showLabels = true,
+    valueFormat,
+    locale,
+    labelFormatter,
+    valueAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
+    class: className,
+  }: Props = $props();
+
+  const isEmpty = $derived(!data?.length);
+
+  const formatters = $derived(
+    chartFormatters({ valueFormat, locale, tooltipValueFormatter, labelFormatter })
+  );
+
+  // 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 names = data.map((item) => item.name);
+    const rangeCount = Math.max(0, ...data.map((item) => item.ranges?.length ?? 0));
+    const shades = chartColors.ranges;
+
+    // Qualitative ranges, stacked as bands behind each row; widths are the
+    // gaps between consecutive boundaries
+    const rangeSeries = Array.from({ length: rangeCount }, (_, band) => ({
+      name: `Range ${band + 1}`,
+      type: 'bar',
+      stack: 'ranges',
+      silent: true,
+      barWidth: '70%',
+      yAxisIndex: 0,
+      itemStyle: { color: shades[Math.min(band, shades.length - 1)], borderRadius: 0 },
+      tooltip: { show: false },
+      data: data.map((item) => {
+        const ranges = item.ranges ?? [];
+        if (band >= ranges.length) return null;
+        return ranges[band] - (band > 0 ? ranges[band - 1] : 0);
+      }),
+    }));
+
+    const measure = {
+      name: 'Value',
+      type: 'bar',
+      // A second, hidden category axis, so the narrower measure bar centres
+      // on the range bands instead of sitting beside them
+      yAxisIndex: 1,
+      barWidth: '30%',
+      z: 3,
+      data: data.map((item, index) => ({
+        value: item.value,
+        name: item.name,
+        itemStyle: item.color ? { color: item.color } : undefined,
+        label: pointLabel(item.label, formatters.label, { position: 'right' }),
+      })),
+      itemStyle: { color: chartColors.foreground, borderRadius: 0 },
+      label: buildDataLabel({ show: true, position: 'right' }, undefined, {
+        show: showLabels,
+        formatter: formatters.label,
+        getLabel: (_series, index) => data[index]?.label,
+      }),
+    };
+
+    const targets = {
+      name: 'Target',
+      type: 'scatter',
+      yAxisIndex: 0,
+      symbol: 'rect',
+      symbolSize: [3, Math.round(rowHeight * 0.6)],
+      itemStyle: { color: chartColors.foreground },
+      z: 4,
+      data: data.flatMap((item, index) =>
+        typeof item.target === 'number' ? [{ value: [item.target, index], name: item.name }] : []
+      ),
+    };
+
+    const categoryAxis = {
+      type: 'category' as const,
+      data: names,
+      // First row at the top
+      inverse: true,
+      axisTick: { show: false },
+      axisLine: { show: false },
+    };
+
+    return mergeChartOption(
+      {
+        grid: { left: '3%', right: '8%', top: 8, bottom: '3%', containLabel: true },
+        tooltip: buildTooltip(
+          {
+            trigger: 'axis',
+            axisPointer: { type: 'none' },
+            formatter: (params: unknown) => {
+              const list = (Array.isArray(params) ? params : [params]) as { dataIndex?: number }[];
+              const item = data[list[0]?.dataIndex ?? 0];
+              if (!item) return '';
+              const value = formatValue(item.value, formatters.tooltip);
+              const target =
+                typeof item.target === 'number'
+                  ? `<br/>Target: ${escapeHtml(formatValue(item.target, formatters.tooltip))}`
+                  : '';
+              return `${escapeHtml(item.name)}<br/>Value: <strong>${escapeHtml(value)}</strong>${target}`;
+            },
+          },
+          { show: showTooltip, formatter: tooltipFormatter }
+        ),
+        xAxis: buildAxis(
+          { type: 'value', min: 0, splitLine: { show: showGrid } },
+          formatters.axis(valueAxisConfig)
+        ),
+        yAxis: [categoryAxis, { ...categoryAxis, show: false }],
+        series: [...rangeSeries, measure, targets],
+      } as EChartsOption,
+      optionOverride
+    );
+  });
+
+  const accessibilityDescription = $derived(
+    description ||
+      (!isEmpty ? generateBulletDescription(title, data, formatters.format) : undefined)
+  );
+
+  const dataTable = $derived(isEmpty ? undefined : bulletTable(data));
+
+  const resolvedHeight = $derived(
+    resolveChartHeight(height, data?.length ?? 0, { rowHeight, minHeight, maxHeight, chrome: 48 })
+  );
+
+  // Manage ECharts instance lifecycle (init, theme, resize, option updates)
+  const chart = useChart({
+    option: () => option,
+    theme: () => theme,
+    animation: () => animation,
+    isEmpty: () => isEmpty,
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click:
+          onClick &&
+          ((params) => {
+            // Rows are reported by their item, whichever mark was clicked
+            const mapped = toDataPointParams(params, 'click');
+            const index = data.findIndex((item) => item.name === mapped.name);
+            if (index === -1) return;
+            onClick({ ...mapped, dataIndex: index, value: data[index].value });
+          }),
+      }),
+    onCreated: () => onReady,
+  });
+</script>
+
+<ChartContainer
+  {title}
+  description={accessibilityDescription}
+  height={resolvedHeight}
+  {minHeight}
+  {maxHeight}
+  {loading}
+  {error}
+  {onRetry}
+  empty={isEmpty}
+  {emptyMessage}
+  class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  format={formatters.format}
+  {exportable}
+  exportImage={chart.exportImage}
+>
+  <div bind:this={chart.container} class="h-full w-full"></div>
+</ChartContainer>

package/dist/lib/components/report/BulletChart.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { BulletChartProps } from '@classic-homes/charts-core';
+interface Props extends Omit<BulletChartProps, 'class'> {
+    class?: string;
+}
+declare const BulletChart: import("svelte").Component<Props, {}, "">;
+type BulletChart = ReturnType<typeof BulletChart>;
+export default BulletChart;