@opendata-ai/openchart-svelte 2.0.0

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@opendata-ai/openchart-svelte",
+  "version": "2.0.0",
+  "description": "Svelte components for openchart: <Chart />, <DataTable />, <Graph />, <VizThemeProvider />",
+  "license": "Apache-2.0",
+  "author": "Riley Hilliard",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tryopendata/openchart.git",
+    "directory": "packages/svelte"
+  },
+  "homepage": "https://github.com/tryopendata/openchart#readme",
+  "bugs": "https://github.com/tryopendata/openchart/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "svelte": "./dist/index.js",
+  "sideEffects": false,
+  "keywords": [
+    "chart",
+    "visualization",
+    "svelte",
+    "data-table",
+    "svg",
+    "d3",
+    "declarative"
+  ],
+  "scripts": {
+    "build": "svelte-package -i src -o dist",
+    "test": "vitest run",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "dependencies": {
+    "@opendata-ai/openchart-core": "2.0.0",
+    "@opendata-ai/openchart-engine": "2.0.0",
+    "@opendata-ai/openchart-vanilla": "2.0.0"
+  },
+  "peerDependencies": {
+    "svelte": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.0",
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "@testing-library/svelte": "^5.2.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0"
+  }
+}

package/src/Chart.svelte

@@ -0,0 +1,132 @@
+<!--
+  Chart component: Svelte 5 wrapper around the vanilla adapter.
+
+  Mounts a chart instance on render, updates when spec/options change,
+  and cleans up on unmount. All heavy lifting is done by the vanilla
+  createChart() function.
+-->
+<script lang="ts">
+import type {
+  Annotation,
+  AnnotationOffset,
+  ChartSpec,
+  DarkMode,
+  ElementEdit,
+  GraphSpec,
+  MarkEvent,
+  TextAnnotation,
+  ThemeConfig,
+} from '@opendata-ai/openchart-core';
+import { type ChartInstance, createChart, type MountOptions } from '@opendata-ai/openchart-vanilla';
+import { onMount, untrack } from 'svelte';
+import { getVizDarkMode, getVizTheme } from './context.js';
+
+let {
+  spec,
+  theme,
+  darkMode,
+  onmarkclick,
+  onmarkhover,
+  onmarkleave,
+  onlegendtoggle,
+  onannotationclick,
+  onannotationedit,
+  onedit,
+  ondatapointclick,
+  class: className,
+  style,
+}: {
+  spec: ChartSpec | GraphSpec;
+  theme?: ThemeConfig;
+  darkMode?: DarkMode;
+  onmarkclick?: (event: MarkEvent) => void;
+  onmarkhover?: (event: MarkEvent) => void;
+  onmarkleave?: () => void;
+  onlegendtoggle?: (series: string, visible: boolean) => void;
+  onannotationclick?: (annotation: Annotation, event: MouseEvent) => void;
+  onannotationedit?: (annotation: TextAnnotation, offset: AnnotationOffset) => void;
+  onedit?: (edit: ElementEdit) => void;
+  ondatapointclick?: (data: Record<string, unknown>) => void;
+  class?: string;
+  style?: string;
+} = $props();
+
+let containerEl: HTMLDivElement;
+let instance: ChartInstance | null = null;
+
+const ctxTheme = getVizTheme();
+const ctxDarkMode = getVizDarkMode();
+
+onMount(() => {
+  return () => {
+    instance?.destroy();
+    instance = null;
+  };
+});
+
+// Stable callback wrappers that read current handler props without
+// creating reactive dependencies. This prevents callback prop changes
+// from triggering a full chart destroy/recreate cycle.
+const stableHandlers: MountOptions = {
+  onMarkClick: (event: MarkEvent) => untrack(() => onmarkclick)?.(event),
+  onMarkHover: (event: MarkEvent) => untrack(() => onmarkhover)?.(event),
+  onMarkLeave: () => untrack(() => onmarkleave)?.(),
+  onLegendToggle: (series: string, visible: boolean) =>
+    untrack(() => onlegendtoggle)?.(series, visible),
+  onAnnotationClick: (annotation: Annotation, event: MouseEvent) =>
+    untrack(() => onannotationclick)?.(annotation, event),
+  onDataPointClick: (data: Record<string, unknown>) => untrack(() => ondatapointclick)?.(data),
+};
+
+// Editing callbacks - only defined as stable wrappers, but only
+// included in options when the consumer provides the prop.
+const stableOnAnnotationEdit = (annotation: TextAnnotation, offset: AnnotationOffset) =>
+  untrack(() => onannotationedit)?.(annotation, offset);
+const stableOnEdit = (edit: ElementEdit) => untrack(() => onedit)?.(edit);
+
+let prevSpec = '';
+
+// Effect 1: Mount/recreate chart on theme/darkMode changes.
+// Reads spec via untrack() so spec changes don't trigger full recreate.
+$effect(() => {
+  const resolvedTheme = theme ?? ctxTheme?.();
+  const resolvedDarkMode = darkMode ?? ctxDarkMode?.();
+  // Read spec without tracking - spec changes handled in Effect 2
+  const currentSpec = untrack(() => spec);
+
+  instance?.destroy();
+
+  const hasAnnotationEdit = untrack(() => onannotationedit) !== undefined;
+  const hasEdit = untrack(() => onedit) !== undefined;
+
+  const options: MountOptions = {
+    theme: resolvedTheme,
+    darkMode: resolvedDarkMode,
+    responsive: true,
+    ...stableHandlers,
+    ...(hasAnnotationEdit ? { onAnnotationEdit: stableOnAnnotationEdit } : {}),
+    ...(hasEdit ? { onEdit: stableOnEdit } : {}),
+  };
+
+  instance = createChart(containerEl, currentSpec, options);
+  prevSpec = JSON.stringify(currentSpec);
+});
+
+// Effect 2: Update chart when spec changes (no destroy/recreate).
+$effect(() => {
+  const currentSpec = spec;
+  if (!instance) return;
+
+  const specString = JSON.stringify(currentSpec);
+  if (specString !== prevSpec) {
+    prevSpec = specString;
+    instance.update(currentSpec);
+  }
+});
+</script>
+
+<div
+  bind:this={containerEl}
+  class={className ? `viz-chart-root ${className}` : 'viz-chart-root'}
+  {style}
+></div>

