@opendata-ai/openchart-engine 1.2.0 → 2.1.0

package/package.json

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

package/src/annotations/__tests__/compute.test.ts

@@ -451,4 +451,230 @@ describe('computeAnnotations', () => {
       expect(dy).toBe(-10);
     });
   });
+
+  // -----------------------------------------------------------------
+  // Connector origin auto-selection
+  // -----------------------------------------------------------------
+
+  describe('connector origin auto-selection', () => {
+    it('connector starts from top edge when data point is above label', () => {
+      // Push label far below AND to the right so the top-center is unambiguously closest
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Below point',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 150 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+      const fontSize = 12; // DEFAULT_ANNOTATION_FONT_SIZE
+
+      // Data point is far above the label, so connector should exit from the top edge
+      const topEdgeY = label.y - fontSize;
+      expect(connector.from.y).toBeCloseTo(topEdgeY, 0);
+    });
+
+    it('connector starts from bottom edge when data point is below label', () => {
+      // Push label far above the data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Above point',
+          anchor: 'top',
+          offset: { dx: 0, dy: -80 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+      const fontSize = 12;
+      const lineHeight = 1.3;
+      const lines = label.text.split('\n');
+
+      // Data point is below the label, so connector should exit from the bottom edge
+      const bottomEdgeY = label.y - fontSize + lines.length * fontSize * lineHeight;
+      expect(connector.from.y).toBeCloseTo(bottomEdgeY, 0);
+    });
+
+    it('connector starts from left edge when data point is left of label', () => {
+      // Push label far to the right of the data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Right of point',
+          anchor: 'right',
+          offset: { dx: 120, dy: 0 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // Data point is to the left, so connector should exit from the left edge
+      // For single-line text, left edge x = label.x
+      expect(connector.from.x).toBeCloseTo(label.x, 0);
+    });
+
+    it('connector starts from right edge when data point is right of label', () => {
+      // Push label far to the left of the data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2021-01-01',
+          y: 20,
+          text: 'Left of point',
+          anchor: 'left',
+          offset: { dx: -120, dy: 0 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // Data point is to the right, so connector should exit from the right edge
+      // Right edge is at label.x + textWidth
+      // For single-line "Left of point" with fontSize=12, weight=400:
+      // textWidth = 14 chars * 12 * 0.55 * 1.0 = 92.4
+      expect(connector.from.x).toBeGreaterThan(label.x + 50); // well past the center
+    });
+
+    it('multi-line text connector uses correct centered bounding box', () => {
+      // Multi-line text with label pushed below data point
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'First line\nSecond line',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // For multi-line, labelX is the center. The connector should exit
+      // from the top-center since data point is above.
+      // Top-center x should be at labelX (the center of the multi-line text)
+      expect(connector.from.x).toBeCloseTo(label.x, 0);
+    });
+
+    it('connector origin changes when label moves to the other side', () => {
+      // Same data point, label pushed right vs left
+      const specRight = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Test label',
+          anchor: 'right',
+          offset: { dx: 120, dy: 0 },
+        },
+      ]);
+      const specLeft = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Test label',
+          anchor: 'left',
+          offset: { dx: -120, dy: 0 },
+        },
+      ]);
+      const scalesRight = computeScales(specRight, chartArea, specRight.data);
+      const scalesLeft = computeScales(specLeft, chartArea, specLeft.data);
+
+      const annotationsRight = computeAnnotations(specRight, scalesRight, chartArea, fullStrategy);
+      const annotationsLeft = computeAnnotations(specLeft, scalesLeft, chartArea, fullStrategy);
+
+      const labelRight = annotationsRight[0].label!;
+      const labelLeft = annotationsLeft[0].label!;
+      const fromRight = labelRight.connector!.from;
+      const fromLeft = labelLeft.connector!.from;
+
+      // When label is to the right of data, connector exits from left edge (= label.x)
+      expect(fromRight.x).toBeCloseTo(labelRight.x, 0);
+      // When label is to the left of data, connector exits from right edge (label.x + textWidth)
+      expect(fromLeft.x).toBeGreaterThan(labelLeft.x + 30); // well past the left edge
+    });
+
+    it('connectorOffset is still applied on top of auto-selected origin', () => {
+      const specWithOffset = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Offset test',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+          connectorOffset: { from: { dx: 10, dy: 5 } },
+        },
+      ]);
+      const specNoOffset = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Offset test',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+        },
+      ]);
+      const scales = computeScales(specWithOffset, chartArea, specWithOffset.data);
+
+      const withOffset = computeAnnotations(specWithOffset, scales, chartArea, fullStrategy);
+      const withoutOffset = computeAnnotations(specNoOffset, scales, chartArea, fullStrategy);
+
+      const fromWith = withOffset[0].label!.connector!.from;
+      const fromWithout = withoutOffset[0].label!.connector!.from;
+
+      expect(fromWith.x - fromWithout.x).toBeCloseTo(10, 0);
+      expect(fromWith.y - fromWithout.y).toBeCloseTo(5, 0);
+    });
+
+    it('curve connector still uses right edge regardless of data point position', () => {
+      // Push label below and to the right, but curve should still start from right edge
+      const spec = makeSpec([
+        {
+          type: 'text',
+          x: '2020-01-01',
+          y: 20,
+          text: 'Curve test',
+          anchor: 'bottom',
+          offset: { dx: 0, dy: 80 },
+          connector: 'curve',
+        },
+      ]);
+      const scales = computeScales(spec, chartArea, spec.data);
+      const annotations = computeAnnotations(spec, scales, chartArea, fullStrategy);
+
+      const label = annotations[0].label!;
+      const connector = label.connector!;
+
+      // Curve should start from right edge of text, not top edge
+      // Right edge x ≈ label.x + textWidth
+      // "Curve test" = 10 chars * 12 * 0.55 = 66
+      expect(connector.from.x).toBeCloseTo(label.x + 66, 1);
+    });
+  });
 });

