@outsidedata/dolex 0.1.0

package/src/renderers/d3/comparison/bump-chart.ts

@@ -0,0 +1,262 @@
+/**
+ * Bump chart D3 renderer.
+ *
+ * Shows rankings over time. X-axis is time periods (ordinal),
+ * Y-axis is rank (1 at top, inverted). Each entity is a smooth
+ * line connecting its rank at each time period.
+ */
+
+import type { VisualizationSpec } from '../../../types.js';
+import {
+  createSvg,
+  buildColorScale,
+  createLegend,
+  createTooltip,
+  showTooltip,
+  hideTooltip,
+  positionTooltip,
+  formatValue,
+  TEXT_MUTED,
+  GRID_COLOR,
+  DARK_BG,
+  truncateLabel,
+} from '../shared.js';
+
+declare const d3: any;
+
+export function renderBumpChart(container: HTMLElement, spec: VisualizationSpec): void {
+  const { config, encoding, data } = spec;
+
+  const categoryField = config.categoryField || encoding.color?.field || 'entity';
+  const timeField = config.timeField || encoding.x?.field || 'period';
+  const valueField = config.valueField || encoding.y?.field || 'value';
+  const showLabels = config.showLabels !== false;
+  const strokeWidth = config.strokeWidth ?? 2.5;
+  const dotRadius = config.dotRadius ?? 5;
+
+  container.style.display = 'flex';
+  container.style.flexDirection = 'column';
+  container.style.background = DARK_BG;
+  container.style.borderRadius = '8px';
+  container.style.overflow = 'hidden';
+
+  const chartWrapper = document.createElement('div');
+  chartWrapper.style.flex = '1';
+  chartWrapper.style.minHeight = '0';
+  container.appendChild(chartWrapper);
+
+  const { svg, g, dims } = createSvg(chartWrapper, spec, { left: 40, right: 100 });
+  svg.style('background', 'none').style('border-radius', '0');
+  const tooltip = createTooltip(container);
+
+  // Extract unique entities and periods (preserve data order for periods)
+  const periodSet = new Set<string>();
+  data.forEach((d) => periodSet.add(String(d[timeField])));
+  const periods = [...periodSet];
+
+  const entitySet = new Set<string>();
+  data.forEach((d) => entitySet.add(String(d[categoryField])));
+  const entities = [...entitySet];
+
+  // Build a lookup: entity -> period -> value
+  const lookup: Record<string, Record<string, number>> = {};
+  entities.forEach((e) => {
+    lookup[e] = {};
+  });
+  data.forEach((d) => {
+    const e = String(d[categoryField]);
+    const p = String(d[timeField]);
+    lookup[e][p] = Number(d[valueField]);
+  });
+
+  // Compute ranks: for each period, sort entities by value descending, assign rank 1,2,3...
+  const ranks: Record<string, Record<string, number>> = {};
+  entities.forEach((e) => {
+    ranks[e] = {};
+  });
+
+  periods.forEach((period) => {
+    const entitiesWithValues = entities
+      .filter((e) => lookup[e][period] != null && !isNaN(lookup[e][period]))
+      .map((e) => ({ entity: e, value: lookup[e][period] }));
+
+    entitiesWithValues.sort((a, b) => b.value - a.value);
+
+    entitiesWithValues.forEach((item, idx) => {
+      ranks[item.entity][period] = idx + 1;
+    });
+  });
+
+  const maxRank = entities.length;
+
+  // Scales
+  const xScale = d3
+    .scalePoint()
+    .domain(periods)
+    .range([0, dims.innerWidth])
+    .padding(0.5);
+
+  const yScale = d3
+    .scaleLinear()
+    .domain([1, maxRank])
+    .range([20, dims.innerHeight - 20]);
+
+  const colorScale = buildColorScale(encoding.color, data);
+
+  // Draw faint horizontal gridlines at each rank
+  for (let rank = 1; rank <= maxRank; rank++) {
+    g.append('line')
+      .attr('x1', 0)
+      .attr('y1', yScale(rank))
+      .attr('x2', dims.innerWidth)
+      .attr('y2', yScale(rank))
+      .attr('stroke', GRID_COLOR)
+      .attr('stroke-width', 0.5)
+      .attr('stroke-dasharray', '3,3');
+
+    // Rank labels on left
+    g.append('text')
+      .attr('x', -8)
+      .attr('y', yScale(rank))
+      .attr('text-anchor', 'end')
+      .attr('dominant-baseline', 'middle')
+      .attr('fill', TEXT_MUTED)
+      .attr('font-size', '10px')
+      .attr('font-family', 'Inter, system-ui, sans-serif')
+      .text(`#${rank}`);
+  }
+
+  // Period labels along x-axis
+  periods.forEach((period) => {
+    g.append('text')
+      .attr('x', xScale(period))
+      .attr('y', dims.innerHeight + 20)
+      .attr('text-anchor', 'middle')
+      .attr('fill', TEXT_MUTED)
+      .attr('font-size', '11px')
+      .attr('font-weight', '500')
+      .attr('font-family', 'Inter, system-ui, sans-serif')
+      .text(String(period));
+  });
+
+  // Draw lines and dots for each entity
+  const isSinglePeriod = periods.length <= 1;
+
+  if (!isSinglePeriod) {
+    const line = d3
+      .line()
+      .x((d: any) => xScale(d.period))
+      .y((d: any) => yScale(d.rank))
+      .curve(d3.curveBumpX);
+
+    entities.forEach((entity) => {
+      const points = periods
+        .filter((p) => ranks[entity][p] != null)
+        .map((p) => ({
+          period: p,
+          rank: ranks[entity][p],
+          value: lookup[entity][p],
+        }));
+
+      if (points.length < 2) return;
+
+      const color = colorScale(entity);
+
+      g.append('path')
+        .datum(points)
+        .attr('d', line)
+        .attr('fill', 'none')
+        .attr('stroke', color)
+        .attr('stroke-width', strokeWidth)
+        .attr('opacity', 0.8);
+
+      points.forEach((pt) => {
+        g.append('circle')
+          .attr('cx', xScale(pt.period))
+          .attr('cy', yScale(pt.rank))
+          .attr('r', dotRadius)
+          .attr('fill', color)
+          .attr('stroke', DARK_BG)
+          .attr('stroke-width', 2)
+          .attr('cursor', 'pointer')
+          .on('mouseover', function (event: MouseEvent) {
+            d3.select(this).attr('r', dotRadius + 2);
+            showTooltip(
+              tooltip,
+              `<strong>${entity}</strong><br/>Period: ${pt.period}<br/>Rank: #${pt.rank}<br/>Value: ${formatValue(pt.value)}`,
+              event
+            );
+          })
+          .on('mousemove', (event: MouseEvent) => {
+            positionTooltip(tooltip, event);
+          })
+          .on('mouseout', function () {
+            d3.select(this).attr('r', dotRadius);
+            hideTooltip(tooltip);
+          });
+      });
+
+      if (showLabels) {
+        const lastPt = points[points.length - 1];
+        g.append('text')
+          .attr('x', xScale(lastPt.period)! + dotRadius + 6)
+          .attr('y', yScale(lastPt.rank))
+          .attr('dominant-baseline', 'middle')
+          .attr('fill', color)
+          .attr('font-size', '11px')
+          .attr('font-weight', '500')
+          .attr('font-family', 'Inter, system-ui, sans-serif')
+          .text(truncateLabel(entity, 14));
+      }
+    });
+  } else {
+    const singlePeriod = periods[0];
+    const dotX = dims.innerWidth / 2;
+
+    entities.forEach((entity) => {
+      const rank = ranks[entity][singlePeriod];
+      if (rank == null) return;
+      const value = lookup[entity][singlePeriod];
+      const color = colorScale(entity);
+
+      g.append('circle')
+        .attr('cx', dotX)
+        .attr('cy', yScale(rank))
+        .attr('r', 6)
+        .attr('fill', color)
+        .attr('stroke', DARK_BG)
+        .attr('stroke-width', 2)
+        .attr('cursor', 'pointer')
+        .on('mouseover', function (event: MouseEvent) {
+          d3.select(this).attr('r', 8);
+          showTooltip(
+            tooltip,
+            `<strong>${entity}</strong><br/>Period: ${singlePeriod}<br/>Rank: #${rank}<br/>Value: ${formatValue(value)}`,
+            event
+          );
+        })
+        .on('mousemove', (event: MouseEvent) => {
+          positionTooltip(tooltip, event);
+        })
+        .on('mouseout', function () {
+          d3.select(this).attr('r', 6);
+          hideTooltip(tooltip);
+        });
+
+      g.append('text')
+        .attr('x', dotX + 12)
+        .attr('y', yScale(rank))
+        .attr('dominant-baseline', 'middle')
+        .attr('fill', color)
+        .attr('font-size', '11px')
+        .attr('font-weight', '500')
+        .attr('font-family', 'Inter, system-ui, sans-serif')
+        .text(`${entity.length > 14 ? entity.slice(0, 13) + '\u2026' : entity} (${formatValue(value)})`);
+    });
+  }
+
+  if (!showLabels) {
+    const legendDiv = createLegend(colorScale);
+    container.appendChild(legendDiv);
+  }
+}

