@blueprint-chart/lib 0.2.0 → 0.4.0

package/README.md

@@ -10,6 +10,25 @@ npm install @blueprint-chart/lib
 
 ## Quick start
 
+### Node — write SVG and PNG to disk
+
+```ts
+import { render } from '@blueprint-chart/lib'
+import { writeFile } from 'node:fs/promises'
+
+const chart = await render(bpc)
+await writeFile('chart.svg', await chart.toSvg())
+await writeFile('chart.png', await chart.toPng({ width: 1200 }))
+```
+
+### Browser — mount and step scenes
+
+```ts
+const { mount, scene } = await render(bpc)
+mount('#chart')   // element or selector
+scene(2)          // advance to scene index 2
+```
+
 The simplest way to render a chart is the IIFE runtime, which auto-scans the document for embedded chart definitions and renders each one inline (inside a sandboxed iframe inserted before the script tag):
 
 ```html

package/dist/charts/motion.d.ts

@@ -1,3 +1,12 @@
+/**
+ * @deprecated As of the Scene Transition Orchestrator, mark rendering has fully
+ * migrated to `packages/lib/src/transitions/` (SceneTransition + featureJoin +
+ * tweenFrameGeometry): the legacy `reinsertWithOffset` mark-translate wrapper is
+ * gone. What remains here is the cross-type fade path and the transition-duration
+ * flag: every renderer and the axis subsystem still call `setRenderTransition` /
+ * `getDefaultTransitionMs`, and cross-type transitions use `snapshotForFadeOut` /
+ * `commitFadeOut` / `fadeIn`. This file can be deleted once those move too.
+ */
 /**
  * Returns 0 when the user prefers reduced motion, otherwise returns the input duration.
  */
@@ -13,15 +22,6 @@ export declare function setRenderTransition(enabled: boolean): void;
  * Returns 0 when not in a scene transition (i.e. setRenderTransition(false) was last called).
  */
 export declare function getDefaultTransitionMs(): number;
-/**
- * Reinsert prior elements into a parent, wrapping them in a compensating
- * `<g translate(dx,dy)>` that transitions to identity over the default
- * duration.  This corrects for chartArea origin shifts (e.g. when legend
- * toggles change margins) so that prior elements don't visually jump.
- *
- * When dx/dy are both 0, elements are appended directly without a wrapper.
- */
-export declare function reinsertWithOffset(parent: Element, elements: Element[], dx: number, dy: number): void;
 /**
  * Fade an element in using the Web Animations API.
  * Respects `prefers-reduced-motion` via `getTransitionDuration`.

package/dist/charts/plugins/plugin-host.d.ts

@@ -0,0 +1,16 @@
+import { D3Blueprint } from 'd3-blueprint';
+import * as d3 from 'd3';
+/**
+ * Minimal D3Blueprint host whose only job is to carry the legacy plugins
+ * (tooltip, crosshair, annotations) that consume the `.use()` / `.draw()` API.
+ *
+ * Marks are rendered through the SceneTransition orchestrator's featureJoin, not
+ * this class — so `initialize` defines no layers. Renderers that have migrated
+ * their marks but still host plugins use `createPluginHost` instead of declaring
+ * a per-file empty subclass.
+ */
+declare class PluginHost extends D3Blueprint<unknown> {
+    initialize(): void;
+}
+export declare function createPluginHost(selection: d3.Selection<SVGGElement, unknown, null, undefined>): PluginHost;
+export {};

package/dist/charts/transition-cache.d.ts

@@ -2,6 +2,17 @@ import { Margin } from './types';
 export interface CachedChart {
     chartType: string;
     margin?: Margin;
+    /**
+     * The plot rect (origin + size) this render used for its marks/clip, so the
+     * next same-type transition can ease the frame geometry from the exact prior
+     * rect instead of reconstructing it from margins. Shape matches `PlotRect`.
+     */
+    plotRect?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
 }
 export declare function getCachedChart(container: HTMLElement): CachedChart | undefined;
 export declare function setCachedChart(container: HTMLElement, entry: CachedChart): void;

package/dist/charts/value-label-fit.d.ts

@@ -0,0 +1,11 @@
+export interface ValueLabelFitInput {
+    text: string;
+    placement: 'inside' | 'outside';
+    orientation: 'vertical' | 'horizontal';
+    /** px extent along x (vertical bar: thickness; horizontal bar: length) */
+    barWidth: number;
+    /** px extent along y (vertical bar: length; horizontal bar: thickness) */
+    barHeight: number;
+}
+export declare function estimateLabelWidth(text: string): number;
+export declare function shouldRenderValueLabel(input: ValueLabelFitInput): boolean;

package/dist/dsl/serializer.d.ts

@@ -1,3 +1,4 @@
 import { ChartNode } from './types';
 export declare function serialize(ast: ChartNode): string;
+export declare function compactSerializeDeep(ast: ChartNode): string;
 export declare function compactSerialize(ast: ChartNode): string;

package/dist/index.d.ts

@@ -25,14 +25,15 @@ export { getCachedChart } from './charts/transition-cache';
 export { getCvdFilterId, createCvdSvgFilter, simulateCvdColor, checkCvdColors } from './charts/colorblind';
 export type { CvdType, CvdIssue } from './charts/colorblind';
 export { parse } from './dsl/parser';
-export { serialize, compactSerialize } from './dsl/serializer';
+export { serialize, compactSerialize, compactSerializeDeep } from './dsl/serializer';
 export { propertyMap, extractChartTypeOptions, dataEntriesToString, extractSceneOverrides, convertColorizes, convertHighlights, convertAreaFills, convertAnnotations, convertSeriesOverrides } from './dsl/converter';
 export type { AnnotationNode, AnnotationVisibilityNode, PointAnnotationNode, RangeAnnotationNode, FreeAnnotationNode, AreaFillNode, ChartNode, DataNode, ColorizeNode, HighlightNode, PropertyNode, SceneNode, SeriesNode, TransformNode } from './dsl/types';
 export { validateChart } from './dsl/validate';
 export type { ValidationIssue, ValidationResult } from './dsl/validate';
 export { samples } from './samples';
 export type { ChartSample } from './samples';
-export { renderBpc, renderChart, astToDefinition, resolveScene } from './render';
-export type { ChartDefinition, RenderOptions, ResolvedChartState } from './render';
+export { renderBpc, renderChart, astToDefinition, resolveScene, render } from './render';
+export type { ChartDefinition, RenderOptions, ResolvedChartState, ChartHandle, RenderApiOptions, OutputOptions } from './render';
+export { ChartParseError, PngBrowserUnsupportedError, MissingNodeRenderDepsError } from './render';
 export { SceneTransition, getSceneTransition, featureJoin, snapshotLiveAttrs, BC_TRANSITION_NAME, } from './transitions';
 export type { CommitOptions, TransitionMode, SceneTransitionState, FeatureRole, FeatureJoinConfig, AttrMap, AttrValue, } from './transitions';