@classic-homes/charts-svelte 0.1.38 → 0.3.0

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

@@ -1,14 +1,31 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  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;
@@ -16,6 +33,23 @@
     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;
+    /** 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;
   }
 
@@ -23,6 +57,8 @@
     title,
     description,
     height = 400,
+    minHeight,
+    maxHeight,
     loading,
     error,
     empty,
@@ -30,6 +66,13 @@
     onRetry,
     class: className,
     wrapperClass,
+    legend,
+    legendPosition = 'bottom',
+    dataTable,
+    showDataTable = 'sr-only',
+    format,
+    exportable,
+    exportImage,
     children,
   }: Props = $props();
 
@@ -38,27 +81,150 @@
 
   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>
 
-{#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}
+    aria-busy={loading || undefined}
     data-testid="chart-container"
-    class={cn('rounded-lg border border-border bg-card', wrapperClass)}
+    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}
+
+{#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}
+
+{#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 framed}
+  <div
+    data-testid="chart-frame"
+    class={cn('flex flex-col rounded-lg border border-border bg-card', wrapperClass)}
+  >
+    {#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,8 +1,17 @@
 import type { Snippet } from 'svelte';
+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;
@@ -10,6 +19,23 @@ 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;
+    /** 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/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/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

@@ -2,12 +2,18 @@ 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';
+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

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