@opendata-ai/openchart-core 6.19.3 → 6.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-core",
-  "version": "6.19.3",
+  "version": "6.21.0",
   "description": "Types, theme, colors, accessibility, and utilities for openchart",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",

package/src/index.ts

@@ -58,6 +58,7 @@ export {
   BRAND_RESERVE_WIDTH,
   computeChrome,
   estimateTextWidth,
+  wrapText,
 } from './layout/index';
 
 // ---------------------------------------------------------------------------

package/src/layout/__tests__/text-measure.test.ts

@@ -30,6 +30,15 @@ describe('estimateTextWidth', () => {
     expect(width).toBeGreaterThan(100);
     expect(width).toBeLessThan(250);
   });
+
+  // Characterization test (refactor/v7-cohesion step 1):
+  // Pins the AVG_CHAR_WIDTH_RATIO = 0.57 constant introduced in commit e7b98f9.
+  // Any future tuning of the ratio changes layout-wide text wrapping decisions,
+  // so we freeze the exact numeric output of the canonical call.
+  it('estimateTextWidth("sample", 14, 400) returns the locked numeric value', () => {
+    // 6 chars * (14 * 0.57 * 1.0) = 6 * 7.98 = 47.88
+    expect(estimateTextWidth('sample', 14, 400)).toBeCloseTo(47.88, 5);
+  });
 });
 
 describe('estimateTextHeight', () => {

package/src/layout/index.ts

@@ -11,3 +11,4 @@ export {
   estimateTextHeight,
   estimateTextWidth,
 } from './text-measure';
+export { wrapText } from './text-wrap';

package/src/layout/text-wrap.ts

@@ -0,0 +1,93 @@
+/**
+ * Word-wrap a text string into lines that fit within a max width.
+ *
+ * Shared by the SVG chart renderer and the sankey renderer. When a
+ * `measureText` callback is provided, uses real DOM measurement for
+ * accurate wrapping. Otherwise falls back to a character-width
+ * heuristic driven by `estimateCharWidth` from text-measure.ts.
+ *
+ * Callers that want heuristic-only behavior (e.g. sankey) should omit
+ * the measureText argument. Do not change the signature without
+ * re-verifying visual baselines for every caller.
+ */
+
+import type { MeasureTextFn } from '../types/layout';
+import { estimateCharWidth } from './text-measure';
+
+/**
+ * Break text into lines that fit within maxWidth using word wrapping.
+ *
+ * Splits on explicit newlines first, then word-wraps each segment.
+ * Preserves empty segments so consecutive newlines produce blank lines.
+ *
+ * @param text - The text to wrap. May contain `\n` for forced breaks.
+ * @param fontSize - Font size in pixels.
+ * @param fontWeight - Font weight (100-900).
+ * @param maxWidth - Maximum line width in pixels. Non-positive values return `[text]` unchanged.
+ * @param measureText - Optional real text measurer. When omitted, uses a character-width heuristic.
+ */
+export function wrapText(
+  text: string,
+  fontSize: number,
+  fontWeight: number,
+  maxWidth: number,
+  measureText?: MeasureTextFn,
+): string[] {
+  if (maxWidth <= 0) return [text];
+
+  // Split on explicit newlines first
+  const segments = text.split('\n');
+  if (segments.length > 1) {
+    return segments.flatMap((segment) =>
+      segment.length === 0 ? [''] : wrapText(segment, fontSize, fontWeight, maxWidth, measureText),
+    );
+  }
+
+  // Use real text measurement when available
+  if (measureText) {
+    const textWidth = measureText(text, fontSize, fontWeight).width;
+    if (textWidth <= maxWidth) return [text];
+
+    const words = text.split(' ');
+    const lines: string[] = [];
+    let current = '';
+
+    for (const word of words) {
+      const candidate = current ? `${current} ${word}` : word;
+      const candidateWidth = measureText(candidate, fontSize, fontWeight).width;
+      if (candidateWidth > maxWidth && current) {
+        lines.push(current);
+        current = word;
+      } else {
+        current = candidate;
+      }
+    }
+    if (current) lines.push(current);
+
+    return lines;
+  }
+
+  // Heuristic: estimate character width from font size and weight.
+  // Reuses the same ratio and weight adjustment constants as text-measure.
+  const charWidth = estimateCharWidth(fontSize, fontWeight);
+  const maxChars = Math.floor(maxWidth / charWidth);
+
+  if (text.length <= maxChars) return [text];
+
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let current = '';
+
+  for (const word of words) {
+    const candidate = current ? `${current} ${word}` : word;
+    if (candidate.length > maxChars && current) {
+      lines.push(current);
+      current = word;
+    } else {
+      current = candidate;
+    }
+  }
+  if (current) lines.push(current);
+
+  return lines;
+}