@opendata-ai/openchart-vue 8.0.0-rc.2 → 8.0.0-rc.21

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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';
 export * from '@opendata-ai/openchart-core';
-import { MountOptions, ChartInstance, GraphInstance, TableInstance, TableState, TableMountOptions } from '@opendata-ai/openchart-vanilla';
+import { MountOptions, ChartInstance, CameraFlightOptions, GraphHighlightTarget, GraphLegendData, GraphInstance, TableInstance, TableState, TableMountOptions, GraphTooltipFormatter, 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 * as vue from 'vue';
@@ -112,6 +112,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, {
@@ -155,6 +159,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;
@@ -174,6 +182,7 @@ declare const Chart: vue.DefineComponent<vue.ExtractPropTypes<{
     style: string | CSSProperties;
     selectedElement: ElementRef;
     highlight: string[] | null;
+    editable: boolean;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
 interface ChartStoryProps {
@@ -308,17 +317,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 +369,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,10 +612,22 @@ declare const DataTable: vue.DefineComponent<vue.ExtractPropTypes<{
     page: number;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
 
+/** 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;
 }
@@ -560,6 +644,18 @@ declare const Graph: 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;
@@ -573,7 +669,20 @@ declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
     '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<GraphSpec>;
@@ -587,6 +696,18 @@ declare const Graph: 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;
@@ -596,22 +717,32 @@ declare const Graph: vue.DefineComponent<vue.ExtractPropTypes<{
         default: undefined;
     };
 }>> & Readonly<{
+    "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>;
 
-type MapFeatureEvent = {
-    id: string | number;
-    name?: string;
-    data: Record<string, unknown> | null;
-};
-
 interface MapProps {
     spec: MapSpec;
     theme?: ThemeConfig;
@@ -643,8 +774,8 @@ declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
 }>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
     [key: string]: any;
 }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
-    'mark-click': (_event: MapFeatureEvent) => true;
-    'mark-hover': (_event: MapFeatureEvent | null) => true;
+    'mark-click': (_event: MapMarkEvent) => true;
+    'mark-hover': (_event: MapMarkEvent | null) => true;
 }, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
     spec: {
         type: PropType<MapSpec>;
@@ -667,8 +798,8 @@ declare const GeoMap: vue.DefineComponent<vue.ExtractPropTypes<{
         default: undefined;
     };
 }>> & Readonly<{
-    "onMark-click"?: ((_event: MapFeatureEvent) => any) | undefined;
-    "onMark-hover"?: ((_event: MapFeatureEvent | null) => any) | undefined;
+    "onMark-click"?: ((_event: MapMarkEvent) => any) | undefined;
+    "onMark-hover"?: ((_event: MapMarkEvent | null) => any) | undefined;
 }>, {
     theme: ThemeConfig;
     darkMode: DarkMode;
@@ -734,8 +865,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;

package/dist/index.js

@@ -190,6 +190,10 @@ var Chart = defineComponent2({
     highlight: {
       type: [Array, null],
       default: void 0
+    },
+    editable: {
+      type: Boolean,
+      default: void 0
     }
   },
   emits: {
@@ -247,6 +251,7 @@ var Chart = defineComponent2({
         ...hasTextEditListener ? {
           onTextEdit: (element, oldText, newText) => emit("text-edit", element, oldText, newText)
         } : {},
+        ...props.editable != null ? { editable: props.editable } : {},
         ...props.selectedElement ? { selectedElement: props.selectedElement } : {},
         responsive: true
       };
@@ -313,6 +318,7 @@ var Chart = defineComponent2({
       [
         () => props.theme,
         () => props.darkMode,
+        () => props.editable,
         () => contextTheme?.value,
         () => contextDarkMode?.value
       ],
@@ -574,26 +580,66 @@ function useGraph() {
   function clearSearch() {
     graphRef.value?.clearSearch();
   }
-  function zoomToFit() {
-    graphRef.value?.zoomToFit();
+  function getSearchMatches() {
+    return graphRef.value?.getSearchMatches() ?? [];
+  }
+  function zoomToFit(opts) {
+    graphRef.value?.zoomToFit(opts);
+  }
+  function zoomToNode(nodeId, opts) {
+    graphRef.value?.zoomToNode(nodeId, opts);
+  }
+  function flyTo(target, opts) {
+    graphRef.value?.flyTo(target, opts);
   }
-  function zoomToNode(nodeId) {
-    graphRef.value?.zoomToNode(nodeId);
+  function centerAt(x, y, opts) {
+    graphRef.value?.centerAt(x, y, opts);
   }
-  function selectNode(nodeId) {
-    graphRef.value?.selectNode(nodeId);
+  function getCamera() {
+    return graphRef.value?.getCamera() ?? { x: 0, y: 0, k: 1 };
+  }
+  function selectNode(nodeId, opts) {
+    graphRef.value?.selectNode(nodeId, opts);
   }
   function getSelectedNodes() {
     return graphRef.value?.getSelectedNodes() ?? [];
   }
+  function highlight(target, opts) {
+    graphRef.value?.highlight(target, opts);
+  }
+  function clearHighlight() {
+    graphRef.value?.clearHighlight();
+  }
+  function getHighlight() {
+    return graphRef.value?.getHighlight() ?? null;
+  }
+  function getLegend() {
+    return graphRef.value?.getLegend() ?? null;
+  }
+  function setActiveCategories(values) {
+    graphRef.value?.setActiveCategories(values);
+  }
+  function getActiveCategories() {
+    return graphRef.value?.getActiveCategories() ?? [];
+  }
   return {
     graphRef,
     search,
     clearSearch,
+    getSearchMatches,
     zoomToFit,
     zoomToNode,
+    flyTo,
+    centerAt,
+    getCamera,
     selectNode,
-    getSelectedNodes
+    getSelectedNodes,
+    highlight,
+    clearHighlight,
+    getHighlight,
+    getLegend,
+    setActiveCategories,
+    getActiveCategories
   };
 }
 
@@ -841,6 +887,9 @@ import {
   ref as ref10,
   watch as watch8
 } from "vue";
+function tooltipOn(tooltip) {
+  return tooltip !== false;
+}
 var Graph = defineComponent5({
   name: "Graph",
   props: {
@@ -856,6 +905,18 @@ var Graph = defineComponent5({
       type: String,
       default: void 0
     },
+    tooltip: {
+      type: [Boolean, Object],
+      default: void 0
+    },
+    legend: {
+      type: [Boolean, Object],
+      default: void 0
+    },
+    fitOnLoad: {
+      type: Boolean,
+      default: void 0
+    },
     class: {
       type: String,
       default: void 0
@@ -868,12 +929,19 @@ var Graph = defineComponent5({
   emits: {
     "node-click": (_node) => true,
     "node-double-click": (_node) => true,
-    "selection-change": (_nodeIds) => true
+    "node-hover": (_node) => true,
+    "edge-hover": (_edge) => true,
+    "selection-change": (_nodeIds) => true,
+    "legend-hover": (_entry) => true,
+    "legend-toggle": (_activeValues) => true,
+    "highlight-change": (_nodeIds) => true,
+    "camera-change": (_camera) => true
   },
   setup(props, { emit, expose }) {
     const containerRef = ref10(null);
     let instance = null;
     let prevSpec = "";
+    let mountedOnce = false;
     const contextTheme = inject5(VizThemeKey, void 0);
     const contextDarkMode = inject5(VizDarkModeKey, void 0);
     function resolveTheme() {
@@ -882,19 +950,36 @@ var Graph = defineComponent5({
     function resolveDarkMode() {
       return props.darkMode ?? contextDarkMode?.value;
     }
+    const stableTooltipFormatter = (item, defaults) => {
+      const t = props.tooltip;
+      const fn = t && typeof t === "object" ? t.formatter : void 0;
+      return fn ? fn(item, defaults) : defaults;
+    };
     function mountGraph() {
       const container = containerRef.value;
       if (!container) return;
+      const tooltipOption = tooltipOn(props.tooltip) ? { formatter: stableTooltipFormatter } : false;
       const options = {
         theme: resolveTheme(),
         darkMode: resolveDarkMode(),
+        tooltip: tooltipOption,
+        legend: props.legend,
+        fitOnLoad: props.fitOnLoad,
         onNodeClick: (node) => emit("node-click", node),
         onNodeDoubleClick: (node) => emit("node-double-click", node),
+        onNodeHover: (node) => emit("node-hover", node),
+        onEdgeHover: (edge) => emit("edge-hover", edge),
         onSelectionChange: (nodeIds) => emit("selection-change", nodeIds),
-        responsive: true
+        onLegendHover: (entry) => emit("legend-hover", entry),
+        onLegendToggle: (activeValues) => emit("legend-toggle", activeValues),
+        onHighlightChange: (nodeIds) => emit("highlight-change", nodeIds),
+        onCameraChange: (camera) => emit("camera-change", camera),
+        responsive: true,
+        suppressEntrance: mountedOnce
       };
       instance = createGraph(container, props.spec, options);
       prevSpec = JSON.stringify(props.spec);
+      mountedOnce = true;
     }
     function destroyGraph() {
       instance?.destroy();
@@ -908,18 +993,51 @@ var Graph = defineComponent5({
       clearSearch() {
         instance?.clearSearch();
       },
-      zoomToFit() {
-        instance?.zoomToFit();
+      getSearchMatches() {
+        return instance?.getSearchMatches() ?? [];
+      },
+      zoomToFit(opts) {
+        instance?.zoomToFit(opts);
+      },
+      zoomToNode(nodeId, opts) {
+        instance?.zoomToNode(nodeId, opts);
+      },
+      flyTo(target, opts) {
+        instance?.flyTo(target, opts);
+      },
+      centerAt(x, y, opts) {
+        instance?.centerAt(x, y, opts);
       },
-      zoomToNode(nodeId) {
-        instance?.zoomToNode(nodeId);
+      getCamera() {
+        return instance?.getCamera() ?? { x: 0, y: 0, k: 1 };
       },
-      selectNode(nodeId) {
-        instance?.selectNode(nodeId);
+      selectNode(nodeId, opts) {
+        instance?.selectNode(nodeId, opts);
       },
       getSelectedNodes() {
         return instance?.getSelectedNodes() ?? [];
       },
+      highlight(target, opts) {
+        instance?.highlight(target, opts);
+      },
+      clearHighlight() {
+        instance?.clearHighlight();
+      },
+      getHighlight() {
+        return instance?.getHighlight() ?? null;
+      },
+      getLegend() {
+        return instance?.getLegend() ?? null;
+      },
+      setActiveCategories(values) {
+        instance?.setActiveCategories(values);
+      },
+      getActiveCategories() {
+        return instance?.getActiveCategories() ?? [];
+      },
+      updateVisuals(spec) {
+        instance?.updateVisuals(spec);
+      },
       get instance() {
         return instance;
       }
@@ -966,7 +1084,9 @@ var Graph = defineComponent5({
 });
 
 // src/Map.ts
-import { createMap } from "@opendata-ai/openchart-vanilla";
+import {
+  createMap
+} from "@opendata-ai/openchart-vanilla";
 import {
   defineComponent as defineComponent6,
   h as h6,