@blueprint-chart/lib 0.1.29 → 0.1.31

package/README.md

@@ -23,7 +23,7 @@ The simplest way to render a chart is the IIFE runtime, which auto-scans the doc
 </script>
 ```
 
-For programmatic use in an ES module project, the lib exposes the underlying primitives: `parse` (DSL → AST), `buildChartOptions` (AST → render options), `createFrame`/`createCanvas`, and the chart registry (`registerChart`, `getChart`). See [src/index.ts](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/index.ts) for the full public API.
+For programmatic use in an ES module project, the lib exposes the underlying primitives: `parse` (DSL → AST), `validateChart` (AST → `ValidationResult` with typed errors and warnings), `buildChartOptions` (AST → render options), `createFrame`/`createCanvas`, and the chart registry (`registerChart`, `getChart`). See [src/index.ts](https://github.com/blueprint-chart/blueprint-chart/blob/main/packages/lib/src/index.ts) for the full public API.
 
 ## DSL Grammar
 
@@ -37,7 +37,7 @@ ChartMember = DataBlock | Colorize | AreaFill | Annotation | Series | Scene | Pr
 
 DataBlock   = "data" "{" Property* "}"
 Colorize    = "colorize" String "{" Property* "}"
-AreaFill    = "areafill" String String "{" Property* "}"
+AreaFill    = "area-fill" String String "{" Property* "}"
 Annotation  = "annotation" String "{" Property* "}"
 Series      = "series" String "{" Property* "}"
 Scene       = "scene" String "{" SceneMember* "}"

package/dist/dsl/index.d.ts

@@ -1,3 +1,3 @@
 export { parse } from './parser';
 export { serialize } from './serializer';
-export type { AnnotationNode, AreaFillNode, ChartNode, DataNode, ColorizeNode, HighlightNode, PropertyNode, SceneNode, SeriesNode, StepNode, TransformNode } from './types';
+export type { AnnotationNode, AreaFillNode, ChartNode, DataNode, ColorizeNode, HighlightNode, PropertyNode, SceneNode, SeriesNode, TransformNode } from './types';

package/dist/dsl/types.d.ts

@@ -5,6 +5,12 @@ export interface PropertyNode {
     value: string | number;
     isPercentage: boolean;
     values?: (string | number)[];
+    /**
+     * Set when a data row's key was written as a quoted string and collides
+     * with the reserved `series` meta-row key. A quoted `"series"` row is a
+     * real data category; only the unquoted `series = ...` row names columns.
+     */
+    quotedKey?: boolean;
 }
 export interface DataNode {
     type: DslNodeType.Data;
@@ -68,8 +74,6 @@ export interface SceneNode {
     series: SeriesNode[];
     transforms: TransformNode[];
 }
-/** @deprecated Use SceneNode instead */
-export type StepNode = SceneNode;
 export interface TransformNode {
     type: DslNodeType.Transform;
     transformType: string;

package/dist/dsl/validate.d.ts

@@ -0,0 +1,36 @@
+import { ChartNode } from './types';
+/**
+ * A single validation finding. `code` is a stable machine-readable identifier,
+ * `path` locates the offending node (dotted, scene-prefixed where relevant),
+ * `message` is human-readable, and `suggestion` is an optional nearest-match
+ * hint ("did you mean …").
+ */
+export interface ValidationIssue {
+    code: string;
+    path: string;
+    message: string;
+    suggestion?: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * Per-kind allowlists for annotation body property keys, derived from the keys
+ * convertAnnotations() in converter.ts actually reads for each kind. Anything
+ * not listed is silently ignored by the converter, so we flag it. This is what
+ * catches the `fromX`/`toX`-on-a-range bug.
+ */
+export declare const POINT_ANNOTATION_KEYS: Set<string>;
+export declare const RANGE_ANNOTATION_KEYS: Set<string>;
+export declare const FREE_ANNOTATION_KEYS: Set<string>;
+/**
+ * Validate a chart AST for value-level semantic problems that the renderer
+ * would otherwise swallow with silent fallbacks (devex-review finding 6).
+ *
+ * Returns errors (things that change or drop the user's intent) and warnings
+ * (currently none; reserved for softer signals). `valid` is true iff there are
+ * no errors.
+ */
+export declare function validateChart(ast: ChartNode): ValidationResult;

package/dist/enums.d.ts

@@ -76,6 +76,12 @@ export declare enum AnnotationKind {
     Range = "range",
     Free = "free"
 }
+/**
+ * Maps an annotation kind to its DSL block keyword. Used by the serializer,
+ * the editor's DSL output, and the validator so the three never drift apart
+ * (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"
@@ -183,7 +189,7 @@ export declare enum DslNodeType {
     Data = "data",
     Colorize = "colorize",
     Highlight = "highlight",
-    AreaFill = "areafill",
+    AreaFill = "area-fill",
     Annotation = "annotation",
     Series = "series",
     AnnotationVisibility = "annotation-visibility",

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 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 { 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';
 export type { FrameElements } from './charts/frame/frame';
@@ -26,7 +27,9 @@ export type { CvdType, CvdIssue } from './charts/colorblind';
 export { parse } from './dsl/parser';
 export { serialize, compactSerialize } 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, StepNode, TransformNode } from './dsl/types';
+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';