package/src/DataTable.svelte

@@ -0,0 +1,132 @@
+<!--
+  DataTable component: Svelte 5 wrapper around the vanilla table adapter.
+
+  Mounts a table instance on render, updates when spec changes,
+  and cleans up on unmount. Supports both controlled and uncontrolled modes
+  for sort, search, and pagination state.
+-->
+<script lang="ts">
+import type { DarkMode, SortState, TableSpec, ThemeConfig } from '@opendata-ai/openchart-core';
+import {
+  createTable,
+  type TableInstance,
+  type TableMountOptions,
+} from '@opendata-ai/openchart-vanilla';
+import { onMount, untrack } from 'svelte';
+import { getVizDarkMode, getVizTheme } from './context.js';
+
+let {
+  spec,
+  theme,
+  darkMode,
+  onrowclick,
+  onsortchange,
+  onsearchchange,
+  onpagechange,
+  sort,
+  search,
+  page,
+  class: className,
+  style,
+}: {
+  spec: TableSpec;
+  theme?: ThemeConfig;
+  darkMode?: DarkMode;
+  onrowclick?: (row: Record<string, unknown>) => void;
+  onsortchange?: (sort: SortState | null) => void;
+  onsearchchange?: (query: string) => void;
+  onpagechange?: (page: number) => void;
+  sort?: SortState | null;
+  search?: string;
+  page?: number;
+  class?: string;
+  style?: string;
+} = $props();
+
+let containerEl: HTMLDivElement;
+let instance: TableInstance | null = null;
+
+const ctxTheme = getVizTheme();
+const ctxDarkMode = getVizDarkMode();
+
+const isControlled = $derived(sort !== undefined || search !== undefined || page !== undefined);
+
+onMount(() => {
+  return () => {
+    instance?.destroy();
+    instance = null;
+  };
+});
+
+let prevSpec = '';
+
+// Effect 1: Mount/recreate table on theme/darkMode changes.
+$effect(() => {
+  const resolvedTheme = theme ?? ctxTheme?.();
+  const resolvedDarkMode = darkMode ?? ctxDarkMode?.();
+  // Read spec and controlled state without tracking
+  const currentSpec = untrack(() => spec);
+  const currentIsControlled = untrack(() => isControlled);
+  const currentSort = untrack(() => sort);
+  const currentSearch = untrack(() => search);
+  const currentPage = untrack(() => page);
+
+  instance?.destroy();
+
+  const mountOptions: TableMountOptions = {
+    theme: resolvedTheme,
+    darkMode: resolvedDarkMode,
+    onRowClick: (row: Record<string, unknown>) => untrack(() => onrowclick)?.(row),
+    responsive: true,
+    onStateChange: (state) => {
+      if (state.sort !== undefined) untrack(() => onsortchange)?.(state.sort);
+      if (state.search !== undefined) untrack(() => onsearchchange)?.(state.search);
+      if (state.page !== undefined) untrack(() => onpagechange)?.(state.page);
+    },
+  };
+
+  if (currentIsControlled) {
+    mountOptions.externalState = {
+      sort: currentSort ?? null,
+      search: currentSearch ?? '',
+      page: currentPage ?? 0,
+    };
+  }
+
+  instance = createTable(containerEl, currentSpec, mountOptions);
+  prevSpec = JSON.stringify(currentSpec);
+});
+
+// Effect 2: Update table when spec changes (no destroy/recreate).
+$effect(() => {
+  const currentSpec = spec;
+  if (!instance) return;
+
+  const specString = JSON.stringify(currentSpec);
+  if (specString !== prevSpec) {
+    prevSpec = specString;
+    instance.update(currentSpec);
+  }
+});
+
+// Effect 3: Sync controlled state without remounting.
+$effect(() => {
+  const currentIsControlled = isControlled;
+  const currentSort = sort;
+  const currentSearch = search;
+  const currentPage = page;
+  if (!instance || !currentIsControlled) return;
+
+  instance.setState({
+    sort: currentSort ?? null,
+    search: currentSearch ?? '',
+    page: currentPage ?? 0,
+  });
+});
+</script>
+
+<div
+  bind:this={containerEl}
+  class={className ? `viz-table-root ${className}` : 'viz-table-root'}
+  {style}
+></div>

