@classic-homes/charts-svelte 0.2.0 → 0.3.1

package/README.md

@@ -0,0 +1,50 @@
+# @classic-homes/charts-svelte
+
+Svelte ECharts components for the Classic Theme design system. Charts pick up the Classic light and dark themes from `@classic-homes/charts-core`.
+
+## Installation
+
+```bash
+npm install @classic-homes/charts-svelte echarts svelte
+```
+
+Peer dependencies: `echarts@^5.5.0`, `svelte@^5.20.0`.
+
+## Quick Start
+
+```svelte
+<script lang="ts">
+  import { LineChart } from '@classic-homes/charts-svelte';
+
+  const data = {
+    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
+    series: [
+      { name: '2024', data: [120, 132, 101, 134, 90, 230] },
+      { name: '2025', data: [220, 182, 191, 234, 290, 330] },
+    ],
+  };
+</script>
+
+<LineChart title="Monthly Revenue" {data} smooth height={400} />
+```
+
+## Exports
+
+- **Charts**: `LineChart`, `BarChart`, `PieChart`, `AreaChart`, `ScatterChart`, `DonutChart`, `RadarChart`, `FunnelChart`, `GaugeChart`, `HeatmapChart`, `TreemapChart`, `CandlestickChart`, `SankeyChart`, `ComboChart`, `DotPlotChart`, `BulletChart`, `HistogramChart`, `BoxPlotChart`, `WaterfallChart`
+- **Stat helpers**: `Sparkline`, `StatCard`, `StatGroup`
+- **Base components**: `ChartContainer`, `ChartSkeleton`, `ChartError`, `ChartEmpty`, `ChartLegend`, `ChartDataTable`
+- **Composables**: `useChart`, `useChartTheme`, `useChartResize`, `useChartLegend`, `useReducedMotion`, `registerClassicThemes`, `registerEchartsModules`, `exportChartImage`
+- **Data helpers** (from `@classic-homes/charts-core`): `fromRecords`, `toSliceData`, `binValues`, `boxplotStats`, `waterfallLayout`, `formatValue`, `computeDelta`, `tableToCsv`, `downloadCsv`
+
+Chart data and option types are exported from the package root, and also from `@classic-homes/charts-core/types`.
+
+```svelte
+<script lang="ts">
+  import { ChartSkeleton, DonutChart, type PieSliceData } from '@classic-homes/charts-svelte';
+</script>
+```
+
+## Related Packages
+
+- `@classic-homes/charts-core`: shared themes, types, and utilities
+- `@classic-homes/charts-react`: React equivalents for the core and extended charts

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

@@ -1,15 +1,31 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
-  import type { ChartLegendPosition } from '@classic-homes/charts-core';
+  import {
+    chartFilename,
+    downloadCsv,
+    downloadFile,
+    type ChartDataTable as ChartDataTableData,
+    type ChartExportConfig,
+    type ChartLegendPosition,
+  } from '@classic-homes/charts-core';
   import { cn } from '../../utils.js';
   import ChartSkeleton from './ChartSkeleton.svelte';
   import ChartError from './ChartError.svelte';
   import ChartEmpty from './ChartEmpty.svelte';
+  import ChartDataTable from './ChartDataTable.svelte';
 
   interface Props {
     title: string;
     description?: string;
     height?: number | string;
+    /** Minimum height in pixels */
+    minHeight?: number;
+    /** Maximum height in pixels */
+    maxHeight?: number;
+    /**
+     * Loading. With no data yet this shows a skeleton; over an existing chart
+     * it dims the chart instead, keeping its zoom and legend state.
+     */
     loading?: boolean;
     error?: string | null;
     empty?: boolean;
@@ -24,6 +40,16 @@
     legend?: Snippet;
     /** Where the custom legend sits (defaults to 'bottom') */
     legendPosition?: ChartLegendPosition;
+    /** The chart's data as a table, for screen readers, "Show data" and CSV export */
+    dataTable?: ChartDataTableData;
+    /** 'sr-only' renders the table for screen readers, true adds a visible toggle */
+    showDataTable?: boolean | 'sr-only';
+    /** Formats values in the data table */
+    format?: (value: number) => string;
+    /** Show download buttons */
+    exportable?: boolean | ChartExportConfig;
+    /** Renders the chart to an image data URL, for the PNG download */
+    exportImage?: () => string | null;
     children: Snippet;
   }
 
