@opendata-ai/openchart-react 2.0.0

package/src/hooks/useTableState.ts

@@ -0,0 +1,76 @@
+/**
+ * useTableState: managed state hook for controlled table usage.
+ *
+ * Provides individual sort/search/page state with setters and a
+ * resetState function to return to initial values.
+ */
+
+import type { SortState } from '@opendata-ai/openchart-core';
+import { useCallback, useState } from 'react';
+
+export interface UseTableStateReturn {
+  sort: SortState | null;
+  setSort: (sort: SortState | null) => void;
+  search: string;
+  setSearch: (query: string) => void;
+  page: number;
+  setPage: (page: number) => void;
+  resetState: () => void;
+}
+
+export interface UseTableStateOptions {
+  sort?: SortState | null;
+  search?: string;
+  page?: number;
+}
+
+/**
+ * Hook for managing table state (sort, search, page).
+ *
+ * Use with the DataTable component's controlled props:
+ * ```tsx
+ * const { sort, search, page, setSort, setSearch, setPage } = useTableState();
+ * <DataTable
+ *   spec={spec}
+ *   sort={sort}
+ *   search={search}
+ *   page={page}
+ *   onSortChange={setSort}
+ *   onSearchChange={setSearch}
+ *   onPageChange={setPage}
+ * />
+ * ```
+ */
+export function useTableState(initialState?: UseTableStateOptions): UseTableStateReturn {
+  const [sort, setSortInternal] = useState<SortState | null>(initialState?.sort ?? null);
+  const [search, setSearchInternal] = useState(initialState?.search ?? '');
+  const [page, setPageInternal] = useState(initialState?.page ?? 0);
+
+  const setSort = useCallback((newSort: SortState | null) => {
+    setSortInternal(newSort);
+  }, []);
+
+  const setSearch = useCallback((query: string) => {
+    setSearchInternal(query);
+  }, []);
+
+  const setPage = useCallback((newPage: number) => {
+    setPageInternal(newPage);
+  }, []);
+
+  const resetState = useCallback(() => {
+    setSortInternal(initialState?.sort ?? null);
+    setSearchInternal(initialState?.search ?? '');
+    setPageInternal(initialState?.page ?? 0);
+  }, [initialState?.sort, initialState?.search, initialState?.page]);
+
+  return {
+    sort,
+    setSort,
+    search,
+    setSearch,
+    page,
+    setPage,
+    resetState,
+  };
+}

package/src/hooks.ts

