@opendata-ai/openchart-react 2.0.0

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@opendata-ai/openchart-react",
+  "version": "2.0.0",
+  "description": "React components for openchart: <Chart />, <DataTable />, <VizThemeProvider />",
+  "license": "Apache-2.0",
+  "author": "Riley Hilliard",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tryopendata/openchart.git",
+    "directory": "packages/react"
+  },
+  "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",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "chart",
+    "visualization",
+    "react",
+    "data-table",
+    "svg",
+    "d3",
+    "declarative"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opendata-ai/openchart-core": "2.0.0",
+    "@opendata-ai/openchart-engine": "2.0.0",
+    "@opendata-ai/openchart-vanilla": "2.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/src/Chart.tsx

@@ -0,0 +1,191 @@
+/**
+ * React Chart component: thin wrapper around the vanilla adapter.
+ *
+ * Mounts a chart instance on render, updates when spec changes,
+ * and cleans up on unmount. All heavy lifting is done by the vanilla
+ * createChart() function.
+ */
+
+import type {
+  ChartEventHandlers,
+  ChartSpec,
+  DarkMode,
+  GraphSpec,
+  ThemeConfig,
+} from '@opendata-ai/openchart-core';
+import { type ChartInstance, createChart, type MountOptions } from '@opendata-ai/openchart-vanilla';
+import { type CSSProperties, useCallback, useEffect, useRef } from 'react';
+import { useVizDarkMode, useVizTheme } from './ThemeContext';
+
+export interface ChartProps extends ChartEventHandlers {
+  /** The visualization spec to render. */
+  spec: ChartSpec | GraphSpec;
+  /** Theme overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode: "auto", "force", or "off". */
+  darkMode?: DarkMode;
+  /** Callback when a data point is clicked. @deprecated Use onMarkClick instead. */
+  onDataPointClick?: (data: Record<string, unknown>) => void;
+  /** CSS class name for the wrapper div. */
+  className?: string;
+  /** Inline styles for the wrapper div. */
+  style?: CSSProperties;
+}
+
+/**
+ * React component that renders a visualization from a spec.
+ *
+ * Uses the vanilla adapter internally. The spec is compiled and rendered
+ * as SVG inside a wrapper div. Spec changes trigger re-renders via the
+ * vanilla adapter's update() method.
+ */
+export function Chart({
+  spec,
+  theme: themeProp,
+  darkMode,
+  onDataPointClick,
+  onMarkClick,
+  onMarkHover,
+  onMarkLeave,
+  onLegendToggle,
+  onAnnotationClick,
+  onAnnotationEdit,
+  onEdit,
+  className,
+  style,
+}: ChartProps) {
+  const contextTheme = useVizTheme();
+  const contextDarkMode = useVizDarkMode();
+  const theme = themeProp ?? contextTheme;
+  const resolvedDarkMode = darkMode ?? contextDarkMode;
+  const containerRef = useRef<HTMLDivElement>(null);
+  const chartRef = useRef<ChartInstance | null>(null);
+  const specRef = useRef<string>('');
+
+  // Store event handlers in refs so they don't trigger chart recreation.
+  // Inline arrow functions create new references every render, which would
+  // destroy and recreate the entire chart instance without this pattern.
+  const handlersRef = useRef<{
+    onDataPointClick?: ChartProps['onDataPointClick'];
+    onMarkClick?: ChartProps['onMarkClick'];
+    onMarkHover?: ChartProps['onMarkHover'];
+    onMarkLeave?: ChartProps['onMarkLeave'];
+    onLegendToggle?: ChartProps['onLegendToggle'];
+    onAnnotationClick?: ChartProps['onAnnotationClick'];
+    onAnnotationEdit?: ChartProps['onAnnotationEdit'];
+    onEdit?: ChartProps['onEdit'];
+  }>({});
+  handlersRef.current = {
+    onDataPointClick,
+    onMarkClick,
+    onMarkHover,
+    onMarkLeave,
+    onLegendToggle,
+    onAnnotationClick,
+    onAnnotationEdit,
+    onEdit,
+  };
+
+  // Stable callback wrappers that read from refs
+  const stableOnDataPointClick = useCallback(
+    (data: Record<string, unknown>) => handlersRef.current.onDataPointClick?.(data),
+    [],
+  );
+  const stableOnMarkClick = useCallback(
+    (event: import('@opendata-ai/openchart-core').MarkEvent) =>
+      handlersRef.current.onMarkClick?.(event),
+    [],
+  );
+  const stableOnMarkHover = useCallback(
+    (event: import('@opendata-ai/openchart-core').MarkEvent) =>
+      handlersRef.current.onMarkHover?.(event),
+    [],
+  );
+  const stableOnMarkLeave = useCallback(() => handlersRef.current.onMarkLeave?.(), []);
+  const stableOnLegendToggle = useCallback(
+    (series: string, visible: boolean) => handlersRef.current.onLegendToggle?.(series, visible),
+    [],
+  );
+  const stableOnAnnotationClick = useCallback(
+    (annotation: import('@opendata-ai/openchart-core').Annotation, event: MouseEvent) =>
+      handlersRef.current.onAnnotationClick?.(annotation, event),
+    [],
+  );
+  const stableOnAnnotationEdit = useCallback(
+    (
+      annotation: import('@opendata-ai/openchart-core').TextAnnotation,
+      updatedOffset: import('@opendata-ai/openchart-core').AnnotationOffset,
+    ) => handlersRef.current.onAnnotationEdit?.(annotation, updatedOffset),
+    [],
+  );
+  const stableOnEdit = useCallback(
+    (edit: import('@opendata-ai/openchart-core').ElementEdit) => handlersRef.current.onEdit?.(edit),
+    [],
+  );
+
+  // Mount chart and recreate when theme/darkMode change.
+  // Event handlers use stable refs so they don't trigger recreation.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: spec intentionally excluded - spec changes handled via update() in Effect 2
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const options: MountOptions = {
+      theme,
+      darkMode: resolvedDarkMode,
+      onDataPointClick: stableOnDataPointClick,
+      onMarkClick: stableOnMarkClick,
+      onMarkHover: stableOnMarkHover,
+      onMarkLeave: stableOnMarkLeave,
+      onLegendToggle: stableOnLegendToggle,
+      onAnnotationClick: stableOnAnnotationClick,
+      // Only include editing callbacks when the consumer provides them.
+      // The stable wrappers are always truthy, so gating on handlersRef
+      // avoids adding unstable prop references to the effect deps.
+      ...(handlersRef.current.onAnnotationEdit ? { onAnnotationEdit: stableOnAnnotationEdit } : {}),
+      ...(handlersRef.current.onEdit ? { onEdit: stableOnEdit } : {}),
+      responsive: true,
+    };
+
+    chartRef.current = createChart(container, spec, options);
+    specRef.current = JSON.stringify(spec);
+
+    return () => {
+      chartRef.current?.destroy();
+      chartRef.current = null;
+    };
+    // Only recreate when theme or darkMode change. Event handlers use stable refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    theme,
+    resolvedDarkMode,
+    stableOnAnnotationClick,
+    stableOnDataPointClick,
+    stableOnEdit,
+    stableOnLegendToggle,
+    stableOnMarkClick,
+    stableOnMarkHover,
+    stableOnMarkLeave,
+    stableOnAnnotationEdit,
+  ]);
+
+  // Update chart when spec changes
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart) return;
+
+    const specString = JSON.stringify(spec);
+    if (specString !== specRef.current) {
+      specRef.current = specString;
+      chart.update(spec);
+    }
+  }, [spec]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className ? `viz-chart-root ${className}` : 'viz-chart-root'}
+      style={style}
+    />
+  );
+}