package/src/Graph.svelte

@@ -0,0 +1,119 @@
+<!--
+  Graph component: Svelte 5 wrapper around the vanilla adapter.
+
+  Mounts a graph instance on render, updates when spec changes,
+  and cleans up on unmount. All heavy lifting is done by the vanilla
+  createGraph() function.
+
+  Exposes imperative methods via component exports for programmatic
+  control (search, zoom, select).
+-->
+<script lang="ts">
+import type { DarkMode, GraphSpec, ThemeConfig } from '@opendata-ai/openchart-core';
+import {
+  createGraph,
+  type GraphInstance,
+  type GraphMountOptions,
+} from '@opendata-ai/openchart-vanilla';
+import { onMount, untrack } from 'svelte';
+import { getVizDarkMode, getVizTheme } from './context.js';
+
+let {
+  spec,
+  theme,
+  darkMode,
+  onnodeclick,
+  onnodedoubleclick,
+  onselectionchange,
+  class: className,
+  style,
+}: {
+  spec: GraphSpec;
+  theme?: ThemeConfig;
+  darkMode?: DarkMode;
+  onnodeclick?: (node: Record<string, unknown>) => void;
+  onnodedoubleclick?: (node: Record<string, unknown>) => void;
+  onselectionchange?: (nodeIds: string[]) => void;
+  class?: string;
+  style?: string;
+} = $props();
+
+let containerEl: HTMLDivElement;
+let instance: GraphInstance | null = null;
+
+const ctxTheme = getVizTheme();
+const ctxDarkMode = getVizDarkMode();
+
+onMount(() => {
+  return () => {
+    instance?.destroy();
+    instance = null;
+  };
+});
+
+let prevSpec = '';
+
+// Effect 1: Mount/recreate graph on theme/darkMode changes.
+$effect(() => {
+  const resolvedTheme = theme ?? ctxTheme?.();
+  const resolvedDarkMode = darkMode ?? ctxDarkMode?.();
+  const currentSpec = untrack(() => spec);
+
+  instance?.destroy();
+
+  const options: GraphMountOptions = {
+    theme: resolvedTheme,
+    darkMode: resolvedDarkMode,
+    onNodeClick: (node: Record<string, unknown>) => untrack(() => onnodeclick)?.(node),
+    onNodeDoubleClick: (node: Record<string, unknown>) => untrack(() => onnodedoubleclick)?.(node),
+    onSelectionChange: (nodeIds: string[]) => untrack(() => onselectionchange)?.(nodeIds),
+    responsive: true,
+  };
+
+  instance = createGraph(containerEl, currentSpec, options);
+  prevSpec = JSON.stringify(currentSpec);
+});
+
+// Effect 2: Update graph when spec changes (no destroy/recreate).
+$effect(() => {
+  const currentSpec = spec;
+  if (!instance) return;
+
+  const specString = JSON.stringify(currentSpec);
+  if (specString !== prevSpec) {
+    prevSpec = specString;
+    instance.update(currentSpec);
+  }
+});
+
+// Imperative methods exposed via component exports
+export function search(query: string): void {
+  instance?.search(query);
+}
+
+export function clearSearch(): void {
+  instance?.clearSearch();
+}
+
+export function zoomToFit(): void {
+  instance?.zoomToFit();
+}
+
+export function zoomToNode(nodeId: string): void {
+  instance?.zoomToNode(nodeId);
+}
+
+export function selectNode(nodeId: string): void {
+  instance?.selectNode(nodeId);
+}
+
+export function getSelectedNodes(): string[] {
+  return instance?.getSelectedNodes() ?? [];
+}
+</script>
+
+<div
+  bind:this={containerEl}
+  class={className ? `viz-graph-root ${className}` : 'viz-graph-root'}
+  {style}
+></div>

