@classic-homes/charts-svelte 0.1.38 → 0.2.0

package/dist/lib/components/base/ChartContainer.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  import type { ChartLegendPosition } from '@classic-homes/charts-core';
   import { cn } from '../../utils.js';
   import ChartSkeleton from './ChartSkeleton.svelte';
   import ChartError from './ChartError.svelte';
@@ -16,6 +17,13 @@
     onRetry?: () => void;
     class?: string;
     wrapperClass?: string;
+    /**
+     * Custom legend, rendered beside the chart rather than inside the
+     * `role="img"` element so its controls stay accessible
+     */
+    legend?: Snippet;
+    /** Where the custom legend sits (defaults to 'bottom') */
+    legendPosition?: ChartLegendPosition;
     children: Snippet;
   }
 
@@ -30,6 +38,8 @@
     onRetry,
     class: className,
     wrapperClass,
+    legend,
+    legendPosition = 'bottom',
     children,
   }: Props = $props();
 
@@ -38,21 +48,19 @@
 
   const heightStyle = $derived(typeof height === 'number' ? `${height}px` : height);
   const descriptionId = $derived(description ? `${uid}-desc` : undefined);
+
+  // The legend's DOM order follows its visual position
+  const side = $derived(legendPosition === 'left' || legendPosition === 'right');
+  const leading = $derived(legendPosition === 'top' || legendPosition === 'left');
 </script>
 
