@opendata-ai/openchart-vue 2.0.0

package/README.md

@@ -0,0 +1,98 @@
+# @opendata-ai/openchart-vue
+
+Vue 3 components for OpenChart. Renders chart specs as SVG and table specs as DOM, with Vue reactivity and lifecycle management.
+
+## Install
+
+```bash
+npm install @opendata-ai/openchart-vue @opendata-ai/openchart-core
+```
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { Chart } from '@opendata-ai/openchart-vue';
+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');
+</script>
+
+<template>
+  <Chart :spec="spec" />
+</template>
+```
+
+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
+
+When you're rendering arbitrary `VizSpec` values and don't know the type ahead of time, `Visualization` inspects the spec and routes to the correct component.
+
+```vue
+<script setup lang="ts">
+import { Visualization } from '@opendata-ai/openchart-vue';
+import type { VizSpec } from '@opendata-ai/openchart-core';
+
+const props = defineProps<{ spec: VizSpec }>();
+</script>
+
+<template>
+  <!-- Renders Chart, DataTable, or Graph based on spec.type -->
+  <Visualization :spec="props.spec" />
+</template>
+```
+
+If you need event handlers or component-specific props, use the specific component directly instead.
+
+## Dark mode and theming
+
+Wrap components with `VizThemeProvider` to set theme and dark mode for all child visualizations. It uses Vue's `provide`/`inject` under the hood, so all `Chart`, `DataTable`, and `Graph` components inside the provider inherit its values.
+
+```vue
+<script setup lang="ts">
+import { VizThemeProvider, Chart } from '@opendata-ai/openchart-vue';
+</script>
+
+<template>
+  <VizThemeProvider :theme="myTheme" dark-mode="auto">
+    <Chart :spec="spec1" />
+    <Chart :spec="spec2" />
+  </VizThemeProvider>
+</template>
+```
+
+`darkMode` accepts `"auto"` (follows system preference), `"force"` (always dark), or `"off"` (always light).
+
+For one-off overrides, pass `dark-mode` or `theme` directly on an individual component. Component-level props take priority over the provider.
+
+## Composables
+
+For lower-level control or custom rendering:
+
+- `useChart(spec, options?)` - Returns `{ containerRef, chart, layout }`. Bind `containerRef` via `ref`
+- `useGraph()` - Returns `{ componentRef, search, zoomToFit, ... }`. Bind to `<Graph>` via `ref`
+- `useTable(spec, options?)` - Returns `{ containerRef, table, layout }`. Bind `containerRef` via `ref`
+- `useTableState(options?)` - Manages table sorting, pagination, and search state
+- `useDarkMode(preference?)` - Resolves dark mode preference against system settings
+
+Context composables for reading provider values directly:
+
+- `useVizTheme()` - Returns the theme from the nearest `VizThemeProvider`
+- `useVizDarkMode()` - Returns the dark mode preference from the nearest provider

package/dist/index.d.ts

@@ -0,0 +1,521 @@
+export { ChartLayout, ChartSpec, CompileOptions, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-engine';
+import * as vue from 'vue';
+import { PropType, CSSProperties, Ref, ShallowRef, InjectionKey, ComputedRef } from 'vue';
+import { ChartSpec, GraphSpec, ThemeConfig, DarkMode, MarkEvent, Annotation, TextAnnotation, AnnotationOffset, ElementEdit, ChartLayout, TableSpec, SortState, VizSpec } from '@opendata-ai/openchart-core';
+import { MountOptions, ChartInstance, GraphInstance, TableInstance, TableState, TableMountOptions } from '@opendata-ai/openchart-vanilla';
+
+interface ChartProps {
+    spec: ChartSpec | GraphSpec;
+    theme?: ThemeConfig;
+    darkMode?: DarkMode;
+    class?: string;
+    style?: string | CSSProperties;
+}
+declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<ChartSpec | GraphSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    'mark-click': (_event: MarkEvent) => true;
+    'mark-hover': (_event: MarkEvent) => true;
+    'mark-leave': () => true;
+    'legend-toggle': (_series: string, _visible: boolean) => true;
+    'annotation-click': (_annotation: Annotation, _event: MouseEvent) => true;
+    'annotation-edit': (_annotation: TextAnnotation, _updatedOffset: AnnotationOffset) => true;
+    edit: (_edit: ElementEdit) => true;
+    'data-point-click': (_data: Record<string, unknown>) => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<ChartSpec | GraphSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onMark-click"?: ((_event: MarkEvent) => any) | undefined;
+    "onMark-hover"?: ((_event: MarkEvent) => any) | undefined;
+    "onMark-leave"?: (() => any) | undefined;
+    "onLegend-toggle"?: ((_series: string, _visible: boolean) => any) | undefined;
+    "onAnnotation-click"?: ((_annotation: Annotation, _event: MouseEvent) => any) | undefined;
+    "onAnnotation-edit"?: ((_annotation: TextAnnotation, _updatedOffset: AnnotationOffset) => any) | undefined;
+    onEdit?: ((_edit: ElementEdit) => any) | undefined;
+    "onData-point-click"?: ((_data: Record<string, unknown>) => any) | undefined;
+}>, {
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    class: string;
+    style: string | CSSProperties;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * 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.
+ */
+
+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;
+}
+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.
+ */
+declare function useChart(spec: Ref<ChartSpec | GraphSpec>, options?: UseChartOptions): UseChartReturn;
+
+/**
+ * useDarkMode: composable that resolves a DarkMode preference to a boolean.
+ *
+ * - "force" -> true
+ * - "off" -> false
+ * - "auto" -> matches system preference (reactive to changes)
+ */
+
+/**
+ * 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.
+ */
+declare function useDarkMode(mode: Ref<DarkMode | undefined>): Ref<boolean>;
+
+/**
+ * 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.
+ */
+
+/** Handle exposed by Graph component via expose(). */
+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;
+}
+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>
+ * ```
+ */
+declare function useGraph(): UseGraphReturn;
+
+/**
+ * useTable: composable for manual table lifecycle control.
+ *
+ * Attaches to a container ref, mounts a vanilla table instance,
+ * and exposes the instance and current state.
+ */
+
+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.
+ */
+declare function useTable(spec: Ref<TableSpec>, options?: TableMountOptions): UseTableReturn;
+
+/**
+ * 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.
+ */
+
+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;
+}
+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>
+ * ```
+ */
+declare function useTableState(initialState?: UseTableStateOptions): UseTableStateReturn;
+
+/**
+ * Theme injection context for Vue.
+ *
+ * Provides typed injection keys and composables for accessing theme
+ * and dark mode from any descendant component within a VizThemeProvider.
+ */
+
+/** Injection key for the theme config ref. */
+declare const VizThemeKey: InjectionKey<Ref<ThemeConfig | undefined>>;
+/** Injection key for the dark mode ref. */
+declare const VizDarkModeKey: InjectionKey<Ref<DarkMode | undefined>>;
+/**
+ * Read the current theme from the nearest VizThemeProvider.
+ * Returns a computed ref that stays reactive to provider changes.
+ */
+declare function useVizTheme(): ComputedRef<ThemeConfig | undefined>;
+/**
+ * Read the current dark mode preference from the nearest VizThemeProvider.
+ * Returns a computed ref that stays reactive to provider changes.
+ */
+declare function useVizDarkMode(): ComputedRef<DarkMode | undefined>;
+
+interface DataTableProps {
+    spec: TableSpec;
+    theme?: ThemeConfig;
+    darkMode?: DarkMode;
+    class?: string;
+    style?: string | CSSProperties;
+    sort?: SortState | null;
+    search?: string;
+    page?: number;
+}
+declare const DataTable: vue.DefineComponent<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<TableSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+    sort: {
+        type: PropType<SortState | null>;
+        default: undefined;
+    };
+    search: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    page: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    'row-click': (_row: Record<string, unknown>) => true;
+    'update:sort': (_sort: SortState | null) => true;
+    'update:search': (_query: string) => true;
+    'update:page': (_page: number) => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<TableSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+    sort: {
+        type: PropType<SortState | null>;
+        default: undefined;
+    };
+    search: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    page: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onRow-click"?: ((_row: Record<string, unknown>) => any) | undefined;
+    "onUpdate:sort"?: ((_sort: SortState | null) => any) | undefined;
+    "onUpdate:search"?: ((_query: string) => any) | undefined;
+    "onUpdate:page"?: ((_page: number) => any) | undefined;
+}>, {
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    class: string;
+    style: string | CSSProperties;
+    sort: SortState | null;
+    search: string;
+    page: number;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+interface GraphProps {
+    spec: GraphSpec;
+    theme?: ThemeConfig;
+    darkMode?: DarkMode;
+    class?: string;
+    style?: string | CSSProperties;
+}
+declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<GraphSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
+    'node-click': (_node: Record<string, unknown>) => true;
+    'node-double-click': (_node: Record<string, unknown>) => true;
+    'selection-change': (_nodeIds: string[]) => true;
+}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<GraphSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+}>> & Readonly<{
+    "onNode-click"?: ((_node: Record<string, unknown>) => any) | undefined;
+    "onNode-double-click"?: ((_node: Record<string, unknown>) => any) | undefined;
+    "onSelection-change"?: ((_nodeIds: string[]) => any) | undefined;
+}>, {
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    class: string;
+    style: string | CSSProperties;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+interface VizThemeProviderProps {
+    theme: ThemeConfig | undefined;
+    darkMode?: DarkMode;
+}
+declare const VizThemeProvider: vue.DefineComponent<vue.ExtractPropTypes<{
+    theme: {
+        type: PropType<ThemeConfig | undefined>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | undefined, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    theme: {
+        type: PropType<ThemeConfig | undefined>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    theme: ThemeConfig | undefined;
+    darkMode: DarkMode;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+interface VisualizationProps {
+    spec: VizSpec;
+    theme?: ThemeConfig;
+    darkMode?: DarkMode;
+    class?: string;
+    style?: string | CSSProperties;
+}
+declare const Visualization: vue.DefineComponent<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<VizSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    spec: {
+        type: PropType<VizSpec>;
+        required: true;
+    };
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: undefined;
+    };
+    darkMode: {
+        type: PropType<DarkMode>;
+        default: undefined;
+    };
+    class: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    style: {
+        type: PropType<string | CSSProperties>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    theme: ThemeConfig;
+    darkMode: DarkMode;
+    class: string;
+    style: string | CSSProperties;
+}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+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, VizDarkModeKey, VizThemeKey, VizThemeProvider, type VizThemeProviderProps, useChart, useDarkMode, useGraph, useTable, useTableState, useVizDarkMode, useVizTheme };