@classic-homes/charts-svelte 0.2.0 → 0.3.0

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

@@ -0,0 +1,226 @@
+<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 { HistogramChartProps } from '@classic-homes/charts-core';
+  import {
+    binValues,
+    buildAxis,
+    buildDataLabel,
+    buildTooltip,
+    escapeHtml,
+    generateHistogramDescription,
+    getChartColors,
+    gridInset,
+    histogramTable,
+    mergeChartOption,
+    resolveValueFormatter,
+  } 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<HistogramChartProps, 'class'> {
+    class?: string;
+  }
+
+  let {
+    title,
+    description,
+    values,
+    bins,
+    binWidth,
+    seriesName = 'Count',
+    color,
+    height = 400,
+    minHeight,
+    maxHeight,
+    loading,
+    error,
+    onRetry,
+    emptyMessage,
+    theme = 'auto',
+    animation = true,
+    showTooltip = true,
+    showGrid = true,
+    showLabels = false,
+    valueFormat,
+    locale,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    referenceLines,
+    referenceBands,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    option: optionOverride,
+    onReady,
+    events,
+    showDataTable,
+    exportable,
+    patterns,
+    onClick,
+    class: className,
+  }: Props = $props();
+
+  // `valueFormat` writes the bucket bounds; counts are plain numbers
+  const boundFormat = $derived(resolveValueFormatter(valueFormat, locale));
+
+  const buckets = $derived(binValues(values ?? [], { bins, binWidth, format: boundFormat }));
+  const total = $derived(buckets.reduce((sum, bucket) => sum + bucket.count, 0));
+
+  const isEmpty = $derived(!buckets.length || total === 0);
+
+  // 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 series: Record<string, unknown> = {
+      name: seriesName,
+      type: 'bar',
+      // Adjacent buckets touch: a histogram's bars are a continuous range
+      barCategoryGap: '2%',
+      // Lift the theme's bar width cap so buckets fill their range
+      barMaxWidth: 1000,
+      data: buckets.map((bucket) => bucket.count),
+      itemStyle: { color: color ?? chartColors.series[0], borderRadius: [2, 2, 0, 0] },
+      label: buildDataLabel({ show: true, position: 'top' }, undefined, {
+        show: showLabels,
+        formatter: labelFormatter,
+      }),
+    };
+
+    // Reference lines mark a count (e.g. a capacity), not a bucket
+    if (referenceLines?.length || referenceBands?.length) {
+      series.markLine = referenceLines?.length
+        ? {
+            silent: true,
+            symbol: 'none',
+            animation: false,
+            data: referenceLines.map((line) => ({
+              ...(typeof line.value === 'number'
+                ? { yAxis: line.value }
+                : { type: line.value, valueDim: 'y' }),
+              lineStyle: {
+                type: line.style ?? 'dashed',
+                color: line.color ?? chartColors.reference,
+              },
+              label: {
+                position: 'insideEndTop',
+                color: line.color ?? chartColors.reference,
+                formatter: line.label ?? '{c}',
+              },
+            })),
+          }
+        : undefined;
+      series.markArea = referenceBands?.length
+        ? {
+            silent: true,
+            data: referenceBands.map((band) => [
+              {
+                yAxis: band.from,
+                name: band.label,
+                itemStyle: { color: band.color ?? chartColors.referenceBand },
+              },
+              { yAxis: band.to },
+            ]),
+          }
+        : undefined;
+    }
+
+    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;
+                marker?: string;
+              }[];
+              const bucket = buckets[list[0]?.dataIndex ?? 0];
+              if (!bucket) return '';
+              const share = total ? ((bucket.count / total) * 100).toFixed(1) : '0';
+              const count = tooltipValueFormatter
+                ? tooltipValueFormatter(bucket.count)
+                : bucket.count.toLocaleString(locale ?? 'en-US');
+              return `${escapeHtml(bucket.label)}<br/>${list[0]?.marker ?? ''}${escapeHtml(seriesName)}: <strong>${escapeHtml(count)}</strong> (${share}%)`;
+            },
+          },
+          { show: showTooltip, formatter: tooltipFormatter }
+        ),
+        xAxis: buildAxis(
+          {
+            type: 'category',
+            data: buckets.map((bucket) => bucket.label),
+            axisTick: { alignWithLabel: true },
+          },
+          xAxisConfig
+        ),
+        yAxis: buildAxis(
+          { type: 'value', minInterval: 1, splitLine: { show: showGrid } },
+          yAxisConfig
+        ),
+        series: [series],
+      } as EChartsOption,
+      optionOverride
+    );
+  });
+
+  const accessibilityDescription = $derived(
+    description || (!isEmpty ? generateHistogramDescription(title, buckets, total) : undefined)
+  );
+
+  const dataTable = $derived(isEmpty ? undefined : histogramTable(buckets));
+
+  // 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'))),
+      }),
+    onCreated: () => onReady,
+  });
+</script>
+
+<ChartContainer
+  {title}
+  description={accessibilityDescription}
+  {height}
+  {minHeight}
+  {maxHeight}
+  {loading}
+  {error}
+  {onRetry}
+  empty={isEmpty}
+  {emptyMessage}
+  class={cn(className)}
+  {dataTable}
+  {showDataTable}
+  {exportable}
+  exportImage={chart.exportImage}
+>
+  <div bind:this={chart.container} class="h-full w-full"></div>
+</ChartContainer>

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

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

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

