@classic-homes/charts-svelte 0.2.0 → 0.3.0

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

@@ -0,0 +1,327 @@
+<script lang="ts">
+  import * as echarts from 'echarts/core';
+  import { BarChart as EChartsBarChart, LineChart as EChartsLineChart } from 'echarts/charts';
+  import { GridComponent, TooltipComponent, LegendComponent } from 'echarts/components';
+  import type { EChartsOption } from 'echarts';
+
+  import type { ComboChartProps } from '@classic-homes/charts-core';
+  import {
+    allSeriesEmpty,
+    buildAxis,
+    buildDataLabel,
+    buildDataZoom,
+    buildLegend,
+    buildTooltip,
+    categoryTable,
+    chartFormatters,
+    colorWithAlpha,
+    escapeHtml,
+    generateComboChartDescription,
+    getChartColors,
+    gridInset,
+    hasPointLabels,
+    mergeChartOption,
+    resolveValueFormatter,
+    seriesLabelLookup,
+    valueAxisConfig,
+    valueLabelFormatter,
+    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([
+    EChartsBarChart,
+    EChartsLineChart,
+    GridComponent,
+    TooltipComponent,
+    LegendComponent,
+  ]);
+
+  interface Props extends Omit<ComboChartProps, 'class'>, CustomLegendProps {
+    class?: string;
+  }
+
+  let {
+    title,
+    description,
+    data,
+    height = 400,
+    minHeight,
+    maxHeight,
+    loading,
+    error,
+    onRetry,
+    emptyMessage,
+    theme = 'auto',
+    animation = true,
+    showLegend = true,
+    showTooltip = true,
+    showGrid = true,
+    stacked = false,
+    smooth = false,
+    showLabels = false,
+    connectNulls = false,
+    valueFormat,
+    secondaryValueFormat,
+    locale,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    secondaryYAxisConfig,
+    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 || allSeriesEmpty(data?.series));
+
+  const formatters = $derived(
+    chartFormatters({ valueFormat, locale, tooltipValueFormatter, labelFormatter })
+  );
+  const secondaryFormat = $derived(
+    resolveValueFormatter(secondaryValueFormat, locale) ?? formatters.format
+  );
+  const secondaryTitled = $derived(
+    secondaryYAxisConfig?.name !== undefined &&
+      (secondaryYAxisConfig.nameLocation ?? 'middle') === 'middle'
+  );
+  const hasSecondary = $derived(data?.series?.some((s) => s.axis === 'secondary') ?? false);
+
+  // 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 getLabel = seriesLabelLookup(data.series);
+    const legendBottom = builtInLegend && (legendConfig?.position ?? 'bottom') === 'bottom';
+    const anyBars = data.series.some((s) => (s.type ?? 'bar') === 'bar');
+
+    const series = data.series.map((source, index) => {
+      const type = source.type ?? 'bar';
+      const secondary = source.axis === 'secondary';
+      // Each axis has its own format, so each series labels with its own
+      const label =
+        labelFormatter ??
+        (secondary && secondaryFormat ? valueLabelFormatter(secondaryFormat) : formatters.label);
+      const color = source.color || chartColors.series[index % chartColors.series.length];
+      const common = {
+        name: source.name,
+        yAxisIndex: secondary ? 1 : 0,
+        data: withPointLabels(source.data, source.labels, label, { position: 'top' }),
+        itemStyle: source.color ? { color: source.color } : undefined,
+        label: buildDataLabel({ show: true, position: 'top' }, undefined, {
+          show: showLabels,
+          formatter: label,
+          getLabel,
+        }),
+        emphasis: { focus: 'series' },
+      };
+      if (type === 'bar') {
+        return { ...common, type: 'bar', stack: source.stack ?? (stacked ? 'Total' : undefined) };
+      }
+      return {
+        ...common,
+        type: 'line',
+        smooth,
+        connectNulls,
+        showSymbol: true,
+        symbolSize: showLabels || hasPointLabels([source]) ? 6 : 5,
+        // Lines sit above bars
+        z: 3,
+        stack: source.stack,
+        areaStyle: type === 'area' ? { color: colorWithAlpha(color, 0.25) } : undefined,
+      };
+    });
+
+    // A per-series value formatter, so tooltips write each value in its axis' format
+    const tooltipValue = (value: number, seriesIndex: number) => {
+      if (tooltipValueFormatter) return tooltipValueFormatter(value);
+      const fmt =
+        data.series[seriesIndex]?.axis === 'secondary' ? secondaryFormat : formatters.format;
+      return fmt ? fmt(value) : String(value);
+    };
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...withZoomInset(
+            {
+              ...gridInset(legendConfig, builtInLegend, xAxisConfig, yAxisConfig),
+              // Room for a centred secondary axis title beside its tick labels
+              ...(secondaryTitled && { right: 36 }),
+            },
+            dataZoom,
+            'x'
+          ),
+        },
+        tooltip: buildTooltip(
+          {
+            trigger: 'axis',
+            axisPointer: { type: anyBars ? 'shadow' : 'line' },
+            formatter: tooltipFormatter
+              ? undefined
+              : (params: unknown) => {
+                  const list = (Array.isArray(params) ? params : [params]) as {
+                    axisValueLabel?: string;
+                    marker?: string;
+                    seriesName?: string;
+                    seriesIndex?: number;
+                    value?: unknown;
+                  }[];
+                  const rows = list.map((p) => {
+                    // Missing values show as a dash
+                    const value =
+                      typeof p.value === 'number' ? tooltipValue(p.value, p.seriesIndex ?? 0) : '-';
+                    return `${p.marker ?? ''}${escapeHtml(p.seriesName ?? '')}<span style="float:right;margin-left:16px;font-weight:600">${escapeHtml(value)}</span>`;
+                  });
+                  return [escapeHtml(list[0]?.axisValueLabel ?? ''), ...rows].join('<br/>');
+                },
+          },
+          { show: showTooltip, formatter: tooltipFormatter, getLabel }
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        dataZoom: buildDataZoom(dataZoom, 'x', legendBottom ? 36 : 0),
+        xAxis: buildAxis(
+          {
+            type: 'category',
+            data: data.categories,
+            axisTick: { alignWithLabel: true },
+          },
+          xAxisConfig
+        ),
+        yAxis: [
+          buildAxis({ type: 'value', splitLine: { show: showGrid } }, formatters.axis(yAxisConfig)),
+          ...(hasSecondary
+            ? [
+                buildAxis(
+                  // The secondary axis' grid lines would not line up with the primary's
+                  { type: 'value', position: 'right', splitLine: { show: false } },
+                  valueAxisConfig(
+                    secondaryTitled
+                      ? // Clear wide tick labels such as "$500,000"
+                        { nameGap: 64, ...secondaryYAxisConfig }
+                      : secondaryYAxisConfig,
+                    secondaryFormat
+                  )
+                ),
+              ]
+            : []),
+        ],
+        series: withReferenceMarks(series, referenceLines, referenceBands, {
+          valueAxis: 'y',
+          format: formatters.format,
+          color: chartColors.reference,
+          bandColor: chartColors.referenceBand,
+        }),
+      } as EChartsOption,
+      optionOverride
+    );
+  });
+
+  const accessibilityDescription = $derived(
+    description ||
+      (!isEmpty ? generateComboChartDescription(title, data, formatters.format) : undefined)
+  );
+
+  // Secondary-axis columns are written as plain numbers when their format differs
+  const dataTable = $derived.by(() => {
+    if (isEmpty) return undefined;
+    const table = categoryTable(data);
+    if (!secondaryValueFormat) return table;
+    return {
+      ...table,
+      columns: table.columns?.map((column, index) =>
+        index > 0 && data.series[index - 1]?.axis === 'secondary' ? ('number' as const) : column
+      ),
+    };
+  });
+
+  // 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,
+    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={formatters.format}
+  {exportable}
+  exportImage={chart.exportImage}
+>
+  <div bind:this={chart.container} class="h-full w-full"></div>
+</ChartContainer>

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

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

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