package/src/DataTable.tsx

@@ -0,0 +1,165 @@
+/**
+ * DataTable component: React 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.
+ */
+
+import type { DarkMode, SortState, TableSpec, ThemeConfig } from '@opendata-ai/openchart-core';
+import {
+  createTable,
+  type TableInstance,
+  type TableMountOptions,
+} from '@opendata-ai/openchart-vanilla';
+import { type CSSProperties, useCallback, useEffect, useRef } from 'react';
+import { useVizDarkMode, useVizTheme } from './ThemeContext';
+
+export interface DataTableProps {
+  /** The table spec to render. */
+  spec: TableSpec;
+  /** Theme overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode: "auto", "force", or "off". */
+  darkMode?: DarkMode;
+  /** Row click handler. */
+  onRowClick?: (row: Record<string, unknown>) => void;
+  /** Callback when sort changes. */
+  onSortChange?: (sort: SortState | null) => void;
+  /** Callback when search changes. */
+  onSearchChange?: (query: string) => void;
+  /** Callback when page changes. */
+  onPageChange?: (page: number) => void;
+  /** CSS class name for the wrapper div. */
+  className?: string;
+  /** Inline styles for the wrapper div. */
+  style?: CSSProperties;
+  /** Controlled sort state. */
+  sort?: SortState | null;
+  /** Controlled search query. */
+  search?: string;
+  /** Controlled page number. */
+  page?: number;
+}
+
+/**
+ * React component that renders a data table from a TableSpec.
+ *
+ * Uses the vanilla adapter internally. Supports controlled and uncontrolled
+ * modes for sort, search, and pagination state.
+ */
+export function DataTable({
+  spec,
+  theme: themeProp,
+  darkMode,
+  onRowClick,
+  onSortChange,
+  onSearchChange,
+  onPageChange,
+  className,
+  style,
+  sort,
+  search,
+  page,
+}: DataTableProps) {
+  const contextTheme = useVizTheme();
+  const contextDarkMode = useVizDarkMode();
+  const theme = themeProp ?? contextTheme;
+  const resolvedDarkMode = darkMode ?? contextDarkMode;
+  const containerRef = useRef<HTMLDivElement>(null);
+  const tableRef = useRef<TableInstance | null>(null);
+
+  // Store event handlers in refs so they don't trigger table recreation.
+  const handlersRef = useRef<{
+    onRowClick?: DataTableProps['onRowClick'];
+    onSortChange?: DataTableProps['onSortChange'];
+    onSearchChange?: DataTableProps['onSearchChange'];
+    onPageChange?: DataTableProps['onPageChange'];
+  }>({});
+  handlersRef.current = { onRowClick, onSortChange, onSearchChange, onPageChange };
+
+  // Stable callback wrappers that read from refs
+  const stableOnRowClick = useCallback(
+    (row: Record<string, unknown>) => handlersRef.current.onRowClick?.(row),
+    [],
+  );
+  const stableOnStateChange = useCallback(
+    (state: { sort?: SortState | null; search?: string; page?: number }) => {
+      if (state.sort !== undefined) handlersRef.current.onSortChange?.(state.sort);
+      if (state.search !== undefined) handlersRef.current.onSearchChange?.(state.search);
+      if (state.page !== undefined) handlersRef.current.onPageChange?.(state.page);
+    },
+    [],
+  );
+
+  const prevSpecRef = useRef<string>('');
+
+  // Determine if we're in controlled mode
+  const isControlled = sort !== undefined || search !== undefined || page !== undefined;
+
+  // Effect 1: Mount/unmount. Only recreate when structural options change.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: spec, sort, search, page intentionally excluded - handled via update()/setState() in Effects 2-3
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const mountOptions: TableMountOptions = {
+      theme,
+      darkMode: resolvedDarkMode,
+      onRowClick: stableOnRowClick,
+      responsive: true,
+      onStateChange: stableOnStateChange,
+    };
+
+    if (isControlled) {
+      mountOptions.externalState = {
+        sort: sort ?? null,
+        search: search ?? '',
+        page: page ?? 0,
+      };
+    }
+
+    tableRef.current = createTable(container, spec, mountOptions);
+    prevSpecRef.current = JSON.stringify(spec);
+
+    return () => {
+      tableRef.current?.destroy();
+      tableRef.current = null;
+    };
+    // Only recreate on structural option changes (theme, darkMode, onRowClick).
+    // Controlled state updates are handled in Effect 2.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [theme, resolvedDarkMode, isControlled, stableOnRowClick, stableOnStateChange]);
+
+  // Effect 2: Sync controlled state without remounting.
+  useEffect(() => {
+    const table = tableRef.current;
+    if (!table || !isControlled) return;
+
+    table.setState({
+      sort: sort ?? null,
+      search: search ?? '',
+      page: page ?? 0,
+    });
+  }, [sort, search, page, isControlled]);
+
+  // Effect 3: Sync spec changes via update().
+  useEffect(() => {
+    const table = tableRef.current;
+    if (!table) return;
+
+    const specString = JSON.stringify(spec);
+    if (specString !== prevSpecRef.current) {
+      prevSpecRef.current = specString;
+      table.update(spec);
+    }
+  }, [spec]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className ? `viz-table-root ${className}` : 'viz-table-root'}
+      style={style}
+    />
+  );
+}

