@blueprint-chart/lib 0.3.0 → 1.0.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/types.d.ts

@@ -72,7 +72,10 @@ export interface AnnotationLineConfig {
     circleColor?: string;
 }
 interface AnnotationBase {
-    id?: string;
+    /** Internal transition-matching key, assigned during scene resolution. Never author-supplied. */
+    key?: string;
+    /** How many scenes this annotation lives for: a positive integer count, or 'always'. Defaults to 1. */
+    repeat?: number | 'always';
     text?: string;
     textColor?: string;
     textOutline?: boolean;

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/converter.d.ts

@@ -24,7 +24,6 @@ export declare function extractSceneOverrides(scene: SceneNode, chartType: strin
     highlights: SceneNode['highlights'];
     areaFills: SceneNode['areaFills'];
     annotations: SceneNode['annotations'];
-    annotationVisibility: SceneNode['annotationVisibility'];
     series: SceneNode['series'];
     transforms: SceneNode['transforms'];
 };

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/dsl/types.d.ts

@@ -1,4 +1,4 @@
-import { DslNodeType, AnnotationKind, AnnotationAction } from '../enums';
+import { DslNodeType, AnnotationKind } from '../enums';
 export interface PropertyNode {
     type: DslNodeType.Property;
     key: string;
@@ -73,14 +73,6 @@ export interface SeriesNode {
     /** `//` comment lines authored immediately above this node, text only (no `//`). */
     leadingComments?: string[];
 }
-export interface AnnotationVisibilityNode {
-    type: DslNodeType.AnnotationVisibility;
-    action: AnnotationAction;
-    kind: AnnotationKind;
-    id: string;
-    /** `//` comment lines authored immediately above this node, text only (no `//`). */
-    leadingComments?: string[];
-}
 export interface SceneNode {
     type: DslNodeType.Scene;
     name: string | null;
@@ -90,7 +82,6 @@ export interface SceneNode {
     highlights: HighlightNode[];
     areaFills: AreaFillNode[];
     annotations: AnnotationNode[];
-    annotationVisibility: AnnotationVisibilityNode[];
     series: SeriesNode[];
     transforms: TransformNode[];
     /** `//` comment lines authored immediately above this node, text only (no `//`). */
@@ -112,7 +103,6 @@ export interface ChartNode {
     highlights: HighlightNode[];
     areaFills: AreaFillNode[];
     annotations: AnnotationNode[];
-    annotationVisibility: AnnotationVisibilityNode[];
     series: SeriesNode[];
     scenes: SceneNode[];
     transforms: TransformNode[];

package/dist/enums.d.ts

@@ -82,10 +82,6 @@ export declare enum AnnotationKind {
  * (e.g. `point` -> `annotation`, not the enum's raw value).
  */
 export declare const ANNOTATION_KIND_KEYWORD: Record<AnnotationKind, string>;
-export declare enum AnnotationAction {
-    Hide = "hide",
-    Show = "show"
-}
 export declare enum RangeAnchor {
     Start = "start",
     Center = "center",
@@ -192,7 +188,6 @@ export declare enum DslNodeType {
     AreaFill = "area-fill",
     Annotation = "annotation",
     Series = "series",
-    AnnotationVisibility = "annotation-visibility",
     Scene = "scene",
     Transform = "transform",
     Chart = "chart"

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { ChartType, AxisDirection, ScaleType, GridStyle, LabelPosition, LabelRotation, TickPosition, FrameSizing, CompassDirection, AnnotationLineStyle, StrokeStyle, AnnotationKind, AnnotationAction, RangeAnchor, Orientation, SymbolShape, SymbolShowOn, SymbolStyle, SortDirection, SortMode, LegendPosition, Anchor, ValueLabelPosition, CrosshairDirection, CrosshairStyle, StackMode, LineStyle, ChartOptionType, DirectLabelMode, Interpolation, DslNodeType, } from './enums';
+export { ChartType, AxisDirection, ScaleType, GridStyle, LabelPosition, LabelRotation, TickPosition, FrameSizing, CompassDirection, AnnotationLineStyle, StrokeStyle, AnnotationKind, RangeAnchor, Orientation, SymbolShape, SymbolShowOn, SymbolStyle, SortDirection, SortMode, LegendPosition, Anchor, ValueLabelPosition, CrosshairDirection, CrosshairStyle, StackMode, LineStyle, ChartOptionType, DirectLabelMode, Interpolation, DslNodeType, } from './enums';
 export { ANNOTATION_KIND_KEYWORD } from './enums';
 export type { ChartData, ChartOptions, ChartRenderer, ChartOptionDef, ChartTypeOptions, ChartTypeOptionKey, ColorizeConfig, HighlightConfig, AxisOptions, FrameOptions, AreaFillConfig, AnnotationConfig, PointAnnotationConfig, RangeAnnotationConfig, FreeAnnotationConfig, AnnotationLineConfig, LineSymbolConfig, SeriesOverride, Margin, } from './charts/types';
 export { createFrame } from './charts/frame/frame';
@@ -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 type { AnnotationNode, 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';