@outsidedata/dolex 0.1.0

package/src/renderers/d3/flow/sankey-layout.ts

@@ -0,0 +1,202 @@
+/**
+ * Simplified sankey layout computation.
+ *
+ * Assigns nodes to layers via topological ordering,
+ * then positions nodes and links within available space.
+ * Extracted from the sankey renderer for clarity.
+ */
+
+declare const d3: any;
+
+export interface SankeyNode {
+  name: string;
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+  value: number;
+  sourceLinks: SankeyLink[];
+  targetLinks: SankeyLink[];
+  layer: number;
+}
+
+export interface SankeyLink {
+  source: SankeyNode;
+  target: SankeyNode;
+  value: number;
+  width: number;
+  y0: number;
+  y1: number;
+}
+
+export function computeSankeyLayout(
+  nodeNames: string[],
+  linkData: { source: string; target: string; value: number }[],
+  width: number,
+  height: number,
+  nodeWidth: number,
+  nodePadding: number
+): { nodes: SankeyNode[]; links: SankeyLink[] } {
+  // Create node map
+  const nodeMap = new Map<string, SankeyNode>();
+  nodeNames.forEach((name) => {
+    nodeMap.set(name, {
+      name,
+      x0: 0,
+      x1: 0,
+      y0: 0,
+      y1: 0,
+      value: 0,
+      sourceLinks: [],
+      targetLinks: [],
+      layer: 0,
+    });
+  });
+
+  // Create links
+  const links: SankeyLink[] = linkData
+    .map((l) => {
+      const source = nodeMap.get(l.source);
+      const target = nodeMap.get(l.target);
+      if (!source || !target) return null;
+      const link: SankeyLink = {
+        source,
+        target,
+        value: l.value,
+        width: 0,
+        y0: 0,
+        y1: 0,
+      };
+      source.sourceLinks.push(link);
+      target.targetLinks.push(link);
+      return link;
+    })
+    .filter(Boolean) as SankeyLink[];
+
+  const nodes = [...nodeMap.values()];
+
+  computeNodeValues(nodes);
+  assignLayers(nodes);
+  positionNodes(nodes, width, height, nodeWidth, nodePadding);
+  computeLinkPositions(nodes, links);
+
+  return { nodes, links };
+}
+
+function computeNodeValues(nodes: SankeyNode[]): void {
+  nodes.forEach((node) => {
+    const outSum = node.sourceLinks.reduce((s, l) => s + l.value, 0);
+    const inSum = node.targetLinks.reduce((s, l) => s + l.value, 0);
+    node.value = Math.max(outSum, inSum);
+  });
+}
+
+function assignLayers(nodes: SankeyNode[]): void {
+  const sources = nodes.filter((n) => n.targetLinks.length === 0);
+  const visited = new Set<string>();
+  const queue = sources.map((n) => ({ node: n, layer: 0 }));
+
+  while (queue.length > 0) {
+    const { node, layer } = queue.shift()!;
+    if (visited.has(node.name)) continue;
+    visited.add(node.name);
+    node.layer = layer;
+
+    node.sourceLinks.forEach((link) => {
+      if (!visited.has(link.target.name)) {
+        queue.push({ node: link.target, layer: layer + 1 });
+      }
+    });
+  }
+
+  // Handle unvisited nodes (cycles or disconnected)
+  nodes.forEach((n) => {
+    if (!visited.has(n.name)) {
+      n.layer = 0;
+      visited.add(n.name);
+    }
+  });
+}
+
+function positionNodes(
+  nodes: SankeyNode[],
+  width: number,
+  height: number,
+  nodeWidth: number,
+  nodePadding: number
+): void {
+  const maxLayer = d3.max(nodes, (n: SankeyNode) => n.layer) || 0;
+  const layerGap = maxLayer > 0 ? (width - nodeWidth) / maxLayer : 0;
+
+  // Assign x positions
+  nodes.forEach((node) => {
+    node.x0 = node.layer * layerGap;
+    node.x1 = node.x0 + nodeWidth;
+  });
+
+  // Group by layer and assign y positions
+  const layers: SankeyNode[][] = [];
+  for (let i = 0; i <= maxLayer; i++) {
+    layers[i] = nodes.filter((n) => n.layer === i);
+  }
+
+  layers.forEach((layerNodes) => {
+    layerNodes.sort((a, b) => b.value - a.value);
+
+    const totalValue = layerNodes.reduce((s, n) => s + n.value, 0);
+    const totalPadding = (layerNodes.length - 1) * nodePadding;
+    const availableHeight = height - totalPadding;
+    const scale = totalValue > 0 ? availableHeight / totalValue : 1;
+
+    const MIN_NODE_HEIGHT = 3;
+    let y = 0;
+    layerNodes.forEach((node) => {
+      node.y0 = y;
+      node.y1 = y + Math.max(node.value * scale, MIN_NODE_HEIGHT);
+      y = node.y1 + nodePadding;
+    });
+
+    // Compress if exceeding height
+    const excess = y - nodePadding - height;
+    if (excess > 0 && layerNodes.length > 0) {
+      const compressionFactor = height / (y - nodePadding);
+      let cy = 0;
+      layerNodes.forEach((node) => {
+        const h = (node.y1 - node.y0) * compressionFactor;
+        node.y0 = cy;
+        node.y1 = cy + h;
+        cy += h + nodePadding * compressionFactor;
+      });
+    }
+  });
+}
+
+function computeLinkPositions(nodes: SankeyNode[], links: SankeyLink[]): void {
+  const MIN_LINK_WIDTH = 2;
+
+  links.forEach((link) => {
+    const sourceTotal = link.source.value || 1;
+    const sourceHeight = link.source.y1 - link.source.y0;
+    link.width = Math.max((link.value / sourceTotal) * sourceHeight, MIN_LINK_WIDTH);
+  });
+
+  nodes.forEach((node) => {
+    let sy = node.y0;
+    node.sourceLinks.sort((a, b) => a.target.y0 - b.target.y0);
+    node.sourceLinks.forEach((link) => {
+      link.y0 = sy;
+      sy += link.width;
+    });
+
+    let ty = node.y0;
+    node.targetLinks.sort((a, b) => a.source.y0 - b.source.y0);
+    node.targetLinks.forEach((link) => {
+      const targetTotal = node.value || 1;
+      const targetHeight = node.y1 - node.y0;
+      const w = Math.max((link.value / targetTotal) * targetHeight, MIN_LINK_WIDTH);
+      link.y1 = ty;
+      link.width = Math.min(link.width, w) || link.width;
+      ty += w;
+    });
+  });
+}

