@opendata-ai/openchart-vue 8.0.0-rc.8 → 8.0.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { BarListSpec, ThemeConfig, DarkMode, ChartSpec, LayerSpec, GraphSpec, ElementRef, MarkEvent, Annotation, TextAnnotation, AnnotationOffset, ElementEdit, MapSpec, ChartLayout, TableSpec, SortState, SankeySpec, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
+import { BarListSpec, ThemeConfig, DarkMode, ChartSpec, LayerSpec, GraphSpec, ElementRef, MarkEvent, Annotation, TextAnnotation, AnnotationOffset, ElementEdit, GeoMapSpec, ChartLayout, TableSpec, SortState, SankeySpec, TileMapSpec, VizSpec } from '@opendata-ai/openchart-core';
 export * from '@opendata-ai/openchart-core';
-import { MountOptions, ChartInstance, GraphInstance, TableInstance, TableState, TableMountOptions, MapMarkEvent } from '@opendata-ai/openchart-vanilla';
-export { JPGExportOptions, PNGExportOptions, exportCSV, exportJPG, exportPNG, exportSVG } from '@opendata-ai/openchart-vanilla';
-export { ChartRenderer, CompileResult, CompiledGraphEdge, CompiledGraphNode, GraphCompilation, NormalizedBarListSpec, NormalizedChartSpec, NormalizedChrome, NormalizedGraphSpec, NormalizedMapSpec, NormalizedSankeySpec, NormalizedSpec, NormalizedTableSpec, SimulationConfig, ValidationError, ValidationErrorCode, ValidationResult, clearRenderers, compile, compileBarList, compileChart, compileGraph, compileMap, compileSankey, compileTable, getChartRenderer, normalizeSpec, registerChartRenderer, validateSpec } from '@opendata-ai/openchart-engine';
+import { MountOptions, ChartInstance, CameraFlightOptions, GraphHighlightTarget, GraphLegendData, GraphInstance, TableInstance, TableState, TableMountOptions, GeoMapMarkEvent, GraphTooltipFormatter } from '@opendata-ai/openchart-vanilla';
+export { JPGExportOptions, PNGExportOptions, SVGExportOptions, SpecSequenceOptions, exportCSV, exportJPG, exportPNG, exportSVG, exportSVGWithFonts, exportSpecSequence } from '@opendata-ai/openchart-vanilla';
+export { ChartRenderer, CompileResult, CompiledGraphEdge, CompiledGraphNode, GraphCompilation, NormalizedBarListSpec, NormalizedChartSpec, NormalizedChrome, NormalizedGeoMapSpec, NormalizedGraphSpec, NormalizedSankeySpec, NormalizedSpec, NormalizedTableSpec, NormalizedTileMapSpec, SimulationConfig, ValidationError, ValidationErrorCode, ValidationResult, clearRenderers, compile, compileBarList, compileChart, compileGeoMap, compileGraph, compileSankey, compileTable, compileTileMap, getChartRenderer, normalizeSpec, registerChartRenderer, validateSpec } from '@opendata-ai/openchart-engine';
 import * as vue from 'vue';
 import { PropType, CSSProperties, VNode, Ref, ShallowRef, InjectionKey, ComputedRef } from 'vue';
 import { ChartStoryOptions } from '@opendata-ai/openchart-vanilla/story';
@@ -80,6 +80,8 @@ interface ChartProps {
     spec: ChartSpec | LayerSpec | GraphSpec;
     theme?: ThemeConfig;
     darkMode?: DarkMode;
+    /** Rendering backend for point marks; see the vanilla `MountOptions.renderer`. */
+    renderer?: 'auto' | 'svg' | 'canvas';
     class?: string;
     style?: string | CSSProperties;
 }
@@ -96,6 +98,10 @@ declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<DarkMode>;
         default: undefined;
     };
+    renderer: {
+        type: PropType<"auto" | "svg" | "canvas">;
+        default: undefined;
+    };
     class: {
         type: StringConstructor;
         default: undefined;
@@ -112,6 +118,10 @@ declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<string[] | null>;
         default: undefined;
     };
+    editable: {
+        type: PropType<boolean>;
+        default: undefined;
+    };
 }>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
@@ -139,6 +149,10 @@ declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<DarkMode>;
         default: undefined;
     };
