@classic-homes/charts-svelte 0.2.0 → 0.3.0

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

@@ -0,0 +1,271 @@
+<script lang="ts">
+  import * as echarts from 'echarts/core';
+  import { BarChart as EChartsBarChart } from 'echarts/charts';
+  import { GridComponent, TooltipComponent } from 'echarts/components';
+  import type { EChartsOption } from 'echarts';
+
+  import type { WaterfallChartProps } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildTooltip,
+    chartFormatters,
+    escapeHtml,
+    formatValue,
+    generateWaterfallDescription,
+    getChartColors,
+    gridInset,
+    mergeChartOption,
+    waterfallLayout,
+    waterfallTable,
+    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([EChartsBarChart, GridComponent, TooltipComponent]);
+
+  interface Props extends Omit<WaterfallChartProps, 'class'> {
+    class?: string;
+  }
+
+  let {
+    title,
+    description,
+    data,
+    increaseColor,
+    decreaseColor,
+    totalColor,
+    height = 400,
+    minHeight,
+    maxHeight,
+    loading,
+    error,
+    onRetry,
+    emptyMessage,
+    theme = 'auto',
+    animation = true,
+    showTooltip = true,
+    showGrid = true,
+    showLabels = true,
+    valueFormat,
+    locale,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    referenceLines,
+    referenceBands,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
+    class: className,
+  }: Props = $props();
+
+  const isEmpty = $derived(!data?.length);
+
+  const bars = $derived(waterfallLayout(data ?? []));
+
+  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 colorOf = (index: number) => {
+      const bar = bars[index];
+      return (
+        data[index].color ??
+        (bar.kind === 'total'
+          ? (totalColor ?? chartColors.series[0])
+          : bar.kind === 'increase'
+            ? (increaseColor ?? chartColors.success)
+            : (decreaseColor ?? chartColors.destructive))
+      );
+    };
+
+    // The step's own label: a signed change, or the total
+    const labelText = (index: number) => {
+      const step = data[index];
+      const bar = bars[index];
+      if (step.label) return step.label;
+      if (typeof labelFormatter === 'function') {
+        return labelFormatter({
+          name: step.name,
+          value: bar.value,
+          seriesName: title,
+          seriesIndex: 0,
+          dataIndex: index,
+        });
+      }
+      const text = formatValue(Math.abs(bar.value), formatters.format);
+      if (bar.kind === 'total') return formatValue(bar.value, formatters.format);
+      return `${bar.value < 0 ? '−' : '+'}${text}`;
+    };
+
+    // Each bar is an invisible base plus its parts above and below zero
+    // (see waterfallLayout); the label sits on whichever part is drawn
+    const piece = (part: 'positive' | 'negative') => ({
+      name: part === 'positive' ? 'Increase' : 'Decrease',
+      type: 'bar',
+      stack: 'waterfall',
+      barMaxWidth: 64,
+      data: bars.map((bar, index) => {
+        const value = bar[part];
+        const labelled =
+          part === 'positive' ? bar.positive !== 0 || bar.negative === 0 : bar.positive === 0;
+        return {
+          value,
+          name: data[index].name,
+          itemStyle: { color: colorOf(index), borderRadius: 0 },
+          label: {
+            show: showLabels && labelled,
+            position: part === 'positive' ? 'top' : 'bottom',
+            // A template string is ECharts' to fill; anything else is our text
+            formatter: typeof labelFormatter === 'string' ? labelFormatter : () => labelText(index),
+            color: chartColors.foreground,
+          },
+        };
+      }),
+    });
+
+    const series = [
+      {
+        name: 'Base',
+        type: 'bar',
+        stack: 'waterfall',
+        silent: true,
+        itemStyle: { color: 'transparent', borderColor: 'transparent' },
+        emphasis: { disabled: true },
+        tooltip: { show: false },
+        data: bars.map((bar) => bar.base),
+      },
+      piece('positive'),
+      piece('negative'),
+    ];
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...gridInset(undefined, false, xAxisConfig, yAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
+            trigger: 'axis',
+            axisPointer: { type: 'shadow' },
+            formatter: (params: unknown) => {
+              const list = (Array.isArray(params) ? params : [params]) as { dataIndex?: number }[];
+              const index = list[0]?.dataIndex ?? 0;
+              const step = data[index];
+              const bar = bars[index];
+              if (!step || !bar) return '';
+              const fmt = (value: number) => escapeHtml(formatValue(value, formatters.tooltip));
+              if (bar.kind === 'total') {
+                return `${escapeHtml(step.name)}<br/>Total: <strong>${fmt(bar.end)}</strong>`;
+              }
+              const sign = bar.value < 0 ? '−' : '+';
+              return `${escapeHtml(step.name)}<br/>Change: <strong>${sign}${fmt(Math.abs(bar.value))}</strong><br/>Running total: ${fmt(bar.end)}`;
+            },
+          },
+          { show: showTooltip, formatter: tooltipFormatter }
+        ),
+        xAxis: buildAxis(
+          {
+            type: 'category',
+            data: data.map((step) => step.name),
+            axisTick: { alignWithLabel: true },
+          },
+          xAxisConfig
+        ),
+        yAxis: buildAxis(
+          { type: 'value', splitLine: { show: showGrid } },
+          formatters.axis(yAxisConfig)
+        ),
+        series: withReferenceMarks(
+          series,
+          referenceLines?.filter((line) => typeof line.value === 'number'),
+          referenceBands,
+          {
+            valueAxis: 'y',
+            format: formatters.format,
+            color: chartColors.reference,
+            bandColor: chartColors.referenceBand,
+          }
+        ),
+      } as EChartsOption,
+      optionOverride
+    );
+  });
+
+  const accessibilityDescription = $derived(
+    description ||
+      (!isEmpty
+        ? generateWaterfallDescription(
+            title,
+            data,
+            bars[bars.length - 1]?.end ?? 0,
+            formatters.format
+          )
+        : undefined)
+  );
+
+  const dataTable = $derived(isEmpty ? undefined : waterfallTable(data, bars));
+
+  // 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');
+            const bar = bars[mapped.dataIndex];
+            if (!bar) return;
+            onClick({ ...mapped, seriesName: title, value: bar.value });
+          }),
+      }),
+    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/WaterfallChart.svelte.d.ts

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

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