package/src/renderers/d3/flow/sankey.ts

@@ -0,0 +1,189 @@
+/**
+ * Sankey diagram D3 renderer.
+ */
+
+import type { VisualizationSpec } from '../../../types.js';
+import {
+  createSvg,
+  createTooltip,
+  showTooltip,
+  hideTooltip,
+  positionTooltip,
+  formatValue,
+  renderEmptyState,
+  isAllZeros,
+  DEFAULT_PALETTE,
+  TEXT_COLOR,
+  truncateLabel,
+} from '../shared.js';
+import { computeSankeyLayout } from './sankey-layout.js';
+import type { SankeyNode, SankeyLink } from './sankey-layout.js';
+
+declare const d3: any;
+
+export function renderSankey(container: HTMLElement, spec: VisualizationSpec): void {
+  const { config, encoding, data } = spec;
+  const sourceField = config.sourceField || encoding.source?.field;
+  const targetField = config.targetField || encoding.target?.field;
+  const valueField = config.valueField || encoding.size?.field;
+  const nodeWidth = config.nodeWidth ?? 20;
+  const nodePadding = config.nodePadding ?? 10;
+  const linkOpacity = config.linkOpacity ?? 0.4;
+
+  const { svg, g, dims } = createSvg(container, spec, { top: 40, left: 20, right: 20, bottom: 20 });
+  const tooltip = createTooltip(container);
+
+  // Check if all values are zero
+  if (valueField && isAllZeros(data, valueField)) {
+    renderEmptyState(g, dims);
+    return;
+  }
+
+  // Build nodes and links from data or config
+  let nodeNames: string[];
+  let linkData: { source: string; target: string; value: number }[];
+
+  if (config.nodes && config.links) {
+    nodeNames = config.nodes.map((n: any) => n.name);
+    linkData = config.links;
+  } else {
+    const sources = data.map((d) => String(d[sourceField]));
+    const targets = data.map((d) => String(d[targetField]));
+    nodeNames = [...new Set([...sources, ...targets])];
+    linkData = data.map((d) => ({
+      source: String(d[sourceField]),
+      target: String(d[targetField]),
+      value: Number(d[valueField]) || 1,
+    }));
+  }
+
+  const { nodes, links } = computeSankeyLayout(
+    nodeNames, linkData, dims.innerWidth, dims.innerHeight, nodeWidth, nodePadding
+  );
+
+  const nodeColorScale = d3.scaleOrdinal().domain(nodeNames).range(DEFAULT_PALETTE);
+
+  drawLinks(g, links, nodeColorScale, linkOpacity, tooltip);
+  drawNodes(g, nodes, nodeColorScale, dims, tooltip);
+
+  if (config.showLabels !== false) {
+    drawNodeLabels(g, nodes, config, dims);
+  }
+}
+
+function drawLinks(
+  g: any,
+  links: SankeyLink[],
+  colorScale: any,
+  linkOpacity: number,
+  tooltip: HTMLDivElement
+): void {
+  const linkPath = (link: SankeyLink) => {
+    const sx = link.source.x1;
+    const tx = link.target.x0;
+    const mx = (sx + tx) / 2;
+    const sy0 = link.y0;
+    const ty0 = link.y1;
+    const w = link.width;
+
+    return `
+      M ${sx},${sy0}
+      C ${mx},${sy0} ${mx},${ty0} ${tx},${ty0}
+      L ${tx},${ty0 + w}
+      C ${mx},${ty0 + w} ${mx},${sy0 + w} ${sx},${sy0 + w}
+      Z
+    `;
+  };
+
+  g.selectAll('.sankey-link')
+    .data(links)
+    .join('path')
+    .attr('class', 'sankey-link')
+    .attr('d', linkPath)
+    .attr('fill', (d: SankeyLink) => colorScale(d.source.name))
+    .attr('opacity', linkOpacity)
+    .attr('stroke', 'none')
+    .on('mouseover', function (event: MouseEvent, d: SankeyLink) {
+      d3.select(this).attr('opacity', linkOpacity + 0.3);
+      showTooltip(
+        tooltip,
+        `<strong>${d.source.name} → ${d.target.name}</strong><br/>Value: ${formatValue(d.value)}`,
+        event
+      );
+    })
+    .on('mousemove', (event: MouseEvent) => {
+      positionTooltip(tooltip, event);
+    })
+    .on('mouseout', function () {
+      d3.select(this).attr('opacity', linkOpacity);
+      hideTooltip(tooltip);
+    });
+}
+
+function drawNodes(
+  g: any,
+  nodes: SankeyNode[],
+  colorScale: any,
+  dims: any,
+  tooltip: HTMLDivElement
+): void {
+  g.selectAll('.sankey-node')
+    .data(nodes)
+    .join('rect')
+    .attr('class', 'sankey-node')
+    .attr('x', (d: SankeyNode) => d.x0)
+    .attr('y', (d: SankeyNode) => d.y0)
+    .attr('width', (d: SankeyNode) => d.x1 - d.x0)
+    .attr('height', (d: SankeyNode) => Math.max(d.y1 - d.y0, 3))
+    .attr('fill', (d: SankeyNode) => colorScale(d.name))
+    .attr('rx', 2)
+    .attr('stroke', '#0f1117')
+    .attr('stroke-width', 1)
+    .on('mouseover', function (event: MouseEvent, d: SankeyNode) {
+      d3.select(this).attr('opacity', 0.8);
+      const inflow = d.targetLinks.reduce((s, l) => s + l.value, 0);
+      const outflow = d.sourceLinks.reduce((s, l) => s + l.value, 0);
+      let html = `<strong>${d.name}</strong><br/>Total: ${formatValue(d.value)}`;
+      if (inflow > 0) html += `<br/>Inflow: ${formatValue(inflow)}`;
+      if (outflow > 0) html += `<br/>Outflow: ${formatValue(outflow)}`;
+      showTooltip(tooltip, html, event);
+    })
+    .on('mousemove', (event: MouseEvent) => {
+      positionTooltip(tooltip, event);
+    })
+    .on('mouseout', function () {
+      d3.select(this).attr('opacity', 1);
+      hideTooltip(tooltip);
+    });
+}
+
+function drawNodeLabels(
+  g: any,
+  nodes: SankeyNode[],
+  config: VisualizationSpec['config'],
+  dims: any
+): void {
+  g.selectAll('.sankey-label')
+    .data(nodes)
+    .join('text')
+    .attr('class', 'sankey-label')
+    .attr('x', (d: SankeyNode) => {
+      if (d.x0 < dims.innerWidth / 2) return d.x1 + 6;
+      return d.x0 - 6;
+    })
+    .attr('y', (d: SankeyNode) => (d.y0 + d.y1) / 2)
+    .attr('dy', '0.35em')
+    .attr('text-anchor', (d: SankeyNode) => (d.x0 < dims.innerWidth / 2 ? 'start' : 'end'))
+    .attr('fill', TEXT_COLOR)
+    .attr('font-size', '11px')
+    .attr('font-family', 'Inter, system-ui, sans-serif')
+    .text((d: SankeyNode) => {
+      const isRight = d.x0 >= dims.innerWidth / 2;
+      const availChars = isRight
+        ? Math.max(10, Math.floor((d.x0 - 6) / 6.5))
+        : Math.max(10, Math.floor((dims.innerWidth - d.x1 - 6) / 6.5));
+      const label = truncateLabel(d.name, Math.min(availChars, 30));
+      if (config.showValues !== false) return `${label} (${formatValue(d.value)})`;
+      return label;
+    });
+}

