@outsidedata/dolex 0.1.0

package/src/utils/export.ts

@@ -0,0 +1,148 @@
+/**
+ * SVG Export Utilities — extract, inline, and download charts.
+ *
+ * Provides functions to serialize SVG elements to strings, inline
+ * computed styles for portability, and trigger browser downloads
+ * as SVG or PNG. All functions are DOM-dependent (browser only).
+ */
+
+// ─── SVG TO STRING ───────────────────────────────────────────────────────────
+
+/**
+ * Serialize an SVG element to a string.
+ *
+ * @param svgElement - The SVG DOM element
+ * @returns SVG markup string
+ */
+export function svgToString(svgElement: SVGSVGElement): string {
+  const serializer = new XMLSerializer();
+  let svgString = serializer.serializeToString(svgElement);
+
+  // Ensure XML declaration and namespace
+  if (!svgString.startsWith('<?xml')) {
+    svgString = '<?xml version="1.0" encoding="UTF-8"?>\n' + svgString;
+  }
+  if (!svgString.includes('xmlns="http://www.w3.org/2000/svg"')) {
+    svgString = svgString.replace('<svg', '<svg xmlns="http://www.w3.org/2000/svg"');
+  }
+
+  return svgString;
+}
+
+// ─── INLINE STYLES ───────────────────────────────────────────────────────────
+
+/** CSS properties to inline for portability */
+const INLINE_PROPS = [
+  'fill',
+  'stroke',
+  'stroke-width',
+  'stroke-dasharray',
+  'opacity',
+  'font-family',
+  'font-size',
+  'font-weight',
+  'text-anchor',
+  'dominant-baseline',
+  'transform',
+] as const;
+
+/**
+ * Inline computed styles on all SVG child elements.
+ *
+ * This makes the SVG portable — it will look the same when opened
+ * outside the original page context (e.g., in Illustrator, Figma).
+ *
+ * @param svgElement - The SVG DOM element to process (mutated in place)
+ */
+export function inlineStyles(svgElement: SVGSVGElement): void {
+  const elements = svgElement.querySelectorAll('*');
+  elements.forEach((el) => {
+    const computed = getComputedStyle(el);
+    const style = (el as SVGElement).style;
+    for (const prop of INLINE_PROPS) {
+      const value = computed.getPropertyValue(prop);
+      if (value && value !== 'none' && value !== 'normal' && value !== '0px') {
+        style.setProperty(prop, value);
+      }
+    }
+  });
+}
+
+// ─── DOWNLOAD SVG ────────────────────────────────────────────────────────────
+
+/**
+ * Trigger a browser download of an SVG element as an .svg file.
+ *
+ * @param svgElement - The SVG DOM element
+ * @param filename - Download filename (default 'chart.svg')
+ * @param options - Optional: whether to inline styles first
+ */
+export function downloadSvg(
+  svgElement: SVGSVGElement,
+  filename = 'chart.svg',
+  options?: { inlineStyles?: boolean }
+): void {
+  if (options?.inlineStyles !== false) {
+    inlineStyles(svgElement);
+  }
+
+  const svgString = svgToString(svgElement);
+  const blob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}
+
+// ─── SVG TO PNG ──────────────────────────────────────────────────────────────
+
+/**
+ * Convert an SVG element to a PNG data URL via canvas.
+ *
+ * @param svgElement - The SVG DOM element
+ * @param scale - Resolution multiplier (default 2 for retina)
+ * @returns Promise resolving to a PNG data URL string
+ */
+export function svgToPng(svgElement: SVGSVGElement, scale = 2): Promise<string> {
+  return new Promise((resolve, reject) => {
+    inlineStyles(svgElement);
+
+    const svgString = svgToString(svgElement);
+    const width = svgElement.width.baseVal.value || 800;
+    const height = svgElement.height.baseVal.value || 500;
+
+    const canvas = document.createElement('canvas');
+    canvas.width = width * scale;
+    canvas.height = height * scale;
+
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+      reject(new Error('Canvas 2D context not available'));
+      return;
+    }
+
+    ctx.scale(scale, scale);
+
+    const img = new Image();
+    const blob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' });
+    const url = URL.createObjectURL(blob);
+
+    img.onload = () => {
+      ctx.drawImage(img, 0, 0, width, height);
+      URL.revokeObjectURL(url);
+      resolve(canvas.toDataURL('image/png'));
+    };
+
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error('Failed to load SVG into image'));
+    };
+
+    img.src = url;
+  });
+}