@@ -31,6 +57,8 @@
     title,
     description,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
     empty,
@@ -40,6 +68,11 @@
     wrapperClass,
     legend,
     legendPosition = 'bottom',
+    dataTable,
+    showDataTable = 'sr-only',
+    format,
+    exportable,
+    exportImage,
     children,
   }: Props = $props();
 
@@ -48,10 +81,39 @@
 
   const heightStyle = $derived(typeof height === 'number' ? `${height}px` : height);
   const descriptionId = $derived(description ? `${uid}-desc` : undefined);
+  const tableId = `${uid}-table`;
 
   // The legend's DOM order follows its visual position
   const side = $derived(legendPosition === 'left' || legendPosition === 'right');
   const leading = $derived(legendPosition === 'top' || legendPosition === 'left');
+
+  const exportConfig = $derived<ChartExportConfig | undefined>(
+    exportable ? (exportable === true ? {} : exportable) : undefined
+  );
+  const canExportImage = $derived(!!exportConfig && exportConfig.image !== false && !!exportImage);
+  const canExportCsv = $derived(!!exportConfig && exportConfig.csv !== false && !!dataTable);
+  const filename = $derived(exportConfig?.filename ?? chartFilename(title));
+
+  // A hidden table of thousands of rows (a dense scatter or heatmap) costs
+  // more than it helps; "Show data" and CSV export still offer the data
+  const SR_TABLE_MAX_ROWS = 500;
+
+  let tableOpen = $state(false);
+  const toggleTable = $derived(showDataTable === true && !!dataTable);
+  const toolbar = $derived(canExportImage || canExportCsv || toggleTable);
+  const framed = $derived(!!legend || toolbar);
+
+  function downloadImage() {
+    const url = exportImage?.();
+    if (url) downloadFile(url, `${filename}.png`);
+  }
+
+  function downloadData() {
+    if (dataTable) downloadCsv(dataTable, filename);
+  }
+
+  const buttonClass =
+    'rounded-md px-2 py-1 text-xs font-medium text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring';
 </script>
 
 {#snippet chart(chartClass: string)}
@@ -59,15 +121,31 @@
     role="img"
     aria-label={title}
     aria-describedby={descriptionId}
+    aria-busy={loading || undefined}
     data-testid="chart-container"
-    class={chartClass}
+    class={cn('relative', chartClass)}
   >
     {#if description}
       <span id={descriptionId} class="sr-only">{description}</span>
     {/if}
-    <div class={cn('h-full w-full', className)} style:height={heightStyle}>
+    <div
+      class={cn('h-full w-full', className)}
+      style:height={heightStyle}
+      style:min-height={minHeight !== undefined ? `${minHeight}px` : undefined}
+      style:max-height={maxHeight !== undefined ? `${maxHeight}px` : undefined}
+    >
       {@render children()}
     </div>
+    {#if loading}
+      <div
+        data-testid="chart-loading-overlay"
+        class="absolute inset-0 flex items-center justify-center rounded-lg bg-card/60"
+      >
+        <span
+          class="h-6 w-6 animate-spin rounded-full border-2 border-muted-foreground/30 border-t-muted-foreground motion-reduce:animate-none"
+        ></span>
+      </div>
+    {/if}
   </div>
 {/snippet}
 
@@ -80,24 +158,73 @@
   </div>
 {/snippet}
 
-{#if loading}
-  <ChartSkeleton {height} class={wrapperClass} />
+{#snippet srTable()}
+  {#if dataTable && showDataTable === 'sr-only' && dataTable.rows.length <= SR_TABLE_MAX_ROWS}
+    <ChartDataTable table={dataTable} caption={`${title} data`} {format} srOnly />
+  {/if}
+{/snippet}
+
+{#if loading && empty}
+  <ChartSkeleton {height} label={`Loading ${title}`} class={wrapperClass} />
 {:else if error}
   <ChartError message={error} {height} {onRetry} class={wrapperClass} />
 {:else if empty}
   <ChartEmpty message={emptyMessage} {height} class={wrapperClass} />
-{:else if legend}
+{:else if framed}
   <div
-    class={cn(
-      'flex rounded-lg border border-border bg-card',
-      side ? 'flex-row' : 'flex-col',
-      wrapperClass
-    )}
+    data-testid="chart-frame"
+    class={cn('flex flex-col rounded-lg border border-border bg-card', wrapperClass)}
   >
-    {#if leading}{@render legendArea(legend)}{/if}
-    {@render chart('min-h-0 min-w-0 flex-1')}
-    {#if !leading}{@render legendArea(legend)}{/if}
+    {#if toolbar}
+      <div data-testid="chart-toolbar" class="flex justify-end gap-1 px-2 pt-2 print:hidden">
+        {#if toggleTable}
+          <button
+            type="button"
+            class={buttonClass}
+            aria-expanded={tableOpen}
+            aria-controls={tableId}
+            onclick={() => (tableOpen = !tableOpen)}
+          >
+            {tableOpen ? 'Hide data' : 'Show data'}
+          </button>
+        {/if}
+        {#if canExportImage}
+          <button
+            type="button"
+            class={buttonClass}
+            aria-label={`Download ${title} as PNG`}
+            onclick={downloadImage}
+          >
+            PNG
+          </button>
+        {/if}
+        {#if canExportCsv}
+          <button
+            type="button"
+            class={buttonClass}
+            aria-label={`Download ${title} data as CSV`}
+            onclick={downloadData}
+          >
+            CSV
+          </button>
+        {/if}
+      </div>
+    {/if}
+    <div class={cn('flex min-h-0 flex-1', side ? 'flex-row' : 'flex-col')}>
+      {#if legend && leading}{@render legendArea(legend)}{/if}
+      {@render chart('min-h-0 min-w-0 flex-1')}
+      {#if legend && !leading}{@render legendArea(legend)}{/if}
+    </div>
+    {#if toggleTable && dataTable}
+      <div id={tableId} hidden={!tableOpen} class="border-t border-border p-2">
+        {#if tableOpen}
+          <ChartDataTable table={dataTable} caption={`${title} data`} {format} />
+        {/if}
+      </div>
+    {/if}
+    {@render srTable()}
   </div>
 {:else}
   {@render chart(cn('rounded-lg border border-border bg-card', wrapperClass))}
+  {@render srTable()}
 {/if}

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

@@ -1,9 +1,17 @@
 import type { Snippet } from 'svelte';
-import type { ChartLegendPosition } from '@classic-homes/charts-core';
+import { type ChartDataTable as ChartDataTableData, type ChartExportConfig, type ChartLegendPosition } from '@classic-homes/charts-core';
 interface Props {
     title: string;
     description?: string;
     height?: number | string;
+    /** Minimum height in pixels */
+    minHeight?: number;
+    /** Maximum height in pixels */
+    maxHeight?: number;
+    /**
+     * Loading. With no data yet this shows a skeleton; over an existing chart
+     * it dims the chart instead, keeping its zoom and legend state.
+     */
     loading?: boolean;
     error?: string | null;
     empty?: boolean;
@@ -18,6 +26,16 @@ interface Props {
     legend?: Snippet;
     /** Where the custom legend sits (defaults to 'bottom') */
     legendPosition?: ChartLegendPosition;
+    /** The chart's data as a table, for screen readers, "Show data" and CSV export */
+    dataTable?: ChartDataTableData;
+    /** 'sr-only' renders the table for screen readers, true adds a visible toggle */
+    showDataTable?: boolean | 'sr-only';
+    /** Formats values in the data table */
+    format?: (value: number) => string;
+    /** Show download buttons */
+    exportable?: boolean | ChartExportConfig;
+    /** Renders the chart to an image data URL, for the PNG download */
+    exportImage?: () => string | null;
     children: Snippet;
 }
 declare const ChartContainer: import("svelte").Component<Props, {}, "">;

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

@@ -0,0 +1,59 @@
+<script lang="ts">
+  import { formatTableCell, type ChartDataTable } from '@classic-homes/charts-core';
+  import { cn } from '../../utils.js';
+
+  interface Props {
+    /** Table contents */
+    table: ChartDataTable;
+    /** Caption naming the chart the data belongs to */
+    caption: string;
+    /** Formats 'value' columns */
+    format?: (value: number) => string;
+    /** Hide visually, leaving the table to screen readers */
+    srOnly?: boolean;
+    class?: string;
+  }
+
+  let { table, caption, format, srOnly = false, class: className }: Props = $props();
+</script>
+
+<div
+  data-testid="chart-data-table"
+  class={cn(srOnly ? 'sr-only' : 'max-h-80 overflow-auto', className)}
+>
+  <table class="w-full border-collapse text-sm">
+    <caption class={srOnly ? undefined : 'sr-only'}>{caption}</caption>
+    <thead>
+      <tr>
+        {#each table.headers as header, column (column)}
+          <th
+            scope="col"
+            class={cn(
+              'sticky top-0 border-b border-border bg-card px-3 py-2 font-medium text-muted-foreground',
+              column === 0 ? 'text-left' : 'text-right'
+            )}
+          >
+            {header}
+          </th>
+        {/each}
+      </tr>
+    </thead>
+    <tbody>
+      {#each table.rows as row, rowIndex (rowIndex)}
+        <tr class="border-b border-border last:border-0">
+          {#each row as cell, column (column)}
+            {#if column === 0}
+              <th scope="row" class="px-3 py-1.5 text-left font-normal text-foreground">
+                {formatTableCell(table, cell, column, format)}
+              </th>
+            {:else}
+              <td class="px-3 py-1.5 text-right tabular-nums text-foreground">
+                {formatTableCell(table, cell, column, format)}
+              </td>
+            {/if}
+          {/each}
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>

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

@@ -0,0 +1,15 @@
+import { type ChartDataTable } from '@classic-homes/charts-core';
+interface Props {
+    /** Table contents */
+    table: ChartDataTable;
+    /** Caption naming the chart the data belongs to */
+    caption: string;
+    /** Formats 'value' columns */
+    format?: (value: number) => string;
+    /** Hide visually, leaving the table to screen readers */
+    srOnly?: boolean;
+    class?: string;
+}
+declare const ChartDataTable: import("svelte").Component<Props, {}, "">;
+type ChartDataTable = ReturnType<typeof ChartDataTable>;
+export default ChartDataTable;

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

@@ -14,6 +14,7 @@
 
 <div
   data-testid="chart-empty"
+  role="status"
   class={cn(
     'flex flex-col items-center justify-center rounded-lg border border-border bg-muted/50',
     className

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

@@ -3,20 +3,25 @@
 
   interface Props {
     height?: number | string;
+    /** Accessible name announced while loading (defaults to 'Loading chart') */
+    label?: string;
     class?: string;
   }
 
-  let { height = 400, class: className }: Props = $props();
+  let { height = 400, label = 'Loading chart', class: className }: Props = $props();
 
   const heightStyle = $derived(typeof height === 'number' ? `${height}px` : height);
 </script>
 
 <div
   data-testid="chart-skeleton"
+  role="status"
+  aria-busy="true"
+  aria-label={label}
   class={cn('animate-pulse rounded-lg border border-border bg-muted', className)}
   style:height={heightStyle}
 >
-  <div class="flex h-full flex-col p-4">
+  <div class="flex h-full flex-col p-4" aria-hidden="true">
     <!-- Title skeleton -->
     <div class="mb-4 h-5 w-1/3 rounded bg-muted-foreground/20"></div>
 

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

@@ -1,5 +1,7 @@
 interface Props {
     height?: number | string;
+    /** Accessible name announced while loading (defaults to 'Loading chart') */
+    label?: string;
     class?: string;
 }
 declare const ChartSkeleton: import("svelte").Component<Props, {}, "">;

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

@@ -3,14 +3,17 @@ 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';
+export { default as ChartDataTable } from './ChartDataTable.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';
+import type ChartDataTable from './ChartDataTable.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>;
+export type ChartDataTableProps = ComponentProps<typeof ChartDataTable>;

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

@@ -3,3 +3,4 @@ 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';
+export { default as ChartDataTable } from './ChartDataTable.svelte';