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

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { ChartLayout, ChartSpec, CompileOptions, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-engine';
-import { BarListSpec, BarListLayout, ThemeConfig, DarkMode, GraphSpec, MapSpec, MapLayout, RectMark, Mark, BarTableCell, CategoryTableCell, TableCell, FlagTableCell, HeatmapTableCell, ImageTableCell, SparklineTableCell, TextTableCell, SankeySpec, SankeyLayout, ChartLayout, TableSpec, SortState, TableLayout, TileMapSpec, TileMapLayout, TooltipContent, ResolvedYouDrawIt } from '@opendata-ai/openchart-core';
-import { J as JPGExportOptions, S as SVGExportOptions, C as Camera } from './mount-CUKQLeqD.js';
-export { a as ChartInstance, E as ExportOptions, M as MountOptions, P as PNGExportOptions, U as UpdateOptions, c as createChart, e as exportCSV, b as exportJPG, d as exportPNG, f as exportSVG, g as exportSVGWithFonts } from './mount-CUKQLeqD.js';
+import { BarListSpec, BarListLayout, ThemeConfig, DarkMode, ChartLayout, ChartSpec, LayerSpec, AnimationEase, GraphSpec, TooltipContent, GeoMapSpec, GeoMapLayout, RectMark, Mark, BarTableCell, CategoryTableCell, TableCell, FlagTableCell, HeatmapTableCell, ImageTableCell, SparklineTableCell, TextTableCell, SankeySpec, SankeyLayout, TableSpec, SortState, TableLayout, TileMapSpec, TileMapLayout, ResolvedYouDrawIt } from '@opendata-ai/openchart-core';
+import { J as JPGExportOptions, S as SVGExportOptions, C as Camera } from './mount-CL-nA0f-.js';
+export { a as ChartInstance, E as ExportOptions, M as MountOptions, P as PNGExportOptions, U as UpdateOptions, c as createChart, e as exportCSV, b as exportJPG, d as exportPNG, f as exportSVG, g as exportSVGWithFonts } from './mount-CL-nA0f-.js';
 import { Placement } from '@floating-ui/dom';
+import './export-gif.js';
 
 /**
  * BarList mount API: the main entry point for vanilla JS barlist usage.
@@ -38,6 +39,142 @@ interface BarListInstance {
 }
 declare function createBarList(container: HTMLElement, spec: BarListSpec, options?: BarListMountOptions): BarListInstance;
 
+/**
+ * Exports for charts rendered in canvas mark mode.
+ *
+ * On screen, canvas mode splits the figure across two surfaces: a `<canvas>`
+ * painting background, gridlines and dots, and an SVG carrying axes, trendline,
+ * annotations and chrome. Serializing the SVG alone would export a chart with
+ * no data in it, so every format has to re-materialize the missing half.
+ *
+ * Two strategies, chosen by point count:
+ *
+ * - **Vector** (at or below `VECTOR_EXPORT_MAX_POINTS`): re-render the layout
+ *   as if canvas mode had never been asked for. `renderChartSVG` keys ONLY on
+ *   `opts.canvasMarks`, never on `layout.markRenderMode`, so simply omitting
+ *   the option yields a full-fidelity SVG by construction -- true gradients,
+ *   vector gridlines, real background rect, one `<circle>` per dot. Pixel-
+ *   identical to what an SVG-mode chart of the same spec exports.
+ *
+ * - **Raster marks** (above it): keep the SVG vector for everything except the
+ *   dots, and inline one canvas pass of the marks as an `<image>`. 50,000
+ *   `<circle>` elements is not a file anyone wants; the gridlines, axes and
+ *   text stay crisp and only the dot cloud rasterizes.
+ */
+
+/**
+ * Point count above which SVG/PNG export inlines the marks as a raster
+ * `<image>` instead of emitting one `<circle>` each.
+ *
+ * A judgment cap. Below it the per-element cost is worth full vector fidelity;
+ * above it the file size and the consuming editor's patience are not.
+ */
+declare const VECTOR_EXPORT_MAX_POINTS = 5000;
+/**
+ * Materialize a canvas-mode layout into a single self-contained SVG element.
+ *
+ * This is what every export format consumes: SVG serializes it directly, and
+ * PNG/JPG/GIF rasterize it. Raster formats always take the vector path
+ * regardless of point count -- they are becoming pixels anyway, so the one-shot
+ * cost of the full SVG buys pixel-parity with SVG mode for free.
+ *
+ * This is also why the GIF path needs no canvas compositing. Handing the
+ * encoder a complete SVG means the existing frame pipeline works unchanged: no
+ * per-frame `drawImage` of the live mark canvas, no background sourced from a
+ * suppressed rect, no second code path to keep in sync with the first.
+ */
+declare function materializeCanvasModeSVG(layout: ChartLayout, opts?: {
+    forceVector?: boolean;
+}): SVGElement;
+
+/**
+ * Multi-spec ("keyframe") GIF export.
+ *
+ * The single-chart GIF export (`exportGIF`) reproduces ONE chart's entrance
+ * animation. Some charts animate a different way: a component swaps in a whole
+ * new spec on a timer (e.g. a year-by-year stepper), and the on-screen chart
+ * tweens between them via `chart.update()` (bars grow/shrink smoothly). The DATA
+ * changes across frames, and the motion is the update transition — neither of
+ * which `exportGIF` can express.
+ *
+ * `exportSpecSequence` reproduces that. It mounts one offscreen chart, holds the
+ * first spec, then walks the rest by driving `chart.beginManualUpdate(spec)` and
+ * stepping the returned transition frame-by-frame (no rAF clock), rasterizing
+ * each step. Between transitions it holds the settled frame for `dwellMs`. The
+ * result is the same bar tween the reader sees on screen, captured to GIF.
+ *
+ * `gifenc` is an optional peer dependency, loaded dynamically.
+ */
+
+interface SpecSequenceOptions {
+    /** DPI scaling factor, matching PNG export. Defaults to 2. */
+    dpi?: number;
+    /** Frames per second for the tween between specs. Defaults to 25. */
+    fps?: number;
+    /** How long to hold each spec's settled frame, in ms. Defaults to 1200 (the common stepper cadence). */
+    dwellMs?: number;
+    /**
+     * Loop behavior, same semantics as `exportGIF`:
+     * - `false` / omitted: play once, then hold the final frame
+     * - `true`: loop forever
+     * - a number: loop that many times, then hold
+     */
+    loop?: boolean | number;
+    /** Render width in CSS px. Required — pass the on-screen chart width so the export matches. */
+    width: number;
+    /** Render height in CSS px. Required — pass the on-screen chart height so the export matches. */
+    height: number;
+    /** Dark mode for the rendered charts. Defaults to 'off' (light). */
+    darkMode?: 'auto' | 'force' | 'off';
+    /**
+     * Rendering backend for point marks; see `MountOptions.renderer`. Pass the
+     * SAME value your on-screen chart mounts with so the export matches.
+     */
+    renderer?: 'auto' | 'svg' | 'canvas';
+    /**
+     * Theme overrides applied when rendering, exactly as a consumer's live wrapper
+     * would apply them. Pass the SAME theme your on-screen chart uses (e.g. the
+     * blog's `blogChartTheme(isDark)`), or the export won't match — its background,
+     * gridlines, and chrome colors fall back to openchart's raw defaults.
+     */
+    theme?: ThemeConfig;
+    /** Embed fonts as base64 so text matches on-screen. Defaults to true. */
+    embedFonts?: boolean;
+    /** Opaque background fill. Defaults to the chart's own background (white if transparent). */
+    backgroundColor?: string;
+}
+/**
+ * Render an ordered list of specs to an animated GIF Blob. Holds the first spec,
+ * then tweens to each subsequent spec (openchart's update transition, driven
+ * frame-by-frame) and holds it — reproducing the on-screen bar grow/shrink.
+ *
+ * @param specs - Ordered specs, one per keyframe (e.g. one per year).
+ * @param options - dpi, fps, dwell, loop, size (required), dark mode, theme, fonts.
+ * @returns A Promise resolving to the GIF Blob.
+ */
+declare function exportSpecSequence(specs: Array<ChartSpec | LayerSpec>, options: SpecSequenceOptions): Promise<Blob>;
+
+/**
+ * Animated camera for the graph.
+ *
+ * Flights interpolate between two `ZoomTransform`s along d3's geodesic
+ * `interpolateZoom` path (smooth zoom-and-pan that pulls back to see both
+ * endpoints before diving in). A flight is a {@link GraphAnimation}, driven by
+ * the mount's AnimationScheduler.
+ *
+ * `interpolateZoom` operates on a `[cx, cy, width]` "view" — the graph-space
+ * center and the graph-space width visible across the viewport. We convert the
+ * ZoomTransform ⇄ view around a fixed viewport size.
+ */
+
+/** Options controlling a camera flight. */
+interface CameraFlightOptions {
+    /** Duration in ms, or `'auto'` to derive from the zoom distance. */
+    duration?: number | 'auto';
+    /** Easing preset. Default `'smooth'`. */
+    ease?: AnimationEase;
+}
+
 /**
  * Creates a Web Worker running the force simulation.
  *
@@ -58,21 +195,99 @@ declare function createSimulationWorker(): Worker;
  * simulation ticks. Returns a GraphInstance with update/search/zoom/destroy.
  */
 
+/**
+ * A programmatic highlight target. Resolved once at call time into a node id set
+ * and rendered through the focus model (eased crossfade). See {@link GraphInstance.highlight}.
+ */
+type GraphHighlightTarget = {
+    nodeIds: string[];
+} | {
+    category: {
+        field: string;
+        value: string | string[];
+    };
+} | {
+    neighborsOf: string;
+    includeSelf?: boolean;
+};
+/** A hovered node or edge, passed to a tooltip formatter. */
+interface GraphTooltipItem {
+    kind: 'node' | 'edge';
+    /** The raw datum (node record, or edge record with source/target). */
+    data: Record<string, unknown>;
+}
+/**
+ * Custom tooltip content builder. Receives the hovered item and the library's
+ * default {@link TooltipContent}, returns replacement content.
+ *
+ * Safety contract:
+ * - A returned `TooltipContent` or `string` is escaped by the library (strings
+ *   are inserted via `textContent`, never `innerHTML`).
+ * - A returned `HTMLElement` is trusted verbatim — the host owns sanitization.
+ * - `null` suppresses the tooltip for that item.
+ */
+type GraphTooltipFormatter = (item: GraphTooltipItem, defaults: TooltipContent) => TooltipContent | string | HTMLElement | null;
+/** Built-in legend data (headless mirror of the rendered legend). */
+interface GraphLegendData {
+    field: string | null;
+    nodes: Array<{
+        label: string;
+        color: string;
+        count?: number;
+        active: boolean;
+    }>;
+    edges: Array<{
+        label: string;
+        color: string;
+        count?: number;
+    }>;
+}
 interface GraphMountOptions {
     theme?: ThemeConfig;
     darkMode?: DarkMode;
     responsive?: boolean;
     /** Show the tryOpenData.ai watermark. Defaults to true. */
     watermark?: boolean;
-    /** Show the built-in tooltip on node/edge hover. Defaults to true. */
-    tooltip?: boolean;
-    /** Show the built-in legend. Defaults to true. */
-    legend?: boolean;
+    /** Show the built-in tooltip; pass an object for a custom formatter. Defaults to true. */
+    tooltip?: boolean | {
+        formatter?: GraphTooltipFormatter;
+    };
+    /**
+     * Built-in legend. `true` (default) renders an interactive legend with counts.
+     * `false` renders none (set this if you render your own legend). An object
+     * toggles interactivity/counts.
+     */
+    legend?: boolean | {
+        interactive?: boolean;
+        counts?: boolean;
+    };
     onNodeClick?: (node: Record<string, unknown>) => void;
     onNodeDoubleClick?: (node: Record<string, unknown>) => void;
     onNodeHover?: (node: Record<string, unknown> | null) => void;
     onEdgeHover?: (edge: Record<string, unknown> | null) => void;
     onSelectionChange?: (nodeIds: string[]) => void;
+    /** Fired when the user hovers a legend entry (null on leave). */
+    onLegendHover?: (entry: {
+        field: string;
+        value: string;
+    } | null) => void;
+    /** Fired when legend toggle state changes; `activeValues` is the active category set (empty = all). */
+    onLegendToggle?: (activeValues: string[]) => void;
+    /** Fired whenever the highlight set changes (programmatic or legend), null when cleared. */
+    onHighlightChange?: (nodeIds: string[] | null) => void;
+    /**
+     * Fit the graph to the viewport on the first tick. Default true. Set false to
+     * restore a saved camera (e.g. getCamera() + flyTo) without the initial fit.
+     */
+    fitOnLoad?: boolean;
+    /** Camera change callback, rAF-coalesced (fires at most once per rendered frame). */
+    onCameraChange?: (camera: {
+        x: number;
+        y: number;
+        k: number;
+    }) => void;
+    /** Skip the entrance reveal/flight on mount (spec unchanged; used by wrappers when recreating for a theme/darkMode-only change so the entrance doesn't replay). Warmup still runs. */
+    suppressEntrance?: boolean;
 }
 interface GraphInstance {
     update(spec: GraphSpec): void;
@@ -80,10 +295,49 @@ interface GraphInstance {
     updateVisuals(spec: GraphSpec): void;
     search(query: string): void;
     clearSearch(): void;
-    zoomToFit(): void;
-    zoomToNode(nodeId: string): void;
-    selectNode(nodeId: string): void;
+    /** Fit all nodes into the viewport. Animated by default; `{ duration: 0 }` snaps. */
+    zoomToFit(opts?: CameraFlightOptions & {
+        padding?: number;
+    }): void;
+    /** Fly to a node and zoom in (default scale 2). Tracks the node while it settles. */
+    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 (graph-space center-ish transform components). */
+    getCamera(): {
+        x: number;
+        y: number;
+        k: number;
+    };
+    /** Select a node; `{ fly: true }` also flies to it (default follows interaction.select.flyTo). */
+    selectNode(nodeId: string, opts?: {
+        fly?: boolean;
+    } & CameraFlightOptions): void;
     getSelectedNodes(): string[];
+    /** Node ids currently matching the active search query. */
+    getSearchMatches(): string[];
+    /** Emphasize a set of nodes; eased via the focus model. Resets legend toggles. */
+    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 (node categories + edge categories). */
+    getLegend(): GraphLegendData;
+    /** 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[];
     resize(): void;
     destroy(): void;
 }
@@ -105,7 +359,7 @@ declare function createGraph(container: HTMLElement, spec: GraphSpec, options?:
  * on the `[data-oc-map-camera]` group, never as a CSS transform.
  */
 
-interface MapCameraOptions {
+interface GeoMapCameraOptions {
     /** Transition duration in ms. 0 snaps instantly. Default 600. */
     duration?: number;
     /** Padding in map-local units around the target. Default 16. */
@@ -115,18 +369,18 @@ interface MapCameraOptions {
 /**
  * Map mount API: the main entry point for vanilla JS map usage.
  *
- * createMap() takes a container, MapSpec, and options, compiles the
+ * createGeoMap() takes a container, GeoMapSpec, and options, compiles the
  * map, renders it as SVG, sets up responsive resizing, tooltip interaction,
- * and returns a MapInstance with update/resize/export/destroy.
+ * and returns a GeoMapInstance with update/resize/export/destroy.
  */
 
-type MapMarkEvent = {
+type GeoMapMarkEvent = {
     kind: 'feature' | 'point';
     id: string | number;
     name?: string;
     data: Record<string, unknown> | null;
 };
-interface MapMountOptions {
+interface GeoMapMountOptions {
     /** Theme overrides. */
     theme?: ThemeConfig;
     /** Dark mode setting: "auto" (system pref), "force", or "off". */
@@ -138,13 +392,13 @@ interface MapMountOptions {
     /** Show tooltips on hover. Defaults to true. */
     tooltip?: boolean;
     /** Callback when a feature or point is clicked. */
-    onMarkClick?: (event: MapMarkEvent) => void;
+    onMarkClick?: (event: GeoMapMarkEvent) => void;
     /** Callback when a feature or point is hovered (null on mouse leave). */
-    onMarkHover?: (event: MapMarkEvent | null) => void;
+    onMarkHover?: (event: GeoMapMarkEvent | null) => void;
 }
-interface MapInstance {
+interface GeoMapInstance {
     /** Re-compile and re-render with a new spec. */
-    update(spec: MapSpec): void;
+    update(spec: GeoMapSpec): void;
     /** Re-compile at current container dimensions. */
     resize(): void;
     /** Export the map. */
@@ -152,11 +406,11 @@ interface MapInstance {
     /** Remove all DOM elements and disconnect observers. */
     destroy(): void;
     /** The current compiled layout. */
-    readonly layout: MapLayout;
+    readonly layout: GeoMapLayout;
     /** Zoom to one or more features by ID. */
-    zoomTo(featureId: string | number | Array<string | number>, opts?: MapCameraOptions): void;
+    zoomTo(featureId: string | number | Array<string | number>, opts?: GeoMapCameraOptions): void;
     /** Pan to a feature keeping the current zoom level. */
-    panTo(featureId: string | number, opts?: MapCameraOptions): void;
+    panTo(featureId: string | number, opts?: GeoMapCameraOptions): void;
     /** Fit the camera to an arbitrary bounding box, or reset to full view if no target. */
     fitBounds(target?: {
         x: number;
@@ -164,9 +418,9 @@ interface MapInstance {
         width: number;
         height: number;
         padding?: number;
-    }, opts?: MapCameraOptions): void;
+    }, opts?: GeoMapCameraOptions): void;
     /** Reset the camera to the full map view. */
-    resetView(opts?: MapCameraOptions): void;
+    resetView(opts?: GeoMapCameraOptions): void;
     /** Get a snapshot of the current camera state. */
     getCamera(): Camera;
     /** Set the camera to an exact state (no animation). */
@@ -175,7 +429,23 @@ interface MapInstance {
 /**
  * Create a map instance from a spec and mount it into a container.
  */
-declare function createMap(container: HTMLElement, spec: MapSpec, options?: MapMountOptions): MapInstance;
+declare function createGeoMap(container: HTMLElement, spec: GeoMapSpec, options?: GeoMapMountOptions): GeoMapInstance;
+
+/**
+ * Default cap on the mark count that still runs a tweened data-update
+ * transition. Override per chart with `animation.update.maxMarks`.
+ */
+declare const DEFAULT_UPDATE_MAX_MARKS = 500;
+/**
+ * Default cap when the destination layout renders its points on canvas.
+ *
+ * Two orders of magnitude above the SVG cap because the cost model is
+ * different: a canvas frame writes into typed arrays and issues one batched
+ * fill per color bucket, where the SVG path writes attributes on one DOM
+ * element per mark. The cap that keeps low-end devices honest for DOM writes
+ * would veto exactly the high-cardinality morphs canvas mode exists to serve.
+ */
+declare const CANVAS_DEFAULT_UPDATE_MAX_MARKS = 20000;
 
 /**
  * Mark rendering: dispatches to per-mark-type sub-renderers (line, area, rect,
@@ -307,6 +577,7 @@ declare function createSankey(container: HTMLElement, spec: SankeySpec, options?
 declare function renderChartSVG(layout: ChartLayout, container: HTMLElement, opts?: {
     animate?: boolean;
     crosshair?: boolean;
+    canvasMarks?: boolean;
 }): SVGElement;
 
 /**
@@ -499,9 +770,20 @@ interface TooltipShowOptions {
      */
     placement?: Placement;
 }
+/**
+ * Content accepted by {@link TooltipManager.show}. A structured
+ * {@link TooltipContent} is rendered by the manager; `{ text }` is inserted as
+ * plain text (escaped via textContent); `{ element }` is a caller-owned node
+ * trusted verbatim (the host owns sanitization).
+ */
+type TooltipInput = TooltipContent | {
+    text: string;
+} | {
+    element: HTMLElement;
+};
 interface TooltipManager {
     /** Show the tooltip with content at a given position. */
-    show(content: TooltipContent, x: number, y: number, opts?: TooltipShowOptions): void;
+    show(content: TooltipInput, x: number, y: number, opts?: TooltipShowOptions): void;
     /** Hide the tooltip. */
     hide(): void;
     /** Remove the tooltip element and clean up event listeners. */
@@ -565,4 +847,4 @@ interface YouDrawItController {
  */
 declare function createYouDrawIt(options: YouDrawItOptions): YouDrawItController;
 
-export { type BarListInstance, type BarListMountOptions, Camera, type GraphInstance, type GraphMountOptions, JPGExportOptions, type KeyboardNavOptions, type MapCameraOptions, type MapInstance, type MapMarkEvent, type MapMountOptions, SVGExportOptions, type SankeyInstance, type SankeyMountOptions, type TableInstance, type TableMountOptions, type TableState, type TextEditOverlayConfig, type TileMapInstance, type TileMapMountOptions, type TooltipManager, type YouDrawItController, type YouDrawItOptions, attachKeyboardNav, createBarList, createGraph, createMap, createSankey, createSimulationWorker, createTable, createTextEditOverlay, createTileMap, createTooltipManager, createYouDrawIt, observeResize, rectPathWithCorners, registerMarkRenderer, renderBarCell, renderCategoryCell, renderCell, renderChartSVG, renderFlagCell, renderHeatmapCell, renderImageCell, renderSparklineCell, renderTable, renderTextCell };
+export { type BarListInstance, type BarListMountOptions, CANVAS_DEFAULT_UPDATE_MAX_MARKS, Camera, type CameraFlightOptions, DEFAULT_UPDATE_MAX_MARKS, type GeoMapCameraOptions, type GeoMapInstance, type GeoMapMarkEvent, type GeoMapMountOptions, type GraphHighlightTarget, type GraphInstance, type GraphLegendData, type GraphMountOptions, type GraphTooltipFormatter, type GraphTooltipItem, JPGExportOptions, type KeyboardNavOptions, SVGExportOptions, type SankeyInstance, type SankeyMountOptions, type SpecSequenceOptions, type TableInstance, type TableMountOptions, type TableState, type TextEditOverlayConfig, type TileMapInstance, type TileMapMountOptions, type TooltipManager, VECTOR_EXPORT_MAX_POINTS, type YouDrawItController, type YouDrawItOptions, attachKeyboardNav, createBarList, createGeoMap, createGraph, createSankey, createSimulationWorker, createTable, createTextEditOverlay, createTileMap, createTooltipManager, createYouDrawIt, exportSpecSequence, materializeCanvasModeSVG, observeResize, rectPathWithCorners, registerMarkRenderer, renderBarCell, renderCategoryCell, renderCell, renderChartSVG, renderFlagCell, renderHeatmapCell, renderImageCell, renderSparklineCell, renderTable, renderTextCell };