@opendata-ai/openchart-react 2.0.0

package/src/__tests__/hooks.test.tsx

@@ -0,0 +1,160 @@
+/**
+ * Tests for useChart and useDarkMode hooks.
+ *
+ * Note: renderHook from @testing-library/react doesn't work in this project
+ * due to bun's React dual-instance issue (renderHook's internal TestComponent
+ * uses a different React copy than the hooks under test). Instead, we render
+ * thin wrapper components that expose hook state via the DOM, then assert
+ * using render + waitFor.
+ */
+
+import type { ChartSpec } from '@opendata-ai/openchart-core';
+import { render, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { useChart, useDarkMode } from '../hooks';
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const barSpec: ChartSpec = {
+  type: 'bar',
+  data: [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 30 },
+  ],
+  encoding: {
+    x: { field: 'value', type: 'quantitative' },
+    y: { field: 'name', type: 'nominal' },
+  },
+};
+
+// ---------------------------------------------------------------------------
+// useDarkMode
+// ---------------------------------------------------------------------------
+
+function DarkModeHarness({ mode }: { mode?: 'auto' | 'force' | 'off' }) {
+  const isDark = useDarkMode(mode);
+  return <div data-testid="dark-mode">{String(isDark)}</div>;
+}
+
+describe('useDarkMode', () => {
+  it('returns false when no mode is provided', async () => {
+    const { container } = render(<DarkModeHarness />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('false');
+    });
+  });
+
+  it('returns false for "off" mode', async () => {
+    const { container } = render(<DarkModeHarness mode="off" />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('false');
+    });
+  });
+
+  it('returns true for "force" mode', async () => {
+    const { container } = render(<DarkModeHarness mode="force" />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('true');
+    });
+  });
+
+  it('reflects system preference for "auto" mode when dark', async () => {
+    const spy = vi.spyOn(window, 'matchMedia').mockImplementation(
+      (query: string) =>
+        ({
+          matches: query === '(prefers-color-scheme: dark)',
+          media: query,
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+        }) as unknown as MediaQueryList,
+    );
+
+    const { container } = render(<DarkModeHarness mode="auto" />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('true');
+    });
+
+    spy.mockRestore();
+  });
+
+  it('reflects system preference for "auto" mode when light', async () => {
+    const spy = vi.spyOn(window, 'matchMedia').mockImplementation(
+      (query: string) =>
+        ({
+          matches: false,
+          media: query,
+          addEventListener: vi.fn(),
+          removeEventListener: vi.fn(),
+        }) as unknown as MediaQueryList,
+    );
+
+    const { container } = render(<DarkModeHarness mode="auto" />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('false');
+    });
+
+    spy.mockRestore();
+  });
+
+  it('switches from "off" to "force" when mode prop changes', async () => {
+    const { container, rerender } = render(<DarkModeHarness mode="off" />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('false');
+    });
+
+    rerender(<DarkModeHarness mode="force" />);
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="dark-mode"]')?.textContent).toBe('true');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// useChart
+// ---------------------------------------------------------------------------
+
+function ChartHookHarness({ spec }: { spec: ChartSpec }) {
+  const { ref, chart, layout } = useChart(spec);
+  return (
+    <div>
+      <div ref={ref} data-testid="chart-container" />
+      <span data-testid="has-chart">{String(chart !== null)}</span>
+      <span data-testid="has-layout">{String(layout !== null)}</span>
+    </div>
+  );
+}
+
+describe('useChart', () => {
+  it('mounts a chart instance into the ref container', async () => {
+    const { container } = render(<ChartHookHarness spec={barSpec} />);
+
+    await waitFor(() => {
+      const chartContainer = container.querySelector('[data-testid="chart-container"]');
+      const svg = chartContainer?.querySelector('svg');
+      expect(svg).not.toBeNull();
+    });
+  });
+
+  it('produces a non-null layout after mounting', async () => {
+    const { container } = render(<ChartHookHarness spec={barSpec} />);
+
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="has-layout"]')?.textContent).toBe('true');
+    });
+  });
+
+  it('cleans up the chart on unmount', async () => {
+    const { container, unmount } = render(<ChartHookHarness spec={barSpec} />);
+
+    await waitFor(() => {
+      const svg = container.querySelector('svg');
+      expect(svg).not.toBeNull();
+    });
+
+    unmount();
+
+    expect(container.querySelector('svg')).toBeNull();
+  });
+});