package/src/Graph.tsx

@@ -0,0 +1,186 @@
+/**
+ * React Graph component: thin 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.
+ *
+ * Supports forwardRef for imperative control via useGraph() hook.
+ */
+
+import type { DarkMode, GraphSpec, ThemeConfig } from '@opendata-ai/openchart-core';
+import {
+  createGraph,
+  type GraphInstance,
+  type GraphMountOptions,
+} from '@opendata-ai/openchart-vanilla';
+import {
+  type CSSProperties,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+} from 'react';
+import type { GraphHandle } from './hooks/useGraph';
+import { useVizDarkMode, useVizTheme } from './ThemeContext';
+
+export interface GraphProps {
+  /** The graph spec to render. */
+  spec: GraphSpec;
+  /** Theme overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode: "auto", "force", or "off". */
+  darkMode?: DarkMode;
+  /** Callback when a node is clicked. */
+  onNodeClick?: (node: Record<string, unknown>) => void;
+  /** Callback when a node is double-clicked. */
+  onNodeDoubleClick?: (node: Record<string, unknown>) => void;
+  /** Callback when selection changes. */
+  onSelectionChange?: (nodeIds: string[]) => void;
+  /** CSS class name for the wrapper div. */
+  className?: string;
+  /** Inline styles for the wrapper div. */
+  style?: CSSProperties;
+}
+
+/**
+ * React component that renders a force-directed graph from a GraphSpec.
+ *
+ * Uses the vanilla adapter internally. The spec is compiled and rendered
+ * on a canvas inside a wrapper div. Spec changes trigger re-renders via the
+ * vanilla adapter's update() method.
+ *
+ * Supports ref for imperative control via useGraph() hook:
+ * ```tsx
+ * const { ref, search, zoomToFit } = useGraph();
+ * return <Graph ref={ref} spec={spec} />;
+ * ```
+ */
+export const Graph = forwardRef<GraphHandle, GraphProps>(function Graph(
+  {
+    spec,
+    theme: themeProp,
+    darkMode,
+    onNodeClick,
+    onNodeDoubleClick,
+    onSelectionChange,
+    className,
+    style,
+  },
+  ref,
+) {
+  const contextTheme = useVizTheme();
+  const contextDarkMode = useVizDarkMode();
+  const theme = themeProp ?? contextTheme;
+  const resolvedDarkMode = darkMode ?? contextDarkMode;
+  const containerRef = useRef<HTMLDivElement>(null);
+  const graphRef = useRef<GraphInstance | null>(null);
+  const specRef = useRef<string>('');
+
+  // Store event handlers in refs so they don't trigger graph recreation.
+  // Inline arrow functions create new references every render, which would
+  // destroy and recreate the entire graph instance without this pattern.
+  const handlersRef = useRef<{
+    onNodeClick?: GraphProps['onNodeClick'];
+    onNodeDoubleClick?: GraphProps['onNodeDoubleClick'];
+    onSelectionChange?: GraphProps['onSelectionChange'];
+  }>({});
+  handlersRef.current = { onNodeClick, onNodeDoubleClick, onSelectionChange };
+
+  // Stable callback wrappers that read from refs
+  const stableOnNodeClick = useCallback(
+    (node: Record<string, unknown>) => handlersRef.current.onNodeClick?.(node),
+    [],
+  );
+  const stableOnNodeDoubleClick = useCallback(
+    (node: Record<string, unknown>) => handlersRef.current.onNodeDoubleClick?.(node),
+    [],
+  );
+  const stableOnSelectionChange = useCallback(
+    (nodeIds: string[]) => handlersRef.current.onSelectionChange?.(nodeIds),
+    [],
+  );
+
+  // Expose imperative handle for useGraph() hook
+  useImperativeHandle(
+    ref,
+    () => ({
+      search(query: string) {
+        graphRef.current?.search(query);
+      },
+      clearSearch() {
+        graphRef.current?.clearSearch();
+      },
+      zoomToFit() {
+        graphRef.current?.zoomToFit();
+      },
+      zoomToNode(nodeId: string) {
+        graphRef.current?.zoomToNode(nodeId);
+      },
+      selectNode(nodeId: string) {
+        graphRef.current?.selectNode(nodeId);
+      },
+      getSelectedNodes() {
+        return graphRef.current?.getSelectedNodes() ?? [];
+      },
+      get instance() {
+        return graphRef.current;
+      },
+    }),
+    [],
+  );
+
+  // Mount graph and recreate when theme/darkMode change.
+  // Event handlers use stable refs so they don't trigger recreation.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: spec intentionally excluded - spec changes handled via update() in Effect 2
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const options: GraphMountOptions = {
+      theme,
+      darkMode: resolvedDarkMode,
+      onNodeClick: stableOnNodeClick,
+      onNodeDoubleClick: stableOnNodeDoubleClick,
+      onSelectionChange: stableOnSelectionChange,
+      responsive: true,
+    };
+
+    graphRef.current = createGraph(container, spec, options);
+    specRef.current = JSON.stringify(spec);
+
+    return () => {
+      graphRef.current?.destroy();
+      graphRef.current = null;
+    };
+    // Only recreate when theme or darkMode change. Event handlers use stable refs.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    theme,
+    resolvedDarkMode,
+    stableOnNodeClick,
+    stableOnNodeDoubleClick,
+    stableOnSelectionChange,
+  ]);
+
+  // Update graph when spec changes
+  useEffect(() => {
+    const graph = graphRef.current;
+    if (!graph) return;
+
+    const specString = JSON.stringify(spec);
+    if (specString !== specRef.current) {
+      specRef.current = specString;
+      graph.update(spec);
+    }
+  }, [spec]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className ? `viz-graph-root ${className}` : 'viz-graph-root'}
+      style={style}
+    />
+  );
+});