package/src/ThemeProvider.svelte

@@ -0,0 +1,27 @@
+<!--
+  VizThemeProvider: provides a theme and dark mode preference to all
+  descendant Chart, DataTable, and Graph components.
+
+  Components use the context values as fallbacks when no explicit
+  `theme` or `darkMode` prop is passed.
+-->
+<script lang="ts">
+import type { DarkMode, ThemeConfig } from '@opendata-ai/openchart-core';
+import type { Snippet } from 'svelte';
+import { setVizDarkMode, setVizTheme } from './context.js';
+
+let {
+  theme,
+  darkMode,
+  children,
+}: {
+  theme: ThemeConfig | undefined;
+  darkMode?: DarkMode;
+  children: Snippet;
+} = $props();
+
+setVizTheme(() => theme);
+setVizDarkMode(() => darkMode);
+</script>
+
+{@render children()}

package/src/Visualization.svelte

@@ -0,0 +1,35 @@
+<!--
+  Visualization routing component: renders Chart, DataTable, or Graph
+  based on the spec type. Use this when rendering arbitrary VizSpec values.
+
+  For event handlers, use the specific component (Chart, DataTable, Graph) directly.
+-->
+<script lang="ts">
+import type { DarkMode, ThemeConfig, VizSpec } from '@opendata-ai/openchart-core';
+import { isGraphSpec, isTableSpec } from '@opendata-ai/openchart-core';
+import Chart from './Chart.svelte';
+import DataTable from './DataTable.svelte';
+import Graph from './Graph.svelte';
+
+let {
+  spec,
+  theme,
+  darkMode,
+  class: className,
+  style,
+}: {
+  spec: VizSpec;
+  theme?: ThemeConfig;
+  darkMode?: DarkMode;
+  class?: string;
+  style?: string;
+} = $props();
+</script>
+
+{#if isTableSpec(spec)}
+  <DataTable {spec} {theme} {darkMode} class={className} {style} />
+{:else if isGraphSpec(spec)}
+  <Graph {spec} {theme} {darkMode} class={className} {style} />
+{:else}
+  <Chart {spec} {theme} {darkMode} class={className} {style} />
+{/if}

package/src/__tests__/Chart.test.ts

@@ -0,0 +1,134 @@
+import type { ChartSpec } from '@opendata-ai/openchart-core';
+import { cleanup, render, waitFor } from '@testing-library/svelte';
+import { afterEach, describe, expect, it } from 'vitest';
+import Chart from '../Chart.svelte';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const lineSpec: ChartSpec = {
+  type: 'line',
+  data: [
+    { date: '2020-01-01', value: 10, country: 'US' },
+    { date: '2021-01-01', value: 40, country: 'US' },
+    { date: '2020-01-01', value: 15, country: 'UK' },
+    { date: '2021-01-01', value: 35, country: 'UK' },
+  ],
+  encoding: {
+    x: { field: 'date', type: 'temporal' },
+    y: { field: 'value', type: 'quantitative' },
+    color: { field: 'country', type: 'nominal' },
+  },
+  chrome: {
+    title: 'GDP Growth',
+    subtitle: 'US vs UK over time',
+    source: 'World Bank',
+  },
+};
+
+const barSpec: ChartSpec = {
+  type: 'bar',
+  data: [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 30 },
+    { name: 'C', value: 20 },
+  ],
+  encoding: {
+    x: { field: 'value', type: 'quantitative' },
+    y: { field: 'name', type: 'nominal' },
+  },
+  chrome: {
+    title: 'Updated Title',
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Helper: render Chart and wait for SVG to appear ($effect is deferred)
+// ---------------------------------------------------------------------------
+
+async function renderChart(props: { spec: ChartSpec; [key: string]: unknown }) {
+  const result = render(Chart, { props });
+  await waitFor(() => {
+    expect(result.container.querySelector('svg')).not.toBeNull();
+  });
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+afterEach(() => {
+  cleanup();
+});
+
+describe('<Chart />', () => {
+  it('renders an SVG element', async () => {
+    const { container } = await renderChart({ spec: lineSpec });
+    const svg = container.querySelector('svg');
+    expect(svg).not.toBeNull();
+    expect(svg?.getAttribute('class')).toBe('viz-chart');
+  });
+
+  it('renders chrome text elements', async () => {
+    const { container } = await renderChart({ spec: lineSpec });
+
+    const title = container.querySelector('.viz-title');
+    expect(title).not.toBeNull();
+    expect(title?.textContent).toBe('GDP Growth');
+
+    const subtitle = container.querySelector('.viz-subtitle');
+    expect(subtitle?.textContent).toBe('US vs UK over time');
+
+    const source = container.querySelector('.viz-source');
+    expect(source?.textContent).toBe('World Bank');
+  });
+
+  it('spec changes trigger re-render', async () => {
+    const { container, rerender } = await renderChart({ spec: lineSpec });
+
+    const titleBefore = container.querySelector('.viz-title');
+    expect(titleBefore?.textContent).toBe('GDP Growth');
+
+    await rerender({ spec: barSpec });
+    await waitFor(() => {
+      expect(container.querySelector('.viz-title')?.textContent).toBe('Updated Title');
+    });
+  });
+
+  it('unmounting cleans up chart instance', async () => {
+    const { container, unmount } = await renderChart({ spec: lineSpec });
+
+    const svgBefore = container.querySelector('svg');
+    expect(svgBefore).not.toBeNull();
+
+    unmount();
+
+    expect(container.querySelector('svg')).toBeNull();
+  });
+
+  it('className prop passes through to wrapper div', async () => {
+    const { container } = await renderChart({ spec: lineSpec, class: 'my-chart' });
+
+    const wrapper = container.firstElementChild as HTMLElement;
+    expect(wrapper?.className).toContain('my-chart');
+  });
+
+  it('renders with dark mode option', async () => {
+    const { container } = await renderChart({ spec: lineSpec, darkMode: 'force' });
+
+    const svg = container.querySelector('svg');
+    expect(svg).not.toBeNull();
+  });
+
+  it('style prop passes through to wrapper div', async () => {
+    const { container } = await renderChart({
+      spec: lineSpec,
+      style: 'border: 1px solid red',
+    });
+
+    const wrapper = container.firstElementChild as HTMLElement;
+    expect(wrapper?.style.border).toBe('1px solid red');
+  });
+});