@@ -0,0 +1,145 @@
+/**
+ * React hooks for chart lifecycle and dark mode resolution.
+ *
+ * useChart: manual control over a chart instance (for advanced usage).
+ * useDarkMode: resolves the DarkMode preference to a boolean.
+ */
+
+import type { ChartLayout, ChartSpec, DarkMode, GraphSpec } from '@opendata-ai/openchart-core';
+import { type ChartInstance, createChart, type MountOptions } from '@opendata-ai/openchart-vanilla';
+import { useEffect, useRef, useState } from 'react';
+
+// ---------------------------------------------------------------------------
+// useChart
+// ---------------------------------------------------------------------------
+
+export interface UseChartOptions {
+  /** Theme overrides. */
+  theme?: MountOptions['theme'];
+  /** Dark mode setting. */
+  darkMode?: MountOptions['darkMode'];
+  /** Data point click handler. */
+  onDataPointClick?: MountOptions['onDataPointClick'];
+  /** Enable responsive resizing. Defaults to true. */
+  responsive?: boolean;
+}
+
+export interface UseChartReturn {
+  /** Ref to attach to the container div. */
+  ref: React.RefObject<HTMLDivElement | null>;
+  /** The chart instance (null until mounted). */
+  chart: ChartInstance | null;
+  /** The current compiled layout (null until mounted). */
+  layout: ChartLayout | null;
+}
+
+/**
+ * Hook for manual chart lifecycle control.
+ *
+ * Attach the returned ref to a container div. The chart mounts
+ * automatically and updates when the spec changes.
+ *
+ * @param spec - The visualization spec.
+ * @param options - Mount options.
+ * @returns { ref, chart, layout }
+ */
+export function useChart(spec: ChartSpec | GraphSpec, options?: UseChartOptions): UseChartReturn {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const chartRef = useRef<ChartInstance | null>(null);
+  const [layout, setLayout] = useState<ChartLayout | null>(null);
+  const specRef = useRef<string>('');
+
+  // Mount / unmount
+  // biome-ignore lint/correctness/useExhaustiveDependencies: spec intentionally excluded - spec changes handled via update() in the update effect
+  useEffect(() => {
+    const container = ref.current;
+    if (!container) return;
+
+    const mountOpts: MountOptions = {
+      theme: options?.theme,
+      darkMode: options?.darkMode,
+      onDataPointClick: options?.onDataPointClick,
+      responsive: options?.responsive,
+    };
+
+    const chart = createChart(container, spec, mountOpts);
+    chartRef.current = chart;
+    setLayout(chart.layout);
+    specRef.current = JSON.stringify(spec);
+
+    return () => {
+      chart.destroy();
+      chartRef.current = null;
+      setLayout(null);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [options?.theme, options?.darkMode, options?.onDataPointClick, options?.responsive]);
+
+  // Update on spec change
+  useEffect(() => {
+    const chart = chartRef.current;
+    if (!chart) return;
+
+    const specString = JSON.stringify(spec);
+    if (specString !== specRef.current) {
+      specRef.current = specString;
+      chart.update(spec);
+      setLayout(chart.layout);
+    }
+  }, [spec]);
+
+  return {
+    ref,
+    chart: chartRef.current,
+    layout,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// useDarkMode
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a DarkMode preference to a boolean.
+ *
+ * - "force" -> true
+ * - "off" -> false
+ * - "auto" -> matches system preference (reactive to changes)
+ *
+ * @param mode - The dark mode preference.
+ * @returns Whether dark mode is active.
+ */
+export function useDarkMode(mode?: DarkMode): boolean {
+  const [isDark, setIsDark] = useState(() => resolveInitial(mode));
+
+  useEffect(() => {
+    if (mode !== 'auto') {
+      setIsDark(mode === 'force');
+      return;
+    }
+
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      setIsDark(false);
+      return;
+    }
+
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    setIsDark(mq.matches);
+
+    const handler = (e: MediaQueryListEvent) => setIsDark(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, [mode]);
+
+  return isDark;
+}
+
+function resolveInitial(mode?: DarkMode): boolean {
+  if (mode === 'force') return true;
+  if (mode === 'off' || mode === undefined) return false;
+  // "auto"
+  if (typeof window !== 'undefined' && window.matchMedia) {
+    return window.matchMedia('(prefers-color-scheme: dark)').matches;
+  }
+  return false;
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+/**
+ * @opendata-ai/openchart-react
+ *
+ * React adapter for openchart. Provides <Chart /> and <DataTable />
+ * components that wrap the vanilla adapter with React lifecycle management.
+ */
+
+// Re-export core types for convenience
+export type {
+  ChartLayout,
+  ChartSpec,
+  CompileOptions,
+  TableLayout,
+  TableSpec,
+  VizSpec,
+} from '@opendata-ai/openchart-engine';
+export type { ChartProps } from './Chart';
+// Components
+export { Chart } from './Chart';
+export type { DataTableProps } from './DataTable';
+export { DataTable } from './DataTable';
+export type { GraphProps } from './Graph';
+export { Graph } from './Graph';
+export type { UseChartOptions, UseChartReturn } from './hooks';
+// Hooks
+export { useChart, useDarkMode } from './hooks';
+export type { GraphHandle, UseGraphReturn } from './hooks/useGraph';
+export { useGraph } from './hooks/useGraph';
+export type { UseTableReturn } from './hooks/useTable';
+export { useTable } from './hooks/useTable';
+export type { UseTableStateOptions, UseTableStateReturn } from './hooks/useTableState';
+export { useTableState } from './hooks/useTableState';
+export type { VizThemeProviderProps } from './ThemeContext';
+// Theme context
+export { useVizDarkMode, useVizTheme, VizThemeProvider } from './ThemeContext';
+export type { VisualizationProps } from './Visualization';
+export { Visualization } from './Visualization';