@opendata-ai/openchart-vanilla 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,327 @@
+export { ChartLayout, ChartSpec, CompileOptions, TableLayout, TableSpec, VizSpec } from '@opendata-ai/openchart-engine';
+import { GraphSpec, ThemeConfig, DarkMode, ChartSpec, ChartLayout, ChartEventHandlers, BarTableCell, CategoryTableCell, TableCell, FlagTableCell, HeatmapTableCell, ImageTableCell, SparklineTableCell, TextTableCell, Mark, TableSpec, SortState, TableLayout, TooltipContent } from '@opendata-ai/openchart-core';
+
+/**
+ * Export utilities: serialize charts to SVG, PNG, or CSV.
+ *
+ * - SVG: serializes the rendered DOM element via XMLSerializer
+ * - PNG: renders SVG to canvas, then extracts as Blob
+ * - CSV: converts a data array to comma-separated text
+ */
+/**
+ * Serialize an SVG element to an XML string.
+ *
+ * @param svgElement - The rendered SVG element to serialize.
+ * @returns The SVG markup as a string.
+ */
+declare function exportSVG(svgElement: SVGElement): string;
+interface PNGExportOptions {
+    /** DPI scaling factor. Defaults to 2 for retina-quality output. */
+    dpi?: number;
+}
+/**
+ * Render an SVG element to a PNG Blob via a canvas.
+ *
+ * @param svgElement - The rendered SVG element.
+ * @param options - Optional DPI scaling.
+ * @returns A Promise resolving to the PNG Blob.
+ */
+declare function exportPNG(svgElement: SVGElement, options?: PNGExportOptions): Promise<Blob>;
+/**
+ * Convert an array of data objects to a CSV string.
+ *
+ * Uses the keys from the first row as column headers.
+ * Values are quoted if they contain commas, quotes, or newlines.
+ *
+ * @param data - Array of row objects.
+ * @returns CSV-formatted string.
+ */
+declare function exportCSV(data: Record<string, unknown>[]): string;
+
+/**
+ * Creates a Web Worker running the force simulation.
+ *
+ * Uses the `new URL` + `import.meta.url` pattern recognized by Vite, Webpack 5,
+ * Parcel, and esbuild. The bundler resolves the worker file path at build time
+ * and handles the asset accordingly.
+ *
+ * - Vite dev (Ladle): resolves src/graph/simulation-worker.ts directly, serves
+ *   it as a native ES module worker with on-the-fly TypeScript transform.
+ * - Production (tsup + bun build): dist/simulation-worker.js is a self-contained
+ *   IIFE produced by `bun build`. The consuming app's bundler copies it as an
+ *   asset and rewrites the URL.
+ *
+ * Usage:
+ *   import { createSimulationWorker } from '@opendata-ai/openchart-vanilla';
+ *   const worker = createSimulationWorker();
+ *   worker.postMessage({ type: 'init', nodes, links, width: 800, height: 600 });
+ *   worker.onmessage = (e) => console.log(e.data);
+ */
+declare function createSimulationWorker(): Worker;
+
+/**
+ * Graph mount API: the main entry point for vanilla JS graph usage.
+ *
+ * createGraph() takes a container, GraphSpec, and options, compiles the graph,
+ * creates a force simulation, canvas renderer, spatial index, interaction
+ * manager, and search manager, then runs an animation loop driven by
+ * simulation ticks. Returns a GraphInstance with update/search/zoom/destroy.
+ */
+
+interface GraphMountOptions {
+    theme?: ThemeConfig;
+    darkMode?: DarkMode;
+    responsive?: boolean;
+    onNodeClick?: (node: Record<string, unknown>) => void;
+    onNodeDoubleClick?: (node: Record<string, unknown>) => void;
+    onSelectionChange?: (nodeIds: string[]) => void;
+}
+interface GraphInstance {
+    update(spec: GraphSpec): void;
+    search(query: string): void;
+    clearSearch(): void;
+    zoomToFit(): void;
+    zoomToNode(nodeId: string): void;
+    selectNode(nodeId: string): void;
+    getSelectedNodes(): string[];
+    resize(): void;
+    destroy(): void;
+}
+/**
+ * Create a graph instance from a spec and mount it into a container.
+ *
+ * @param container - The DOM element to render into.
+ * @param spec - The graph spec.
+ * @param options - Mount options.
+ * @returns A GraphInstance with update/search/zoom/destroy methods.
+ */
+declare function createGraph(container: HTMLElement, spec: GraphSpec, options?: GraphMountOptions): GraphInstance;
+
+/**
+ * Mount API: the main entry point for vanilla JS usage.
+ *
+ * createChart() takes a container, spec, and options, compiles the chart,
+ * renders it as SVG, sets up responsive resizing, tooltip interaction
+ * (mouse/touch/keyboard), keyboard navigation between data points,
+ * and returns a ChartInstance with update/resize/export/destroy methods.
+ */
+
+interface MountOptions extends ChartEventHandlers {
+    /** Theme overrides. */
+    theme?: ThemeConfig;
+    /** Dark mode setting: "auto" (system pref), "force", or "off". */
+    darkMode?: DarkMode;
+    /** Callback when a data point is clicked. @deprecated Use onMarkClick instead. */
+    onDataPointClick?: (data: Record<string, unknown>) => void;
+    /** Enable responsive resizing. Defaults to true. */
+    responsive?: boolean;
+}
+interface ExportOptions extends PNGExportOptions {
+}
+interface ChartInstance {
+    /** Re-compile and re-render with a new spec. */
+    update(spec: ChartSpec | GraphSpec): void;
+    /** Re-compile at current container dimensions. */
+    resize(): void;
+    /** Export the chart. */
+    export(format: 'svg'): string;
+    export(format: 'png', options?: ExportOptions): Promise<Blob>;
+    export(format: 'csv'): string;
+    export(format: 'svg' | 'png' | 'csv', options?: ExportOptions): string | Promise<Blob>;
+    /** Remove all DOM elements and disconnect observers. */
+    destroy(): void;
+    /** The current compiled layout (for hooks / debugging). */
+    readonly layout: ChartLayout;
+}
+/**
+ * Create a chart instance from a spec and mount it into a container.
+ *
+ * @param container - The DOM element to render into.
+ * @param spec - The visualization spec.
+ * @param options - Mount options (theme, darkMode, responsive, etc.).
+ * @returns A ChartInstance with update/resize/export/destroy methods.
+ */
+declare function createChart(container: HTMLElement, spec: ChartSpec | GraphSpec, options?: MountOptions): ChartInstance;
+
+/**
+ * Table cell renderers: produce DOM elements for each cell type.
+ *
+ * Each renderer takes a resolved TableCell and returns an HTMLElement
+ * (typically a <td>) with appropriate content, styling, and classes.
+ */
+
+/** Render a plain text cell. */
+declare function renderTextCell(cell: TextTableCell): HTMLTableCellElement;
+/** Render a heatmap-colored cell. */
+declare function renderHeatmapCell(cell: HeatmapTableCell): HTMLTableCellElement;
+/** Render a category-colored cell. */
+declare function renderCategoryCell(cell: CategoryTableCell): HTMLTableCellElement;
+/** Render a cell with an inline bar visualization. */
+declare function renderBarCell(cell: BarTableCell): HTMLTableCellElement;
+/** Render a cell with an inline sparkline SVG. */
+declare function renderSparklineCell(cell: SparklineTableCell): HTMLTableCellElement;
+/** Render a cell with an image. */
+declare function renderImageCell(cell: ImageTableCell): HTMLTableCellElement;
+/** Render a cell with a country flag emoji. */
+declare function renderFlagCell(cell: FlagTableCell): HTMLTableCellElement;
+/** Render any table cell by dispatching on its cellType. */
+declare function renderCell(cell: TableCell): HTMLTableCellElement;
+
+/**
+ * Resize observer: thin wrapper around ResizeObserver with debounce.
+ *
+ * Watches a container element for size changes and calls back with
+ * the new width and height. Debounced at ~60fps (16ms) to avoid
+ * excessive re-renders during drag resizes.
+ */
+/**
+ * Observe a container element for size changes.
+ *
+ * @param container - The element to watch.
+ * @param callback - Called with (width, height) when size changes.
+ * @returns A cleanup function that disconnects the observer.
+ */
+declare function observeResize(container: HTMLElement, callback: (width: number, height: number) => void): () => void;
+
+/**
+ * SVG renderer: converts a ChartLayout into SVG DOM elements.
+ *
+ * Creates an <svg> element with viewBox matching layout dimensions,
+ * renders chrome (title/subtitle/source), axes, marks, annotations,
+ * and legend. All styling via inline SVG attributes from layout data.
+ *
+ * Mark rendering dispatches per mark type with dedicated renderers
+ * for line, area, rect, arc, and point marks.
+ */
+
+type MarkRenderer<T extends Mark> = (mark: T, index: number) => SVGElement;
+/**
+ * Register a mark renderer for a specific mark type.
+ * Built-in renderers are registered below for all chart types.
+ */
+declare function registerMarkRenderer<T extends Mark>(type: T['type'], renderer: MarkRenderer<T>): void;
+/**
+ * Render a compiled ChartLayout into an SVG element and append it to a container.
+ *
+ * @param layout - Compiled ChartLayout from compileChart().
+ * @param container - DOM element to mount the SVG into.
+ * @returns The created SVG element.
+ */
+declare function renderChartSVG(layout: ChartLayout, container: HTMLElement): SVGElement;
+
+/**
+ * Table keyboard navigation: arrow-key cell navigation, Enter to sort,
+ * Escape to clear search, and aria-activedescendant management.
+ *
+ * Designed to be wired up by table-mount.ts after render. Returns a
+ * cleanup function to remove listeners on re-render or destroy.
+ */
+interface KeyboardNavOptions {
+    /** The wrapper element containing the whole table UI. */
+    wrapper: HTMLElement;
+    /** Callback to trigger sort on a column. */
+    onSort: (columnKey: string) => void;
+    /** Callback to clear search and return focus to the table body. */
+    onClearSearch: () => void;
+    /** Callback to announce text to screen readers via the live region. */
+    onAnnounce: (message: string) => void;
+}
+/**
+ * Attach keyboard navigation to a rendered table.
+ *
+ * @returns A cleanup function that removes all event listeners.
+ */
+declare function attachKeyboardNav(options: KeyboardNavOptions): () => void;
+
+/**
+ * Table mount API: the main entry point for vanilla JS table usage.
+ *
+ * createTable() takes a container, spec, and options, compiles the table,
+ * renders it as HTML, sets up responsive resizing, sort/search/pagination
+ * interactivity, and returns a TableInstance with update/resize/export/destroy.
+ *
+ * Supports both controlled and uncontrolled modes:
+ * - Uncontrolled (default): manages sort/search/page internally
+ * - Controlled: reads state from externalState, fires onStateChange
+ */
+
+interface TableState {
+    sort: SortState | null;
+    search: string;
+    page: number;
+}
+interface TableMountOptions {
+    theme?: ThemeConfig;
+    darkMode?: DarkMode;
+    responsive?: boolean;
+    onRowClick?: (row: Record<string, unknown>) => void;
+    onStateChange?: (state: TableState) => void;
+    externalState?: {
+        sort?: SortState | null;
+        search?: string;
+        page?: number;
+    };
+}
+interface TableInstance {
+    update(spec: TableSpec): void;
+    resize(): void;
+    export(format: 'csv'): string;
+    getState(): TableState;
+    setState(partial: Partial<TableState>): void;
+    destroy(): void;
+}
+/**
+ * Create a table instance from a spec and mount it into a container.
+ *
+ * @param container - The DOM element to render into.
+ * @param spec - The table spec.
+ * @param options - Mount options.
+ * @returns A TableInstance with update/resize/export/destroy methods.
+ */
+declare function createTable(container: HTMLElement, spec: TableSpec, options?: TableMountOptions): TableInstance;
+
+/**
+ * Table renderer: produces semantic HTML from a TableLayout.
+ *
+ * renderTable() creates the full DOM structure: chrome, search bar,
+ * scrollable table with sticky column support, pagination, and footer.
+ * The returned element replaces or appends to the given container.
+ */
+
+/**
+ * Render a TableLayout into a full DOM structure.
+ *
+ * @param layout - The compiled table layout.
+ * @param container - The container element to render into.
+ * @returns The wrapper element that was created.
+ */
+declare function renderTable(layout: TableLayout, container: HTMLElement): HTMLElement;
+
+/**
+ * Tooltip manager: creates and positions a floating tooltip element.
+ *
+ * Shows tooltip content near the mouse/touch position with viewport
+ * edge avoidance. Touch support via tap-to-show, tap-outside-to-hide.
+ */
+
+interface TooltipManager {
+    /** Show the tooltip with content at a given position. */
+    show(content: TooltipContent, x: number, y: number): void;
+    /** Hide the tooltip. */
+    hide(): void;
+    /** Remove the tooltip element and clean up event listeners. */
+    destroy(): void;
+}
+/**
+ * Create a tooltip manager attached to a container element.
+ *
+ * The manager creates a floating div positioned relative to the container.
+ * Content is rendered as a title line with optional color indicator,
+ * followed by a compact list of field-value pairs.
+ *
+ * @param container - The parent element for the tooltip.
+ * @returns TooltipManager with show/hide/destroy methods.
+ */
+declare function createTooltipManager(container: HTMLElement): TooltipManager;
+
+export { type ChartInstance, type ExportOptions, type GraphInstance, type GraphMountOptions, type KeyboardNavOptions, type MountOptions, type PNGExportOptions, type TableInstance, type TableMountOptions, type TableState, type TooltipManager, attachKeyboardNav, createChart, createGraph, createSimulationWorker, createTable, createTooltipManager, exportCSV, exportPNG, exportSVG, observeResize, registerMarkRenderer, renderBarCell, renderCategoryCell, renderCell, renderChartSVG, renderFlagCell, renderHeatmapCell, renderImageCell, renderSparklineCell, renderTable, renderTextCell };