@blueprint-chart/lib 0.2.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/dist/transitions/frame-geometry.d.ts

@@ -0,0 +1,53 @@
+import { SceneTransition } from './scene-transition';
+/** Plot rectangle in chart-area coordinates: origin + inner size. */
+export interface PlotRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface FrameGeometryOptions {
+    /** The chart-area `<g>` whose `transform` carries the plot origin. */
+    group: SVGGElement;
+    /** The plot clip rect, if any (width/height interpolate with the plot size). */
+    clipRect: SVGRectElement | null;
+    from: PlotRect;
+    to: PlotRect;
+}
+/**
+ * Ease the plot frame geometry (chart-area group origin + clip size) from the
+ * prior scene's rect to the new one on the orchestrator's `bc-scene` clock.
+ *
+ * The new render has already placed the group/clip at the NEW geometry, so the
+ * tween first resets them to `from` and eases to `to`. The group `transform`
+ * uses the point-wise interpolator (d3's default string interp mangles it);
+ * clip width/height are numeric and use d3's default attr tween.
+ *
+ * Registers a buffered flush, so call it during `committing` (e.g. inside
+ * `SceneTransition.run`). On the snap path (duration 0 / reduced motion) the
+ * geometry is set directly to `to`.
+ */
+export interface PlotFrameOptions {
+    /** The chart's `<svg>` (used to find the clip rect by id). */
+    svg: SVGSVGElement;
+    /** The plot clip-path id (its `rect` size interpolates with the plot). */
+    clipId: string;
+    /** The chart-area `<g>` whose `transform` carries the plot origin. */
+    group: SVGGElement;
+    /** The prior scene's plot rect (from the transition cache), if any. */
+    from: PlotRect | undefined;
+    /** This render's plot rect. */
+    to: PlotRect;
+    /** Only ease when true (same-type transition with prior marks to tween from). */
+    active: boolean;
+}
+/**
+ * Renderer-facing wrapper over {@link tweenFrameGeometry}: resolves the clip
+ * rect from `svg`/`clipId` and eases from the cached prior plot rect to this
+ * render's rect. No-ops unless `active` and a prior rect exist. Using the cached
+ * prior rect (rather than reconstructing it from margins) keeps the `from`
+ * geometry exact even when a chart's plot height differs from its inner height
+ * (e.g. a category-label band) or carries clip inflation.
+ */
+export declare function tweenPlotFrame(orch: SceneTransition, opts: PlotFrameOptions): void;
+export declare function tweenFrameGeometry(orch: SceneTransition, opts: FrameGeometryOptions): void;

package/dist/transitions/index.d.ts

@@ -2,6 +2,9 @@ export { SceneTransition, getSceneTransition } from './scene-transition';
 export { BC_TRANSITION_NAME } from './types';
 export type { CommitOptions } from './scene-transition';
 export { featureJoin } from './feature-join';
+export { interpolatePath } from './interpolate-path';
+export { tweenFrameGeometry, tweenPlotFrame } from './frame-geometry';
+export type { PlotRect, FrameGeometryOptions, PlotFrameOptions } from './frame-geometry';
 export { roleScan, tagsCompatible, shouldEscalateToFade, ROLE_MATCH_THRESHOLD } from './role-matcher';
 export { snapshotLiveAttrs } from './snapshot';
 export type { TransitionMode, SceneTransitionState, FeatureRole, FeatureJoinConfig, AttrMap, AttrValue, } from './types';

package/dist/transitions/interpolate-path.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Interpolate two SVG path `d` strings point-wise.
+ *
+ * d3's default `interpolateString` pairs numbers by document order and
+ * fuses/garbles them when the two paths have different counts — observed
+ * producing ~1e11 coordinates during area resizes. This splits each path
+ * into a command skeleton + number list; when the skeletons match it
+ * interpolates the numbers pairwise, otherwise it hard-switches at the
+ * midpoint so a malformed blend is never emitted.
+ */
+export declare function interpolatePath(a: string, b: string): (t: number) => string;

package/dist/transitions/types.d.ts

@@ -17,7 +17,7 @@ export type SceneTransitionState = 'idle' | 'committing' | 'animating';
  * `'axis-tick.value'`. The role-matcher (future plan) acts on this tag;
  * v1 stores it without acting on it for cross-type.
  */
-export type FeatureRole = 'mark-per-category' | 'mark-per-cell' | 'series-path' | 'axis-tick.value' | 'axis-tick.category' | 'value-label' | 'annotation.point' | 'annotation.range' | 'annotation.free';
+export type FeatureRole = 'mark-per-category' | 'mark-per-cell' | 'series-path' | 'series-area' | 'series-line' | 'axis-tick.value' | 'axis-tick.category' | 'value-label' | 'annotation.point' | 'annotation.range' | 'annotation.free';
 /** Subset of SVG / HTML attribute values we tween. */
 export type AttrValue = string | number;
 /** Map of attribute name → value. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blueprint-chart/lib",
-  "version": "0.2.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"
   }
 }