@opendata-ai/openchart-vue 2.0.0

package/src/composables/useChart.ts

@@ -0,0 +1,95 @@
+/**
+ * useChart: composable for manual chart lifecycle control.
+ *
+ * Provides a template ref to attach to a container div. The chart
+ * mounts automatically and updates when the spec changes.
+ */
+
+import type {
+  ChartLayout,
+  ChartSpec,
+  DarkMode,
+  GraphSpec,
+  ThemeConfig,
+} from '@opendata-ai/openchart-core';
+import { type ChartInstance, createChart, type MountOptions } from '@opendata-ai/openchart-vanilla';
+import { onMounted, onUnmounted, type Ref, ref, type ShallowRef, shallowRef, watch } from 'vue';
+
+export interface UseChartOptions {
+  /** Theme overrides. */
+  theme?: ThemeConfig;
+  /** Dark mode setting. */
+  darkMode?: DarkMode;
+  /** Data point click handler. */
+  onDataPointClick?: MountOptions['onDataPointClick'];
+  /** Enable responsive resizing. Defaults to true. */
+  responsive?: boolean;
+}
+
+export interface UseChartReturn {
+  /** Template ref to attach to the container div. */
+  containerRef: Ref<HTMLDivElement | null>;
+  /** The chart instance (null until mounted). */
+  chart: ShallowRef<ChartInstance | null>;
+  /** The current compiled layout (null until mounted). */
+  layout: ShallowRef<ChartLayout | null>;
+}
+
+/**
+ * Composable for manual chart lifecycle control.
+ *
+ * Attach the returned containerRef to a container div via `ref="containerRef"`.
+ * The chart mounts automatically and updates when the spec changes.
+ */
+export function useChart(
+  spec: Ref<ChartSpec | GraphSpec>,
+  options?: UseChartOptions,
+): UseChartReturn {
+  const containerRef = ref<HTMLDivElement | null>(null);
+  const chart = shallowRef<ChartInstance | null>(null);
+  const layout = shallowRef<ChartLayout | null>(null);
+
+  function mount() {
+    const container = containerRef.value;
+    if (!container) return;
+
+    const mountOpts: MountOptions = {
+      theme: options?.theme,
+      darkMode: options?.darkMode,
+      onDataPointClick: options?.onDataPointClick,
+      responsive: options?.responsive,
+    };
+
+    const instance = createChart(container, spec.value, mountOpts);
+    chart.value = instance;
+    layout.value = instance.layout;
+  }
+
+  function destroy() {
+    chart.value?.destroy();
+    chart.value = null;
+    layout.value = null;
+  }
+
+  onMounted(() => {
+    mount();
+  });
+
+  onUnmounted(() => {
+    destroy();
+  });
+
+  // Update on spec change
+  watch(spec, (newSpec) => {
+    const instance = chart.value;
+    if (!instance) return;
+    instance.update(newSpec);
+    layout.value = instance.layout;
+  });
+
+  return {
+    containerRef,
+    chart,
+    layout,
+  };
+}

package/src/composables/useDarkMode.ts