+    renderer: {
+        type: PropType<"auto" | "svg" | "canvas">;
+        default: undefined;
+    };
     class: {
         type: StringConstructor;
         default: undefined;
@@ -155,6 +169,10 @@ declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<string[] | null>;
         default: undefined;
     };
+    editable: {
+        type: PropType<boolean>;
+        default: undefined;
+    };
 }>> & Readonly<{
     onSelect?: ((_element: ElementRef) => any) | undefined;
     "onMark-click"?: ((_event: MarkEvent) => any) | undefined;
@@ -172,12 +190,14 @@ declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
     darkMode: DarkMode;
     class: string;
     style: string | CSSProperties;
+    renderer: "auto" | "canvas" | "svg";
     selectedElement: ElementRef;
     highlight: string[] | null;
+    editable: boolean;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
 interface ChartStoryProps {
-    spec: ChartSpec | LayerSpec | GraphSpec | MapSpec;
+    spec: ChartSpec | LayerSpec | GraphSpec | GeoMapSpec;
     steps: ChartStoryOptions['steps'];
     narrative?: VNode[];
     step?: number;
@@ -187,7 +207,7 @@ interface ChartStoryProps {
 }
 declare const ChartStory: vue.DefineComponent<vue.ExtractPropTypes<{
     spec: {
-        type: PropType<ChartSpec | LayerSpec | GraphSpec | MapSpec>;
+        type: PropType<ChartSpec | LayerSpec | GraphSpec | GeoMapSpec>;
         required: true;
     };
     steps: {
@@ -218,7 +238,7 @@ declare const ChartStory: vue.DefineComponent<vue.ExtractPropTypes<{
     [key: string]: any;
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     spec: {
-        type: PropType<ChartSpec | LayerSpec | GraphSpec | MapSpec>;
+        type: PropType<ChartSpec | LayerSpec | GraphSpec | GeoMapSpec>;
         required: true;
     };
     steps: {
@@ -271,6 +291,8 @@ interface UseChartOptions {
     onDataPointClick?: MountOptions['onDataPointClick'];
     /** Enable responsive resizing. Defaults to true. */
     responsive?: boolean;
+    /** Rendering backend for point marks; see the vanilla `MountOptions.renderer`. */
+    renderer?: MountOptions['renderer'];
 }
 interface UseChartReturn {
     /** Template ref to attach to the container div. */
@@ -308,17 +330,48 @@ 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.
+ * (search, zoom, select, fly, highlight) for programmatic control of the
+ * graph instance. The full vanilla GraphInstance API is threaded through.
  */
 
+/** Camera transform components (graph-space). */
+type GraphCamera = {
+    x: number;
+    y: number;
+    k: number;
+};
 /** 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;
+    getSearchMatches: () => string[];
+    zoomToFit: (opts?: CameraFlightOptions & {
+        padding?: number;
+    }) => void;
+    zoomToNode: (nodeId: string, opts?: CameraFlightOptions & {
+        scale?: number;
+    }) => void;
+    flyTo: (target: {
+        x: number;
+        y: number;
+        k?: number;
+    }, opts?: CameraFlightOptions) => void;
+    centerAt: (x: number, y: number, opts?: CameraFlightOptions) => void;
+    getCamera: () => GraphCamera;
+    selectNode: (nodeId: string, opts?: {
+        fly?: boolean;
+    } & CameraFlightOptions) => void;
     getSelectedNodes: () => string[];
+    highlight: (target: GraphHighlightTarget, opts?: {
+        dimOpacity?: number;
+    }) => void;
+    clearHighlight: () => void;
+    getHighlight: () => string[] | null;
+    getLegend: () => GraphLegendData | null;
+    setActiveCategories: (values: string[]) => void;
+    getActiveCategories: () => string[];
+    /** Re-compile encoding/legend/chrome without restarting the simulation. */
+    updateVisuals: (spec: GraphSpec) => void;
     /** The underlying GraphInstance from the vanilla adapter. */
     instance: GraphInstance | null;
 }
@@ -329,14 +382,46 @@ interface UseGraphReturn {
     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;
+    /** Node ids currently matching the active search query. */
+    getSearchMatches: () => string[];
+    /** Zoom to fit all nodes in view. Animated by default; `{ duration: 0 }` snaps. */
+    zoomToFit: (opts?: CameraFlightOptions & {
+        padding?: number;
+    }) => void;
+    /** Fly to a node and zoom in (default scale 2). */
+    zoomToNode: (nodeId: string, opts?: CameraFlightOptions & {
+        scale?: number;
+    }) => void;
+    /** Fly the camera to a graph-space target. */
+    flyTo: (target: {
+        x: number;
+        y: number;
+        k?: number;
+    }, opts?: CameraFlightOptions) => void;
+    /** Center the camera on a graph-space point (keeps current zoom). */
+    centerAt: (x: number, y: number, opts?: CameraFlightOptions) => void;
+    /** Current camera transform. */
+    getCamera: () => GraphCamera;
+    /** Select a node by id; `{ fly: true }` also flies to it. */
+    selectNode: (nodeId: string, opts?: {
+        fly?: boolean;
+    } & CameraFlightOptions) => void;
     /** Get the currently selected node ids. */
     getSelectedNodes: () => string[];
+    /** Emphasize a set of nodes; eased via the focus model. */
+    highlight: (target: GraphHighlightTarget, opts?: {
+        dimOpacity?: number;
+    }) => void;
+    /** Clear any programmatic highlight (and legend toggles). */
+    clearHighlight: () => void;
+    /** The currently highlighted node ids, or null when nothing is highlighted. */
+    getHighlight: () => string[] | null;
+    /** Headless snapshot of the legend. */
+    getLegend: () => GraphLegendData | null;
+    /** Set the active category filter declaratively (replaces legend toggle state). */
+    setActiveCategories: (values: string[]) => void;
+    /** Current active category values (empty = all active, no filter). */
+    getActiveCategories: () => string[];
 }
 /**
  * Composable for imperative graph control.
@@ -540,16 +625,16 @@ declare const DataTable: vue.DefineComponent<vue.ExtractPropTypes<{
     page: number;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
-interface GraphProps {
-    spec: GraphSpec;
+interface GeoMapProps {
+    spec: GeoMapSpec;
     theme?: ThemeConfig;
     darkMode?: DarkMode;
     class?: string;
     style?: string | CSSProperties;
 }
-declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
+declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
     spec: {
-        type: PropType<GraphSpec>;
+        type: PropType<GeoMapSpec>;
         required: true;
     };
     theme: {
@@ -571,12 +656,11 @@ declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
 }>, () => 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;
+    'mark-click': (_event: GeoMapMarkEvent) => true;
+    'mark-hover': (_event: GeoMapMarkEvent | null) => true;
 }, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     spec: {
-        type: PropType<GraphSpec>;
+        type: PropType<GeoMapSpec>;
         required: true;
     };
     theme: {
@@ -596,9 +680,8 @@ declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
         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;
+    "onMark-click"?: ((_event: GeoMapMarkEvent) => any) | undefined;
+    "onMark-hover"?: ((_event: GeoMapMarkEvent | null) => any) | undefined;
 }>, {
     theme: ThemeConfig;
     darkMode: DarkMode;
@@ -606,16 +689,28 @@ declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
     style: string | CSSProperties;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
-interface MapProps {
-    spec: MapSpec;
+/** Tooltip prop: `false` off, `true` default, or an object with a formatter. */
+type GraphTooltipProp = boolean | {
+    formatter?: GraphTooltipFormatter;
+};
+/** Legend prop: `false` off, `true` default, or an object toggling interactivity/counts. */
+type GraphLegendProp = boolean | {
+    interactive?: boolean;
+    counts?: boolean;
+};
+interface GraphProps {
+    spec: GraphSpec;
     theme?: ThemeConfig;
     darkMode?: DarkMode;
+    tooltip?: GraphTooltipProp;
+    legend?: GraphLegendProp;
+    fitOnLoad?: boolean;
     class?: string;
     style?: string | CSSProperties;
 }
-declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
+declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
     spec: {
-        type: PropType<MapSpec>;
+        type: PropType<GraphSpec>;
         required: true;
     };
     theme: {
@@ -626,6 +721,18 @@ declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<DarkMode>;
         default: undefined;
     };
+    tooltip: {
+        type: PropType<GraphTooltipProp>;
+        default: undefined;
+    };
+    legend: {
+        type: PropType<GraphLegendProp>;
+        default: undefined;
+    };
+    fitOnLoad: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
     class: {
         type: StringConstructor;
         default: undefined;
@@ -637,11 +744,25 @@ declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
 }>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
-    'mark-click': (_event: MapMarkEvent) => true;
-    'mark-hover': (_event: MapMarkEvent | null) => true;
+    'node-click': (_node: Record<string, unknown>) => true;
+    'node-double-click': (_node: Record<string, unknown>) => true;
+    'node-hover': (_node: Record<string, unknown> | null) => true;
+    'edge-hover': (_edge: Record<string, unknown> | null) => true;
+    'selection-change': (_nodeIds: string[]) => true;
+    'legend-hover': (_entry: {
+        field: string;
+        value: string;
+    } | null) => true;
+    'legend-toggle': (_activeValues: string[]) => true;
+    'highlight-change': (_nodeIds: string[] | null) => true;
+    'camera-change': (_camera: {
+        x: number;
+        y: number;
+        k: number;
+    }) => true;
 }, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     spec: {
-        type: PropType<MapSpec>;
+        type: PropType<GraphSpec>;
         required: true;
     };
     theme: {
@@ -652,6 +773,18 @@ declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
         type: PropType<DarkMode>;
         default: undefined;
     };
+    tooltip: {
+        type: PropType<GraphTooltipProp>;
+        default: undefined;
+    };
+    legend: {
+        type: PropType<GraphLegendProp>;
+        default: undefined;
+    };
+    fitOnLoad: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
     class: {
         type: StringConstructor;
         default: undefined;
@@ -661,13 +794,30 @@ declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
         default: undefined;
     };
 }>> & Readonly<{
-    "onMark-click"?: ((_event: MapMarkEvent) => any) | undefined;
-    "onMark-hover"?: ((_event: MapMarkEvent | null) => any) | undefined;
+    "onLegend-toggle"?: ((_activeValues: string[]) => any) | undefined;
+    "onNode-click"?: ((_node: Record<string, unknown>) => any) | undefined;
+    "onNode-double-click"?: ((_node: Record<string, unknown>) => any) | undefined;
+    "onNode-hover"?: ((_node: Record<string, unknown> | null) => any) | undefined;
+    "onEdge-hover"?: ((_edge: Record<string, unknown> | null) => any) | undefined;
+    "onSelection-change"?: ((_nodeIds: string[]) => any) | undefined;
+    "onLegend-hover"?: ((_entry: {
+        field: string;
+        value: string;
+    } | null) => any) | undefined;
+    "onHighlight-change"?: ((_nodeIds: string[] | null) => any) | undefined;
+    "onCamera-change"?: ((_camera: {
+        x: number;
+        y: number;
+        k: number;
+    }) => any) | undefined;
 }>, {
     theme: ThemeConfig;
     darkMode: DarkMode;
     class: string;
     style: string | CSSProperties;
+    legend: GraphLegendProp;
+    tooltip: GraphTooltipProp;
+    fitOnLoad: boolean;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
 interface SankeyProps {
@@ -728,8 +878,8 @@ declare const Sankey: vue.DefineComponent<vue.ExtractPropTypes<{
     };
 }>> & Readonly<{
     "onNode-click"?: ((_node: Record<string, unknown>) => any) | undefined;
-    "onLink-click"?: ((_link: Record<string, unknown>) => any) | undefined;
     "onNode-hover"?: ((_node: Record<string, unknown> | null) => any) | undefined;
+    "onLink-click"?: ((_link: Record<string, unknown>) => any) | undefined;
     "onLink-hover"?: ((_link: Record<string, unknown> | null) => any) | undefined;
 }>, {
     theme: ThemeConfig;
@@ -895,4 +1045,4 @@ declare const Visualization: vue.DefineComponent<vue.ExtractPropTypes<{
     style: string | CSSProperties;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
-export { BarList, type BarListProps, type BarListRowEvent, Chart, type ChartProps, ChartStory, type ChartStoryProps, DataTable, type DataTableProps, GeoMap, Graph, type GraphHandle, type GraphProps, type MapProps, Sankey, type SankeyProps, TileMap, type TileMapProps, 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 };
+export { BarList, type BarListProps, type BarListRowEvent, Chart, type ChartProps, ChartStory, type ChartStoryProps, DataTable, type DataTableProps, GeoMap, type GeoMapProps, Graph, type GraphHandle, type GraphProps, Sankey, type SankeyProps, TileMap, type TileMapProps, 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 };