-{#if loading}
-  <ChartSkeleton {height} class={wrapperClass} />
-{:else if error}
-  <ChartError message={error} {height} {onRetry} class={wrapperClass} />
-{:else if empty}
-  <ChartEmpty message={emptyMessage} {height} class={wrapperClass} />
-{:else}
+{#snippet chart(chartClass: string)}
   <div
     role="img"
     aria-label={title}
     aria-describedby={descriptionId}
     data-testid="chart-container"
-    class={cn('rounded-lg border border-border bg-card', wrapperClass)}
+    class={chartClass}
   >
     {#if description}
       <span id={descriptionId} class="sr-only">{description}</span>
@@ -61,4 +69,35 @@
       {@render children()}
     </div>
   </div>
+{/snippet}
+
+{#snippet legendArea(content: Snippet)}
+  <div
+    data-testid="chart-legend"
+    class={cn('flex shrink-0 p-2', side ? 'items-center' : 'justify-center')}
+  >
+    {@render content()}
+  </div>
+{/snippet}
+
+{#if loading}
+  <ChartSkeleton {height} class={wrapperClass} />
+{:else if error}
+  <ChartError message={error} {height} {onRetry} class={wrapperClass} />
+{:else if empty}
+  <ChartEmpty message={emptyMessage} {height} class={wrapperClass} />
+{:else if legend}
+  <div
+    class={cn(
+      'flex rounded-lg border border-border bg-card',
+      side ? 'flex-row' : 'flex-col',
+      wrapperClass
+    )}
+  >
+    {#if leading}{@render legendArea(legend)}{/if}
+    {@render chart('min-h-0 min-w-0 flex-1')}
+    {#if !leading}{@render legendArea(legend)}{/if}
+  </div>
+{:else}
+  {@render chart(cn('rounded-lg border border-border bg-card', wrapperClass))}
 {/if}

package/dist/lib/components/base/ChartContainer.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { Snippet } from 'svelte';
+import type { ChartLegendPosition } from '@classic-homes/charts-core';
 interface Props {
     title: string;
     description?: string;
@@ -10,6 +11,13 @@ interface Props {
     onRetry?: () => void;
     class?: string;
     wrapperClass?: string;
+    /**
+     * Custom legend, rendered beside the chart rather than inside the
+     * `role="img"` element so its controls stay accessible
+     */
+    legend?: Snippet;
+    /** Where the custom legend sits (defaults to 'bottom') */
+    legendPosition?: ChartLegendPosition;
     children: Snippet;
 }
 declare const ChartContainer: import("svelte").Component<Props, {}, "">;

package/dist/lib/components/base/ChartLegend.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import type { LegendRenderProps } from '@classic-homes/charts-core';
+  import { cn } from '../../utils.js';
+
+  interface Props
+    extends
+      Pick<LegendRenderProps, 'items' | 'toggle'>,
+      Partial<Omit<LegendRenderProps, 'items' | 'toggle'>> {
+    /** Lay items out in a column (defaults to vertical for left/right positions) */
+    orientation?: 'horizontal' | 'vertical';
+    /** Additional classes for the list */
+    class?: string;
+  }
+
+  let {
+    items,
+    toggle,
+    position = 'bottom',
+    chartTitle,
+    orientation,
+    class: className,
+  }: Props = $props();
+
+  const vertical = $derived(
+    (orientation ?? (position === 'left' || position === 'right' ? 'vertical' : 'horizontal')) ===
+      'vertical'
+  );
+</script>
+
+<!--
+  Accessible HTML legend for use with a chart's `renderLegend` snippet. Each
+  item is a toggle button that shows or hides its series.
+-->
+<ul
+  aria-label={chartTitle ? `${chartTitle} legend` : 'Chart legend'}
+  class={cn('flex gap-1 text-sm', vertical ? 'flex-col' : 'flex-wrap justify-center', className)}
+>
+  {#each items as item (item.name)}
+    <li>
+      <button
+        type="button"
+        aria-pressed={item.visible}
+        onclick={() => toggle(item.name)}
+        class={cn(
+          'inline-flex items-center gap-2 rounded-md px-2 py-1 text-left hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          item.visible ? 'text-foreground' : 'text-muted-foreground line-through'
+        )}
+      >
+        <span
+          aria-hidden="true"
+          class="h-3 w-3 shrink-0 rounded-sm"
+          style:background-color={item.color}
+          style:opacity={item.visible ? 1 : 0.35}
+        ></span>
+        {item.name}
+      </button>
+    </li>
+  {/each}
+</ul>

package/dist/lib/components/base/ChartLegend.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { LegendRenderProps } from '@classic-homes/charts-core';
+interface Props extends Pick<LegendRenderProps, 'items' | 'toggle'>, Partial<Omit<LegendRenderProps, 'items' | 'toggle'>> {
+    /** Lay items out in a column (defaults to vertical for left/right positions) */
+    orientation?: 'horizontal' | 'vertical';
+    /** Additional classes for the list */
+    class?: string;
+}
+declare const ChartLegend: import("svelte").Component<Props, {}, "">;
+type ChartLegend = ReturnType<typeof ChartLegend>;
+export default ChartLegend;

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

@@ -2,12 +2,15 @@ export { default as ChartContainer } from './ChartContainer.svelte';
 export { default as ChartSkeleton } from './ChartSkeleton.svelte';
 export { default as ChartError } from './ChartError.svelte';
 export { default as ChartEmpty } from './ChartEmpty.svelte';
+export { default as ChartLegend } from './ChartLegend.svelte';
 import type { ComponentProps } from 'svelte';
 import type ChartContainer from './ChartContainer.svelte';
 import type ChartSkeleton from './ChartSkeleton.svelte';
 import type ChartError from './ChartError.svelte';
 import type ChartEmpty from './ChartEmpty.svelte';
+import type ChartLegend from './ChartLegend.svelte';
 export type ChartContainerProps = ComponentProps<typeof ChartContainer>;
 export type ChartSkeletonProps = ComponentProps<typeof ChartSkeleton>;
 export type ChartErrorProps = ComponentProps<typeof ChartError>;
 export type ChartEmptyProps = ComponentProps<typeof ChartEmpty>;
+export type ChartLegendProps = ComponentProps<typeof ChartLegend>;

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

@@ -2,3 +2,4 @@ export { default as ChartContainer } from './ChartContainer.svelte';
 export { default as ChartSkeleton } from './ChartSkeleton.svelte';
 export { default as ChartError } from './ChartError.svelte';
 export { default as ChartEmpty } from './ChartEmpty.svelte';
+export { default as ChartLegend } from './ChartLegend.svelte';

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

@@ -11,10 +11,26 @@
   import type { EChartsOption } from 'echarts';
 
   import type { AreaChartProps, DataPointEventParams } from '@classic-homes/charts-core';
-  import { colorWithAlpha, getChartColors } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    colorWithAlpha,
+    getChartColors,
+    hasPointLabels,
+    gridInset,
+    mergeChartOption,
+    seriesLabelLookup,
+    withPointLabels,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.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
@@ -27,7 +43,7 @@
     CanvasRenderer,
   ]);
 
-  interface Props extends Omit<AreaChartProps, 'class'> {
+  interface Props extends Omit<AreaChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -47,6 +63,16 @@
     smooth = false,
     stacked = false,
     gradient = true,
+    showLabels = false,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -61,15 +87,21 @@
   const option: EChartsOption = $derived.by(() => {
     if (isEmpty) return {};
 
-    return {
-      grid: {
-        left: '3%',
-        right: '4%',
-        bottom: '3%',
-        containLabel: true,
-      },
-      tooltip: showTooltip
-        ? {
+    const getLabel = seriesLabelLookup(data.series);
+    // ECharts hides line labels along with the symbol
+    const showSymbol = showLabels || hasPointLabels(data.series);
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
             trigger: 'axis',
             axisPointer: {
               type: 'cross',
@@ -77,51 +109,69 @@
                 backgroundColor: chartColors.axisPointerLabel,
               },
             },
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: tooltipValueFormatter,
+            getLabel,
           }
-        : undefined,
-      legend: showLegend
-        ? {
-            data: data.series.map((s) => s.name),
-            bottom: 0,
-          }
-        : undefined,
-      xAxis: {
-        type: 'category',
-        boundaryGap: false,
-        data: data.categories,
-      },
-      yAxis: {
-        type: 'value',
-        splitLine: {
-          show: showGrid,
-        },
-      },
-      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: series.data,
-          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,
-          emphasis: {
-            focus: 'series',
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          legendConfig,
+          { show: showLegend, custom: !!renderLegend }
+        ),
+        xAxis: buildAxis(
+          {
+            type: 'category',
+            boundaryGap: false,
+            data: data.categories,
           },
-          showSymbol: false,
-        };
-      }),
-    };
+          xAxisConfig
+        ),
+        yAxis: buildAxis(
+          {
+            type: 'value',
+            splitLine: {
+              show: showGrid,
+            },
+          },
+          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,
+          };
+        }),
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
@@ -131,6 +181,16 @@
         : undefined)
   );
 
+  // 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,
@@ -138,6 +198,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -156,6 +217,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -165,6 +230,8 @@
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  legend={renderLegend ? customLegend : undefined}
+  legendPosition={legendConfig?.position}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

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

@@ -1,5 +1,6 @@
 import type { AreaChartProps } from '@classic-homes/charts-core';
-interface Props extends Omit<AreaChartProps, 'class'> {
+import { type CustomLegendProps } from '../../composables/useChartLegend.svelte.js';
+interface Props extends Omit<AreaChartProps, 'class'>, CustomLegendProps {
     class?: string;
 }
 declare const AreaChart: import("svelte").Component<Props, {}, "">;

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

@@ -11,10 +11,25 @@
   import type { EChartsOption } from 'echarts';
 
   import type { BarChartProps, DataPointEventParams } from '@classic-homes/charts-core';
-  import { generateBarChartDescription } from '@classic-homes/charts-core';
+  import {
+    buildAxis,
+    buildDataLabel,
+    buildLegend,
+    buildTooltip,
+    generateBarChartDescription,
+    getChartColors,
+    gridInset,
+    mergeChartOption,
+    seriesLabelLookup,
+    withPointLabels,
+  } from '@classic-homes/charts-core';
 
   import { cn } from '../../utils.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
@@ -27,7 +42,7 @@
     CanvasRenderer,
   ]);
 
-  interface Props extends Omit<BarChartProps, 'class'> {
+  interface Props extends Omit<BarChartProps, 'class'>, CustomLegendProps {
     class?: string;
   }
 
@@ -47,6 +62,15 @@
     orientation = 'vertical',
     stacked = false,
     showValues = false,
+    labelFormatter,
+    xAxisConfig,
+    yAxisConfig,
+    tooltipFormatter,
+    tooltipValueFormatter,
+    legend: legendConfig,
+    renderLegend,
+    onLegendChange,
+    option: optionOverride,
     onClick,
     class: className,
   }: Props = $props();
@@ -75,52 +99,77 @@
       },
     };
 