@@ -0,0 +1,71 @@
+/**
+ * useDarkMode: composable that resolves a DarkMode preference to a boolean.
+ *
+ * - "force" -> true
+ * - "off" -> false
+ * - "auto" -> matches system preference (reactive to changes)
+ */
+
+import type { DarkMode } from '@opendata-ai/openchart-core';
+import { onUnmounted, type Ref, ref, watch } from 'vue';
+
+/**
+ * Resolve a DarkMode preference to a reactive boolean.
+ *
+ * For "auto" mode, watches the system `prefers-color-scheme` media query
+ * and updates reactively when the user changes their OS theme.
+ */
+export function useDarkMode(mode: Ref<DarkMode | undefined>): Ref<boolean> {
+  const isDark = ref(resolveInitial(mode.value));
+  let cleanup: (() => void) | null = null;
+
+  function setup(currentMode: DarkMode | undefined) {
+    // Clean up previous listener
+    cleanup?.();
+    cleanup = null;
+
+    if (currentMode !== 'auto') {
+      isDark.value = currentMode === 'force';
+      return;
+    }
+
+    if (typeof window === 'undefined' || !window.matchMedia) {
+      isDark.value = false;
+      return;
+    }
+
+    const mq = window.matchMedia('(prefers-color-scheme: dark)');
+    isDark.value = mq.matches;
+
+    const handler = (e: MediaQueryListEvent) => {
+      isDark.value = e.matches;
+    };
+    mq.addEventListener('change', handler);
+    cleanup = () => mq.removeEventListener('change', handler);
+  }
+
+  // Run setup for initial value
+  setup(mode.value);
+
+  // React to mode changes
+  watch(mode, (newMode) => {
+    setup(newMode);
+  });
+
+  onUnmounted(() => {
+    cleanup?.();
+    cleanup = null;
+  });
+
+  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/composables/useGraph.ts

@@ -0,0 +1,89 @@
+/**
+ * useGraph: composable for imperative graph control.
+ *
+ * Provides a template 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 { type Ref, ref } from 'vue';
+
+/** Handle exposed by Graph component via expose(). */
+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;
+}
+
+export interface UseGraphReturn {
+  /** Template ref to pass to <Graph ref={graphRef} />. */
+  graphRef: Ref<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[];
+}
+
+/**
+ * Composable for imperative graph control.
+ *
+ * Usage:
+ * ```vue
+ * <script setup>
+ * const { graphRef, search, zoomToFit } = useGraph();
+ * </script>
+ * <template>
+ *   <Graph ref="graphRef" :spec="spec" />
+ * </template>
+ * ```
+ */
+export function useGraph(): UseGraphReturn {
+  const graphRef = ref<GraphHandle | null>(null);
+
+  function search(query: string) {
+    graphRef.value?.search(query);
+  }
+
+  function clearSearch() {
+    graphRef.value?.clearSearch();
+  }
+
+  function zoomToFit() {
+    graphRef.value?.zoomToFit();
+  }
+
+  function zoomToNode(nodeId: string) {
+    graphRef.value?.zoomToNode(nodeId);
+  }
+
+  function selectNode(nodeId: string) {
+    graphRef.value?.selectNode(nodeId);
+  }
+
+  function getSelectedNodes(): string[] {
+    return graphRef.value?.getSelectedNodes() ?? [];
+  }
+
+  return {
+    graphRef,
+    search,
+    clearSearch,
+    zoomToFit,
+    zoomToNode,
+    selectNode,
+    getSelectedNodes,
+  };
+}

package/src/composables/useTable.ts

@@ -0,0 +1,88 @@
+/**
+ * useTable: composable 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 { onMounted, onUnmounted, type Ref, ref, type ShallowRef, shallowRef, watch } from 'vue';
+
+export interface UseTableReturn {
+  /** Template ref to attach to the container div. */
+  containerRef: Ref<HTMLDivElement | null>;
+  /** The table instance (null until mounted). */
+  table: ShallowRef<TableInstance | null>;
+  /** The current table state (sort, search, page). */
+  state: Ref<TableState>;
+}
+
+/**
+ * Composable for manual table lifecycle control.
+ *
+ * Attach the returned containerRef to a container div via `ref="containerRef"`.
+ * The table mounts automatically and updates when the spec changes.
+ */
+export function useTable(spec: Ref<TableSpec>, options?: TableMountOptions): UseTableReturn {
+  const containerRef = ref<HTMLDivElement | null>(null);
+  const table = shallowRef<TableInstance | null>(null);
+  const state = ref<TableState>({
+    sort: null,
+    search: '',
+    page: 0,
+  });
+
+  const originalOnStateChange = options?.onStateChange;
+
+  function handleStateChange(newState: TableState) {
+    state.value = newState;
+    originalOnStateChange?.(newState);
+  }
+
+  function mount() {
+    const container = containerRef.value;
+    if (!container) return;
+
+    const mountOpts: TableMountOptions = {
+      ...options,
+      onStateChange: handleStateChange,
+    };
+
+    const instance = createTable(container, spec.value, mountOpts);
+    table.value = instance;
+    state.value = instance.getState();
+  }
+
+  function destroy() {
+    table.value?.destroy();
+    table.value = null;
+  }
+
+  onMounted(() => {
+    mount();
+  });
+
+  onUnmounted(() => {
+    destroy();
+  });
+
+  // Update on spec change
+  watch(spec, (newSpec) => {
+    const instance = table.value;
+    if (!instance) return;
+    instance.update(newSpec);
+    state.value = instance.getState();
+  });
+
+  return {
+    containerRef,
+    table,
+    state,
+  };
+}

package/src/composables/useTableState.ts