package/src/__tests__/update-vs-remount.test.tsx

@@ -0,0 +1,133 @@
+/**
+ * Tests that spec changes go through the update() path rather than
+ * destroying and recreating the chart/table instance.
+ */
+
+import type { ChartSpec, TableSpec } from '@opendata-ai/openchart-core';
+import { cleanup, render, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { Chart } from '../Chart';
+import { DataTable } from '../DataTable';
+
+// ---------------------------------------------------------------------------
+// Mock the vanilla adapter to track create/update/destroy calls
+// ---------------------------------------------------------------------------
+
+const mockChartInstance = {
+  update: vi.fn(),
+  resize: vi.fn(),
+  destroy: vi.fn(),
+  export: vi.fn(),
+  layout: {} as unknown,
+};
+
+const mockTableInstance = {
+  update: vi.fn(),
+  setState: vi.fn(),
+  destroy: vi.fn(),
+  layout: {} as unknown,
+};
+
+vi.mock('@opendata-ai/openchart-vanilla', () => ({
+  createChart: vi.fn(() => ({ ...mockChartInstance })),
+  createTable: vi.fn(() => ({ ...mockTableInstance })),
+  createGraph: vi.fn(),
+}));
+
+// Import after mock setup
+const { createChart, createTable } = await import('@opendata-ai/openchart-vanilla');
+
+// ---------------------------------------------------------------------------
+// Test data
+// ---------------------------------------------------------------------------
+
+const lineSpec: ChartSpec = {
+  type: 'line',
+  data: [
+    { x: '2020', y: 10 },
+    { x: '2021', y: 20 },
+  ],
+  encoding: {
+    x: { field: 'x', type: 'temporal' },
+    y: { field: 'y', type: 'quantitative' },
+  },
+};
+
+const barSpec: ChartSpec = {
+  type: 'bar',
+  data: [
+    { name: 'A', value: 10 },
+    { name: 'B', value: 20 },
+  ],
+  encoding: {
+    x: { field: 'value', type: 'quantitative' },
+    y: { field: 'name', type: 'nominal' },
+  },
+};
+
+const tableSpec: TableSpec = {
+  type: 'table',
+  data: [{ a: 1 }],
+  columns: [{ key: 'a', label: 'A' }],
+};
+
+const updatedTableSpec: TableSpec = {
+  type: 'table',
+  data: [{ a: 1 }, { a: 2 }],
+  columns: [{ key: 'a', label: 'A' }],
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+describe('Chart update-vs-remount', () => {
+  it('calls createChart once on initial mount', async () => {
+    render(<Chart spec={lineSpec} />);
+    await waitFor(() => {
+      expect(createChart).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('calls update() not createChart() on spec change', async () => {
+    const { rerender } = render(<Chart spec={lineSpec} />);
+    await waitFor(() => {
+      expect(createChart).toHaveBeenCalledTimes(1);
+    });
+
+    rerender(<Chart spec={barSpec} />);
+    await waitFor(() => {
+      // createChart should NOT be called again
+      expect(createChart).toHaveBeenCalledTimes(1);
+      // update should be called with the new spec
+      expect(mockChartInstance.update).toHaveBeenCalledWith(barSpec);
+    });
+  });
+});
+
+describe('DataTable update-vs-remount', () => {
+  it('calls createTable once on initial mount', async () => {
+    render(<DataTable spec={tableSpec} />);
+    await waitFor(() => {
+      expect(createTable).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it('calls update() not createTable() on spec change', async () => {
+    const { rerender } = render(<DataTable spec={tableSpec} />);
+    await waitFor(() => {
+      expect(createTable).toHaveBeenCalledTimes(1);
+    });
+
+    rerender(<DataTable spec={updatedTableSpec} />);
+    await waitFor(() => {
+      expect(createTable).toHaveBeenCalledTimes(1);
+      expect(mockTableInstance.update).toHaveBeenCalledWith(updatedTableSpec);
+    });
+  });
+});

package/src/__tests__/useTableState.test.tsx

@@ -0,0 +1,218 @@
+/**
+ * Tests for useTableState hook.
+ *
+ * Uses thin wrapper components that expose hook state via the DOM,
+ * since renderHook is broken by bun's React dual-instance issue.
+ */
+
+import { fireEvent, render, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { type UseTableStateOptions, useTableState } from '../hooks/useTableState';
+
+// ---------------------------------------------------------------------------
+// Test harness: renders hook state to the DOM
+// ---------------------------------------------------------------------------
+
+interface HarnessProps {
+  initialState?: UseTableStateOptions;
+}
+
+function TableStateHarness({ initialState }: HarnessProps) {
+  const { sort, search, page, setSort, setSearch, setPage, resetState } =
+    useTableState(initialState);
+
+  return (
+    <div>
+      <span data-testid="sort">{sort ? `${sort.column}:${sort.direction}` : 'null'}</span>
+      <span data-testid="search">{search}</span>
+      <span data-testid="page">{String(page)}</span>
+      <button
+        type="button"
+        data-testid="set-sort-name-asc"
+        onClick={() => setSort({ column: 'name', direction: 'asc' })}
+      >
+        sort name asc
+      </button>
+      <button
+        type="button"
+        data-testid="set-sort-age-desc"
+        onClick={() => setSort({ column: 'age', direction: 'desc' })}
+      >
+        sort age desc
+      </button>
+      <button type="button" data-testid="clear-sort" onClick={() => setSort(null)}>
+        clear sort
+      </button>
+      <button type="button" data-testid="set-search" onClick={() => setSearch('filter text')}>
+        set search
+      </button>
+      <button type="button" data-testid="set-page-5" onClick={() => setPage(5)}>
+        page 5
+      </button>
+      <button type="button" data-testid="reset" onClick={() => resetState()}>
+        reset
+      </button>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+async function renderHarness(initialState?: UseTableStateOptions) {
+  const result = render(<TableStateHarness initialState={initialState} />);
+  // Wait for initial render to complete
+  await waitFor(() => {
+    expect(result.container.querySelector('[data-testid="page"]')).not.toBeNull();
+  });
+  return result;
+}
+
+function getState(container: HTMLElement) {
+  return {
+    sort: container.querySelector('[data-testid="sort"]')?.textContent ?? '',
+    search: container.querySelector('[data-testid="search"]')?.textContent ?? '',
+    page: container.querySelector('[data-testid="page"]')?.textContent ?? '',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('useTableState', () => {
+  // -------------------------------------------------------------------------
+  // Default initial state
+  // -------------------------------------------------------------------------
+
+  it('initializes with default values when no options provided', async () => {
+    const { container } = await renderHarness();
+    const state = getState(container);
+
+    expect(state.sort).toBe('null');
+    expect(state.search).toBe('');
+    expect(state.page).toBe('0');
+  });
+
+  // -------------------------------------------------------------------------
+  // Custom initial state
+  // -------------------------------------------------------------------------
+
+  it('initializes with provided sort state', async () => {
+    const { container } = await renderHarness({
+      sort: { column: 'name', direction: 'asc' },
+    });
+    expect(getState(container).sort).toBe('name:asc');
+  });
+
+  it('initializes with provided search string', async () => {
+    const { container } = await renderHarness({ search: 'hello' });
+    expect(getState(container).search).toBe('hello');
+  });
+
+  it('initializes with provided page number', async () => {
+    const { container } = await renderHarness({ page: 3 });
+    expect(getState(container).page).toBe('3');
+  });
+
+  // -------------------------------------------------------------------------
+  // State setters
+  // -------------------------------------------------------------------------
+
+  it('setSort updates the sort state', async () => {
+    const { container } = await renderHarness();
+
+    fireEvent.click(container.querySelector('[data-testid="set-sort-age-desc"]')!);
+    await waitFor(() => {
+      expect(getState(container).sort).toBe('age:desc');
+    });
+  });
+
+  it('setSort can clear sort by passing null', async () => {
+    const { container } = await renderHarness({
+      sort: { column: 'name', direction: 'asc' },
+    });
+    expect(getState(container).sort).toBe('name:asc');
+
+    fireEvent.click(container.querySelector('[data-testid="clear-sort"]')!);
+    await waitFor(() => {
+      expect(getState(container).sort).toBe('null');
+    });
+  });
+
+  it('setSearch updates the search query', async () => {
+    const { container } = await renderHarness();
+
+    fireEvent.click(container.querySelector('[data-testid="set-search"]')!);
+    await waitFor(() => {
+      expect(getState(container).search).toBe('filter text');
+    });
+  });
+
+  it('setPage updates the current page', async () => {
+    const { container } = await renderHarness();
+
+    fireEvent.click(container.querySelector('[data-testid="set-page-5"]')!);
+    await waitFor(() => {
+      expect(getState(container).page).toBe('5');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // resetState
+  // -------------------------------------------------------------------------
+
+  it('resetState restores default initial values', async () => {
+    const { container } = await renderHarness();
+
+    // Change all values
+    fireEvent.click(container.querySelector('[data-testid="set-sort-name-asc"]')!);
+    fireEvent.click(container.querySelector('[data-testid="set-search"]')!);
+    fireEvent.click(container.querySelector('[data-testid="set-page-5"]')!);
+
+    await waitFor(() => {
+      expect(getState(container).sort).toBe('name:asc');
+      expect(getState(container).search).toBe('filter text');
+      expect(getState(container).page).toBe('5');
+    });
+
+    // Reset
+    fireEvent.click(container.querySelector('[data-testid="reset"]')!);
+
+    await waitFor(() => {
+      expect(getState(container).sort).toBe('null');
+      expect(getState(container).search).toBe('');
+      expect(getState(container).page).toBe('0');
+    });
+  });
+
+  it('resetState restores custom initial values', async () => {
+    const initialState = {
+      sort: { column: 'age', direction: 'desc' as const },
+      search: 'initial',
+      page: 1,
+    };
+    const { container } = await renderHarness(initialState);
+
+    // Change all values
+    fireEvent.click(container.querySelector('[data-testid="clear-sort"]')!);
+    fireEvent.click(container.querySelector('[data-testid="set-search"]')!);
+    fireEvent.click(container.querySelector('[data-testid="set-page-5"]')!);
+
+    await waitFor(() => {
+      expect(getState(container).sort).toBe('null');
+      expect(getState(container).search).toBe('filter text');
+      expect(getState(container).page).toBe('5');
+    });
+
+    // Reset to initial
+    fireEvent.click(container.querySelector('[data-testid="reset"]')!);
+
+    await waitFor(() => {
+      expect(getState(container).sort).toBe('age:desc');
+      expect(getState(container).search).toBe('initial');
+      expect(getState(container).page).toBe('1');
+    });
+  });
+});

package/src/hooks/useGraph.ts

@@ -0,0 +1,85 @@
+/**
+ * useGraph: hook for imperative graph control.
+ *
+ * Provides a ref to pass to <Graph /> and exposes graph methods
+ * (search, zoom, select) for programmatic control of the graph instance.
+ */
+
+import type { GraphInstance } from '@opendata-ai/openchart-vanilla';
+import { useCallback, useRef } from 'react';
+
+export interface UseGraphReturn {
+  /** Ref to pass to <Graph ref={ref} />. */
+  ref: React.RefObject<GraphHandle | null>;
+  /** Search for nodes matching a query string. */
+  search: (query: string) => void;
+  /** Clear the current search. */
+  clearSearch: () => void;
+  /** Zoom to fit all nodes in view. */
+  zoomToFit: () => void;
+  /** Zoom and center on a specific node. */
+  zoomToNode: (nodeId: string) => void;
+  /** Select a node by id. */
+  selectNode: (nodeId: string) => void;
+  /** Get the currently selected node ids. */
+  getSelectedNodes: () => string[];
+}
+
+/** Handle exposed by Graph component via forwardRef. */
+export interface GraphHandle {
+  search: (query: string) => void;
+  clearSearch: () => void;
+  zoomToFit: () => void;
+  zoomToNode: (nodeId: string) => void;
+  selectNode: (nodeId: string) => void;
+  getSelectedNodes: () => string[];
+  /** The underlying GraphInstance from the vanilla adapter. */
+  instance: GraphInstance | null;
+}
+
+/**
+ * Hook for imperative graph control.
+ *
+ * Usage:
+ * ```tsx
+ * const { ref, search, zoomToFit } = useGraph();
+ * return <Graph ref={ref} spec={spec} />;
+ * ```
+ */
+export function useGraph(): UseGraphReturn {
+  const ref = useRef<GraphHandle | null>(null);
+
+  const search = useCallback((query: string) => {
+    ref.current?.search(query);
+  }, []);
+
+  const clearSearch = useCallback(() => {
+    ref.current?.clearSearch();
+  }, []);
+
+  const zoomToFit = useCallback(() => {
+    ref.current?.zoomToFit();
+  }, []);
+
+  const zoomToNode = useCallback((nodeId: string) => {
+    ref.current?.zoomToNode(nodeId);
+  }, []);
+
+  const selectNode = useCallback((nodeId: string) => {
+    ref.current?.selectNode(nodeId);
+  }, []);
+
+  const getSelectedNodes = useCallback((): string[] => {
+    return ref.current?.getSelectedNodes() ?? [];
+  }, []);
+
+  return {
+    ref,
+    search,
+    clearSearch,
+    zoomToFit,
+    zoomToNode,
+    selectNode,
+    getSelectedNodes,
+  };
+}

package/src/hooks/useTable.ts

@@ -0,0 +1,98 @@
+/**
+ * useTable: hook for manual table lifecycle control.
+ *
+ * Attaches to a container ref, mounts a vanilla table instance,
+ * and exposes the instance and current state.
+ */
+
+import type { TableSpec } from '@opendata-ai/openchart-core';
+import {
+  createTable,
+  type TableInstance,
+  type TableMountOptions,
+  type TableState,
+} from '@opendata-ai/openchart-vanilla';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export interface UseTableReturn {
+  /** Ref to attach to the container div. */
+  ref: React.RefObject<HTMLDivElement | null>;
+  /** The table instance (null until mounted). */
+  table: TableInstance | null;
+  /** The current table state (sort, search, page). */
+  state: TableState;
+}
+
+/**
+ * Hook for manual table lifecycle control.
+ *
+ * Attach the returned ref to a container div. The table mounts
+ * automatically and updates when the spec changes.
+ *
+ * @param spec - The table spec.
+ * @param options - Mount options.
+ * @returns { ref, table, state }
+ */
+export function useTable(spec: TableSpec, options?: TableMountOptions): UseTableReturn {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const tableRef = useRef<TableInstance | null>(null);
+  const [state, setState] = useState<TableState>({
+    sort: null,
+    search: '',
+    page: 0,
+  });
+
+  const originalOnStateChange = options?.onStateChange;
+
+  const handleStateChange = useCallback(
+    (newState: TableState) => {
+      setState(newState);
+      originalOnStateChange?.(newState);
+    },
+    [originalOnStateChange],
+  );
+
+  // Mount / unmount
+  useEffect(() => {
+    const container = ref.current;
+    if (!container) return;
+
+    const mountOpts: TableMountOptions = {
+      ...options,
+      onStateChange: handleStateChange,
+    };
+
+    const table = createTable(container, spec, mountOpts);
+    tableRef.current = table;
+    setState(table.getState());
+
+    return () => {
+      table.destroy();
+      tableRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    options?.theme,
+    options?.darkMode,
+    options?.onRowClick,
+    options?.responsive,
+    handleStateChange,
+    options,
+    spec,
+  ]);
+
+  // Update on spec change
+  useEffect(() => {
+    const table = tableRef.current;
+    if (!table) return;
+
+    table.update(spec);
+    setState(table.getState());
+  }, [spec]);
+
+  return {
+    ref,
+    table: tableRef.current,
+    state,
+  };
+}