@@ -0,0 +1,181 @@
+<script lang="ts">
+  import type { SparklineProps } from '@classic-homes/charts-core';
+  import { cn } from '../../utils.js';
+
+  let {
+    data,
+    variant = 'line',
+    width = '100%',
+    height = 32,
+    color,
+    showLastPoint,
+    referenceLine,
+    min,
+    max,
+    label,
+    class: className,
+  }: SparklineProps = $props();
+
+  // Drawn in a 100-wide viewBox stretched to the element's width, with the
+  // real pixel height, so strokes keep their width at any size
+  const VIEW_WIDTH = 100;
+  const PAD = 2;
+
+  const values = $derived(
+    (data ?? []).map((value) =>
+      typeof value === 'number' && Number.isFinite(value) ? value : null
+    )
+  );
+  const present = $derived(values.filter((value): value is number => value !== null));
+
+  const scale = $derived.by(() => {
+    let lo = min ?? Math.min(...present, variant === 'bar' ? 0 : Infinity);
+    let hi = max ?? Math.max(...present);
+    if (!Number.isFinite(lo) || !Number.isFinite(hi)) return null;
+    if (hi === lo) {
+      // A flat series sits in the middle
+      lo -= 1;
+      hi += 1;
+    }
+    return { lo, hi };
+  });
+
+  const y = (value: number) => {
+    if (!scale) return height / 2;
+    const ratio = (value - scale.lo) / (scale.hi - scale.lo);
+    return PAD + (1 - Math.min(Math.max(ratio, 0), 1)) * (height - PAD * 2);
+  };
+  const x = (index: number) =>
+    values.length <= 1 ? VIEW_WIDTH / 2 : (index / (values.length - 1)) * VIEW_WIDTH;
+
+  // Runs of consecutive present values; gaps break the line
+  const segments = $derived.by(() => {
+    const runs: [number, number][][] = [];
+    let run: [number, number][] = [];
+    values.forEach((value, index) => {
+      if (value === null) {
+        if (run.length) runs.push(run);
+        run = [];
+      } else {
+        run.push([x(index), y(value)]);
+      }
+    });
+    if (run.length) runs.push(run);
+    return runs;
+  });
+
+  const linePath = $derived(
+    segments
+      .map((run) =>
+        run.map(([px, py], i) => `${i ? 'L' : 'M'}${px.toFixed(2)},${py.toFixed(2)}`).join('')
+      )
+      .join('')
+  );
+
+  const baseline = $derived(scale ? y(Math.max(scale.lo, Math.min(0, scale.hi))) : height - PAD);
+
+  const areaPath = $derived(
+    segments
+      .map((run) => {
+        if (run.length < 2) return '';
+        const top = run.map(([px, py], i) => `${i ? 'L' : 'M'}${px.toFixed(2)},${py.toFixed(2)}`);
+        const first = run[0][0].toFixed(2);
+        const last = run[run.length - 1][0].toFixed(2);
+        return `${top.join('')}L${last},${baseline.toFixed(2)}L${first},${baseline.toFixed(2)}Z`;
+      })
+      .join('')
+  );
+
+  const bars = $derived.by(() => {
+    const slot = VIEW_WIDTH / Math.max(values.length, 1);
+    return values.flatMap((value, index) => {
+      if (value === null) return [];
+      const top = Math.min(y(value), baseline);
+      return [
+        {
+          x: index * slot + slot * 0.15,
+          width: slot * 0.7,
+          y: top,
+          height: Math.max(Math.abs(baseline - y(value)), 1),
+        },
+      ];
+    });
+  });
+
+  const lastIndex = $derived.by(() => {
+    for (let index = values.length - 1; index >= 0; index--) {
+      if (values[index] !== null) return index;
+    }
+    return -1;
+  });
+  const showDot = $derived((showLastPoint ?? variant !== 'bar') && lastIndex !== -1);
+
+  const referenceY = $derived.by(() => {
+    if (referenceLine === undefined || !present.length) return null;
+    const value =
+      referenceLine === 'average'
+        ? present.reduce((sum, v) => sum + v, 0) / present.length
+        : referenceLine;
+    return y(value);
+  });
+
+  const widthStyle = $derived(typeof width === 'number' ? `${width}px` : width);
+</script>
+
+<span
+  data-testid="sparkline"
+  class={cn('relative inline-block align-middle text-chart-1', className)}
+  style:width={widthStyle}
+  style:height="{height}px"
+  style:color
+  role={label ? 'img' : undefined}
+  aria-label={label}
+  aria-hidden={label ? undefined : 'true'}
+>
+  <svg
+    class="absolute inset-0 h-full w-full overflow-visible"
+    viewBox="0 0 {VIEW_WIDTH} {height}"
+    preserveAspectRatio="none"
+    aria-hidden="true"
+  >
+    {#if referenceY !== null}
+      <line
+        x1="0"
+        x2={VIEW_WIDTH}
+        y1={referenceY}
+        y2={referenceY}
+        class="stroke-muted-foreground"
+        stroke-width="1"
+        stroke-dasharray="3 3"
+        vector-effect="non-scaling-stroke"
+        opacity="0.6"
+      />
+    {/if}
+    {#if variant === 'bar'}
+      {#each bars as bar, index (index)}
+        <rect x={bar.x} y={bar.y} width={bar.width} height={bar.height} fill="currentColor" />
+      {/each}
+    {:else}
+      {#if variant === 'area' && areaPath}
+        <path d={areaPath} fill="currentColor" opacity="0.15" />
+      {/if}
+      <path
+        d={linePath}
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.5"
+        stroke-linejoin="round"
+        stroke-linecap="round"
+        vector-effect="non-scaling-stroke"
+      />
+    {/if}
+  </svg>
+  {#if showDot && values[lastIndex] !== null}
+    <!-- HTML, not SVG: a circle in the stretched viewBox would be an ellipse -->
+    <span
+      class="absolute h-1.5 w-1.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-current"
+      style:left="{(x(lastIndex) / VIEW_WIDTH) * 100}%"
+      style:top="{y(values[lastIndex] as number)}px"
+    ></span>
+  {/if}
+</span>

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

@@ -0,0 +1,4 @@
+import type { SparklineProps } from '@classic-homes/charts-core';
+declare const Sparkline: import("svelte").Component<SparklineProps, {}, "">;
+type Sparkline = ReturnType<typeof Sparkline>;
+export default Sparkline;

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

@@ -0,0 +1,146 @@
+<script lang="ts">
+  import type { StatCardProps } from '@classic-homes/charts-core';
+  import { computeDelta, formatValue, resolveValueFormatter } from '@classic-homes/charts-core';
+  import { cn } from '../../utils.js';
+  import Sparkline from './Sparkline.svelte';
+
+  let {
+    label,
+    value,
+    valueFormat,
+    locale = 'en-US',
+    delta,
+    hint,
+    definition,
+    href,
+    trend,
+    trendVariant = 'line',
+    tone = 'default',
+    emptyValue = '—',
+    loading = false,
+    class: className,
+  }: StatCardProps = $props();
+
+  const format = $derived(resolveValueFormatter(valueFormat, locale));
+
+  const display = $derived(
+    typeof value === 'string' ? value : formatValue(value ?? null, format, emptyValue)
+  );
+
+  const change = $derived(
+    delta
+      ? computeDelta(delta.current ?? (typeof value === 'number' ? value : null), delta.previous)
+      : null
+  );
+
+  const percentFormat = $derived(
+    new Intl.NumberFormat(locale, {
+      style: 'percent',
+      maximumFractionDigits: 1,
+      signDisplay: 'exceptZero',
+    })
+  );
+
+  const changeText = $derived.by(() => {
+    if (!change || !delta) return '';
+    const sign = change.change > 0 ? '+' : change.change < 0 ? '−' : '';
+    const absolute = `${sign}${formatValue(Math.abs(change.change), format)}`;
+    const percent = change.ratio === null ? null : percentFormat.format(change.ratio);
+    switch (delta.display ?? 'percent') {
+      case 'absolute':
+        return absolute;
+      case 'both':
+        return percent ? `${absolute} (${percent})` : absolute;
+      default:
+        // A change from zero has no percentage
+        return percent ?? absolute;
+    }
+  });
+
+  const changeTone = $derived.by(() => {
+    if (!change || change.direction === 'flat' || delta?.goodWhen === 'none') {
+      return 'text-muted-foreground';
+    }
+    const good = (delta?.goodWhen ?? 'up') === change.direction;
+    return good ? 'text-success' : 'text-destructive';
+  });
+
+  const previousText = $derived(
+    delta && typeof delta.previous === 'number' ? formatValue(delta.previous, format) : ''
+  );
+
+  const valueTone = $derived(
+    {
+      default: 'text-foreground',
+      success: 'text-success',
+      warning: 'text-warning',
+      destructive: 'text-destructive',
+    }[tone]
+  );
+</script>
+
+<svelte:element
+  this={href ? 'a' : 'div'}
+  {href}
+  data-testid="stat-card"
+  aria-busy={loading || undefined}
+  class={cn(
+    'flex flex-col rounded-lg border border-border bg-card p-4 text-card-foreground',
+    href &&
+      'hover:border-ring hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+    className
+  )}
+>
+  <div class="flex items-center gap-1 text-sm font-medium text-muted-foreground">
+    <span>{label}</span>
+    {#if definition}
+      <span class="inline-flex cursor-help" title={definition} aria-hidden="true">
+        <svg class="h-3.5 w-3.5" viewBox="0 0 20 20" fill="currentColor">
+          <path
+            fill-rule="evenodd"
+            d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7-4a1 1 0 11-2 0 1 1 0 012 0zM9 9a1 1 0 000 2v3a1 1 0 001 1h1a1 1 0 100-2v-3a1 1 0 00-1-1H9z"
+            clip-rule="evenodd"
+          />
+        </svg>
+      </span>
+      <span class="sr-only">({definition})</span>
+    {/if}
+  </div>
+
+  {#if loading}
+    <div class="mt-2 h-8 w-24 animate-pulse rounded bg-muted"></div>
+    <div class="mt-2 h-3 w-32 animate-pulse rounded bg-muted"></div>
+  {:else}
+    <div class="mt-1 flex items-end justify-between gap-3">
+      <div class="min-w-0">
+        <div class={cn('text-2xl font-semibold tabular-nums', valueTone)}>{display}</div>
+        {#if changeText}
+          <div class="mt-1 flex flex-wrap items-baseline gap-x-1 text-xs">
+            <span class={cn('font-medium tabular-nums', changeTone)}>
+              <span aria-hidden="true">
+                {change?.direction === 'up' ? '▲' : change?.direction === 'down' ? '▼' : ''}
+              </span>
+              {changeText}
+            </span>
+            <span class="text-muted-foreground">
+              {delta?.label ?? (previousText ? `vs ${previousText}` : '')}
+            </span>
+          </div>
+        {/if}
+        {#if hint}
+          <p class="mt-1 text-xs text-muted-foreground">{hint}</p>
+        {/if}
+      </div>
+      {#if trend?.length}
+        <Sparkline
+          data={trend}
+          variant={trendVariant}
+          width={96}
+          height={32}
+          class="shrink-0"
+          label={`${label} trend`}
+        />
+      {/if}
+    </div>
+  {/if}
+</svelte:element>

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

@@ -0,0 +1,4 @@
+import type { StatCardProps } from '@classic-homes/charts-core';
+declare const StatCard: import("svelte").Component<StatCardProps, {}, "">;
+type StatCard = ReturnType<typeof StatCard>;
+export default StatCard;

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

@@ -0,0 +1,35 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { cn } from '../../utils.js';
+
+  interface Props {
+    /** Columns at the widest breakpoint (defaults to 4) */
+    columns?: 2 | 3 | 4 | 5 | 6;
+    /** Accessible name for the group, e.g. 'Key metrics' */
+    label?: string;
+    class?: string;
+    children: Snippet;
+  }
+
+  let { columns = 4, label, class: className, children }: Props = $props();
+
+  // Full class names, so Tailwind's scanner finds them
+  const columnClass = $derived(
+    {
+      2: 'sm:grid-cols-2',
+      3: 'sm:grid-cols-2 lg:grid-cols-3',
+      4: 'sm:grid-cols-2 lg:grid-cols-4',
+      5: 'sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-5',
+      6: 'sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-6',
+    }[columns]
+  );
+</script>
+
+<div
+  data-testid="stat-group"
+  role={label ? 'group' : undefined}
+  aria-label={label}
+  class={cn('grid grid-cols-1 gap-4', columnClass, className)}
+>
+  {@render children()}
+</div>

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

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    /** Columns at the widest breakpoint (defaults to 4) */
+    columns?: 2 | 3 | 4 | 5 | 6;
+    /** Accessible name for the group, e.g. 'Key metrics' */
+    label?: string;
+    class?: string;
+    children: Snippet;
+}
+declare const StatGroup: import("svelte").Component<Props, {}, "">;
+type StatGroup = ReturnType<typeof StatGroup>;
+export default StatGroup;