@outsidedata/dolex 0.1.0

package/src/renderers/d3/parallel-coordinates.ts

@@ -0,0 +1,227 @@
+/**
+ * Parallel Coordinates D3 renderer.
+ *
+ * Multiple vertical axes evenly spaced. Each data row draws a polyline
+ * connecting its value on each axis. Lines can be colored by a categorical
+ * grouping field. Best for comparing multivariate data across many dimensions.
+ *
+ * Standards: HTML legend below SVG, line-level hover, adaptive tick counts.
+ */
+
+import type { VisualizationSpec } from '../../types.js';
+import {
+  createSvg,
+  buildColorScale,
+  createTooltip,
+  showTooltip,
+  hideTooltip,
+  positionTooltip,
+  formatValue,
+  styleAxis,
+  getAdaptiveTickCount,
+  truncateLabel,
+  createLegend,
+  renderEmptyState,
+  TEXT_COLOR,
+  TEXT_MUTED,
+} from './shared.js';
+import type { LegendCallbacks } from './shared.js';
+import { categorical } from '../../theme/colors.js';
+
+declare const d3: any;
+
+// ─── PARALLEL COORDINATES ────────────────────────────────────────────────────
+
+export function renderParallelCoordinates(container: HTMLElement, spec: VisualizationSpec): void {
+  const { config, encoding, data } = spec;
+
+  const dimensions: string[] = config.dimensions || [];
+  const colorField = config.colorField || encoding.color?.field || null;
+  const labelField = config.labelField || null;
+  const lineOpacity = config.lineOpacity ?? 0.5;
+  const strokeWidth = config.strokeWidth ?? 1.5;
+  const showAxisLabels = config.showAxisLabels !== false;
+
+  if (dimensions.length === 0 || data.length === 0) return;
+
+  const hasLegend = colorField !== null;
+
+  // ── Container layout: flex column with chartWrapper + legend ──
+  container.innerHTML = '';
+  container.style.display = 'flex';
+  container.style.flexDirection = 'column';
+  container.style.overflow = 'hidden';
+
+  const chartWrapper = document.createElement('div');
+  chartWrapper.style.cssText = 'flex: 1; min-height: 0;';
+  container.appendChild(chartWrapper);
+
+  const { svg, g, dims } = createSvg(chartWrapper, spec, {
+    top: 50,
+    bottom: 30,
+    left: 60,
+    right: 30,
+  });
+  const tooltip = createTooltip(container);
+
+  // Check if all values across all dimensions are zero
+  const allZero = dimensions.every(dim => data.every(d => Number(d[dim]) === 0));
+  if (allZero) {
+    svg.style('background', 'none');
+    renderEmptyState(g, dims);
+    return;
+  }
+
+  // Build a y-scale for each dimension
+  const scales: Record<string, any> = {};
+  for (const dim of dimensions) {
+    const extent = d3.extent(data, (d: any) => Number(d[dim])) as [number, number];
+    // Handle case where all values are the same
+    const pad = extent[0] === extent[1] ? 1 : 0;
+    scales[dim] = d3.scaleLinear()
+      .domain([extent[0] - pad, extent[1] + pad])
+      .range([dims.innerHeight, 0])
+      .nice();
+  }
+
+  // Horizontal scale: position of each axis
+  const xScale = d3.scalePoint()
+    .domain(dimensions)
+    .range([0, dims.innerWidth]);
+
+  // Color scale — ensure field is present even when encoding.color only has palette
+  const colorEncoding = colorField
+    ? { ...(encoding.color || {}), field: colorField, type: encoding.color?.type || 'nominal' }
+    : encoding.color;
+  const colorScale = buildColorScale(colorEncoding, data);
+
+  // Adaptive tick count per axis
+  const tickCount = getAdaptiveTickCount(dims.innerHeight, 40);
+
+  // ── Determine if tick labels should be hidden for tight spacing ──
+  const axisSpacing = dimensions.length > 1
+    ? dims.innerWidth / (dimensions.length - 1)
+    : dims.innerWidth;
+  const showTickLabels = showAxisLabels && axisSpacing >= 50;
+
+  // ── Draw vertical axes using D3 axisLeft + styleAxis ──
+  dimensions.forEach((dim: string, dimIdx: number) => {
+    const x = xScale(dim);
+    const yScale = scales[dim];
+
+    const axisG = g.append('g')
+      .attr('class', 'pc-axis')
+      .attr('transform', `translate(${x}, 0)`)
+      .call(
+        d3.axisLeft(yScale)
+          .ticks(tickCount)
+          .tickSize(0)
+          .tickPadding(6)
+          .tickFormat((d: number) => formatValue(d))
+      );
+
+    styleAxis(axisG);
+
+    // Hide tick labels when axes are too close together or explicitly disabled
+    if (!showTickLabels) {
+      axisG.selectAll('.tick text').remove();
+    }
+
+    // Dimension label at top
+    g.append('text')
+      .attr('x', x)
+      .attr('y', -12)
+      .attr('text-anchor', 'middle')
+      .attr('fill', TEXT_COLOR)
+      .attr('font-size', '11px')
+      .attr('font-weight', '500')
+      .attr('font-family', 'Inter, system-ui, sans-serif')
+      .text(truncateLabel(dim, 14));
+  });
+
+  // ── Build path string for a data row ──
+  const pathForRow = (row: any): string => {
+    return dimensions.map((dim: string, i: number) => {
+      const x = xScale(dim);
+      const y = scales[dim](Number(row[dim]));
+      return (i === 0 ? 'M' : 'L') + ` ${x} ${y}`;
+    }).join(' ');
+  };
+
+  // ── Draw polylines for each data row ──
+  const lines = g.selectAll('.pc-line')
+    .data(data)
+    .join('path')
+    .attr('class', 'pc-line')
+    .attr('d', (d: any) => pathForRow(d))
+    .attr('fill', 'none')
+    .attr('stroke', (d: any) => colorField ? colorScale(d[colorField]) : categorical[0])
+    .attr('stroke-width', strokeWidth)
+    .attr('stroke-opacity', lineOpacity)
+    .attr('stroke-linejoin', 'round')
+    .style('cursor', 'pointer');
+
+  // ── Hover interactions: highlight hovered line, dim others ──
+  lines
+    .on('mouseover', function (event: MouseEvent, d: any) {
+      // Dim all lines
+      g.selectAll('.pc-line')
+        .attr('stroke-opacity', 0.08)
+        .attr('stroke-width', strokeWidth * 0.5);
+
+      // Highlight hovered line
+      d3.select(this)
+        .attr('stroke-opacity', 1)
+        .attr('stroke-width', strokeWidth * 2.5)
+        .raise();
+
+      // Build tooltip with entity label + all dimension values
+      let html = '';
+      if (labelField && d[labelField]) {
+        html += `<strong>${d[labelField]}</strong>`;
+        if (colorField && colorField !== labelField) {
+          html += ` <span style="color:#9ca3af">${d[colorField]}</span>`;
+        }
+        html += '<br/>';
+      } else if (colorField) {
+        html += `<strong>${d[colorField]}</strong><br/>`;
+      }
+      html += dimensions.map((dim: string) => {
+        const val = Number(d[dim]);
+        return `${dim}: ${isNaN(val) ? d[dim] : formatValue(val)}`;
+      }).join('<br/>');
+
+      showTooltip(tooltip, html, event);
+    })
+    .on('mousemove', (event: MouseEvent) => {
+      positionTooltip(tooltip, event);
+    })
+    .on('mouseout', function () {
+      // Restore all lines
+      g.selectAll('.pc-line')
+        .attr('stroke-opacity', lineOpacity)
+        .attr('stroke-width', strokeWidth);
+
+      hideTooltip(tooltip);
+    });
+
+  // ── HTML legend below chart with hover highlighting ──
+  if (hasLegend) {
+    const legendDiv = createLegend(colorScale, { shape: 'line', callbacks: {
+      onHover: (category: string) => {
+        g.selectAll('.pc-line').each(function (d: any) {
+          const isMatch = d[colorField!] === category;
+          d3.select(this)
+            .attr('stroke-opacity', isMatch ? Math.min(lineOpacity * 2, 1) : 0.05)
+            .attr('stroke-width', isMatch ? strokeWidth * 1.5 : strokeWidth * 0.5);
+        });
+      },
+      onLeave: () => {
+        g.selectAll('.pc-line')
+          .attr('stroke-opacity', lineOpacity)
+          .attr('stroke-width', strokeWidth);
+      },
+    }});
+    container.appendChild(legendDiv);
+  }
+}

