@opendata-ai/openchart-react 2.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @opendata-ai/openchart-react
+
+React components for OpenChart. Renders chart specs as SVG and table specs as DOM, with full React lifecycle management.
+
+## Install
+
+```bash
+npm install @opendata-ai/openchart-react @opendata-ai/openchart-core
+```
+
+## Quick start
+
+```tsx
+import { Chart } from '@opendata-ai/openchart-react';
+import { lineChart } from '@opendata-ai/openchart-core';
+
+const data = [
+  { date: '2024-01', value: 100 },
+  { date: '2024-02', value: 150 },
+  { date: '2024-03', value: 130 },
+];
+
+const spec = lineChart(data, 'date', 'value');
+
+function App() {
+  return <Chart spec={spec} />;
+}
+```
+
+See the [core README](../core/README.md) for all available spec builders.
+
+## Components
+
+| Component | Purpose |
+|-----------|---------|
+| `Chart` | Renders any chart spec (line, bar, column, pie, scatter, etc.) |
+| `DataTable` | Renders table specs with sorting, search, and pagination |
+| `Graph` | Renders network graph specs with force-directed layout |
+| `Visualization` | Routes to the correct component based on spec type |
+| `VizThemeProvider` | Provides theme and dark mode context to child components |
+
+## Visualization
+
+The recommended entry point when you're rendering arbitrary `VizSpec` values and don't know the type ahead of time. It inspects the spec and routes to `Chart`, `DataTable`, or `Graph` automatically.
+
+```tsx
+import { Visualization } from '@opendata-ai/openchart-react';
+import type { VizSpec } from '@opendata-ai/openchart-core';
+
+function RenderSpec({ spec }: { spec: VizSpec }) {
+  // Renders Chart, DataTable, or Graph based on spec.type
+  return <Visualization spec={spec} />;
+}
+```
+
+If you need event handlers or component-specific props, use the specific component directly instead.
+
+## Dark mode and theming
+
+Wrap your app (or a subtree) with `VizThemeProvider` to set theme and dark mode for all child visualizations. All `Chart`, `DataTable`, and `Graph` components inside the provider inherit its values.
+
+```tsx
+import { VizThemeProvider, Chart } from '@opendata-ai/openchart-react';
+
+function Dashboard({ specs }) {
+  return (
+    <VizThemeProvider theme={myTheme} darkMode="auto">
+      <Chart spec={specs[0]} />
+      <Chart spec={specs[1]} />
+    </VizThemeProvider>
+  );
+}
+```
+
+`darkMode` accepts `"auto"` (follows system preference), `"force"` (always dark), or `"off"` (always light).
+
+For one-off overrides, pass `darkMode` or `theme` directly on an individual component. Component-level props take priority over the provider.
+
+```tsx
+<VizThemeProvider theme={defaultTheme} darkMode="auto">
+  <Chart spec={spec1} />
+  {/* This one stays light regardless of system preference */}
+  <Chart spec={spec2} darkMode="off" />
+</VizThemeProvider>
+```
+
+## Hooks
+
+For lower-level control or custom rendering, these hooks give you direct access to the compilation and rendering pipeline:
+
+- `useChart(spec, options?)` - Returns `{ ref, chart, layout }`. Attach `ref` to a container div
+- `useGraph()` - Returns `{ ref, search, zoomToFit, ... }`. Pair with `<Graph ref={ref} />`
+- `useTable(spec, options?)` - Returns `{ ref, table, layout }`. Attach `ref` to a container div
+- `useTableState(options?)` - Manages table sorting, pagination, and search state
+- `useDarkMode(preference?)` - Resolves dark mode preference against system settings

package/dist/index.d.ts

@@ -0,0 +1,292 @@
+export { ChartLayout, ChartSpec, CompileOptions, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-engine';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ChartEventHandlers, ChartSpec, GraphSpec, ThemeConfig, DarkMode, TableSpec, SortState, ChartLayout, VizSpec } from '@opendata-ai/openchart-core';
+import * as react from 'react';
+import { CSSProperties, ReactNode } from 'react';
+import { GraphInstance, MountOptions, ChartInstance, TableInstance, TableState, TableMountOptions } from '@opendata-ai/openchart-vanilla';
+
+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.
+ */
+declare function Chart({ spec, theme: themeProp, darkMode, onDataPointClick, onMarkClick, onMarkHover, onMarkLeave, onLegendToggle, onAnnotationClick, onAnnotationEdit, onEdit, className, style, }: ChartProps): react_jsx_runtime.JSX.Element;
+
+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.
+ */
+declare function DataTable({ spec, theme: themeProp, darkMode, onRowClick, onSortChange, onSearchChange, onPageChange, className, style, sort, search, page, }: DataTableProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * 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.
+ */
+
+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. */
+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} />;
+ * ```
+ */
+declare function useGraph(): UseGraphReturn;
+
+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} />;
+ * ```
+ */
+declare const Graph: react.ForwardRefExoticComponent<GraphProps & react.RefAttributes<GraphHandle>>;
+
+/**
+ * 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.
+ */
+
+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;
+}
+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 }
+ */
+declare function useChart(spec: ChartSpec | GraphSpec, options?: UseChartOptions): UseChartReturn;
+/**
+ * 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.
+ */
+declare function useDarkMode(mode?: DarkMode): boolean;
+
+/**
+ * useTable: hook for manual table lifecycle control.
+ *
+ * Attaches to a container ref, mounts a vanilla table instance,
+ * and exposes the instance and current state.
+ */
+
+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 }
+ */
+declare function useTable(spec: TableSpec, options?: TableMountOptions): UseTableReturn;
+
+/**
+ * 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.
+ */
+
+interface UseTableStateReturn {
+    sort: SortState | null;
+    setSort: (sort: SortState | null) => void;
+    search: string;
+    setSearch: (query: string) => void;
+    page: number;
+    setPage: (page: number) => void;
+    resetState: () => void;
+}
+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}
+ * />
+ * ```
+ */
+declare function useTableState(initialState?: UseTableStateOptions): UseTableStateReturn;
+
+/** Read the current theme from the nearest VizThemeProvider. */
+declare function useVizTheme(): ThemeConfig | undefined;
+/** Read the current dark mode preference from the nearest VizThemeProvider. */
+declare function useVizDarkMode(): DarkMode | undefined;
+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. */
+declare function VizThemeProvider({ theme, darkMode, children }: VizThemeProviderProps): react_jsx_runtime.JSX.Element;
+
+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.
+ */
+declare function Visualization({ spec, theme, darkMode, className, style }: VisualizationProps): react_jsx_runtime.JSX.Element;
+
+export { Chart, type ChartProps, DataTable, type DataTableProps, Graph, type GraphHandle, type GraphProps, type UseChartOptions, type UseChartReturn, type UseGraphReturn, type UseTableReturn, type UseTableStateOptions, type UseTableStateReturn, Visualization, type VisualizationProps, VizThemeProvider, type VizThemeProviderProps, useChart, useDarkMode, useGraph, useTable, useTableState, useVizDarkMode, useVizTheme };