package/src/annotations/compute.ts

@@ -35,6 +35,7 @@ import type { ResolvedScales } from '../layout/scales';
 
 const DEFAULT_ANNOTATION_FONT_SIZE = 12;
 const DEFAULT_ANNOTATION_FONT_WEIGHT = 400;
+const DEFAULT_LINE_HEIGHT = 1.3;
 const DEFAULT_RANGE_FILL = '#f0c040';
 const DEFAULT_RANGE_OPACITY = 0.15;
 const DEFAULT_REFLINE_DASH = '4 3';
@@ -97,11 +98,36 @@ function makeAnnotationLabelStyle(
     fontSize: fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE,
     fontWeight: fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT,
     fill: fill ?? defaultFill,
-    lineHeight: 1.3,
+    lineHeight: DEFAULT_LINE_HEIGHT,
     textAnchor: 'start',
   };
 }
 
+/**
+ * Compute the bounding box of annotation text at a given label position.
+ * Multi-line text is centered at labelX; single-line starts at labelX.
+ */
+function computeTextBounds(
+  labelX: number,
+  labelY: number,
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+): Rect {
+  const lines = text.split('\n');
+  const isMultiLine = lines.length > 1;
+  const maxWidth = Math.max(...lines.map((line) => estimateTextWidth(line, fontSize, fontWeight)));
+  const totalHeight = lines.length * fontSize * DEFAULT_LINE_HEIGHT;
+  const x = isMultiLine ? labelX - maxWidth / 2 : labelX;
+
+  return {
+    x,
+    y: labelY - fontSize,
+    width: maxWidth,
+    height: totalHeight,
+  };
+}
+
 /**
  * Apply anchor direction to compute label offset from data point.
  * Returns { dx, dy } pixel offsets.
@@ -144,6 +170,57 @@ function applyOffset(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Connector origin: pick the edge midpoint closest to the data point
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the connector origin point on the text bounding box.
+ * For straight connectors, finds the edge midpoint (top, bottom, left, right)
+ * closest to the data point. For curve connectors, always uses the right edge.
+ */
+function computeConnectorOrigin(
+  labelX: number,
+  labelY: number,
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+  targetX: number,
+  targetY: number,
+  connectorStyle: 'straight' | 'curve',
+): { x: number; y: number } {
+  const box = computeTextBounds(labelX, labelY, text, fontSize, fontWeight);
+  const boxCenterX = box.x + box.width / 2;
+  const boxCenterY = box.y + box.height / 2;
+
+  // Curve connectors always start from the right edge
+  if (connectorStyle === 'curve') {
+    return {
+      x: box.x + box.width,
+      y: boxCenterY,
+    };
+  }
+
+  // Normalize the vector from box center to target by the box half-dimensions.
+  // This accounts for the box aspect ratio: a wide text box should prefer
+  // top/bottom exits even when the target is also offset horizontally.
+  const halfW = box.width / 2 || 1;
+  const halfH = box.height / 2 || 1;
+  const ndx = (targetX - boxCenterX) / halfW;
+  const ndy = (targetY - boxCenterY) / halfH;
+
+  if (Math.abs(ndy) >= Math.abs(ndx)) {
+    // Target is more above/below than left/right → use top or bottom edge
+    return ndy < 0
+      ? { x: boxCenterX, y: box.y } // top
+      : { x: boxCenterX, y: box.y + box.height }; // bottom
+  }
+  // Target is more left/right → use left or right edge
+  return ndx < 0
+    ? { x: box.x, y: boxCenterY } // left
+    : { x: box.x + box.width, y: boxCenterY }; // right
+}
+
 // ---------------------------------------------------------------------------
 // Text annotation
 // ---------------------------------------------------------------------------