package/src/ThemeContext.tsx

@@ -0,0 +1,40 @@
+/**
+ * Theme context: provides a theme and dark mode preference to all
+ * descendant Chart, DataTable, and Graph components without prop drilling.
+ *
+ * Components use the context values as fallbacks when no explicit
+ * `theme` or `darkMode` prop is passed.
+ */
+
+import type { DarkMode, ThemeConfig } from '@opendata-ai/openchart-core';
+import { createContext, type ReactNode, useContext } from 'react';
+
+const VizThemeContext = createContext<ThemeConfig | undefined>(undefined);
+const VizDarkModeContext = createContext<DarkMode | undefined>(undefined);
+
+/** Read the current theme from the nearest VizThemeProvider. */
+export function useVizTheme(): ThemeConfig | undefined {
+  return useContext(VizThemeContext);
+}
+
+/** Read the current dark mode preference from the nearest VizThemeProvider. */
+export function useVizDarkMode(): DarkMode | undefined {
+  return useContext(VizDarkModeContext);
+}
+
+export interface VizThemeProviderProps {
+  /** Theme config to provide to descendant viz components. */
+  theme: ThemeConfig | undefined;
+  /** Dark mode preference to provide to descendant viz components. */
+  darkMode?: DarkMode;
+  children: ReactNode;
+}
+
+/** Provides a theme and dark mode preference to all nested Chart, DataTable, and Graph components. */
+export function VizThemeProvider({ theme, darkMode, children }: VizThemeProviderProps) {
+  return (
+    <VizThemeContext.Provider value={theme}>
+      <VizDarkModeContext.Provider value={darkMode}>{children}</VizDarkModeContext.Provider>
+    </VizThemeContext.Provider>
+  );
+}

