@blueprint-chart/lib 0.3.0 → 0.4.0

package/dist/render/backends/dom-backend.d.ts

@@ -0,0 +1,2 @@
+import { RenderBackend } from './types';
+export declare function createDomBackend(): RenderBackend;

package/dist/render/backends/jsdom-env.d.ts

@@ -0,0 +1,13 @@
+import { DOMWindow } from 'jsdom';
+export interface JsdomEnv {
+    window: DOMWindow;
+    container: HTMLElement;
+    serializeSvg: () => string;
+    serializeFrame: () => string | undefined;
+    cleanup: () => void;
+}
+export interface JsdomEnvOptions {
+    width: number;
+    height: number;
+}
+export declare function createJsdomEnv(opts: JsdomEnvOptions): JsdomEnv;

package/dist/render/backends/node-backend.browser.d.ts

@@ -0,0 +1,5 @@
+import { RenderBackend } from './types';
+/** Browser build resolves the node backend to this throwing stub — the heavy
+ *  native deps must never enter a browser bundle. Reached only if a browser
+ *  caller forces the Node path. */
+export declare function createNodeBackend(): RenderBackend;

package/dist/render/backends/node-backend.d.ts

@@ -0,0 +1,2 @@
+import { RenderBackend } from './types';
+export declare function createNodeBackend(): RenderBackend;

package/dist/render/backends/rasterize.d.ts

@@ -0,0 +1,5 @@
+export interface RasterizeOptions {
+    width?: number;
+    height?: number;
+}
+export declare function rasterizeToPng(svg: string, opts?: RasterizeOptions): Promise<Buffer>;

package/dist/render/backends/text-shim.d.ts

@@ -0,0 +1,12 @@
+import { DOMWindow } from 'jsdom';
+/**
+ * Patch jsdom's SVG element prototypes so D3 layout primitives that rely on
+ * text measurement (axes, legends, annotations) return realistic widths.
+ *
+ * jsdom 26 does not expose `SVGTextContentElement` and does not subclass
+ * `<svg:text>` from `SVGGraphicsElement` — text elements are plain
+ * `SVGElement` instances. We therefore patch `SVGElement.prototype` so the
+ * methods exist on the actual prototype chain, while also patching the
+ * spec-correct prototypes if they happen to be available.
+ */
+export declare function installTextShim(window: DOMWindow): void;

package/dist/render/backends/types.d.ts

@@ -0,0 +1,30 @@
+import { ChartDefinition } from '../types';
+export interface BackendRenderOptions {
+    sceneIndex?: number;
+    thumbnail?: boolean;
+    theme?: string;
+}
+/**
+ * A render backend abstracts the DOM environment. The DOM backend uses the
+ * ambient document; the Node backend provisions jsdom. Both render via the
+ * lib's existing renderChart/renderBpc pipeline.
+ */
+export interface RenderBackend {
+    readonly kind: 'dom' | 'node';
+    /** Create a render target. cleanup() detaches/closes it. */
+    createContainer(width: number, height: number): {
+        container: HTMLElement;
+        cleanup: () => void;
+    };
+    /** Render the resolved definition into the container (transition disabled). */
+    renderToContainer(container: HTMLElement, definition: ChartDefinition, opts: BackendRenderOptions): void;
+    /** Serialize the chart SVG markup from a rendered container. */
+    serializeSvg(container: HTMLElement): string;
+    /** Returns the `.bc-frame` outerHTML; falls back to the chart SVG markup when there is no frame (e.g. thumbnail mode). */
+    serializeFrame(container: HTMLElement): string;
+    /** Rasterize SVG markup to a PNG byte array. DOM backend throws PngBrowserUnsupportedError. */
+    rasterizePng(svg: string, opts: {
+        width?: number;
+        height?: number;
+    }): Promise<Uint8Array>;
+}

package/dist/render/errors.d.ts

@@ -0,0 +1,12 @@
+/** Thrown when a BPC source cannot be parsed/resolved before any output is produced. */
+export declare class ChartParseError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Thrown when toPng() is called in a browser environment (PNG export is Node-only in v1). */
+export declare class PngBrowserUnsupportedError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when the Node render backend's optional dependencies are missing or failed to install. */
+export declare class MissingNodeRenderDepsError extends Error {
+    constructor(message: string);
+}

package/dist/render/index.d.ts

@@ -3,3 +3,6 @@ export { renderChart } from './render-chart';
 export { astToDefinition } from './ast-to-definition';
 export { resolveScene } from './resolve-scene';
 export type { ChartDefinition, RenderOptions, ResolvedChartState } from './types';
+export { render } from './public-render';
+export type { ChartHandle, RenderApiOptions, OutputOptions } from './public-render';
+export { ChartParseError, PngBrowserUnsupportedError, MissingNodeRenderDepsError } from './errors';

package/dist/render/public-render.d.ts

@@ -0,0 +1,23 @@
+import { RenderBackend } from './backends/types';
+export interface RenderApiOptions {
+    theme?: string;
+    scene?: number;
+    width?: number;
+    height?: number;
+    frame?: boolean;
+}
+export interface OutputOptions {
+    width?: number;
+    height?: number;
+}
+export interface ChartHandle {
+    toSvg: (opts?: OutputOptions) => Promise<string>;
+    toHtml: (opts?: OutputOptions) => Promise<string>;
+    toPng: (opts?: OutputOptions) => Promise<Uint8Array>;
+    mount: (target: HTMLElement | string) => ChartHandle;
+    scene: (index: number) => ChartHandle;
+}
+/** Internal; exported for tests. Picks the DOM backend in a browser-like env,
+ *  else dynamically loads the Node backend via the conditional subpath export. */
+export declare function selectBackend(): Promise<RenderBackend>;
+export declare function render(source: string, options?: RenderApiOptions): Promise<ChartHandle>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-chart/lib",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "DSL-driven charting library built on D3. Define charts as text, render them anywhere.",
   "keywords": [
     "chart",
@@ -32,6 +32,11 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./internal/node-backend": {
+      "node": "./dist/node-backend/index.js",
+      "browser": "./dist/node-backend/browser.js",
+      "default": "./dist/node-backend/browser.js"
+    },
     "./charts.scss": "./src/charts/chart.scss",
     "./src/charts/chart.scss": "./src/charts/chart.scss"
   },
@@ -56,18 +61,23 @@
   "devDependencies": {
     "@types/chroma-js": "^3.1.2",
     "@types/d3": "^7",
-    "jsdom": "^26",
+    "@types/jsdom": "^21.1.7",
     "peggy": "^4",
     "typescript": "^5.7",
     "vite": "^6",
     "vite-plugin-dts": "^5.0.0",
     "vitest": "^3"
   },
+  "optionalDependencies": {
+    "@napi-rs/canvas": "^0.1.100",
+    "@resvg/resvg-js": "^2.6.2",
+    "jsdom": "^26.1.0"
+  },
   "scripts": {
     "generate:parser": "peggy --format es -o src/dsl/grammar.js src/dsl/grammar.peggy",
     "prebuild": "pnpm run generate:parser",
     "pretest": "pnpm run generate:parser",
-    "build": "vite build && vite build -c vite.lib.config.ts",
+    "build": "vite build && vite build -c vite.lib.config.ts && vite build -c vite.node-backend.config.ts",
     "test": "vitest run"
   }
 }