@@ -0,0 +1,325 @@
+<script lang="ts">
+  import * as echarts from 'echarts/core';
+  import { ScatterChart as EChartsScatterChart, LinesChart } from 'echarts/charts';
+  import { GridComponent, TooltipComponent, LegendComponent } from 'echarts/components';
+  import type { EChartsOption } from 'echarts';
+
+  import type { DotPlotChartProps } from '@classic-homes/charts-core';
+  import {
+    allSeriesEmpty,
+    buildAxis,
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    categoryTable,
+    chartFormatters,
+    escapeHtml,
+    formatValue,
+    generateDotPlotDescription,
+    getChartColors,
+    gridInset,
+    mergeChartOption,
+    pointLabel,
+    resolveChartHeight,
+    seriesLabelLookup,
+    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 {
+    useChartLegend,
+    type CustomLegendProps,
+  } from '../../composables/useChartLegend.svelte.js';
+  import ChartContainer from '../base/ChartContainer.svelte';
+
+  // Register required ECharts modules
+  echarts.use([EChartsScatterChart, LinesChart, GridComponent, TooltipComponent, LegendComponent]);
+
+  interface Props extends Omit<DotPlotChartProps, 'class'>, CustomLegendProps {
+    class?: string;
+  }
+
+  let {
+    title,
+    description,
+    data,
+    height = 'auto',
+    minHeight,
+    maxHeight,
+    rowHeight,
+    loading,
+    error,
+    onRetry,
+    emptyMessage,
+    theme = 'auto',
+    animation = true,
+    showLegend = true,
+    showTooltip = true,
+    showGrid = true,
+    dotSize = 12,
+    connect = false,
+    showLabels = false,
+    valueFormat,
+    locale,
+    labelFormatter,
+    valueAxisConfig,
+    categoryAxisConfig,
+    referenceLines,
+    referenceBands,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
+    class: className,
+  }: Props = $props();
+
+  const isEmpty = $derived(!data?.categories?.length || allSeriesEmpty(data?.series));
+
+  const formatters = $derived(
+    chartFormatters({ valueFormat, locale, tooltipValueFormatter, labelFormatter })
+  );
+
+  // Points are [value, row index], so labels format the first element
+  const dotLabel = $derived<DotPlotChartProps['labelFormatter']>(
+    labelFormatter ??
+      ((params) =>
+        params.label ??
+        formatValue(
+          Array.isArray(params.value) ? params.value[0] : params.value,
+          formatters.format
+        ))
+  );
+
+  // Per-element colours that follow the resolved chart theme
+  const chartColors = $derived.by(() => getChartColors(chart.theme));
+
+  const builtInLegend = $derived(showLegend && !renderLegend);
+
+  // Dot diameter for a weight: dot area grows with the weight
+  const sizeScale = $derived.by(() => {
+    const [smallest, largest] = Array.isArray(dotSize) ? dotSize : [dotSize, dotSize];
+    let maxWeight = 0;
+    for (const s of data?.series ?? []) {
+      for (const weight of s.sizes ?? []) {
+        if (typeof weight === 'number' && weight > maxWeight) maxWeight = weight;
+      }
+    }
+    return (weight: number | null | undefined) =>
+      typeof weight === 'number' && maxWeight > 0 && smallest !== largest
+        ? smallest + Math.sqrt(Math.max(weight, 0) / maxWeight) * (largest - smallest)
+        : largest;
+  });
+
+  const option: EChartsOption = $derived.by(() => {
+    if (isEmpty) return {};
+
+    const getLabel = seriesLabelLookup(data.series);
+
+    const series: Record<string, unknown>[] = data.series.map((source) => ({
+      name: source.name,
+      type: 'scatter',
+      // Missing values leave the row empty
+      data: source.data.flatMap((value, index) =>
+        value == null
+          ? []
+          : [
+              {
+                name: data.categories[index],
+                value: [value, index],
+                symbolSize: sizeScale(source.sizes?.[index]),
+                weight: source.sizes?.[index],
+                label: pointLabel(source.labels?.[index], dotLabel, { position: 'right' }),
+              },
+            ]
+      ),
+      itemStyle: source.color ? { color: source.color } : undefined,
+      label: buildDataLabel({ show: true, position: 'right', distance: 8 }, undefined, {
+        show: showLabels,
+        formatter: dotLabel,
+        getLabel: (seriesIndex, _dataIndex, name) =>
+          getLabel(seriesIndex, data.categories.indexOf(name), name),
+      }),
+      emphasis: { scale: 1.3 },
+      z: 3,
+    }));
+
+    // A line through each row's dots, for comparing series (a dumbbell plot)
+    if (connect && data.series.length > 1) {
+      const segments = data.categories.flatMap((_, index) => {
+        const values = data.series
+          .map((s) => s.data[index])
+          .filter((value): value is number => typeof value === 'number');
+        if (values.length < 2) return [];
+        return [
+          {
+            coords: [
+              [Math.min(...values), index],
+              [Math.max(...values), index],
+            ],
+          },
+        ];
+      });
+      series.push({
+        type: 'lines',
+        coordinateSystem: 'cartesian2d',
+        silent: true,
+        data: segments,
+        lineStyle: { color: chartColors.mutedForeground, width: 2, opacity: 0.5 },
+        z: 2,
+      });
+    }
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '6%',
+          bottom: '3%',
+          // Reference line labels sit above the plot
+          top: referenceLines?.length ? 32 : 16,
+          containLabel: true,
+          ...gridInset(legendConfig, builtInLegend, valueAxisConfig, categoryAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
+            trigger: 'item',
+            formatter: (params: unknown) => {
+              const p = params as {
+                name?: string;
+                marker?: string;
+                seriesName?: string;
+                value?: [number, number];
+                data?: { weight?: number | null };
+              };
+              if (!p.value) return '';
+              const value = formatValue(p.value[0], formatters.tooltip);
+              const weight =
+                typeof p.data?.weight === 'number' ? ` (n = ${formatValue(p.data.weight)})` : '';
+              return `${escapeHtml(p.name ?? '')}<br/>${p.marker ?? ''}${escapeHtml(p.seriesName ?? '')}: <strong>${escapeHtml(value)}</strong>${escapeHtml(weight)}`;
+            },
+          },
+          { show: showTooltip, formatter: tooltipFormatter, getLabel }
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend && data.series.length > 1, custom: !!renderLegend }
+        ),
+        xAxis: buildAxis(
+          {
+            type: 'value',
+            // A zero baseline would hide the differences a dot plot is for
+            scale: true,
+            splitLine: { show: showGrid },
+          },
+          formatters.axis(valueAxisConfig)
+        ),
+        yAxis: buildAxis(
+          {
+            type: 'category',
+            data: data.categories,
+            // First category at the top
+            inverse: true,
+            axisTick: { show: false },
+            axisLine: { show: false },
+            splitLine: { show: showGrid, lineStyle: { type: 'dotted' } },
+          },
+          categoryAxisConfig
+        ),
+        series: withReferenceMarks(series, referenceLines, referenceBands, {
+          valueAxis: 'x',
+          inverse: true,
+          format: formatters.format,
+          color: chartColors.reference,
+          bandColor: chartColors.referenceBand,
+        }),
+      } as EChartsOption,
+      optionOverride
+    );
+  });
+
+  const accessibilityDescription = $derived(
+    description ||
+      (!isEmpty ? generateDotPlotDescription(title, data, formatters.format) : undefined)
+  );
+
+  const dataTable = $derived(isEmpty ? undefined : categoryTable(data));
+
+  const resolvedHeight = $derived(
+    resolveChartHeight(height, data?.categories?.length ?? 0, {
+      rowHeight,
+      minHeight,
+      maxHeight,
+      chrome: 56 + (builtInLegend && (data?.series?.length ?? 0) > 1 ? 36 : 0),
+    })
+  );
+
+  // 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,
+    patterns: () => patterns,
+    events: () =>
+      chartEvents(events, {
+        click:
+          onClick &&
+          ((params) => {
+            const mapped = toDataPointParams(params, 'click');
+            // Report the category's index and the plain value
+            const value = mapped.value as unknown as [number, number];
+            onClick({ ...mapped, dataIndex: value[1], value: value[0] });
+          }),
+      }),
+    onReady: (instance) => legend.attach(instance),
+    onCreated: () => onReady,
+  });
+</script>
+
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
+<ChartContainer
+  {title}
+  description={accessibilityDescription}
+  height={resolvedHeight}
+  {minHeight}
+  {maxHeight}
+  {loading}
+  {error}
+  {onRetry}
+  empty={isEmpty}
+  {emptyMessage}
+  class={cn(className)}
+  legend={renderLegend ? customLegend : undefined}
+  legendPosition={legendConfig?.position}
+  {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/DotPlotChart.svelte.d.ts

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