package/src/Visualization.tsx

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+
+import type { DarkMode, ThemeConfig, VizSpec } from '@opendata-ai/openchart-core';
+import { isGraphSpec, isTableSpec } from '@opendata-ai/openchart-core';
+import type { CSSProperties } from 'react';
+import { Chart } from './Chart';
+import { DataTable } from './DataTable';
+import { Graph } from './Graph';
+
+export interface VisualizationProps {
+  /** The visualization spec to render. */
+  spec: VizSpec;
+  /** Theme overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode: "auto", "force", or "off". */
+  darkMode?: DarkMode;
+  /** CSS class name for the wrapper div. */
+  className?: string;
+  /** Inline styles for the wrapper div. */
+  style?: CSSProperties;
+}
+
+/**
+ * Routes a VizSpec to the appropriate rendering component.
+ *
+ * Accepts any VizSpec and renders it with the correct component based on the
+ * spec's type field. For event handlers, use Chart, DataTable, or Graph directly.
+ */
+export function Visualization({ spec, theme, darkMode, className, style }: VisualizationProps) {
+  if (isTableSpec(spec)) {
+    return (
+      <DataTable
+        spec={spec}
+        theme={theme}
+        darkMode={darkMode}
+        className={className}
+        style={style}
+      />
+    );
+  }
+  if (isGraphSpec(spec)) {
+    return (
+      <Graph spec={spec} theme={theme} darkMode={darkMode} className={className} style={style} />
+    );
+  }
+  return (
+    <Chart spec={spec} theme={theme} darkMode={darkMode} className={className} style={style} />
+  );
+}