@@ -178,25 +255,19 @@ function resolveTextAnnotation(
   const showConnector = annotation.connector !== false;
   const connectorStyle = annotation.connector === 'curve' ? 'curve' : 'straight';
 
-  // Compute connector origin based on style and text layout
+  // Compute connector origin: pick the edge midpoint closest to the data point
   const fontSize = annotation.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = annotation.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
-  const lines = annotation.text.split('\n');
-  const lineHeight = 1.3;
-  let connectorFromX: number;
-  if (connectorStyle === 'curve') {
-    // Curved connectors start from the right edge of the text
-    connectorFromX = labelX + estimateTextWidth(annotation.text, fontSize, fontWeight);
-  } else if (lines.length > 1) {
-    // Multi-line text uses text-anchor: middle, so labelX is already the center
-    connectorFromX = labelX;
-  } else {
-    // Straight connectors start from the horizontal center of the text
-    connectorFromX = labelX + estimateTextWidth(annotation.text, fontSize, fontWeight) / 2;
-  }
-
-  // Connector from.y sits at the bottom of the text block
-  const connectorFromY = labelY + (lines.length - 1) * fontSize * lineHeight + fontSize * 0.3;
+  const { x: connectorFromX, y: connectorFromY } = computeConnectorOrigin(
+    labelX,
+    labelY,
+    annotation.text,
+    fontSize,
+    fontWeight,
+    px,
+    py,
+    connectorStyle,
+  );
 
   // Apply user-provided connector endpoint offsets
   const baseFrom = { x: connectorFromX, y: connectorFromY };
@@ -402,25 +473,9 @@ function resolveRefLineAnnotation(
 
 /** Estimate the bounding box of an annotation label. */
 function estimateLabelBounds(label: ResolvedLabel): Rect {
-  const lines = label.text.split('\n');
   const fontSize = label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
   const fontWeight = label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
-  const lineHeight = label.style.lineHeight ?? 1.3;
-
-  const maxWidth = Math.max(...lines.map((line) => estimateTextWidth(line, fontSize, fontWeight)));
-  const totalHeight = lines.length * fontSize * lineHeight;
-
-  // Multi-line text is rendered with text-anchor: middle by the SVG renderer,
-  // so the text is centered at label.x. Single-line uses the style's textAnchor.
-  const isMultiLine = lines.length > 1;
-  const anchorX = isMultiLine ? label.x - maxWidth / 2 : label.x;
-
-  return {
-    x: anchorX,
-    y: label.y - fontSize,
-    width: maxWidth,
-    height: totalHeight,
-  };
+  return computeTextBounds(label.x, label.y, label.text, fontSize, fontWeight);
 }
 
 /** Check if two rects overlap. */
@@ -491,19 +546,34 @@ function nudgeAnnotationFromObstacles(
   candidates.sort((a, b) => a.distance - b.distance);
 
   for (const { dx, dy } of candidates) {
+    const newLabelX = annotation.label.x + dx;
+    const newLabelY = annotation.label.y + dy;
+
+    // Recompute connector origin for the new label position so the connector
+    // exits from the edge closest to the data point after nudging.
+    let newConnector = annotation.label.connector;
+    if (newConnector) {
+      const annFontSize = annotation.label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+      const annFontWeight = annotation.label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+      const connStyle = newConnector.style === 'curve' ? ('curve' as const) : ('straight' as const);
+      const newFrom = computeConnectorOrigin(
+        newLabelX,
+        newLabelY,
+        annotation.label.text,
+        annFontSize,
+        annFontWeight,
+        px,
+        py,
+        connStyle,
+      );
+      newConnector = { ...newConnector, from: newFrom };
+    }
+
     const candidateLabel: ResolvedLabel = {
       ...annotation.label,
-      x: annotation.label.x + dx,
-      y: annotation.label.y + dy,
-      connector: annotation.label.connector
-        ? {
-            ...annotation.label.connector,
-            from: {
-              x: annotation.label.connector.from.x + dx,
-              y: annotation.label.connector.from.y + dy,
-            },
-          }
-        : undefined,
+      x: newLabelX,
+      y: newLabelY,
+      connector: newConnector,
     };
 
     const candidateBounds = estimateLabelBounds(candidateLabel);

package/src/charts/__tests__/utils.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from 'vitest';
+import { sortByField } from '../utils';
+
+describe('sortByField', () => {
+  // -----------------------------------------------------------------------
+  // Numeric sorting
+  // -----------------------------------------------------------------------
+
+  it('sorts numeric values ascending', () => {
+    const data = [{ v: 30 }, { v: 10 }, { v: 20 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([10, 20, 30]);
+  });
+
+  it('sorts negative and positive numbers correctly', () => {
+    const data = [{ v: 5 }, { v: -3 }, { v: 0 }, { v: -1 }, { v: 2 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([-3, -1, 0, 2, 5]);
+  });
+
+  it('sorts floating point numbers correctly', () => {
+    const data = [{ v: 1.5 }, { v: 1.1 }, { v: 1.9 }, { v: 1.3 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([1.1, 1.3, 1.5, 1.9]);
+  });
+
+  // -----------------------------------------------------------------------
+  // Date string sorting (ISO format)
+  // -----------------------------------------------------------------------
+
+  it('sorts ISO date strings (YYYY-MM-DD) lexicographically', () => {
+    const data = [
+      { date: '2022-01-01', v: 1 },
+      { date: '2020-06-15', v: 2 },
+      { date: '2021-03-10', v: 3 },
+    ];
+    const sorted = sortByField(data, 'date');
+    expect(sorted.map((r) => r.date)).toEqual(['2020-06-15', '2021-03-10', '2022-01-01']);
+  });
+
+  it('sorts dates within the same year by month and day', () => {
+    const data = [
+      { date: '2020-12-25' },
+      { date: '2020-01-01' },
+      { date: '2020-06-15' },
+      { date: '2020-03-20' },
+    ];
+    const sorted = sortByField(data, 'date');
+    expect(sorted.map((r) => r.date)).toEqual([
+      '2020-01-01',
+      '2020-03-20',
+      '2020-06-15',
+      '2020-12-25',
+    ]);
+  });
+
+  it('sorts full ISO datetime strings with time component', () => {
+    const data = [
+      { ts: '2020-01-01T23:59:59Z' },
+      { ts: '2020-01-01T00:00:00Z' },
+      { ts: '2020-01-01T12:30:00Z' },
+    ];
+    const sorted = sortByField(data, 'ts');
+    expect(sorted.map((r) => r.ts)).toEqual([
+      '2020-01-01T00:00:00Z',
+      '2020-01-01T12:30:00Z',
+      '2020-01-01T23:59:59Z',
+    ]);
+  });
+
+  it('sorts reverse-ordered dates correctly', () => {
+    const data = [
+      { date: '2025-01-01' },
+      { date: '2024-01-01' },
+      { date: '2023-01-01' },
+      { date: '2022-01-01' },
+    ];
+    const sorted = sortByField(data, 'date');
+    expect(sorted.map((r) => r.date)).toEqual([
+      '2022-01-01',
+      '2023-01-01',
+      '2024-01-01',
+      '2025-01-01',
+    ]);
+  });
+
+  // -----------------------------------------------------------------------
+  // String-encoded numbers (year columns from CSV data)
+  // -----------------------------------------------------------------------
+
+  it('sorts string-encoded year numbers numerically', () => {
+    const data = [{ year: '2022' }, { year: '2020' }, { year: '2021' }];
+    const sorted = sortByField(data, 'year');
+    expect(sorted.map((r) => r.year)).toEqual(['2020', '2021', '2022']);
+  });
+
+  it('sorts string-encoded decimal numbers numerically', () => {
+    const data = [{ v: '10.5' }, { v: '2.3' }, { v: '100.1' }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual(['2.3', '10.5', '100.1']);
+  });
+
+  // -----------------------------------------------------------------------
+  // Date objects
+  // -----------------------------------------------------------------------
+
+  it('sorts Date objects by timestamp', () => {
+    const d1 = new Date('2020-06-15T00:00:00');
+    const d2 = new Date('2021-06-15T00:00:00');
+    const d3 = new Date('2022-06-15T00:00:00');
+    const data = [{ d: d3 }, { d: d1 }, { d: d2 }];
+    const sorted = sortByField(data, 'd');
+    expect(sorted.map((r) => r.d)).toEqual([d1, d2, d3]);
+  });
+
+  // -----------------------------------------------------------------------
+  // Null / undefined handling
+  // -----------------------------------------------------------------------
+
+  it('pushes nulls to the end', () => {
+    const data = [{ v: null }, { v: 10 }, { v: 30 }, { v: null }, { v: 20 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([10, 20, 30, null, null]);
+  });
+
+  it('pushes undefined (missing field) to the end', () => {
+    const data = [{ other: 1 }, { v: 10, other: 2 }, { v: 20, other: 3 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([10, 20, undefined]);
+  });
+
+  it('handles all-null values without crashing', () => {
+    const data = [{ v: null }, { v: null }, { v: null }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted).toHaveLength(3);
+    expect(sorted.every((r) => r.v === null)).toBe(true);
+  });
+
+  // -----------------------------------------------------------------------
+  // Duplicate values
+  // -----------------------------------------------------------------------
+
+  it('handles duplicate values preserving both rows', () => {
+    const data = [{ v: 20 }, { v: 10 }, { v: 20 }, { v: 10 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([10, 10, 20, 20]);
+  });
+
+  it('handles duplicate date strings', () => {
+    const data = [
+      { date: '2021-01-01', id: 'c' },
+      { date: '2020-01-01', id: 'b' },
+      { date: '2021-01-01', id: 'a' },
+    ];
+    const sorted = sortByField(data, 'date');
+    // Both 2021 rows follow the 2020 row
+    expect(sorted[0].date).toBe('2020-01-01');
+    expect(sorted[1].date).toBe('2021-01-01');
+    expect(sorted[2].date).toBe('2021-01-01');
+  });
+
+  // -----------------------------------------------------------------------
+  // Edge cases
+  // -----------------------------------------------------------------------
+
+  it('returns a new array (no mutation)', () => {
+    const data = [{ v: 30 }, { v: 10 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted).not.toBe(data);
+    expect(data[0].v).toBe(30);
+  });
+
+  it('handles empty array', () => {
+    expect(sortByField([], 'v')).toEqual([]);
+  });
+
+  it('handles single element', () => {
+    const data = [{ v: 42 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted).toHaveLength(1);
+    expect(sorted[0].v).toBe(42);
+  });
+
+  it('handles already-sorted data', () => {
+    const data = [{ v: 1 }, { v: 2 }, { v: 3 }];
+    const sorted = sortByField(data, 'v');
+    expect(sorted.map((r) => r.v)).toEqual([1, 2, 3]);
+  });
+
+  it('sorts pure string values lexicographically', () => {
+    const data = [{ name: 'cherry' }, { name: 'apple' }, { name: 'banana' }];
+    const sorted = sortByField(data, 'name');
+    expect(sorted.map((r) => r.name)).toEqual(['apple', 'banana', 'cherry']);
+  });
+});