package/src/renderers/d3/geo/choropleth.ts

@@ -0,0 +1,198 @@
+import type { VisualizationSpec } from '../../../types.js';
+import {
+  createSvg,
+  createTooltip,
+  showTooltip,
+  hideTooltip,
+  positionTooltip,
+  formatValue,
+  TEXT_COLOR,
+  TEXT_MUTED,
+  AXIS_COLOR,
+} from '../shared.js';
+
+declare const d3: any;
+declare const topojson: any;
+
+function getInterpolator(scheme: string): any {
+  const map: Record<string, any> = {
+    blues: d3.interpolateBlues,
+    greens: d3.interpolateGreens,
+    reds: d3.interpolateReds,
+    oranges: d3.interpolateOranges,
+    purples: d3.interpolatePurples,
+  };
+  return map[scheme.toLowerCase()] || d3.interpolateBlues;
+}
+
+export function renderChoropleth(container: HTMLElement, spec: VisualizationSpec): void {
+  const { config = {}, encoding, data } = spec;
+
+  const geoField = config.geoField || (encoding.geo && encoding.geo.field);
+  const valueField = config.valueField || (encoding.color && encoding.color.field);
+  const projection = config.projection || 'naturalEarth1';
+  const mapType: string = config.mapType || 'world';
+  const colorScheme: string = config.colorScheme || 'blues';
+  const objectName: string | undefined = config.objectName;
+  const nameProperty: string = config.nameProperty || 'name';
+  const customCenter: [number, number] | undefined = config.center;
+  const customScale: number | undefined = config.scale;
+  const parallels: [number, number] | undefined = config.parallels;
+  const rotate: [number, number, number] | undefined = config.rotate;
+  const topojsonData: any = config.topojsonData;
+
+  if (!topojsonData) {
+    container.innerHTML = '<div style="color:#ef4444;padding:20px">TopoJSON data must be embedded at spec-generation time. No CDN fetches.</div>';
+    return;
+  }
+
+  const { svg, g, dims } = createSvg(container, spec, { top: 50, right: 20, bottom: 40, left: 20 });
+  const tooltip = createTooltip(container);
+
+  const valueLookup: Record<string, number> = {};
+  data.forEach((d) => {
+    const key = String(d[geoField]).toLowerCase().trim();
+    valueLookup[key] = Number(d[valueField]);
+  });
+
+  const allValues = data.map((d) => Number(d[valueField])).filter((v) => !isNaN(v));
+  const valExtent = d3.extent(allValues) as [number, number];
+
+  const hasMixedSign = valExtent[0] < 0 && valExtent[1] > 0;
+  const allNegative = valExtent[1] <= 0 && valExtent[0] < 0;
+  let colorScale: any;
+
+  if (hasMixedSign) {
+    const maxAbs = Math.max(Math.abs(valExtent[0]), Math.abs(valExtent[1]));
+    colorScale = d3.scaleDiverging(d3.interpolateRdBu).domain([maxAbs, 0, -maxAbs]);
+  } else if (allNegative) {
+    colorScale = d3.scaleSequential(d3.interpolateReds).domain([valExtent[0], valExtent[1]]);
+  } else {
+    const interpolator = getInterpolator(colorScheme);
+    const rangeRatio = valExtent[0] > 0 ? valExtent[1] / valExtent[0] : valExtent[1] > 0 ? Infinity : 1;
+    colorScale = rangeRatio > 100
+      ? d3.scaleQuantize().domain(valExtent).range(
+          d3.quantize(interpolator, 7)
+        )
+      : d3.scaleSequential(interpolator).domain(valExtent);
+  }
+
+  var features: any;
+  if (objectName) {
+    features = topojson.feature(topojsonData, topojsonData.objects[objectName]);
+  } else {
+    var objects = topojsonData.objects;
+    var objKey: string;
+    if (objects.countries) objKey = 'countries';
+    else if (objects.states) objKey = 'states';
+    else objKey = Object.keys(objects)[0];
+    features = topojson.feature(topojsonData, objects[objKey]);
+  }
+
+  var geoProjection: any;
+  if (projection === 'albersUsa') {
+    geoProjection = d3.geoAlbersUsa().fitSize([dims.innerWidth, dims.innerHeight], features);
+  } else {
+    var projName = 'geo' + projection.charAt(0).toUpperCase() + projection.slice(1);
+    var projFn = d3[projName] || d3.geoNaturalEarth1;
+    geoProjection = projFn();
+    if (rotate) geoProjection.rotate(rotate);
+    if (parallels && typeof geoProjection.parallels === 'function') geoProjection.parallels(parallels);
+    if (customScale) {
+      if (customCenter) geoProjection.center(customCenter);
+      geoProjection.scale(customScale);
+      geoProjection.translate([dims.innerWidth / 2, dims.innerHeight / 2]);
+    } else {
+      geoProjection.fitSize([dims.innerWidth, dims.innerHeight], features);
+    }
+  }
+
+  var path = d3.geoPath().projection(geoProjection);
+
+  function lookupValue(feature: any): number | null {
+    var props = feature.properties || {};
+    var nameFields = [nameProperty, 'name', 'NAME', 'admin', 'ADMIN', 'geounit'];
+    var name = '';
+    for (var i = 0; i < nameFields.length; i++) {
+      if (props[nameFields[i]]) { name = String(props[nameFields[i]]).toLowerCase().trim(); break; }
+    }
+    if (name && valueLookup[name] != null) return valueLookup[name];
+    for (var key in valueLookup) {
+      if (name && (name.indexOf(key) >= 0 || key.indexOf(name) >= 0)) {
+        return valueLookup[key];
+      }
+    }
+    return null;
+  }
+
+  g.selectAll('path.region')
+    .data(features.features)
+    .enter()
+    .append('path')
+    .attr('class', 'region')
+    .attr('d', path)
+    .attr('fill', function (d: any) {
+      var val = lookupValue(d);
+      return val != null ? colorScale(val) : '#1e2028';
+    })
+    .attr('stroke', '#2d3041')
+    .attr('stroke-width', 0.5)
+    .on('mouseover', function (event: MouseEvent, d: any) {
+      var props = d.properties || {};
+      var name = props[nameProperty] || props.name || props.NAME || props.admin || props.geounit || 'Unknown';
+      var val = lookupValue(d);
+      d3.select(this).attr('stroke', TEXT_COLOR).attr('stroke-width', 1.5);
+      showTooltip(
+        tooltip,
+        '<strong>' + name + '</strong>' +
+          (val != null
+            ? '<br/>' + valueField + ': ' + formatValue(val)
+            : '<br/><em>No data</em>'),
+        event
+      );
+    })
+    .on('mousemove', function (event: MouseEvent) {
+      positionTooltip(tooltip, event);
+    })
+    .on('mouseout', function () {
+      d3.select(this).attr('stroke', '#2d3041').attr('stroke-width', 0.5);
+      hideTooltip(tooltip);
+    });
+
+  var legendWidth = Math.min(200, dims.innerWidth * 0.3);
+  var legendHeight = 10;
+  var legendX = dims.innerWidth - legendWidth - 10;
+  var legendY = dims.innerHeight - 30;
+
+  var legendScale = d3.scaleLinear().domain(valExtent).range([0, legendWidth]);
+  var legendAxis = d3
+    .axisBottom(legendScale)
+    .ticks(4)
+    .tickFormat(function (d: number) {
+      return formatValue(d);
+    });
+
+  var gradientId = 'choropleth-gradient-' + Math.random().toString(36).slice(2, 8);
+  var defs = svg.append('defs');
+  var gradient = defs.append('linearGradient').attr('id', gradientId);
+  gradient.append('stop').attr('offset', '0%').attr('stop-color', colorScale(valExtent[0]));
+  gradient.append('stop').attr('offset', '50%').attr('stop-color', colorScale((valExtent[0] + valExtent[1]) / 2));
+  gradient.append('stop').attr('offset', '100%').attr('stop-color', colorScale(valExtent[1]));
+
+  var legendG = g.append('g').attr('transform', 'translate(' + legendX + ',' + legendY + ')');
+  legendG
+    .append('rect')
+    .attr('width', legendWidth)
+    .attr('height', legendHeight)
+    .attr('rx', 3)
+    .style('fill', 'url(#' + gradientId + ')');
+  legendG
+    .append('g')
+    .attr('transform', 'translate(0,' + legendHeight + ')')
+    .call(legendAxis)
+    .selectAll('text')
+    .attr('fill', TEXT_MUTED)
+    .attr('font-size', '9px')
+    .attr('font-family', 'Inter, system-ui, sans-serif');
+  legendG.selectAll('.domain, .tick line').attr('stroke', AXIS_COLOR);
+}