@@ -0,0 +1,80 @@
+/**
+ * useTableState: managed state composable 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 { type Ref, ref } from 'vue';
+
+export interface UseTableStateReturn {
+  sort: Ref<SortState | null>;
+  setSort: (sort: SortState | null) => void;
+  search: Ref<string>;
+  setSearch: (query: string) => void;
+  page: Ref<number>;
+  setPage: (page: number) => void;
+  resetState: () => void;
+}
+
+export interface UseTableStateOptions {
+  sort?: SortState | null;
+  search?: string;
+  page?: number;
+}
+
+/**
+ * Composable for managing table state (sort, search, page).
+ *
+ * Use with the DataTable component's controlled props:
+ * ```vue
+ * <script setup>
+ * const { sort, search, page, setSort, setSearch, setPage } = useTableState();
+ * </script>
+ * <template>
+ *   <DataTable
+ *     :spec="spec"
+ *     :sort="sort"
+ *     :search="search"
+ *     :page="page"
+ *     @update:sort="setSort"
+ *     @update:search="setSearch"
+ *     @update:page="setPage"
+ *   />
+ * </template>
+ * ```
+ */
+export function useTableState(initialState?: UseTableStateOptions): UseTableStateReturn {
+  const sort = ref<SortState | null>(initialState?.sort ?? null);
+  const search = ref(initialState?.search ?? '');
+  const page = ref(initialState?.page ?? 0);
+
+  function setSort(newSort: SortState | null) {
+    sort.value = newSort;
+  }
+
+  function setSearch(query: string) {
+    search.value = query;
+  }
+
+  function setPage(newPage: number) {
+    page.value = newPage;
+  }
+
+  function resetState() {
+    sort.value = initialState?.sort ?? null;
+    search.value = initialState?.search ?? '';
+    page.value = initialState?.page ?? 0;
+  }
+
+  return {
+    sort,
+    setSort,
+    search,
+    setSearch,
+    page,
+    setPage,
+    resetState,
+  };
+}

package/src/context.ts

@@ -0,0 +1,33 @@
+/**
+ * Theme injection context for Vue.
+ *
+ * Provides typed injection keys and composables for accessing theme
+ * and dark mode from any descendant component within a VizThemeProvider.
+ */
+
+import type { DarkMode, ThemeConfig } from '@opendata-ai/openchart-core';
+import { type ComputedRef, computed, type InjectionKey, inject, type Ref } from 'vue';
+
+/** Injection key for the theme config ref. */
+export const VizThemeKey: InjectionKey<Ref<ThemeConfig | undefined>> = Symbol('VizTheme');
+
+/** Injection key for the dark mode ref. */
+export const VizDarkModeKey: InjectionKey<Ref<DarkMode | undefined>> = Symbol('VizDarkMode');
+
+/**
+ * Read the current theme from the nearest VizThemeProvider.
+ * Returns a computed ref that stays reactive to provider changes.
+ */
+export function useVizTheme(): ComputedRef<ThemeConfig | undefined> {
+  const theme = inject(VizThemeKey, undefined);
+  return computed(() => theme?.value);
+}
+
+/**
+ * Read the current dark mode preference from the nearest VizThemeProvider.
+ * Returns a computed ref that stays reactive to provider changes.
+ */
+export function useVizDarkMode(): ComputedRef<DarkMode | undefined> {
+  const darkMode = inject(VizDarkModeKey, undefined);
+  return computed(() => darkMode?.value);
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+/**
+ * @opendata-ai/openchart-vue
+ *
+ * Vue 3 adapter for openchart. Provides <Chart />, <DataTable />, <Graph />,
+ * and <VizThemeProvider /> components that wrap the vanilla adapter with
+ * Vue lifecycle management.
+ */
+
+// Re-export core types for convenience
+export type {
+  ChartLayout,
+  ChartSpec,
+  CompileOptions,
+  TableLayout,
+  TableSpec,
+  VizSpec,
+} from '@opendata-ai/openchart-engine';
+
+// Components
+export type { ChartProps } from './Chart';
+export { Chart } from './Chart';
+// Composables
+export type { UseChartOptions, UseChartReturn } from './composables/useChart';
+export { useChart } from './composables/useChart';
+export { useDarkMode } from './composables/useDarkMode';
+export type { GraphHandle, UseGraphReturn } from './composables/useGraph';
+export { useGraph } from './composables/useGraph';
+export type { UseTableReturn } from './composables/useTable';
+export { useTable } from './composables/useTable';
+export type { UseTableStateOptions, UseTableStateReturn } from './composables/useTableState';
+export { useTableState } from './composables/useTableState';
+// Context (injection keys and composables)
+export { useVizDarkMode, useVizTheme, VizDarkModeKey, VizThemeKey } from './context';
+export type { DataTableProps } from './DataTable';
+export { DataTable } from './DataTable';
+export type { GraphProps } from './Graph';
+export { Graph } from './Graph';
+export type { VizThemeProviderProps } from './ThemeProvider';
+export { VizThemeProvider } from './ThemeProvider';
+export type { VisualizationProps } from './Visualization';
+export { Visualization } from './Visualization';