@@ -0,0 +1,12 @@
+export { default as ComboChart } from './ComboChart.svelte';
+export { default as DotPlotChart } from './DotPlotChart.svelte';
+export { default as BulletChart } from './BulletChart.svelte';
+export { default as HistogramChart } from './HistogramChart.svelte';
+export { default as BoxPlotChart } from './BoxPlotChart.svelte';
+export { default as WaterfallChart } from './WaterfallChart.svelte';
+export { default as Sparkline } from './Sparkline.svelte';
+export { default as StatCard } from './StatCard.svelte';
+export { default as StatGroup } from './StatGroup.svelte';
+import type { ComponentProps } from 'svelte';
+import type StatGroup from './StatGroup.svelte';
+export type StatGroupProps = ComponentProps<typeof StatGroup>;

package/dist/lib/components/report/index.js

@@ -0,0 +1,9 @@
+export { default as ComboChart } from './ComboChart.svelte';
+export { default as DotPlotChart } from './DotPlotChart.svelte';
+export { default as BulletChart } from './BulletChart.svelte';
+export { default as HistogramChart } from './HistogramChart.svelte';
+export { default as BoxPlotChart } from './BoxPlotChart.svelte';
+export { default as WaterfallChart } from './WaterfallChart.svelte';
+export { default as Sparkline } from './Sparkline.svelte';
+export { default as StatCard } from './StatCard.svelte';
+export { default as StatGroup } from './StatGroup.svelte';

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

@@ -1,4 +1,4 @@
-export { useChart, type UseChartOptions, type UseChartReturn } from './useChart.svelte.js';
+export { useChart, exportChartImage, registerEchartsModules, type ExportImageOptions, type UseChartOptions, type UseChartReturn, } from './useChart.svelte.js';
 export { useChartTheme, registerClassicThemes } from './useChartTheme.svelte.js';
 export { useReducedMotion } from './useReducedMotion.svelte.js';
 export { useChartResize } from './useChartResize.svelte.js';

package/dist/lib/composables/index.js

@@ -1,4 +1,4 @@
-export { useChart } from './useChart.svelte.js';
+export { useChart, exportChartImage, registerEchartsModules, } from './useChart.svelte.js';
 export { useChartTheme, registerClassicThemes } from './useChartTheme.svelte.js';
 export { useReducedMotion } from './useReducedMotion.svelte.js';
 export { useChartResize } from './useChartResize.svelte.js';

package/dist/lib/composables/useChart.svelte.d.ts

@@ -1,5 +1,24 @@
 import * as echarts from 'echarts/core';
 import type { EChartsOption } from 'echarts';
