@opendata-ai/openchart-react 6.3.0 → 6.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-react",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "React components for openchart: <Chart />, <DataTable />, <VizThemeProvider />",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -49,9 +49,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "6.3.0",
-    "@opendata-ai/openchart-engine": "6.3.0",
-    "@opendata-ai/openchart-vanilla": "6.3.0"
+    "@opendata-ai/openchart-core": "6.5.0",
+    "@opendata-ai/openchart-engine": "6.5.0",
+    "@opendata-ai/openchart-vanilla": "6.5.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0",

package/src/Chart.tsx

@@ -10,14 +10,33 @@ import type {
   ChartEventHandlers,
   ChartSpec,
   DarkMode,
+  ElementRef,
   GraphSpec,
   LayerSpec,
   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 {
+  type CSSProperties,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+} from 'react';
 import { useVizDarkMode, useVizTheme } from './ThemeContext';
 
+export interface ChartHandle {
+  /** Get the currently selected element, or null if none. */
+  getSelectedElement(): ElementRef | null;
+  /** Programmatically select an element. */
+  select(ref: ElementRef): void;
+  /** Deselect the current element. */
+  deselect(): void;
+  /** The underlying chart instance (null until mounted). */
+  readonly instance: ChartInstance | null;
+}
+
 export interface ChartProps extends ChartEventHandlers {
   /** The visualization spec to render. */
   spec: ChartSpec | LayerSpec | GraphSpec;
@@ -27,6 +46,8 @@ export interface ChartProps extends ChartEventHandlers {
   darkMode?: DarkMode;
   /** Callback when a data point is clicked. @deprecated Use onMarkClick instead. */
   onDataPointClick?: (data: Record<string, unknown>) => void;
+  /** The currently selected element (controlled). */
+  selectedElement?: ElementRef;
   /** CSS class name for the wrapper div. */
   className?: string;
   /** Inline styles for the wrapper div. */
@@ -40,21 +61,28 @@ export interface ChartProps extends ChartEventHandlers {
  * 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) {
+export const Chart = forwardRef<ChartHandle, ChartProps>(function Chart(
+  {
+    spec,
+    theme: themeProp,
+    darkMode,
+    onDataPointClick,
+    onMarkClick,
+    onMarkHover,
+    onMarkLeave,
+    onLegendToggle,
+    onAnnotationClick,
+    onAnnotationEdit,
+    onEdit,
+    onSelect,
+    onDeselect,
+    onTextEdit,
+    selectedElement: selectedElementProp,
+    className,
+    style,
+  },
+  ref,
+) {
   const contextTheme = useVizTheme();
   const contextDarkMode = useVizDarkMode();
   const theme = themeProp ?? contextTheme;
@@ -75,6 +103,9 @@ export function Chart({
     onAnnotationClick?: ChartProps['onAnnotationClick'];
     onAnnotationEdit?: ChartProps['onAnnotationEdit'];
     onEdit?: ChartProps['onEdit'];
+    onSelect?: ChartProps['onSelect'];
+    onDeselect?: ChartProps['onDeselect'];
+    onTextEdit?: ChartProps['onTextEdit'];
   }>({});
   handlersRef.current = {
     onDataPointClick,
@@ -85,6 +116,9 @@ export function Chart({
     onAnnotationClick,
     onAnnotationEdit,
     onEdit,
+    onSelect,
+    onDeselect,
+    onTextEdit,
   };
 
   // Stable callback wrappers that read from refs
@@ -123,6 +157,39 @@ export function Chart({
     (edit: import('@opendata-ai/openchart-core').ElementEdit) => handlersRef.current.onEdit?.(edit),
     [],
   );
+  const stableOnSelect = useCallback(
+    (element: ElementRef) => handlersRef.current.onSelect?.(element),
+    [],
+  );
+  const stableOnDeselect = useCallback(
+    (element: ElementRef) => handlersRef.current.onDeselect?.(element),
+    [],
+  );
+  const stableOnTextEdit = useCallback(
+    (element: ElementRef, oldText: string, newText: string) =>
+      handlersRef.current.onTextEdit?.(element, oldText, newText),
+    [],
+  );
+
+  // Expose imperative handle for ref-based control
+  useImperativeHandle(
+    ref,
+    () => ({
+      getSelectedElement() {
+        return chartRef.current?.getSelectedElement() ?? null;
+      },
+      select(elementRef: ElementRef) {
+        chartRef.current?.select(elementRef);
+      },
+      deselect() {
+        chartRef.current?.deselect();
+      },
+      get instance() {
+        return chartRef.current;
+      },
+    }),
+    [],
+  );
 
   // Mount chart and recreate when theme/darkMode change.
   // Event handlers use stable refs so they don't trigger recreation.
@@ -145,6 +212,10 @@ export function Chart({
       // avoids adding unstable prop references to the effect deps.
       ...(handlersRef.current.onAnnotationEdit ? { onAnnotationEdit: stableOnAnnotationEdit } : {}),
       ...(handlersRef.current.onEdit ? { onEdit: stableOnEdit } : {}),
+      ...(handlersRef.current.onSelect ? { onSelect: stableOnSelect } : {}),
+      ...(handlersRef.current.onDeselect ? { onDeselect: stableOnDeselect } : {}),
+      ...(handlersRef.current.onTextEdit ? { onTextEdit: stableOnTextEdit } : {}),
+      ...(selectedElementProp ? { selectedElement: selectedElementProp } : {}),
       responsive: true,
     };
 
@@ -168,6 +239,9 @@ export function Chart({
     stableOnMarkHover,
     stableOnMarkLeave,
     stableOnAnnotationEdit,
+    stableOnSelect,
+    stableOnDeselect,
+    stableOnTextEdit,
   ]);
 
   // Update chart when spec changes
@@ -182,11 +256,23 @@ export function Chart({
     }
   }, [spec]);
 
+  // Handle selectedElement prop changes separately (like Vue/Svelte adapters)
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart || !chart.select) return;
+
+    if (selectedElementProp) {
+      chart.select(selectedElementProp);
+    } else if (chart.getSelectedElement?.()) {
+      chart.deselect();
+    }
+  }, [selectedElementProp]);
+
   return (
     <div
       ref={containerRef}
-      className={className ? `viz-chart-root ${className}` : 'viz-chart-root'}
+      className={className ? `oc-chart-root ${className}` : 'oc-chart-root'}
       style={style}
     />
   );
-}
+});

package/src/DataTable.tsx

@@ -158,7 +158,7 @@ export function DataTable({
   return (
     <div
       ref={containerRef}
-      className={className ? `viz-table-root ${className}` : 'viz-table-root'}
+      className={className ? `oc-table-root ${className}` : 'oc-table-root'}
       style={style}
     />
   );

package/src/Graph.tsx

@@ -246,7 +246,7 @@ export const Graph = forwardRef<GraphHandle, GraphProps>(function Graph(
   return (
     <div
       ref={containerRef}
-      className={className ? `viz-graph-root ${className}` : 'viz-graph-root'}
+      className={className ? `oc-graph-root ${className}` : 'oc-graph-root'}
       style={style}
     />
   );

package/src/__tests__/Chart.test.tsx

@@ -68,32 +68,32 @@ describe('<Chart />', () => {
     const { container } = await renderChart({ spec: lineSpec });
     const svg = container.querySelector('svg');
     expect(svg).not.toBeNull();
-    expect(svg?.getAttribute('class')).toBe('viz-chart');
+    expect(svg?.getAttribute('class')).toBe('oc-chart');
   });
 
   it('renders chrome text elements', async () => {
     const { container } = await renderChart({ spec: lineSpec });
 
-    const title = container.querySelector('.viz-title');
+    const title = container.querySelector('.oc-title');
     expect(title).not.toBeNull();
     expect(title?.textContent).toBe('GDP Growth');
 
-    const subtitle = container.querySelector('.viz-subtitle');
+    const subtitle = container.querySelector('.oc-subtitle');
     expect(subtitle?.textContent).toBe('US vs UK over time');
 
-    const source = container.querySelector('.viz-source');
+    const source = container.querySelector('.oc-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');
+    const titleBefore = container.querySelector('.oc-title');
     expect(titleBefore?.textContent).toBe('GDP Growth');
 
     rerender(<Chart spec={barSpec} />);
     await waitFor(() => {
-      expect(container.querySelector('.viz-title')?.textContent).toBe('Updated Title');
+      expect(container.querySelector('.oc-title')?.textContent).toBe('Updated Title');
     });
   });
 

package/src/__tests__/DataTable.test.tsx

@@ -77,12 +77,12 @@ describe('<DataTable />', () => {
   it('spec changes trigger re-render', async () => {
     const { container, rerender } = await renderTable({ spec: tableSpec });
 
-    const titleBefore = container.querySelector('.viz-table-title');
+    const titleBefore = container.querySelector('.oc-table-title');
     expect(titleBefore?.textContent).toBe('People Table');
 
     rerender(<DataTable spec={updatedSpec} />);
     await waitFor(() => {
-      expect(container.querySelector('.viz-table-title')?.textContent).toBe('Updated Table');
+      expect(container.querySelector('.oc-table-title')?.textContent).toBe('Updated Table');
     });
 
     const headersAfter = container.querySelectorAll('thead th');

package/src/__tests__/Graph.test.tsx

@@ -73,23 +73,23 @@ describe('<Graph />', () => {
   it('renders chrome text elements', async () => {
     const { container } = await renderGraph({ spec: basicSpec });
 
-    const title = container.querySelector('.viz-title');
+    const title = container.querySelector('.oc-title');
     expect(title).not.toBeNull();
     expect(title?.textContent).toBe('Test Graph');
 
-    const subtitle = container.querySelector('.viz-subtitle');
+    const subtitle = container.querySelector('.oc-subtitle');
     expect(subtitle?.textContent).toBe('A simple test graph');
   });
 
   it('spec changes trigger re-render', async () => {
     const { container, rerender } = await renderGraph({ spec: basicSpec });
 
-    const titleBefore = container.querySelector('.viz-title');
+    const titleBefore = container.querySelector('.oc-title');
     expect(titleBefore?.textContent).toBe('Test Graph');
 
     rerender(<Graph spec={updatedSpec} />);
     await waitFor(() => {
-      expect(container.querySelector('.viz-title')?.textContent).toBe('Updated Graph');
+      expect(container.querySelector('.oc-title')?.textContent).toBe('Updated Graph');
     });
   });
 

package/src/index.ts

@@ -63,7 +63,7 @@ export {
   validateSpec,
 } from '@opendata-ai/openchart-engine';
 
-export type { ChartProps } from './Chart';
+export type { ChartHandle, ChartProps } from './Chart';
 // Components
 export { Chart } from './Chart';
 export type { DataTableProps } from './DataTable';