package/src/utils/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Dolex Utilities — barrel export.
+ */
+
+export {
+  measureText,
+  truncateLabel,
+  abbreviate,
+  avoidCollisions,
+  labelStrategy,
+} from './labels.js';
+
+export type {
+  LabelPosition,
+  ResolvedLabel,
+  LabelStrategyMode,
+  LabelStrategyResult,
+} from './labels.js';
+
+export {
+  getContainerMode,
+  responsiveMargins,
+  responsiveFontSize,
+  responsiveTicks,
+} from './responsive.js';
+
+export type {
+  ContainerMode,
+  ChartMargins,
+} from './responsive.js';
+
+export {
+  svgToString,
+  inlineStyles,
+  downloadSvg,
+  svgToPng,
+} from './export.js';

package/src/utils/labels.ts

@@ -0,0 +1,266 @@
+/**
+ * Smart Label Utilities — the biggest differentiator.
+ *
+ * Every chart renderer benefits from intelligent label placement:
+ * truncation, collision avoidance, abbreviation, and adaptive
+ * strategies based on available space.
+ */
+
+// ─── TEXT MEASUREMENT ────────────────────────────────────────────────────────
+
+/**
+ * Approximate text width in pixels using character-count heuristics.
+ * Works without a DOM (server-side safe). Uses average character widths
+ * for common sans-serif fonts at the given size.
+ *
+ * @param text - The string to measure
+ * @param fontSize - Font size in pixels (default 12)
+ * @returns Approximate width in pixels
+ */
+export function measureText(text: string, fontSize = 12): number {
+  // Average character width ratios for sans-serif (Inter-like) at 1px font-size
+  // Narrow chars: i, l, 1, :, . ~0.3
+  // Wide chars: m, w, M, W ~0.7
+  // Average: ~0.52
+  const narrow = /[il1:.,;!|']/g;
+  const wide = /[mwMWGOQD@]/g;
+  const narrowCount = (text.match(narrow) || []).length;
+  const wideCount = (text.match(wide) || []).length;
+  const normalCount = text.length - narrowCount - wideCount;
+
+  const avgWidth = (narrowCount * 0.33 + normalCount * 0.52 + wideCount * 0.72) * fontSize;
+  return Math.ceil(avgWidth);
+}
+
+// ─── TRUNCATION ──────────────────────────────────────────────────────────────
+
+/**
+ * Truncate a label to fit within a given pixel width.
+ *
+ * @param text - The label text
+ * @param maxWidth - Maximum allowed width in pixels
+ * @param fontSize - Font size in pixels (default 12)
+ * @param ellipsis - Ellipsis string (default '…')
+ * @returns Truncated text with ellipsis if needed
+ */
+export function truncateLabel(
+  text: string,
+  maxWidth: number,
+  fontSize = 12,
+  ellipsis = '…'
+): string {
+  if (measureText(text, fontSize) <= maxWidth) return text;
+
+  const ellipsisWidth = measureText(ellipsis, fontSize);
+  const targetWidth = maxWidth - ellipsisWidth;
+  if (targetWidth <= 0) return ellipsis;
+
+  // Binary search for the right truncation point
+  let lo = 0;
+  let hi = text.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (measureText(text.slice(0, mid), fontSize) <= targetWidth) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+
+  return text.slice(0, lo) + ellipsis;
+}
+
+// ─── ABBREVIATION ────────────────────────────────────────────────────────────
+
+/** Common abbreviation rules for chart labels */
+const ABBREVIATIONS: [RegExp, string][] = [
+  [/\bJanuary\b/gi, 'Jan'],
+  [/\bFebruary\b/gi, 'Feb'],
+  [/\bMarch\b/gi, 'Mar'],
+  [/\bApril\b/gi, 'Apr'],
+  [/\bJune\b/gi, 'Jun'],
+  [/\bJuly\b/gi, 'Jul'],
+  [/\bAugust\b/gi, 'Aug'],
+  [/\bSeptember\b/gi, 'Sep'],
+  [/\bOctober\b/gi, 'Oct'],
+  [/\bNovember\b/gi, 'Nov'],
+  [/\bDecember\b/gi, 'Dec'],
+  [/\bQuarter\b/gi, 'Q'],
+  [/\bDepartment\b/gi, 'Dept'],
+  [/\bManagement\b/gi, 'Mgmt'],
+  [/\bInternational\b/gi, "Int'l"],
+  [/\bManufacturing\b/gi, 'Mfg'],
+  [/\bEngineering\b/gi, 'Eng'],
+  [/\bTechnology\b/gi, 'Tech'],
+  [/\bDevelopment\b/gi, 'Dev'],
+  [/\bUnited States\b/gi, 'US'],
+  [/\bUnited Kingdom\b/gi, 'UK'],
+  [/\bMillions?\b/gi, 'M'],
+  [/\bBillions?\b/gi, 'B'],
+  [/\bThousands?\b/gi, 'K'],
+];
+
+/**
+ * Apply common abbreviation rules to shorten a label.
+ *
+ * @param text - The label text
+ * @returns Abbreviated text
+ */
+export function abbreviate(text: string): string {
+  let result = text;
+  for (const [pattern, replacement] of ABBREVIATIONS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+// ─── COLLISION AVOIDANCE ─────────────────────────────────────────────────────
+
+export interface LabelPosition {
+  x: number;
+  y: number;
+  text: string;
+  width?: number;
+  height?: number;
+}
+
+export interface ResolvedLabel extends LabelPosition {
+  originalY: number;
+  hidden: boolean;
+}
+
+/**
+ * Resolve label collisions by nudging overlapping labels apart vertically.
+ *
+ * Labels are sorted by y position, then any overlapping pair is spread
+ * apart symmetrically. Labels that still can't fit are marked `hidden`.
+ *
+ * @param labels - Array of label positions
+ * @param fontSize - Font size for height estimation (default 12)
+ * @param padding - Minimum vertical gap between labels in pixels (default 2)
+ * @param bounds - Optional vertical bounds { top, bottom }
+ * @returns Resolved labels with adjusted y positions and hidden flags
+ */
+export function avoidCollisions(
+  labels: LabelPosition[],
+  fontSize = 12,
+  padding = 2,
+  bounds?: { top: number; bottom: number }
+): ResolvedLabel[] {
+  const labelHeight = fontSize * 1.2;
+  const minGap = labelHeight + padding;
+
+  // Create resolved copies sorted by y
+  const resolved: ResolvedLabel[] = labels
+    .map((l) => ({
+      ...l,
+      width: l.width ?? measureText(l.text, fontSize),
+      height: l.height ?? labelHeight,
+      originalY: l.y,
+      hidden: false,
+    }))
+    .sort((a, b) => a.y - b.y);
+
+  // Push overlapping labels apart
+  for (let pass = 0; pass < 5; pass++) {
+    let moved = false;
+    for (let i = 1; i < resolved.length; i++) {
+      const prev = resolved[i - 1];
+      const curr = resolved[i];
+      if (prev.hidden || curr.hidden) continue;
+
+      const overlap = prev.y + minGap - curr.y;
+      if (overlap > 0) {
+        const shift = overlap / 2;
+        prev.y -= shift;
+        curr.y += shift;
+        moved = true;
+      }
+    }
+    if (!moved) break;
+  }
+
+  // Clamp to bounds and hide if out of range
+  if (bounds) {
+    for (const label of resolved) {
+      if (label.y < bounds.top || label.y > bounds.bottom) {
+        label.hidden = true;
+      }
+      label.y = Math.max(bounds.top, Math.min(bounds.bottom, label.y));
+    }
+  }
+
+  return resolved;
+}
+
+// ─── LABEL STRATEGY ──────────────────────────────────────────────────────────
+
+export type LabelStrategyMode = 'full' | 'abbreviated' | 'truncated' | 'rotated' | 'hidden';
+
+export interface LabelStrategyResult {
+  mode: LabelStrategyMode;
+  labels: string[];
+  rotation?: number;
+  fontSize: number;
+}
+
+/**
+ * Determine the best labeling strategy given labels and available space.
+ *
+ * Tries strategies in order: full → abbreviated → truncated → rotated → hidden.
+ * Returns the first strategy where all labels fit.
+ *
+ * @param labels - Array of label strings
+ * @param availableWidth - Total available width in pixels
+ * @param fontSize - Base font size (default 12)
+ * @returns The recommended strategy with transformed labels
+ */
+export function labelStrategy(
+  labels: string[],
+  availableWidth: number,
+  fontSize = 12
+): LabelStrategyResult {
+  const perLabel = availableWidth / Math.max(labels.length, 1);
+
+  // Strategy 1: Full labels fit
+  const maxFullWidth = Math.max(...labels.map((l) => measureText(l, fontSize)));
+  if (maxFullWidth <= perLabel) {
+    return { mode: 'full', labels, fontSize };
+  }
+
+  // Strategy 2: Abbreviated labels
+  const abbreviated = labels.map(abbreviate);
+  const maxAbbrWidth = Math.max(...abbreviated.map((l) => measureText(l, fontSize)));
+  if (maxAbbrWidth <= perLabel) {
+    return { mode: 'abbreviated', labels: abbreviated, fontSize };
+  }
+
+  // Strategy 3: Truncated labels
+  const truncated = labels.map((l) => truncateLabel(l, perLabel, fontSize));
+  const maxTruncWidth = Math.max(...truncated.map((l) => measureText(l, fontSize)));
+  if (maxTruncWidth <= perLabel) {
+    return { mode: 'truncated', labels: truncated, fontSize };
+  }
+
+  // Strategy 4: Rotated at 45° (effective width = height ≈ fontSize)
+  // At 45° rotation, the effective horizontal footprint is roughly fontSize * 1.2
+  const rotatedFootprint = fontSize * 1.2;
+  if (rotatedFootprint <= perLabel) {
+    return { mode: 'rotated', labels: abbreviated, rotation: -45, fontSize };
+  }
+
+  // Strategy 5: Smaller font + rotation
+  const smallFontSize = Math.max(9, fontSize - 2);
+  const smallRotatedFootprint = smallFontSize * 1.2;
+  if (smallRotatedFootprint <= perLabel) {
+    return {
+      mode: 'rotated',
+      labels: labels.map((l) => truncateLabel(l, perLabel * 2, smallFontSize)),
+      rotation: -45,
+      fontSize: smallFontSize,
+    };
+  }
+
+  // Strategy 6: Hide labels (too many to show)
+  return { mode: 'hidden', labels: [], fontSize };
+}

package/src/utils/responsive.ts

@@ -0,0 +1,121 @@
+/**
+ * Responsive Utilities — adaptive sizing for different container dimensions.
+ *
+ * Provides container-aware breakpoints, margin calculations, font sizing,
+ * and tick count recommendations so charts look good at any size.
+ */
+
+// ─── CONTAINER MODES ─────────────────────────────────────────────────────────
+
+export type ContainerMode = 'compact' | 'default' | 'wide' | 'large';
+
+/**
+ * Determine the container mode based on width and height.
+ *
+ * @param width - Container width in pixels
+ * @param height - Container height in pixels (optional)
+ * @returns The container mode
+ */
+export function getContainerMode(width: number, height?: number): ContainerMode {
+  if (width < 320) return 'compact';
+  if (width < 600) return 'default';
+  if (width < 1000) return 'wide';
+  return 'large';
+}
+
+// ─── RESPONSIVE MARGINS ──────────────────────────────────────────────────────
+
+export interface ChartMargins {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/**
+ * Calculate responsive margins based on container dimensions.
+ *
+ * Smaller containers get tighter margins to maximize chart area.
+ * Larger containers get roomier margins for labels and legends.
+ *
+ * @param width - Container width in pixels
+ * @param height - Container height in pixels
+ * @param options - Optional overrides
+ * @returns Calculated margins
+ */
+export function responsiveMargins(
+  width: number,
+  height: number,
+  options?: {
+    hasTitle?: boolean;
+    hasXLabel?: boolean;
+    hasYLabel?: boolean;
+    hasLegend?: boolean;
+  }
+): ChartMargins {
+  const mode = getContainerMode(width);
+  const opts = options ?? {};
+
+  const base: Record<ContainerMode, ChartMargins> = {
+    compact: { top: 24, right: 12, bottom: 30, left: 36 },
+    default: { top: 36, right: 24, bottom: 44, left: 52 },
+    wide: { top: 40, right: 30, bottom: 50, left: 60 },
+    large: { top: 48, right: 40, bottom: 56, left: 70 },
+  };
+
+  const m = { ...base[mode] };
+
+  if (opts.hasTitle) m.top += mode === 'compact' ? 8 : 12;
+  if (opts.hasXLabel) m.bottom += mode === 'compact' ? 10 : 16;
+  if (opts.hasYLabel) m.left += mode === 'compact' ? 10 : 16;
+  if (opts.hasLegend) m.right += mode === 'compact' ? 40 : 80;
+
+  return m;
+}
+
+// ─── RESPONSIVE FONT SIZE ────────────────────────────────────────────────────
+
+/**
+ * Calculate responsive font size based on container width.
+ *
+ * @param width - Container width in pixels
+ * @param role - The text role determining base size
+ * @returns Font size in pixels
+ */
+export function responsiveFontSize(
+  width: number,
+  role: 'title' | 'axisLabel' | 'tickLabel' | 'annotation' | 'legend' = 'tickLabel'
+): number {
+  const mode = getContainerMode(width);
+
+  const sizes: Record<typeof role, Record<ContainerMode, number>> = {
+    title: { compact: 11, default: 13, wide: 14, large: 16 },
+    axisLabel: { compact: 9, default: 11, wide: 12, large: 13 },
+    tickLabel: { compact: 8, default: 10, wide: 11, large: 12 },
+    annotation: { compact: 8, default: 10, wide: 11, large: 12 },
+    legend: { compact: 8, default: 10, wide: 11, large: 11 },
+  };
+
+  return sizes[role][mode];
+}
+
+// ─── RESPONSIVE TICKS ────────────────────────────────────────────────────────
+
+/**
+ * Calculate the recommended number of axis ticks based on available axis length.
+ *
+ * @param axisLength - Length of the axis in pixels
+ * @param isCategory - Whether this is a categorical (band) axis
+ * @returns Recommended tick count
+ */
+export function responsiveTicks(axisLength: number, isCategory = false): number {
+  if (isCategory) {
+    // For categories, show every label up to a threshold, then skip
+    const maxVisible = Math.floor(axisLength / 60);
+    return Math.max(2, maxVisible);
+  }
+
+  // Quantitative/temporal: target ~80px per tick
+  const tickCount = Math.max(2, Math.floor(axisLength / 80));
+  return Math.min(tickCount, 12);
+}