package/src/renderers/d3/radar.ts

@@ -0,0 +1,313 @@
+/**
+ * Radar Chart (Spider Chart) D3 renderer.
+ *
+ * Renders overlaid polygons on radial axes, one axis per dimension,
+ * one polygon per entity. Best for 1-4 entities across 3-10 dimensions.
+ *
+ * Standards: HTML legend below SVG, polygon-level hover, adaptive sizing.
+ */
+
+import type { VisualizationSpec } from '../../types.js';
+import {
+  createSvg,
+  buildColorScale,
+  createTooltip,
+  showTooltip,
+  hideTooltip,
+  positionTooltip,
+  formatValue,
+  truncateLabel,
+  createLegend,
+  DARK_BG,
+  TEXT_MUTED,
+  GRID_COLOR,
+  AXIS_COLOR,
+} from './shared.js';
+import type { LegendCallbacks } from './shared.js';
+
+declare const d3: any;
+
+// ─── RADAR RENDERER ──────────────────────────────────────────────────────────
+
+export function renderRadar(container: HTMLElement, spec: VisualizationSpec): void {
+  const { config, data } = spec;
+
+  const categoryField = config.categoryField || 'entity';
+  const dimensions: string[] = config.dimensions || [];
+  const showLabels = config.showLabels !== false;
+  const showGrid = config.showGrid !== false;
+  const gridLevels = config.gridLevels || 5;
+  const fillOpacity = config.fillOpacity ?? 0.2;
+  const strokeWidth = config.strokeWidth ?? 2;
+  const dotRadius = config.dotRadius ?? 4;
+
+  if (dimensions.length === 0) return;
+
+  const hasLegend = data.length > 1;
+
+  // ── Container layout: flex column with chartWrapper + legend ──
+  container.innerHTML = '';
+  container.style.display = 'flex';
+  container.style.flexDirection = 'column';
+  container.style.overflow = 'hidden';
+
+  const chartWrapper = document.createElement('div');
+  chartWrapper.style.cssText = 'flex: 1; min-height: 0;';
+  container.appendChild(chartWrapper);
+
+  // Use createSvg for consistent SVG + title + background
+  // Radar needs equal margins all around for the circular layout
+  const containerWidth = container.clientWidth || 500;
+  const containerHeight = container.clientHeight || 500;
+  const isSmall = Math.min(containerWidth, containerHeight) < 320;
+
+  // Adaptive margins: radar labels sit outside the circle, need room
+  const labelMargin = isSmall ? 40 : 55;
+  const { svg, g, dims } = createSvg(chartWrapper, spec, {
+    top: spec.title ? 55 : 40,
+    right: labelMargin,
+    bottom: 40,
+    left: labelMargin,
+  });
+
+  const tooltip = createTooltip(container);
+
+  // ── Compute radar geometry centered in the inner area ──
+  const radius = Math.min(dims.innerWidth, dims.innerHeight) / 2;
+  const cx = dims.innerWidth / 2;
+  const cy = dims.innerHeight / 2;
+
+  const center = g.append('g')
+    .attr('transform', `translate(${cx}, ${cy})`);
+
+  const angleSlice = (Math.PI * 2) / dimensions.length;
+
+  // ── Scale: find min/max across all entities and dimensions ──
+  let minVal = 0;
+  let maxVal = 0;
+  for (const row of data) {
+    for (const dim of dimensions) {
+      const v = Number(row[dim]) || 0;
+      if (v < minVal) minVal = v;
+      if (v > maxVal) maxVal = v;
+    }
+  }
+  if (maxVal === 0 && minVal === 0) maxVal = 1;
+
+  const rScale = d3.scaleLinear()
+    .domain([minVal, maxVal])
+    .range([0, radius]);
+
+  // ── Grid rings ──
+  if (showGrid) {
+    for (let level = 1; level <= gridLevels; level++) {
+      const r = (radius / gridLevels) * level;
+      const points = dimensions.map((_: string, i: number) => {
+        const angle = angleSlice * i - Math.PI / 2;
+        return [r * Math.cos(angle), r * Math.sin(angle)];
+      });
+      center.append('polygon')
+        .attr('points', points.map((p: number[]) => p.join(',')).join(' '))
+        .attr('fill', 'none')
+        .attr('stroke', GRID_COLOR)
+        .attr('stroke-width', 0.5);
+
+      // Grid level value labels (along 12 o'clock axis)
+      const labelVal = minVal + ((maxVal - minVal) / gridLevels) * level;
+      center.append('text')
+        .attr('x', 4)
+        .attr('y', -r)
+        .attr('fill', TEXT_MUTED)
+        .attr('font-size', isSmall ? '8px' : '9px')
+        .attr('font-family', 'Inter, system-ui, sans-serif')
+        .attr('opacity', 0.6)
+        .text(formatValue(Math.round(labelVal * 100) / 100));
+    }
+  }
+
+  // ── Zero ring (when data includes negatives) ──
+  if (minVal < 0) {
+    const zeroR = rScale(0);
+    const zeroPoints = dimensions.map((_: string, i: number) => {
+      const angle = angleSlice * i - Math.PI / 2;
+      return [zeroR * Math.cos(angle), zeroR * Math.sin(angle)];
+    });
+    center.append('polygon')
+      .attr('points', zeroPoints.map((p: number[]) => p.join(',')).join(' '))
+      .attr('fill', 'none')
+      .attr('stroke', '#ffffff')
+      .attr('stroke-width', 1)
+      .attr('stroke-dasharray', '4,3')
+      .attr('opacity', 0.5);
+  }
+
+  // ── Axis lines + dimension labels ──
+  const maxLabelLen = isSmall ? 10 : 16;
+
+  dimensions.forEach((dim: string, i: number) => {
+    const angle = angleSlice * i - Math.PI / 2;
+    const lineX = radius * Math.cos(angle);
+    const lineY = radius * Math.sin(angle);
+
+    center.append('line')
+      .attr('x1', 0).attr('y1', 0)
+      .attr('x2', lineX).attr('y2', lineY)
+      .attr('stroke', AXIS_COLOR)
+      .attr('stroke-width', 0.5);
+
+    if (showLabels) {
+      const labelR = radius + (isSmall ? 10 : 14);
+      const lx = labelR * Math.cos(angle);
+      const ly = labelR * Math.sin(angle);
+      const anchor = Math.abs(lx) < 1 ? 'middle' : lx > 0 ? 'start' : 'end';
+
+      center.append('text')
+        .attr('x', lx)
+        .attr('y', ly)
+        .attr('text-anchor', anchor)
+        .attr('dominant-baseline', 'central')
+        .attr('fill', TEXT_MUTED)
+        .attr('font-size', isSmall ? '9px' : '11px')
+        .attr('font-family', 'Inter, system-ui, sans-serif')
+        .text(truncateLabel(dim, maxLabelLen));
+    }
+  });
+
+  // ── Color scale ──
+  // Build a color scale from entities for consistent coloring
+  const entityNames = data.map((d: any) => String(d[categoryField]));
+  const colorEncoding = data.length > 1
+    ? { field: categoryField, type: 'nominal' as const }
+    : undefined;
+  const colorScale = buildColorScale(colorEncoding, data);
+
+  // Helper: compute polygon points for a data row
+  function getPolygonPoints(row: Record<string, any>): [number, number][] {
+    return dimensions.map((dim: string, i: number) => {
+      const val = Number(row[dim]) || 0;
+      const angle = angleSlice * i - Math.PI / 2;
+      const r = rScale(val);
+      return [r * Math.cos(angle), r * Math.sin(angle)] as [number, number];
+    });
+  }
+
+  // Adaptive dot radius for small containers
+  const effectiveDotRadius = isSmall ? Math.min(dotRadius, 3) : dotRadius;
+
+  // ── Draw entity polygons ──
+  // For each entity: polygon fill → polygon stroke → dots
+  // Polygons are interactive for entity-level hover
+
+  let activeEntity: string | null = null;
+
+  function highlightEntity(entity: string | null) {
+    activeEntity = entity;
+    if (entity === null) {
+      // Reset all
+      center.selectAll('.radar-polygon')
+        .attr('fill-opacity', fillOpacity)
+        .attr('stroke-width', strokeWidth);
+      center.selectAll('.radar-dot')
+        .attr('opacity', 1);
+    } else {
+      // Highlight the hovered entity, fade others
+      center.selectAll('.radar-polygon').each(function () {
+        const el = d3.select(this);
+        const isMatch = el.attr('data-entity') === entity;
+        el.attr('fill-opacity', isMatch ? Math.min(fillOpacity + 0.15, 0.5) : fillOpacity * 0.3)
+          .attr('stroke-width', isMatch ? strokeWidth + 1 : strokeWidth * 0.5);
+      });
+      center.selectAll('.radar-dot').each(function () {
+        const el = d3.select(this);
+        const isMatch = el.attr('data-entity') === entity;
+        el.attr('opacity', isMatch ? 1 : 0.15);
+      });
+    }
+  }
+
+  data.forEach((row: any, entityIdx: number) => {
+    const entity = String(row[categoryField]);
+    const color = colorScale(entity);
+    const points = getPolygonPoints(row);
+    const pointsStr = points.map((p: number[]) => p.join(',')).join(' ');
+
+    // Filled polygon (interactive)
+    center.append('polygon')
+      .attr('class', 'radar-polygon')
+      .attr('data-entity', entity)
+      .attr('points', pointsStr)
+      .attr('fill', color)
+      .attr('fill-opacity', fillOpacity)
+      .attr('stroke', color)
+      .attr('stroke-width', strokeWidth)
+      .attr('stroke-linejoin', 'round')
+      .style('cursor', 'pointer')
+      .on('mouseover', (event: MouseEvent) => {
+        highlightEntity(entity);
+        // Build entity summary tooltip
+        const dimValues = dimensions.map((dim: string) => {
+          const val = Number(row[dim]) || 0;
+          return `${truncateLabel(dim, 14)}: ${formatValue(val)}`;
+        }).join('<br/>');
+        showTooltip(
+          tooltip,
+          `<strong>${entity}</strong><br/>${dimValues}`,
+          event,
+        );
+      })
+      .on('mousemove', (event: MouseEvent) => {
+        positionTooltip(tooltip, event);
+      })
+      .on('mouseout', () => {
+        highlightEntity(null);
+        hideTooltip(tooltip);
+      });
+
+    // Dots at vertices
+    if (effectiveDotRadius > 0) {
+      points.forEach((p: number[], i: number) => {
+        const dim = dimensions[i];
+        const val = Number(row[dim]) || 0;
+
+        center.append('circle')
+          .attr('class', 'radar-dot')
+          .attr('data-entity', entity)
+          .attr('cx', p[0])
+          .attr('cy', p[1])
+          .attr('r', effectiveDotRadius)
+          .attr('fill', color)
+          .attr('stroke', DARK_BG)
+          .attr('stroke-width', 1.5)
+          .style('cursor', 'pointer')
+          .on('mouseover', (event: MouseEvent) => {
+            highlightEntity(entity);
+            d3.select(event.currentTarget)
+              .attr('r', effectiveDotRadius * 1.5);
+            showTooltip(
+              tooltip,
+              `<strong>${entity}</strong><br/>${dim}: ${formatValue(val)}`,
+              event,
+            );
+          })
+          .on('mousemove', (event: MouseEvent) => {
+            positionTooltip(tooltip, event);
+          })
+          .on('mouseout', (event: MouseEvent) => {
+            highlightEntity(null);
+            d3.select(event.currentTarget)
+              .attr('r', effectiveDotRadius);
+            hideTooltip(tooltip);
+          });
+      });
+    }
+  });
+
+  // ── HTML legend (below chart) with hover highlighting ──
+  if (hasLegend) {
+    const legendDiv = createLegend(colorScale, { shape: 'circle', callbacks: {
+      onHover: (entity: string) => highlightEntity(entity),
+      onLeave: () => highlightEntity(null),
+    }});
+    container.appendChild(legendDiv);
+  }
+}