+import { type ChartEventHandlers } from '@classic-homes/charts-core';
+/**
+ * Register extra ECharts modules (series types, components or renderers)
+ * that an `option` override needs, e.g. `registerEchartsModules([ToolboxComponent])`
+ */
+export declare const registerEchartsModules: typeof echarts.use;
+export interface ExportImageOptions {
+    /** Image format (defaults to 'png') */
+    type?: 'png' | 'jpeg';
+    /** Resolution multiplier (defaults to 2) */
+    pixelRatio?: number;
+    /** Background colour (defaults to the card colour, so the image is not transparent) */
+    backgroundColor?: string;
+}
+/**
+ * Render a chart instance to an image data URL, or null when it has no
+ * live instance
+ */
+export declare function exportChartImage(chart: echarts.ECharts | null | undefined, { type, pixelRatio, backgroundColor }?: ExportImageOptions): string | null;
 export interface UseChartOptions {
     /** Getter returning the ECharts option (animation is resolved by the composable) */
     option: () => EChartsOption;
@@ -9,6 +28,14 @@ export interface UseChartOptions {
     animation?: () => boolean;
     /** Getter returning whether the chart has no data (skips option updates) */
     isEmpty?: () => boolean;
+    /** Getter returning whether series are filled with decal patterns */
+    patterns?: () => boolean | undefined;
+    /**
+     * Getter returning ECharts event handlers by event name. Listeners are
+     * bound for each name with a handler and call the current handler at event
+     * time, so handlers set or replaced after mount work.
+     */
+    events?: () => ChartEventHandlers;
     /**
      * Callback when the chart instance is (re)created. Register event handlers
      * here; a theme change re-runs it so handlers are attached to the live
@@ -17,6 +44,11 @@ export interface UseChartOptions {
      * the chart.
      */
     onReady?: (chart: echarts.ECharts) => void;
+    /**
+     * Getter returning a consumer callback, called with each new instance once
+     * its option is applied (the chart's `onReady` prop)
+     */
+    onCreated?: () => ((chart: echarts.ECharts) => void) | undefined;
 }
 export interface UseChartReturn {
     /** Container element to attach via bind:this */
@@ -27,6 +59,8 @@ export interface UseChartReturn {
     readonly theme: string;
     /** Whether the user prefers reduced motion */
     readonly reducedMotion: boolean;
+    /** Render the chart to an image data URL */
+    exportImage: (options?: ExportImageOptions) => string | null;
 }
 /**
  * Composable to manage ECharts instance lifecycle

package/dist/lib/composables/useChart.svelte.js

@@ -1,9 +1,28 @@
 import { untrack } from 'svelte';
 import * as echarts from 'echarts/core';
+import { AriaComponent, DataZoomInsideComponent, DataZoomSliderComponent, DatasetComponent, GraphicComponent, MarkAreaComponent, MarkLineComponent, } from 'echarts/components';
+import { CanvasRenderer } from 'echarts/renderers';
 import { getReplaceMerge } from '@classic-homes/charts-core';
 import { useChartTheme } from './useChartTheme.svelte.js';
 import { useChartResize } from './useChartResize.svelte.js';
 import { useReducedMotion } from './useReducedMotion.svelte.js';
+// Components every chart can use through props or an `option` override, so
+// overrides do not depend on which other charts an app happens to import
+echarts.use([
+    AriaComponent,
+    DataZoomInsideComponent,
+    DataZoomSliderComponent,
+    DatasetComponent,
+    GraphicComponent,
+    MarkAreaComponent,
+    MarkLineComponent,
+    CanvasRenderer,
+]);
+/**
+ * Register extra ECharts modules (series types, components or renderers)
+ * that an `option` override needs, e.g. `registerEchartsModules([ToolboxComponent])`
+ */
+export const registerEchartsModules = (modules) => echarts.use(modules);
 const isComponentType = (mainType) => echarts.ComponentModel.hasClass(mainType);
 // The option last applied to each instance; a fresh instance has none
 const appliedOptions = new WeakMap();
@@ -21,6 +40,46 @@ function applyOption(chart, next) {
     });
     appliedOptions.set(chart, next);
 }