-    return {
-      grid: {
-        left: '3%',
-        right: '4%',
-        bottom: '3%',
-        containLabel: true,
-      },
-      tooltip: showTooltip
-        ? {
+    const getLabel = seriesLabelLookup(data.series);
+
+    return mergeChartOption(
+      {
+        grid: {
+          left: '3%',
+          right: '4%',
+          bottom: '3%',
+          containLabel: true,
+          ...gridInset(legendConfig, showLegend && !renderLegend, xAxisConfig, yAxisConfig),
+        },
+        tooltip: buildTooltip(
+          {
             trigger: 'axis',
             axisPointer: {
               type: 'shadow',
             },
+          },
+          {
+            show: showTooltip,
+            formatter: tooltipFormatter,
+            valueFormatter: tooltipValueFormatter,
+            getLabel,
           }
-        : undefined,
-      legend: showLegend
-        ? {
-            data: data.series.map((s) => s.name),
-            bottom: 0,
-          }
-        : undefined,
-      xAxis: isHorizontal ? valueAxis : categoryAxis,
-      yAxis: isHorizontal ? categoryAxis : valueAxis,
-      series: data.series.map((series) => ({
-        name: series.name,
-        type: 'bar',
-        data: series.data,
-        stack: stacked ? 'Total' : undefined,
-        itemStyle: series.color ? { color: series.color } : undefined,
-        label: showValues
-          ? {
+        ),
+        legend: buildLegend(
+          data.series.map((s) => s.name),
+          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,
-        emphasis: {
-          focus: 'series',
-        },
-      })),
-    };
+            },
+            undefined,
+            { show: showValues, formatter: labelFormatter, getLabel }
+          ),
+          emphasis: {
+            focus: 'series',
+          },
+        })),
+      } as EChartsOption,
+      optionOverride
+    );
   });
 
   const accessibilityDescription = $derived(
     description || (!isEmpty ? generateBarChartDescription(title, data) : undefined)
   );
 
+  // 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,
@@ -128,6 +177,7 @@
     animation: () => animation,
     isEmpty: () => isEmpty,
     onReady: (instance) => {
+      legend.attach(instance);
       if (onClick) {
         instance.on('click', (params) => {
           onClick({
@@ -146,6 +196,10 @@
   });
 </script>
 
+{#snippet customLegend()}
+  {@render renderLegend?.(legend.renderProps)}
+{/snippet}
+
 <ChartContainer
   {title}
   description={accessibilityDescription}
@@ -155,6 +209,8 @@
   empty={isEmpty}
   {emptyMessage}
   class={cn(className)}
+  legend={renderLegend ? customLegend : undefined}
+  legendPosition={legendConfig?.position}
 >
   <div bind:this={chart.container} class="h-full w-full"></div>
 </ChartContainer>

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

@@ -1,5 +1,6 @@
 import type { BarChartProps } from '@classic-homes/charts-core';
-interface Props extends Omit<BarChartProps, 'class'> {
+import { type CustomLegendProps } from '../../composables/useChartLegend.svelte.js';
+interface Props extends Omit<BarChartProps, 'class'>, CustomLegendProps {
     class?: string;
 }
 declare const BarChart: import("svelte").Component<Props, {}, "">;