package/src/renderers/d3/comparison/connected-dot-plot.ts

@@ -0,0 +1,305 @@
+/**
+ * Connected dot plot D3 renderer.
+ *
+ * For each category row, draws a horizontal line segment from value1 to value2,
+ * with colored dots at each end. Y-axis is categorical (scaleBand),
+ * X-axis is quantitative (scaleLinear).
+ */
+
+import type { VisualizationSpec } from '../../../types.js';
+import {
+  createSvg,
+  buildColorScale,
+  createLegend,
+  addSortControls,
+  contrastText,
+  createTooltip,
+  showTooltip,
+  hideTooltip,
+  positionTooltip,
+  formatValue,
+  styleAxis,
+  calculateLeftMargin,
+  renderEmptyState,
+  isAllZeros,
+  DEFAULT_PALETTE,
+  GRID_COLOR,
+  TEXT_MUTED,
+  DARK_BG,
+} from '../shared.js';
+
+declare const d3: any;
+
+export function renderConnectedDotPlot(container: HTMLElement, spec: VisualizationSpec): void {
+  const { config, encoding, data } = spec;
+
+  const startField = config.metric1Field || config.startField || 'start';
+  const endField = config.metric2Field || config.endField || 'end';
+  const categoryField = config.categoryField || encoding.y?.field || 'category';
+  const showLabels = config.showLabels !== false;
+  const showDifference = config.showDifference === true;
+
+  const startLabel = config.metric1Field || config.startLabel || startField;
+  const endLabel = config.metric2Field || config.endLabel || endField;
+
+  // Sort data
+  let sortedData = [...data];
+  if (config.sortBy === 'value' || config.sortBy === 'gap') {
+    const order = config.sortOrder === 'ascending' ? 1 : -1;
+    sortedData.sort((a, b) => {
+      const diffA = Number(a[endField]) - Number(a[startField]);
+      const diffB = Number(b[endField]) - Number(b[startField]);
+      return order * (diffA - diffB);
+    });
+  } else if (config.sortBy === 'category') {
+    const order = config.sortOrder === 'ascending' ? 1 : -1;
+    sortedData.sort((a, b) => {
+      return order * String(a[categoryField]).localeCompare(
+        String(b[categoryField]), undefined, { sensitivity: 'base', numeric: true }
+      );
+    });
+  }
+
+  // Dot radius is determined after we know the bandwidth (row height)
+
+  // Set up container as flex column: chart on top, legend on bottom
+  container.style.display = 'flex';
+  container.style.flexDirection = 'column';
+  container.style.background = DARK_BG;
+  container.style.borderRadius = '8px';
+  container.style.overflow = 'hidden';
+
+  const chartWrapper = document.createElement('div');
+  chartWrapper.style.flex = '1';
+  chartWrapper.style.minHeight = '0';
+  container.appendChild(chartWrapper);
+
+  // HTML legend below the chart
+  const legendDiv = createLegend([
+    { label: startLabel, color: DEFAULT_PALETTE[0] },
+    { label: endLabel, color: DEFAULT_PALETTE[1] },
+  ], { shape: 'circle' });
+  container.appendChild(legendDiv);
+
+  // Calculate left margin based on category label lengths
+  const categories = sortedData.map((d) => String(d[categoryField]));
+  const leftMargin = calculateLeftMargin(categories);
+
+  const { svg, g, dims } = createSvg(chartWrapper, spec, { left: leftMargin });
+  const tooltip = createTooltip(chartWrapper);
+
+  // Check if both value fields are all zeros
+  if (isAllZeros(sortedData, startField) && isAllZeros(sortedData, endField)) {
+    svg.style('background', 'none');
+    renderEmptyState(g, dims);
+    return;
+  }
+
+  // Y scale — categorical
+  const yScale = d3
+    .scaleBand()
+    .domain(categories)
+    .range([0, dims.innerHeight])
+    .padding(0.3);
+
+  // X scale — quantitative, spanning both start and end values
+  const allValues = sortedData.flatMap((d) => [Number(d[startField]), Number(d[endField])]);
+  const minVal = d3.min(allValues) as number;
+  const maxVal = d3.max(allValues) as number;
+  const padding = (maxVal - minVal) * 0.08 || 1;
+
+  const xScale = d3
+    .scaleLinear()
+    .domain([minVal - padding, maxVal + padding])
+    .range([0, dims.innerWidth])
+    .nice();
+
+  // Axes
+  // X-axis with gridlines
+  const xAxis = g
+    .append('g')
+    .attr('class', 'x-axis')
+    .attr('transform', `translate(0,${dims.innerHeight})`)
+    .call(
+      d3
+        .axisBottom(xScale)
+        .ticks(6)
+        .tickSize(-dims.innerHeight)
+        .tickPadding(8)
+        .tickFormat((d: number) => formatValue(d))
+    );
+
+  styleAxis(xAxis);
+
+  // Y-axis (categorical, no gridlines)
+  const yAxis = g
+    .append('g')
+    .attr('class', 'y-axis')
+    .call(
+      d3
+        .axisLeft(yScale)
+        .tickSize(0)
+        .tickPadding(10)
+        .tickFormat((d: string) => {
+          if (d.length > 30) return d.slice(0, 29) + '\u2026';
+          return d;
+        })
+    );
+
+  styleAxis(yAxis);
+
+  // Color scale — use first two palette colors for start/end dots
+  const colorScale = buildColorScale(encoding.color, sortedData);
+  const startColor = DEFAULT_PALETTE[0];
+  const endColor = DEFAULT_PALETTE[1];
+
+  // Draw connecting lines and dots for each category
+  const bandwidth = yScale.bandwidth();
+
+  // Adaptive dot sizing — never larger than the row, small mode drops labels
+  const maxDotRadius = Math.floor(bandwidth / 2);
+  const LABEL_RADIUS = 11; // ideal size when labels are shown inside
+  const SMALL_RADIUS = 5;  // compact mode
+  const isSmallMode = maxDotRadius < LABEL_RADIUS;
+  const canShowLabels = showLabels && !isSmallMode;
+  const DOT_RADIUS = canShowLabels
+    ? Math.min(LABEL_RADIUS, maxDotRadius)
+    : Math.min(SMALL_RADIUS, maxDotRadius);
+
+  // Invisible full-width row hover targets (drawn first, behind everything)
+  // Each row gets a rect spanning the full chart width so the user doesn't
+  // have to hunt for tiny dots.
+  g.selectAll('.row-hover-target')
+    .data(sortedData)
+    .join('rect')
+    .attr('class', 'row-hover-target')
+    .attr('x', 0)
+    .attr('y', (d: any) => yScale(String(d[categoryField])))
+    .attr('width', dims.innerWidth)
+    .attr('height', bandwidth)
+    .attr('fill', 'transparent')
+    .attr('cursor', 'pointer')
+    .on('mouseover', function (event: MouseEvent, d: any) {
+      const cat = String(d[categoryField]);
+      const startVal = Number(d[startField]);
+      const endVal = Number(d[endField]);
+      const diff = endVal - startVal;
+
+      // Highlight: brighten this row's dots
+      g.selectAll(`.dot-${css(cat)}`).attr('opacity', 0.8).attr('r', DOT_RADIUS + 2);
+
+      showTooltip(
+        tooltip,
+        `<strong>${cat}</strong><br/>${startLabel}: ${formatValue(startVal)}<br/>${endLabel}: ${formatValue(endVal)}<br/>Difference: ${diff >= 0 ? '+' : ''}${formatValue(diff)}`,
+        event
+      );
+    })
+    .on('mousemove', (event: MouseEvent) => {
+      positionTooltip(tooltip, event);
+    })
+    .on('mouseout', function (_event: MouseEvent, d: any) {
+      const cat = String(d[categoryField]);
+      g.selectAll(`.dot-${css(cat)}`).attr('opacity', 1).attr('r', DOT_RADIUS);
+      hideTooltip(tooltip);
+    });
+
+  // Draw lines, dots, and labels per row
+  sortedData.forEach((d) => {
+    const cat = String(d[categoryField]);
+    const startVal = Number(d[startField]);
+    const endVal = Number(d[endField]);
+    const yMid = yScale(cat)! + bandwidth / 2;
+
+    const x1 = xScale(startVal);
+    const x2 = xScale(endVal);
+
+    // Determine left/right so rightmost dot is always drawn on top
+    const leftIsStart = x1 <= x2;
+    const leftX = leftIsStart ? x1 : x2;
+    const rightX = leftIsStart ? x2 : x1;
+    const leftColor = leftIsStart ? startColor : endColor;
+    const rightColor = leftIsStart ? endColor : startColor;
+    const leftVal = leftIsStart ? startVal : endVal;
+    const rightVal = leftIsStart ? endVal : startVal;
+
+    const dotClass = `dot-${css(cat)}`;
+
+    // 1) Connecting line (behind dots)
+    g.append('line')
+      .attr('x1', x1)
+      .attr('y1', yMid)
+      .attr('x2', x2)
+      .attr('y2', yMid)
+      .attr('stroke', GRID_COLOR)
+      .attr('stroke-width', 2)
+      .attr('opacity', 0.6)
+      .attr('pointer-events', 'none');
+
+    // 2) Left dot + label (drawn first, can be covered by right dot)
+    drawDot(g, leftX, yMid, DOT_RADIUS, leftColor, dotClass);
+    const dotsTooClose = Math.abs(rightX - leftX) < DOT_RADIUS * 2.5;
+    if (canShowLabels && !dotsTooClose) {
+      drawLabel(g, leftX, yMid, leftVal, leftColor);
+    }
+
+    // 3) Right dot + label (drawn last, always on top)
+    drawDot(g, rightX, yMid, DOT_RADIUS, rightColor, dotClass);
+    if (canShowLabels) {
+      drawLabel(g, rightX, yMid, rightVal, rightColor);
+    }
+
+    // Difference label (centered on the connecting line)
+    if (showDifference) {
+      const diff = endVal - startVal;
+      const midX = (x1 + x2) / 2;
+      g.append('text')
+        .attr('x', midX)
+        .attr('y', yMid)
+        .attr('text-anchor', 'middle')
+        .attr('dominant-baseline', 'central')
+        .attr('fill', TEXT_MUTED)
+        .attr('font-size', '9px')
+        .attr('font-family', 'Inter, system-ui, sans-serif')
+        .attr('pointer-events', 'none')
+        .text(`${diff >= 0 ? '+' : ''}${formatValue(diff)}`);
+    }
+  });
+
+  // Sort controls (show on hover, top-right corner)
+  addSortControls(svg, container, spec, dims, renderConnectedDotPlot);
+}
+
+/** Sanitize a category string into a valid CSS class fragment. */
+function css(cat: string): string {
+  return cat.replace(/[^a-zA-Z0-9]/g, '_');
+}
+
+function drawDot(
+  g: any, cx: number, cy: number, r: number,
+  color: string, className: string,
+): void {
+  g.append('circle')
+    .attr('class', className)
+    .attr('cx', cx)
+    .attr('cy', cy)
+    .attr('r', r)
+    .attr('fill', color)
+    .attr('stroke', DARK_BG)
+    .attr('stroke-width', 1.5)
+    .attr('pointer-events', 'none');
+}
+
+function drawLabel(g: any, cx: number, cy: number, value: number, bgColor: string): void {
+  g.append('text')
+    .attr('x', cx)
+    .attr('y', cy)
+    .attr('text-anchor', 'middle')
+    .attr('dominant-baseline', 'central')
+    .attr('fill', contrastText(bgColor))
+    .attr('font-size', '8px')
+    .attr('font-weight', '600')
+    .attr('font-family', 'Inter, system-ui, sans-serif')
+    .attr('pointer-events', 'none')
+    .text(formatValue(value));
+}
+