+function captureState(chart) {
+    if (chart.isDisposed())
+        return null;
+    const option = chart.getOption();
+    const selected = option.legend?.[0]?.selected ?? {};
+    return {
+        hidden: Object.keys(selected).filter((name) => selected[name] === false),
+        zoom: (option.dataZoom ?? []).map(({ start, end }) => ({ start, end })),
+    };
+}
+function restoreState(chart, state) {
+    if (!state)
+        return;
+    for (const name of state.hidden)
+        chart.dispatchAction({ type: 'legendUnSelect', name });
+    state.zoom.forEach(({ start, end }, dataZoomIndex) => {
+        if (start !== undefined && end !== undefined && (start !== 0 || end !== 100)) {
+            chart.dispatchAction({ type: 'dataZoom', dataZoomIndex, start, end });
+        }
+    });
+}
+/**
+ * Render a chart instance to an image data URL, or null when it has no
+ * live instance
+ */
+export function exportChartImage(chart, { type = 'png', pixelRatio = 2, backgroundColor } = {}) {
+    if (!chart || chart.isDisposed())
+        return null;
+    const background = backgroundColor ??
+        (typeof document !== 'undefined'
+            ? getComputedStyle(chart.getDom()).getPropertyValue('--card').trim()
+            : '');
+    // Token variables hold bare HSL channels ("0 0% 100%")
+    const color = !background
+        ? '#ffffff'
+        : /^[\d.]+\s/.test(background)
+            ? `hsl(${background})`
+            : background;
+    return chart.getDataURL({ type, pixelRatio, backgroundColor: color });
+}
 /**
  * Composable to manage ECharts instance lifecycle
  * Matches behavior of React useChart hook
@@ -31,15 +90,24 @@ export function useChart(opts) {
     const chartTheme = useChartTheme(() => opts.theme?.() ?? 'auto');
     const reducedMotion = useReducedMotion();
     const chartResize = useChartResize();
-    // Resolve the option with reduced-motion-aware animation
-    const resolveOption = () => ({
-        ...opts.option(),
-        animation: (opts.animation?.() ?? true) && !reducedMotion.value,
-    });
+    // Resolve the option with reduced-motion-aware animation and patterns
+    const resolveOption = () => {
+        const option = {
+            ...opts.option(),
+            animation: (opts.animation?.() ?? true) && !reducedMotion.value,
+        };
+        if (opts.patterns?.()) {
+            // Labels stay off: the container already describes the chart
+            option.aria = { enabled: true, label: { enabled: false }, decal: { show: true } };
+        }
+        return option;
+    };
+    // State to carry over to the instance a theme change re-creates
+    let carried = null;
     // Initialize chart instance (only depends on container and theme). A theme
-    // change disposes and re-creates the instance, restoring the current option
-    // and re-running onReady so event handlers registered there are attached to
-    // the live instance.
+    // change disposes and re-creates the instance, restoring the current option,
+    // legend selection and zoom, and re-running onReady so event handlers
+    // registered there are attached to the live instance.
     $effect(() => {
         const container = containerEl;
         const themeName = chartTheme.theme;
@@ -50,14 +118,21 @@ export function useChart(opts) {
         // Apply the current option and callbacks without tracking them, so data
         // or callback changes update the chart instead of re-initializing it
         untrack(() => {
+            opts.onReady?.(chart);
             if (!(opts.isEmpty?.() ?? false)) {
                 applyOption(chart, resolveOption());
+                // Flush the lazy update so restored actions apply to the new option
+                if (carried)
+                    chart.setOption({}, { lazyUpdate: false });
+                restoreState(chart, carried);
             }
-            opts.onReady?.(chart);
+            carried = null;
+            opts.onCreated?.()?.(chart);
         });
         // Set up ResizeObserver for container-aware resizing
         chartResize.observe(container, chart);
         return () => {
+            carried = captureState(chart);
             chartResize.cleanup(container);
             chart.dispose();
             if (chartInstance === chart) {
@@ -74,6 +149,42 @@ export function useChart(opts) {
             return;
         applyOption(chart, option);
     });
+    // Bind event listeners per event name; each calls the current handler
+    $effect(() => {
+        const chart = chartInstance;
+        const handlers = opts.events?.() ?? {};
+        if (!chart || chart.isDisposed())
+            return;
+        const bound = Object.keys(handlers)
+            .filter((name) => handlers[name])
+            .map((name) => {
+            const listener = (params) => untrack(() => opts.events?.()[name])?.(params);
+            chart.on(name, listener);
+            return [name, listener];
+        });
+        return () => {
+            if (chart.isDisposed())
+                return;
+            for (const [name, listener] of bound)
+                chart.off(name, listener);
+        };
+    });
+    // Charts are drawn to a canvas sized to the screen layout; resize for print
+    $effect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const resize = () => {
+            const chart = chartInstance;
+            if (chart && !chart.isDisposed())
+                chart.resize();
+        };
+        window.addEventListener('beforeprint', resize);
+        window.addEventListener('afterprint', resize);
+        return () => {
+            window.removeEventListener('beforeprint', resize);
+            window.removeEventListener('afterprint', resize);
+        };
+    });
     return {
         get container() {
             return containerEl;
@@ -90,5 +201,6 @@ export function useChart(opts) {
         get reducedMotion() {
             return reducedMotion.value;
         },
+        exportImage: (options) => exportChartImage(chartInstance, options),
     };
 }

package/dist/lib/composables/useChartTheme.svelte.js

@@ -17,22 +17,25 @@ export function registerClassicThemes() {
  * @param getPreference - A getter function that returns the current theme preference
  */
 export function useChartTheme(getPreference) {
-    let currentTheme = $state(THEME_LIGHT);
-    function updateTheme() {
+    function resolveTheme() {
         const preference = getPreference();
-        if (preference !== 'auto') {
-            currentTheme = preference === 'dark' ? THEME_DARK : THEME_LIGHT;
-            return;
-        }
+        if (preference !== 'auto')
+            return preference === 'dark' ? THEME_DARK : THEME_LIGHT;
         // Check for dark class on html element
-        if (typeof document !== 'undefined') {
-            const isDark = document.documentElement.classList.contains('dark');
-            currentTheme = isDark ? THEME_DARK : THEME_LIGHT;
+        if (typeof document !== 'undefined' && document.documentElement.classList.contains('dark')) {
+            return THEME_DARK;
         }
+        return THEME_LIGHT;
+    }
+    // Resolved up front so a chart on a dark page is created dark, rather than
+    // created light and then re-created
+    let currentTheme = $state(resolveTheme());
+    function updateTheme() {
+        currentTheme = resolveTheme();
     }
+    // Themes must exist before the first chart initialises with one
+    registerClassicThemes();
     $effect(() => {
-        // Register themes on first use
-        registerClassicThemes();
         // Initial theme check
         updateTheme();
         const preference = getPreference();

package/dist/lib/events.d.ts

@@ -0,0 +1,15 @@
+import type { ChartEventHandlers, DataPointEventParams, SliceEventParams } from '@classic-homes/charts-core';
+/**
+ * Map ECharts event parameters for a data point (line, bar, area, scatter)
+ */
+export declare function toDataPointParams(params: unknown, fallbackType: string): DataPointEventParams;
+/**
+ * Map ECharts event parameters for a slice (pie, donut, funnel)
+ */
+export declare function toSliceParams(params: unknown, fallbackType: string): SliceEventParams;
+/**
+ * Combine a chart's mapped `onClick`/`onHover` props with its raw `events`
+ * prop into one handler map. When both handle an event, both run, the
+ * mapped handler first.
+ */
+export declare function chartEvents(events: ChartEventHandlers | undefined, mapped: ChartEventHandlers): ChartEventHandlers;

package/dist/lib/events.js

@@ -0,0 +1,56 @@
+const raw = (params) => (params ?? {});
+/**
+ * Map ECharts event parameters for a data point (line, bar, area, scatter)
+ */
+export function toDataPointParams(params, fallbackType) {
+    const p = raw(params);
+    return {
+        type: p.type || fallbackType,
+        componentType: p.componentType || 'series',
+        seriesIndex: p.seriesIndex,
+        seriesName: p.seriesName || '',
+        dataIndex: p.dataIndex ?? 0,
+        name: p.name || '',
+        value: p.value,
+        color: typeof p.color === 'string' ? p.color : undefined,
+        event: p.event?.event,
+    };
+}
+/**
+ * Map ECharts event parameters for a slice (pie, donut, funnel)
+ */
+export function toSliceParams(params, fallbackType) {
+    const p = raw(params);
+    return {
+        type: p.type || fallbackType,
+        componentType: p.componentType || 'series',
+        seriesIndex: p.seriesIndex,
+        seriesName: p.seriesName,
+        dataIndex: p.dataIndex,
+        name: p.name || '',
+        value: p.value,
+        percent: p.percent,
+        color: typeof p.color === 'string' ? p.color : undefined,
+        event: p.event?.event,
+    };
+}
+/**
+ * Combine a chart's mapped `onClick`/`onHover` props with its raw `events`
+ * prop into one handler map. When both handle an event, both run, the
+ * mapped handler first.
+ */
+export function chartEvents(events, mapped) {
+    const merged = { ...events };
+    for (const [name, handler] of Object.entries(mapped)) {
+        if (!handler)
+            continue;
+        const own = events?.[name];
+        merged[name] = own
+            ? (params) => {
+                handler(params);
+                own(params);
+            }
+            : handler;
+    }
+    return merged;
+}