@opendata-ai/openchart-engine 8.0.0-rc.8 → 8.0.0-rc.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-engine",
-  "version": "8.0.0-rc.8",
+  "version": "8.0.0-rc.9",
   "description": "Headless compiler for openchart: spec validation, data compilation, scales, and layout",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -48,7 +48,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "8.0.0-rc.8",
+    "@opendata-ai/openchart-core": "8.0.0-rc.9",
     "d3-array": "^3.2.0",
     "d3-format": "^3.1.2",
     "d3-interpolate": "^3.0.0",

package/src/__tests__/__snapshots__/compile-snapshot.test.ts.snap

@@ -554,6 +554,29 @@ exports[`compileChart snapshot (Step 7 oracle) > clipped-domain bar chart (data
     ],
   ],
   "watermark": false,
+  "xInvert": {
+    "bottomData": 50,
+    "bottomPixel": 577,
+    "scaleType": "linear",
+    "topData": 0,
+    "topPixel": 36.942,
+  },
+  "yInvert": {
+    "bottomData": 0,
+    "bottomPixel": 60.9,
+    "domain": [
+      "A",
+      "B",
+      "C",
+    ],
+    "positions": [
+      297.33805970149257,
+      208.95000000000002,
+      120.56194029850745,
+    ],
+    "topData": 0,
+    "topPixel": 357,
+  },
 }
 `;
 
@@ -1608,6 +1631,20 @@ exports[`compileChart snapshot (Step 7 oracle) > legend-heavy multi-series line
   },
   "tooltipDescriptors": [],
   "watermark": false,
+  "xInvert": {
+    "bottomData": 1609459200000,
+    "bottomPixel": 651.76115,
+    "scaleType": "time",
+    "topData": 1577836800000,
+    "topPixel": 47,
+  },
+  "yInvert": {
+    "bottomData": 40,
+    "bottomPixel": 105.2,
+    "scaleType": "linear",
+    "topData": 8,
+    "topPixel": 410.59999999999997,
+  },
 }
 `;
 
@@ -2335,5 +2372,30 @@ exports[`compileChart snapshot (Step 7 oracle) > watermarked column chart with g
     ],
   ],
   "watermark": true,
+  "xInvert": {
+    "bottomData": 0,
+    "bottomPixel": 577,
+    "domain": [
+      "A",
+      "B",
+      "C",
+      "D",
+    ],
+    "positions": [
+      122.67875862068962,
+      246.30358620689654,
+      369.92841379310346,
+      493.55324137931035,
+    ],
+    "topData": 0,
+    "topPixel": 39.232,
+  },
+  "yInvert": {
+    "bottomData": 70,
+    "bottomPixel": 60.9,
+    "scaleType": "linear",
+    "topData": 0,
+    "topPixel": 297.2,
+  },
 }
 `;

package/src/compile/layer.ts

@@ -611,6 +611,10 @@ function buildPrimarySpec(leaves: ChartSpec[], layerSpec: LayerSpec): ChartSpec
     ...leaves[0],
     data: allData,
     chrome: layerSpec.chrome ?? leaves[0].chrome,
+    // Annotations come from the parent LayerSpec when present, otherwise
+    // the first flattened leaf's. Later leaves' annotations are silently
+    // dropped. The dual-axis path (compileLayerIndependent) explicitly
+    // clears the secondary axis spec's annotations.
     annotations: layerSpec.annotations ?? leaves[0].annotations,
     labels: layerSpec.labels ?? leaves[0].labels,
     legend: layerSpec.legend ?? leaves[0].legend,

package/src/compile.ts

@@ -28,6 +28,7 @@ import type {
   ResolvedAnimation,
   ResolvedAnnotation,
   ResolvedTheme,
+  ScaleInvert,
   TableLayout,
 } from '@opendata-ai/openchart-core';
 import {
@@ -84,7 +85,7 @@ import { computeDimensions } from './layout/dimensions';
 import { computeFacetGrid, facetMinHeight, MIN_PANEL_HEIGHT } from './layout/facet';
 import { computeGridlines } from './layout/gridlines';
 import { createMeasureFn, resolveLayoutPlan } from './layout/plan';
-import { computeScales } from './layout/scales';
+import { computeScales, type ResolvedScale } from './layout/scales';
 import { placeLegend } from './legend/compute';
 import { placeSizeLegend } from './legend/size';
 import { compileSankey as compileSankeyImpl } from './sankey/compile-sankey';
@@ -187,6 +188,52 @@ function applySparklineDefaults(
   return { ...spec, markDef: newMarkDef };
 }
 
+/**
+ * Extract scale inversion anchors from a resolved scale so the vanilla layer
+ * can convert pixel positions back to data-space values without holding the
+ * d3 scale object. Generalizes the YouDrawItYInvert precedent to any axis.
+ */
+function resolveScaleInvert(resolved: ResolvedScale | undefined): ScaleInvert | undefined {
+  if (!resolved) return undefined;
+  const { scale, type } = resolved;
+
+  // Band / point scales: snap to nearest domain value
+  if (type === 'band' || type === 'point') {
+    const domain = (scale as { domain(): string[] }).domain() as (string | number)[];
+    const positions = domain.map((v) => {
+      const pos = (scale as (v: string | number) => number | undefined)(v) ?? 0;
+      return type === 'band' ? pos + (scale as { bandwidth(): number }).bandwidth() / 2 : pos;
+    });
+    const range = (scale as { range(): number[] }).range();
+    return {
+      topPixel: range[0],
+      bottomPixel: range[range.length - 1],
+      topData: 0,
+      bottomData: 0,
+      domain,
+      positions,
+    };
+  }
+
+  // Continuous scales (linear, time, log, pow, sqrt, symlog)
+  const invert = (scale as { invert?: (px: number) => unknown }).invert;
+  if (typeof invert !== 'function') return undefined;
+
+  const range = (scale as { range(): number[] }).range();
+  const topPx = range[0];
+  const bottomPx = range[range.length - 1];
+  const topVal = invert.call(scale, topPx);
+  const bottomVal = invert.call(scale, bottomPx);
+
+  // For time scales, convert Date to epoch ms
+  const topData = topVal instanceof Date ? +topVal : Number(topVal);
+  const bottomData = bottomVal instanceof Date ? +bottomVal : Number(bottomVal);
+  if (!Number.isFinite(topData) || !Number.isFinite(bottomData)) return undefined;
+
+  const scaleType = type as ScaleInvert['scaleType'];
+  return { topPixel: topPx, bottomPixel: bottomPx, topData, bottomData, scaleType };
+}
+
 /**
  * Compile a chart spec into a ChartLayout.
  *
@@ -857,6 +904,10 @@ export function compileChart(spec: unknown, optionsInput: CompileOptions): Chart
 
   const chrome = footnotes ? { ...dims.chrome, footnotes } : dims.chrome;
 
+  // Scale inversion anchors for edit-mode anchor drag (pixel -> data-space)
+  const xInvert = resolveScaleInvert(scales.x);
+  const yInvert = resolveScaleInvert(scales.y);
+
   return {
     area: chartArea,
     chrome,
@@ -890,6 +941,8 @@ export function compileChart(spec: unknown, optionsInput: CompileOptions): Chart
     display: chartSpec.display,
     crosshair,
     measureText: options.measureText,
+    ...(xInvert ? { xInvert } : {}),
+    ...(yInvert ? { yInvert } : {}),
   };
 }
 

package/src/geo/__tests__/compile-map.test.ts

@@ -1000,5 +1000,129 @@ describe('compileMap', () => {
         expect(Number.isFinite(pm.cy)).toBe(true);
       }
     });
+
+    it('encoding.color legend: null suppresses the choropleth legend reserve (basemap-only)', () => {
+      const base = {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [] as Array<Record<string, unknown>>,
+        points: {
+          data: [{ lat: 34, lon: -118, name: 'LA', v: 10 }],
+          longitude: { field: 'lon', type: 'quantitative' },
+          latitude: { field: 'lat', type: 'quantitative' },
+          color: { field: 'v', type: 'quantitative' },
+          key: { field: 'name', type: 'nominal' },
+        },
+        theme: { spacing: { padding: 0 } },
+      };
+      const withLegendNull = compileMap(
+        {
+          ...base,
+          encoding: {
+            key: { field: 'id', type: 'nominal' },
+            color: { field: 'id', type: 'nominal', legend: null },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+      const withoutLegendNull = compileMap(
+        {
+          ...base,
+          encoding: {
+            key: { field: 'id', type: 'nominal' },
+            color: { field: 'id', type: 'nominal' },
+          },
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      // legend: null frees the phantom choropleth swatch row, so the map
+      // area is taller than the spec that reserves it.
+      expect(withLegendNull.categoricalLegend).toBeNull();
+      expect(withLegendNull.area.height).toBeGreaterThan(withoutLegendNull.area.height);
+    });
+
+    it("legend position 'top-left' overlays the point legend inside the map area", () => {
+      const spec = {
+        type: 'map',
+        geo: { features: MINI_TOPO, projection: 'mercator' },
+        data: [] as Array<Record<string, unknown>>,
+        encoding: {
+          key: { field: 'id', type: 'nominal' },
+          color: { field: 'id', type: 'nominal', legend: null },
+        },
+        points: {
+          data: [
+            { lat: 34, lon: -118, name: 'LA', v: 10 },
+            { lat: 40.7, lon: -74, name: 'NYC', v: 90 },
+          ],
+          longitude: { field: 'lon', type: 'quantitative' },
+          latitude: { field: 'lat', type: 'quantitative' },
+          color: { field: 'v', type: 'quantitative' },
+          key: { field: 'name', type: 'nominal' },
+        },
+        theme: { spacing: { padding: 0 } },
+        watermark: false,
+      };
+      const overlay = compileMap(
+        { ...spec, legend: { show: true, position: 'top-left' } },
+        DEFAULT_OPTIONS,
+      );
+      const bottom = compileMap({ ...spec, legend: { show: true } }, DEFAULT_OPTIONS);
+
+      // Overlay reserves no figure height: map area fills the full frame.
+      expect(overlay.area.height).toBeGreaterThan(bottom.area.height);
+      expect(overlay.area.height).toBe(DEFAULT_OPTIONS.height);
+
+      // Legend floats inside the map area's top-left corner, inset from the
+      // edges, and is marked as an overlay for the renderer's backdrop.
+      const legend = overlay.pointContinuousLegend!;
+      expect(legend.position).toBe('top-left');
+      expect(legend.bounds.x).toBeGreaterThan(overlay.area.x);
+      expect(legend.bounds.y).toBeGreaterThan(overlay.area.y);
+      expect(legend.bounds.y + legend.bounds.height).toBeLessThan(
+        overlay.area.y + overlay.area.height,
+      );
+
+      // Default (no position) keeps the bottom-row placement.
+      expect(bottom.pointContinuousLegend!.position).toBe('bottom');
+      expect(bottom.pointContinuousLegend!.bounds.y).toBeGreaterThan(
+        overlay.pointContinuousLegend!.bounds.y,
+      );
+    });
+
+    it("legend position 'top-left' overlays a categorical point legend too", () => {
+      const layout = compileMap(
+        {
+          type: 'map',
+          geo: { features: MINI_TOPO, projection: 'mercator' },
+          data: [],
+          encoding: {
+            key: { field: 'id', type: 'nominal' },
+            color: { field: 'id', type: 'nominal', legend: null },
+          },
+          points: {
+            data: [
+              { lat: 34, lon: -118, name: 'LA', cat: 'x' },
+              { lat: 40.7, lon: -74, name: 'NYC', cat: 'y' },
+            ],
+            longitude: { field: 'lon', type: 'quantitative' },
+            latitude: { field: 'lat', type: 'quantitative' },
+            color: { field: 'cat', type: 'nominal' },
+            key: { field: 'name', type: 'nominal' },
+          },
+          legend: { show: true, position: 'top-left' },
+          theme: { spacing: { padding: 0 } },
+          watermark: false,
+        },
+        DEFAULT_OPTIONS,
+      );
+
+      expect(layout.area.height).toBe(DEFAULT_OPTIONS.height);
+      const legend = layout.pointCategoricalLegend!;
+      expect(legend.position).toBe('top-left');
+      expect(legend.bounds.x).toBeGreaterThan(layout.area.x);
+      expect(legend.bounds.y).toBeGreaterThan(layout.area.y);
+    });
   });
 });

package/src/geo/compile-map.ts

@@ -47,6 +47,13 @@ import { joinDataToFeatures } from './join';
 import { createProjection } from './projections';
 import type { NormalizedMapSpec } from './types';
 
+/**
+ * Inset from the map area's edges for overlay ('top-left') point legends.
+ * The renderer's backdrop extends 10px left of the legend x, so the visible
+ * gap to the frame edge is OVERLAY_LEGEND_INSET - 10.
+ */
+const OVERLAY_LEGEND_INSET = 18;
+
 function validateGeoFeatures(geo: NormalizedMapSpec['geo']): Topology {
   if (!geo.features) {
     throw new Error(
@@ -165,14 +172,21 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
   // 8. Legend height reserve
   const showLegend = mapSpec.legend?.show !== false;
   const colorEncoding = mapSpec.encoding.color;
+  // Channel-level `legend: null` suppresses the choropleth legend (the VL
+  // idiom) — without this, basemap-only maps (empty data + points layer)
+  // reserved a phantom swatch row that letterboxed the map.
+  const showChoroplethLegend = showLegend && colorEncoding?.legend !== null;
   const isQuantitative = colorEncoding?.type === 'quantitative';
   const legendPosition = mapSpec.legend?.position === 'bottom' ? 'bottom' : 'top';
+  // 'top-left' floats the point legend inside the map area (own backdrop, no
+  // height reserve) so the geography keeps the full frame.
+  const pointLegendOverlay = mapSpec.legend?.position === 'top-left';
 
   // Compute legend block height. For quantitative maps, use the continuous
   // legend infrastructure; for categorical, estimate a single swatch row.
   let legendBlockHeight = 0;
   let continuousContent: ReturnType<typeof computeContinuousLegendContentForChannel> = null;
-  if (showLegend && colorEncoding && isQuantitative) {
+  if (showChoroplethLegend && colorEncoding && isQuantitative) {
     const colorValues: number[] = [];
     for (const row of mapSpec.data) {
       const v = row[colorEncoding.field];
@@ -197,13 +211,14 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
       const labelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
       legendBlockHeight = continuousContent.barHeight + CONTINUOUS_LABEL_GAP + labelRowHeight;
     }
-  } else if (showLegend && colorEncoding) {
+  } else if (showChoroplethLegend && colorEncoding) {
     const labelHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
     legendBlockHeight = Math.max(10, labelHeight) + 6;
   }
 
-  // Reserve height for point color legend if applicable
-  if (showLegend && mapSpec.points?.color) {
+  // Reserve height for point color legend if applicable (overlay legends
+  // float inside the map area and reserve nothing)
+  if (showLegend && !pointLegendOverlay && mapSpec.points?.color) {
     if (mapSpec.points.color.type === 'quantitative') {
       const labelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
       legendBlockHeight += CONTINUOUS_BAR_HEIGHT + CONTINUOUS_LABEL_GAP + labelRowHeight + 8;
@@ -221,8 +236,21 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
   }
 
   // 9. Projection + path generator
+  // When points are present, inset the projection by the max point radius so
+  // circles at the geographic edges don't get clipped by the viewBox.
   const projectionType = mapSpec.geo.projection;
-  const projection = createProjection(projectionType, fullArea.width, mapAreaHeight, geoCollection);
+  let pointInset = 0;
+  if (mapSpec.points) {
+    const sizeRange = mapSpec.points.size?.scale?.range as readonly [number, number] | undefined;
+    pointInset = sizeRange ? sizeRange[1] : SIZE_SCALE_DEFAULTS.mapPoint.range[1];
+  }
+  const projection = createProjection(
+    projectionType,
+    fullArea.width,
+    mapAreaHeight,
+    geoCollection,
+    pointInset,
+  );
   const pathGen = geoPath(projection);
 
   // 10. Check winding order (skip for identity: geoArea uses spherical math
@@ -307,7 +335,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
 
     // Build the continuous legend. Maps place it directly (not via placeLegend,
     // which does cartesian-specific positioning above the chart area).
-    if (showLegend && continuousContent) {
+    if (showChoroplethLegend && continuousContent) {
       const labelStyle: TextStyle = {
         fontFamily: theme.fonts.family,
         fontSize: theme.fonts.sizes.small,
@@ -361,7 +389,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
       mapAreaHeight,
       legendReserveGap,
       legendPosition,
-      showLegend,
+      showLegend: showChoroplethLegend,
       droppedFeatures,
     });
     featureMarks = result.marks;
@@ -548,28 +576,34 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
         shape: 'circle' as const,
       }));
 
-      // Position below the map. Only offset by choropleth legend height when
-      // the choropleth legend is also at the bottom (not 'top').
+      // Default: position below the map, offset by choropleth legend height
+      // when that legend is also at the bottom (not 'top'). Overlay
+      // ('top-left'): float inside the map area's top-left corner — the
+      // renderer's backdrop keeps it readable over geography, and the inset
+      // clears the frame edge (plus the backdrop's own 10px x-padding).
       const bottomChoroplethHeight =
         legendPosition === 'bottom'
           ? (continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0)
           : 0;
       const choroplethLegendGap = bottomChoroplethHeight > 0 ? 8 : 0;
-      const legendX = fullArea.x;
-      const legendY =
-        fullArea.y +
-        mapAreaHeight +
-        legendReserveGap +
-        bottomChoroplethHeight +
-        choroplethLegendGap;
-      const legendWidth = fullArea.width;
+      const legendX = pointLegendOverlay ? fullArea.x + OVERLAY_LEGEND_INSET : fullArea.x;
+      const legendY = pointLegendOverlay
+        ? fullArea.y + OVERLAY_LEGEND_INSET
+        : fullArea.y +
+          mapAreaHeight +
+          legendReserveGap +
+          bottomChoroplethHeight +
+          choroplethLegendGap;
+      const legendWidth = pointLegendOverlay
+        ? fullArea.width - OVERLAY_LEGEND_INSET * 2
+        : fullArea.width;
       const swatchSize = 10;
       const swatchGap = 6;
       const entryGap = 16;
 
       pointCategoricalLegend = {
         type: 'categorical',
-        position: 'bottom',
+        position: pointLegendOverlay ? 'top-left' : 'bottom',
         bounds: { x: legendX, y: legendY, width: legendWidth, height: swatchSize + 6 },
         labelStyle,
         entries,
@@ -614,9 +648,10 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
             ? (continuousLegend?.bounds.height ?? categoricalLegend?.bounds.height ?? 0)
             : 0;
         const choroplethLegendGap = bottomChoroplethH > 0 ? 8 : 0;
-        const legendX = fullArea.x;
-        const legendY =
-          fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethH + choroplethLegendGap;
+        const legendX = pointLegendOverlay ? fullArea.x + OVERLAY_LEGEND_INSET : fullArea.x;
+        const legendY = pointLegendOverlay
+          ? fullArea.y + OVERLAY_LEGEND_INSET
+          : fullArea.y + mapAreaHeight + legendReserveGap + bottomChoroplethH + choroplethLegendGap;
         const ptLabelRowHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
         const ptLegendHeight =
           ptContinuousContent.barHeight + CONTINUOUS_LABEL_GAP + ptLabelRowHeight;
@@ -635,7 +670,7 @@ export function compileMap(spec: unknown, options: CompileOptions): MapLayout {
         pointContinuousLegend = {
           type: 'continuous' as const,
           mode: ptContinuousContent.mode,
-          position: 'bottom',
+          position: pointLegendOverlay ? ('top-left' as const) : ('bottom' as const),
           bounds,
           labelStyle,
           bar,

package/src/geo/projections.ts

@@ -12,8 +12,18 @@ export function createProjection(
   width: number,
   height: number,
   geojson: GeoPermissibleObjects,
+  inset = 0,
 ): GeoProjection | GeoIdentityTransform {
   if (type === 'identity') {
+    if (inset > 0) {
+      return geoIdentity().fitExtent(
+        [
+          [inset, inset],
+          [width - inset, height - inset],
+        ],
+        geojson,
+      );
+    }
     return geoIdentity().fitSize([width, height], geojson);
   }
 
@@ -21,7 +31,17 @@ export function createProjection(
     type === 'albersUsa' ? geoAlbersUsa() : type === 'equalEarth' ? geoEqualEarth() : geoMercator();
 
   const fitGeometry = type === 'mercator' ? excludePolarFeatures(geojson) : geojson;
-  projection.fitSize([width, height], fitGeometry);
+  if (inset > 0) {
+    projection.fitExtent(
+      [
+        [inset, inset],
+        [width - inset, height - inset],
+      ],
+      fitGeometry,
+    );
+  } else {
+    projection.fitSize([width, height], fitGeometry);
+  }
   return projection;
 }
 

package/src/legend/compute.ts

@@ -388,9 +388,10 @@ export function computeLegendContent(
     lineHeight: 1.3,
   };
 
-  // Resolve position: spec-level override wins, then responsive strategy
-  const resolvedPosition =
-    spec.legend?.position ?? (strategy.legendPosition === 'right' ? 'right' : 'top');
+  // Resolve position: spec-level override wins, then responsive strategy.
+  // 'top-left' is a map-only overlay position; charts fold it into 'top'.
+  const specPosition = spec.legend?.position === 'top-left' ? 'top' : spec.legend?.position;
+  const resolvedPosition = specPosition ?? (strategy.legendPosition === 'right' ? 'right' : 'top');
 
   // No entries = empty legend with no space
   if (entries.length === 0) {