eleventy-plugin-uncharted 0.5.0 → 0.5.2

package/README.md

@@ -2,7 +2,7 @@
 
 A CSS-based chart plugin for Eleventy. Renders charts as pure HTML/CSS.
 
-**[Full Documentation](https://uncharted.docs.seanlunsford.com/)**
+**[Full Documentation](https://uncharted.seanlunsford.com/)**
 
 ## Installation
 

package/css/uncharted.css

@@ -7,18 +7,33 @@
    ========================================================================== */
 
 :root {
-  --chart-color-1: #2196f3;  /* Blue */
-  --chart-color-2: #4caf50;  /* Green */
-  --chart-color-3: #ff7043;  /* Orange */
-  --chart-color-4: #ffc107;  /* Amber */
-  --chart-color-5: #009688;  /* Teal */
-  --chart-color-6: #9c27b0;  /* Purple */
-  --chart-color-7: #e91e63;  /* Pink */
-  --chart-color-8: #3f51b5;  /* Indigo */
-  --chart-color-9: #f44336;  /* Red */
-  --chart-color-10: #00bcd4; /* Cyan */
-  --chart-color-11: #cddc39; /* Lime */
-  --chart-color-12: #78909c; /* Gray */
+  /* Descriptive color names */
+  --chart-color-blue: #2196f3;
+  --chart-color-green: #4caf50;
+  --chart-color-orange: #ff7043;
+  --chart-color-yellow: #ffc107;
+  --chart-color-teal: #009688;
+  --chart-color-purple: #9c27b0;
+  --chart-color-pink: #e91e63;
+  --chart-color-indigo: #3f51b5;
+  --chart-color-red: #f44336;
+  --chart-color-cyan: #00bcd4;
+  --chart-color-lime: #cddc39;
+  --chart-color-gray: #78909c;
+
+  /* Numeric aliases (for chart data series) */
+  --chart-color-1: var(--chart-color-blue);
+  --chart-color-2: var(--chart-color-green);
+  --chart-color-3: var(--chart-color-orange);
+  --chart-color-4: var(--chart-color-yellow);
+  --chart-color-5: var(--chart-color-teal);
+  --chart-color-6: var(--chart-color-purple);
+  --chart-color-7: var(--chart-color-pink);
+  --chart-color-8: var(--chart-color-indigo);
+  --chart-color-9: var(--chart-color-red);
+  --chart-color-10: var(--chart-color-cyan);
+  --chart-color-11: var(--chart-color-lime);
+  --chart-color-12: var(--chart-color-gray);
 
   /* Backgrounds - neutral with opacity for light/dark adaptability */
   --chart-bg: rgba(128, 128, 128, 0.15);
@@ -30,6 +45,8 @@
   --chart-donut-size: 20rem;
   --chart-donut-hole: 30%;
   --chart-dot-size: 0.75rem;
+  --chart-dot-size-min: 0.375rem;
+  --chart-dot-size-max: 1.5rem;
   --chart-height: 12rem;
 }
 
@@ -87,10 +104,28 @@
   row-gap: 0.375rem;
   list-style: none;
   padding: 0;
-  margin: 0 0 1rem 0;
+  margin: 0;
   font-size: 0.875rem;
 }
 
+/* Legends below chart body */
+.chart-body + .chart-legend,
+.chart-body + .chart-legend-title,
+.chart-body + .chart-size-legend,
+.donut-body + .chart-legend {
+  margin-top: 1rem;
+}
+
+/* Spacing between series legend and size legend */
+.chart-legend + .chart-size-legend {
+  margin-top: 0.75rem;
+}
+
+/* Bar charts keep legend above */
+.chart-stacked-bar .chart-legend {
+  margin-bottom: 1rem;
+}
+
 .chart-legend-item {
   display: flex;
   align-items: center;
@@ -119,6 +154,13 @@
   margin-left: 0.125rem;
 }
 
+.chart-legend-title {
+  display: block;
+  font-size: 0.75rem;
+  font-weight: 600;
+  margin-bottom: 0.375rem;
+}
+
 /* ==========================================================================
    Axes
    ========================================================================== */
@@ -158,9 +200,13 @@
   transform: translateY(50%);
 }
 
+.chart-y-axis:has(.axis-title) {
+  padding-left: 1.25rem;
+}
+
 .chart-y-axis .axis-title {
   position: absolute;
-  left: -0.5rem;
+  left: 0.25rem;
   top: 50%;
   transform: rotate(-90deg) translateX(-50%);
   transform-origin: left center;
@@ -657,6 +703,70 @@
   z-index: 1;
 }
 
+/* Variable-sized dots (size column) */
+.chart-scatter .dot[style*="--size-scale"] {
+  --computed-size: calc(
+    var(--chart-dot-size-min) +
+    var(--size-scale) * (var(--chart-dot-size-max) - var(--chart-dot-size-min))
+  );
+  width: var(--computed-size);
+  height: var(--computed-size);
+}
+
+/* Size legend */
+.chart-size-legend {
+  display: flex;
+  flex-direction: column;
+  gap: 0.375rem;
+  font-size: 0.875rem;
+}
+
+.size-legend-items {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.size-legend-item {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.size-dot {
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0.5;
+}
+
+.size-dot-min {
+  width: var(--chart-dot-size-min);
+  height: var(--chart-dot-size-min);
+}
+
+.size-dot-max {
+  width: var(--chart-dot-size-max);
+  height: var(--chart-dot-size-max);
+}
+
+.size-value {
+  font-size: 0.75rem;
+  opacity: 0.7;
+}
+
+/* Proportional scatter: maintain data aspect ratio */
+.chart-scatter.chart-proportional .chart-body,
+.chart-scatter.chart-proportional .chart-y-axis {
+  min-height: auto;
+}
+
+.chart-scatter.chart-proportional .dot-area {
+  aspect-ratio: var(--data-aspect-ratio, 1);
+  min-height: auto;
+  width: 100%;
+  height: auto;
+}
+
 /* ==========================================================================
    Sankey Chart
    ========================================================================== */
@@ -761,6 +871,15 @@
   opacity: 0.8;
 }
 
+/* Dim all flows and nodes when hovering a node; per-chart inline styles brighten connected ones */
+.chart-sankey-container:has(.chart-sankey-node:hover) .chart-sankey-flow path {
+  opacity: 0.1;
+}
+
+.chart-sankey-container:has(.chart-sankey-node:hover) .chart-sankey-node {
+  opacity: 0.2;
+}
+
 
 /* ==========================================================================
    Animations (Optional)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-uncharted",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "An Eleventy plugin that renders CSS-based charts from CSV data using shortcodes",
   "main": "eleventy.config.js",
   "type": "module",

package/src/renderers/donut.js

@@ -100,6 +100,8 @@ export function renderDonut(config) {
   html += `</div>`;
   html += `</div>`;
 
+  html += `</div>`; // Close donut-body
+
   // Legend with values (or percentages if showPercentages is true)
   const legendLabels = legend ?? segments.map(s => s.label);
   html += `<ul class="chart-legend">`;
@@ -120,8 +122,6 @@ export function renderDonut(config) {
   });
   html += `</ul>`;
 
-  html += `</div>`; // Close donut-body
-
   html += renderDownloadLink(downloadDataUrl, downloadData);
   html += `</figure>`;
 

package/src/renderers/dot.js

@@ -15,7 +15,7 @@ import { formatNumber } from '../formatters.js';
  * @returns {string} - HTML string
  */
 export function renderDot(config) {
-  const { title, subtitle, data, max, min, legend, animate, format, id, rotateLabels, downloadData, downloadDataUrl, connectDots, dots: showDots = true, chartType = 'dot' } = config;
+  const { title, subtitle, data, max, min, legend, legendTitle, animate, format, id, rotateLabels, downloadData, downloadDataUrl, connectDots, dots: showDots = true, chartType = 'dot' } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Dot chart: no data provided -->`;
@@ -58,18 +58,6 @@ export function renderDot(config) {
     html += `</figcaption>`;
   }
 
-  // Legend
-  if (seriesKeys.length > 0) {
-    html += `<ul class="chart-legend">`;
-    seriesKeys.forEach((key, i) => {
-      const label = legendLabels[i] ?? key;
-      const colorClass = `chart-color-${i + 1}`;
-      const seriesClass = `chart-series-${slugify(key)}`;
-      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
-    });
-    html += `</ul>`;
-  }
-
   html += `<div class="chart-body">`;
 
   // Y-axis
@@ -154,6 +142,22 @@ export function renderDot(config) {
 
   html += `</div>`; // close chart-scroll
   html += `</div>`; // close chart-body
+
+  // Legend
+  if (seriesKeys.length > 0 || legendTitle) {
+    if (legendTitle) {
+      html += `<span class="chart-legend-title">${escapeHtml(legendTitle)}</span>`;
+    }
+    html += `<ul class="chart-legend">`;
+    seriesKeys.forEach((key, i) => {
+      const label = legendLabels[i] ?? key;
+      const colorClass = `chart-color-${i + 1}`;
+      const seriesClass = `chart-series-${slugify(key)}`;
+      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
+    });
+    html += `</ul>`;
+  }
+
   html += renderDownloadLink(downloadDataUrl, downloadData);
   html += `</figure>`;
 

package/src/renderers/sankey.js

@@ -164,7 +164,7 @@ export function renderSankey(config) {
   const paddingPct = (nodePadding / 400) * 100; // Convert px to approximate %
   const minNodeHeight = 2; // Minimum node height in percentage points
   const minGapHeight = 4; // Minimum gap to prevent label overlap (%)
-  const minFlowHeightBase = 1.5; // Base minimum flow height (before scaling)
+  const minFlowHeightBase = 0.4; // Base minimum flow height (before scaling)
 
   // Track maximum height needed across all levels
   let maxLevelHeight = 100;
@@ -276,105 +276,25 @@ export function renderSankey(config) {
     return aTargetLevel - bTargetLevel;
   });
 
-  // Calculate flow heights and determine consistent height (max of source/target proportions)
+  // Calculate flow heights proportional to each end's node height.
+  // Flows taper between source and target, naturally filling both nodes.
   const flowData = aggregatedEdges.map((edge, index) => {
     const sourcePos = nodePosition.get(edge.source);
     const targetPos = nodePosition.get(edge.target);
     const sourceThroughput = nodeThroughput.get(edge.source);
     const targetThroughput = nodeThroughput.get(edge.target);
 
-    // Flow height proportional to value at each end
-    const flowHeightSource = (edge.value / sourceThroughput) * sourcePos.height;
-    const flowHeightTarget = (edge.value / targetThroughput) * targetPos.height;
-
-    // Use max for consistent height across the flow
-    const height = Math.max(flowHeightSource, flowHeightTarget);
-
     return {
       ...edge,
       fromLevel: sourcePos.level,
       toLevel: targetPos.level,
-      height,
+      fromHeight: (edge.value / sourceThroughput) * sourcePos.height,
+      toHeight: (edge.value / targetThroughput) * targetPos.height,
       index
     };
   });
 
-  // Check if consistent heights cause overflow and adjust node heights if needed
-  const nodeOutTotal = new Map(); // Total outflow heights per node
-  const nodeInTotal = new Map();  // Total inflow heights per node
-  flowData.forEach(f => {
-    nodeOutTotal.set(f.source, (nodeOutTotal.get(f.source) || 0) + f.height);
-    nodeInTotal.set(f.target, (nodeInTotal.get(f.target) || 0) + f.height);
-  });
-
-  // Expand nodes that need more height for their flows
-  let needsRepositioning = false;
-  nodes.forEach(node => {
-    const pos = nodePosition.get(node);
-    const outTotal = nodeOutTotal.get(node) || 0;
-    const inTotal = nodeInTotal.get(node) || 0;
-    const neededHeight = Math.max(outTotal, inTotal);
-    if (neededHeight > pos.height) {
-      pos.height = neededHeight;
-      needsRepositioning = true;
-    }
-  });
-
-  // Reposition nodes within levels if any heights changed
-  if (needsRepositioning) {
-    levels.forEach((levelNodes, levelIndex) => {
-      let currentTop = 0;
-      levelNodes.forEach(node => {
-        const pos = nodePosition.get(node);
-        pos.top = currentTop;
-        currentTop += pos.height + paddingPct;
-      });
-    });
-
-    // Recalculate maxLevelHeight and scale
-    let newMaxLevelHeight = 100;
-    levels.forEach(levelNodes => {
-      if (levelNodes.length === 0) return;
-      let maxBottom = 0;
-      levelNodes.forEach(node => {
-        const pos = nodePosition.get(node);
-        const bottom = pos.top + pos.height;
-        if (bottom > maxBottom) maxBottom = bottom;
-      });
-      if (maxBottom > newMaxLevelHeight) newMaxLevelHeight = maxBottom;
-    });
-
-    // Scale if needed
-    if (newMaxLevelHeight > 100) {
-      const scale = newMaxLevelHeight / 100;
-      nodePosition.forEach(pos => {
-        pos.top = pos.top / scale;
-        pos.height = pos.height / scale;
-      });
-      flowData.forEach(f => {
-        f.height = f.height / scale;
-      });
-    }
-
-    // Re-center levels
-    levels.forEach(levelNodes => {
-      if (levelNodes.length === 0) return;
-      let maxBottom = 0;
-      levelNodes.forEach(node => {
-        const pos = nodePosition.get(node);
-        const bottom = pos.top + pos.height;
-        if (bottom > maxBottom) maxBottom = bottom;
-      });
-      const centerOffset = (100 - maxBottom) / 2;
-      if (centerOffset > 0) {
-        levelNodes.forEach(node => {
-          nodePosition.get(node).top += centerOffset;
-        });
-      }
-    });
-  }
-
-  // Calculate flow positions with consistent heights
+  // Calculate flow positions within each node
   const nodeOutOffset = new Map();
   const nodeInOffset = new Map();
   nodes.forEach(n => {
@@ -389,8 +309,8 @@ export function renderSankey(config) {
     const sourceOffset = nodeOutOffset.get(f.source);
     const targetOffset = nodeInOffset.get(f.target);
 
-    nodeOutOffset.set(f.source, sourceOffset + f.height);
-    nodeInOffset.set(f.target, targetOffset + f.height);
+    nodeOutOffset.set(f.source, sourceOffset + f.fromHeight);
+    nodeInOffset.set(f.target, targetOffset + f.toHeight);
 
     return {
       ...f,
@@ -495,21 +415,28 @@ export function renderSankey(config) {
     html += `</figcaption>`;
   }
 
-  // Legend (optional)
-  if (legend) {
-    html += `<ul class="chart-legend">`;
-    nodes.forEach((node, i) => {
-      const colorClass = `chart-color-${nodeColors.get(node)}`;
-      const seriesClass = `chart-series-${slugify(node)}`;
-      const throughput = nodeThroughput.get(node);
-      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(node)}`;
-      if (format) {
-        html += ` <span class="legend-value">${formatNumber(throughput, format) || throughput}</span>`;
-      }
-      html += `</li>`;
+  // Build neighbor map for node hover highlighting
+  const nodeNeighbors = new Map();
+  nodes.forEach(n => nodeNeighbors.set(n, new Set()));
+  aggregatedEdges.forEach(({ source, target }) => {
+    nodeNeighbors.get(source).add(target);
+    nodeNeighbors.get(target).add(source);
+  });
+
+  // Generate per-node hover rules: brighten connected flows and nodes, dim the rest
+  html += `<style>`;
+  nodes.forEach(node => {
+    const slug = slugify(node);
+    const prefix = `.chart-sankey-container:has(.chart-series-${slug}:hover)`;
+    // Brighten connected flows
+    html += `${prefix} .chart-flow-${slug} path{opacity:0.8}`;
+    // Brighten hovered node + its neighbors
+    html += `${prefix} .chart-series-${slug}{opacity:1}`;
+    nodeNeighbors.get(node).forEach(neighbor => {
+      html += `${prefix} .chart-series-${slugify(neighbor)}{opacity:1}`;
     });
-    html += `</ul>`;
-  }
+  });
+  html += `</style>`;
 
   html += `<div class="chart-sankey-container">`;
 
@@ -527,19 +454,23 @@ export function renderSankey(config) {
     // SVG path coordinates (0-100 viewBox)
     const y1 = flow.fromTop;
     const y2 = flow.toTop;
-    const h = flow.height;
+    const fh = flow.fromHeight;
+    const th = flow.toHeight;
 
     // Bezier control points at 40% and 60% for smooth S-curve
     const cx1 = 40;
     const cx2 = 60;
 
     // Path: top edge (left to right with curve), then bottom edge (right to left with curve)
+    // Flow tapers between fromHeight at source and toHeight at target
     // Extend slightly past 0/100 to overlap with node columns and prevent subpixel gaps
     const x0 = -2;
     const x1end = 102;
-    const pathD = `M ${x0},${y1.toFixed(2)} C ${cx1},${y1.toFixed(2)} ${cx2},${y2.toFixed(2)} ${x1end},${y2.toFixed(2)} L ${x1end},${(y2 + h).toFixed(2)} C ${cx2},${(y2 + h).toFixed(2)} ${cx1},${(y1 + h).toFixed(2)} ${x0},${(y1 + h).toFixed(2)} Z`;
+    const pathD = `M ${x0},${y1.toFixed(2)} C ${cx1},${y1.toFixed(2)} ${cx2},${y2.toFixed(2)} ${x1end},${y2.toFixed(2)} L ${x1end},${(y2 + th).toFixed(2)} C ${cx2},${(y2 + th).toFixed(2)} ${cx1},${(y1 + fh).toFixed(2)} ${x0},${(y1 + fh).toFixed(2)} Z`;
 
-    html += `<svg class="chart-sankey-flow" viewBox="0 0 100 100" preserveAspectRatio="none" `;
+    const sourceSlug = slugify(flow.source);
+    const targetSlug = slugify(flow.target);
+    html += `<svg class="chart-sankey-flow chart-flow-${sourceSlug} chart-flow-${targetSlug}" viewBox="0 0 100 100" preserveAspectRatio="none" `;
     html += `style="grid-column: ${colStart} / ${colEnd}; --from-level: ${flow.fromLevel}; --flow-index: ${i}; --delay-step: ${delayStep.toFixed(3)}s">`;
     html += `<defs><linearGradient id="sankey-grad-${id || 'default'}-${i}">`;
     html += `<stop offset="0%" style="stop-color: var(--chart-color-${sourceColor})" />`;
@@ -574,6 +505,23 @@ export function renderSankey(config) {
   });
 
   html += `</div>`;
+
+  // Legend (optional)
+  if (legend) {
+    html += `<ul class="chart-legend">`;
+    nodes.forEach((node, i) => {
+      const colorClass = `chart-color-${nodeColors.get(node)}`;
+      const seriesClass = `chart-series-${slugify(node)}`;
+      const throughput = nodeThroughput.get(node);
+      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(node)}`;
+      if (format) {
+        html += ` <span class="legend-value">${formatNumber(throughput, format) || throughput}</span>`;
+      }
+      html += `</li>`;
+    });
+    html += `</ul>`;
+  }
+
   html += renderDownloadLink(downloadDataUrl, downloadData);
   html += `</figure>`;
 

package/src/renderers/scatter.js

@@ -6,19 +6,21 @@ import { formatNumber } from '../formatters.js';
  * @param {Object} config - Chart configuration
  * @param {string} config.title - Chart title
  * @param {string} [config.subtitle] - Chart subtitle
- * @param {Object[]} config.data - Chart data (positional: label, x, y, series)
+ * @param {Object[]} config.data - Chart data (label + named columns: x, y, size, series)
  * @param {number} [config.maxX] - Maximum X value (defaults to max in data)
  * @param {number} [config.maxY] - Maximum Y value (defaults to max in data)
  * @param {number} [config.minX] - Minimum X value (defaults to min in data or 0)
  * @param {number} [config.minY] - Minimum Y value (defaults to min in data or 0)
  * @param {string[]} [config.legend] - Legend labels for series
+ * @param {string} [config.legendTitle] - Title for series legend
+ * @param {string} [config.sizeTitle] - Title for size legend (enables size legend display)
  * @param {boolean} [config.animate] - Enable animations
  * @param {string} [config.titleX] - X-axis title (defaults to column name)
  * @param {string} [config.titleY] - Y-axis title (defaults to column name)
  * @returns {string} - HTML string
  */
 export function renderScatter(config) {
-  const { title, subtitle, data, maxX, maxY, minX, minY, legend, animate, format, titleX, titleY, id, downloadData, downloadDataUrl } = config;
+  const { title, subtitle, data, maxX, maxY, minX, minY, legend, legendTitle, sizeTitle, animate, format, titleX, titleY, id, downloadData, downloadDataUrl, proportional } = config;
 
   // Handle nested X/Y format for scatter charts
   const fmtX = format?.x || format || {};
@@ -30,25 +32,52 @@ export function renderScatter(config) {
 
   const animateClass = animate ? ' chart-animate' : '';
 
-  // Get column keys positionally
+  // Named column detection (case-insensitive), with positional fallback for x/y
   const keys = Object.keys(data[0]);
-  const labelKey = keys[0];           // First column: point labels
-  const xKey = keys[1];               // Second column: X values
-  const yKey = keys[2];               // Third column: Y values
-  const seriesKey = keys[3];          // Fourth column (optional): series
+  const findKey = name => keys.find(k => k.toLowerCase() === name) || null;
+
+  // First column is always label
+  const labelKey = keys[0];
+
+  // X and Y: named if both exist, otherwise positional (columns 2 and 3)
+  const namedX = findKey('x');
+  const namedY = findKey('y');
+  const xKey = (namedX && namedY) ? namedX : keys[1];
+  const yKey = (namedX && namedY) ? namedY : keys[2];
+
+  // Size and series: named only (no positional fallback)
+  const sizeKey = findKey('size');
+  const seriesKey = findKey('series');
 
   // Axis titles: explicit config overrides column names
   const xAxisTitle = titleX ?? xKey;
   const yAxisTitle = titleY ?? yKey;
 
-  // Map data to dots using positional columns
+  // Map data to dots
   const dots = data.map(item => ({
     label: item[labelKey] ?? '',
     x: typeof item[xKey] === 'number' ? item[xKey] : parseFloat(item[xKey]) || 0,
     y: typeof item[yKey] === 'number' ? item[yKey] : parseFloat(item[yKey]) || 0,
+    rawSize: sizeKey ? (typeof item[sizeKey] === 'number' ? item[sizeKey] : parseFloat(item[sizeKey]) || 0) : null,
     series: seriesKey ? (item[seriesKey] ?? 'default') : 'default'
   }));
 
+  // Size normalization: non-positive values get minimum size (scale 0)
+  if (sizeKey) {
+    const sizeValues = dots.map(d => d.rawSize).filter(v => v > 0);
+    const minSizeVal = sizeValues.length ? Math.min(...sizeValues) : 1;
+    const maxSizeVal = sizeValues.length ? Math.max(...sizeValues) : 1;
+    const sizeRange = maxSizeVal - minSizeVal;
+
+    dots.forEach(dot => {
+      if (dot.rawSize <= 0 || sizeRange === 0) {
+        dot.sizeScale = 0;
+      } else {
+        dot.sizeScale = (dot.rawSize - minSizeVal) / sizeRange;
+      }
+    });
+  }
+
   // Calculate bounds
   const xValues = dots.map(d => d.x);
   const yValues = dots.map(d => d.y);
@@ -63,6 +92,7 @@ export function renderScatter(config) {
   const calcMinY = minY ?? (dataMinY < 0 ? dataMinY : 0);
   const rangeX = calcMaxX - calcMinX;
   const rangeY = calcMaxY - calcMinY;
+  const dataAspectRatio = rangeY > 0 ? rangeX / rangeY : 1;
 
   const hasNegativeX = calcMinX < 0;
   const hasNegativeY = calcMinY < 0;
@@ -77,8 +107,9 @@ export function renderScatter(config) {
   const seriesIndex = new Map(seriesList.map((s, i) => [s, i]));
 
   const negativeClasses = (hasNegativeX ? ' has-negative-x' : '') + (hasNegativeY ? ' has-negative-y' : '');
+  const proportionalClass = proportional ? ' chart-proportional' : '';
   const idClass = id ? ` chart-${id}` : '';
-  let html = `<figure class="chart chart-scatter${animateClass}${negativeClasses}${idClass}">`;
+  let html = `<figure class="chart chart-scatter${animateClass}${negativeClasses}${proportionalClass}${idClass}">`;
 
   if (title) {
     html += `<figcaption class="chart-title">${escapeHtml(title)}`;
@@ -88,19 +119,6 @@ export function renderScatter(config) {
     html += `</figcaption>`;
   }
 
-  // Legend (if multiple series)
-  if (seriesList.length > 1 || legend) {
-    const legendLabels = legend ?? seriesList;
-    html += `<ul class="chart-legend">`;
-    seriesList.forEach((series, i) => {
-      const label = legendLabels[i] ?? series;
-      const colorClass = `chart-color-${i + 1}`;
-      const seriesClass = `chart-series-${slugify(series)}`;
-      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
-    });
-    html += `</ul>`;
-  }
-
   html += `<div class="chart-body">`;
 
   // Y-axis
@@ -119,9 +137,11 @@ export function renderScatter(config) {
   if (hasNegativeY) containerStyles.push(`--zero-position-y: ${zeroPctY.toFixed(2)}%`);
   const containerStyle = containerStyles.length > 0 ? ` style="${containerStyles.join('; ')}"` : '';
   html += `<div class="scatter-container"${containerStyle}>`;
-  html += `<div class="dot-area">`;
+  const dotAreaStyle = proportional ? ` style="--data-aspect-ratio: ${dataAspectRatio.toFixed(4)}"` : '';
+  html += `<div class="dot-area"${dotAreaStyle}>`;
   html += `<div class="dot-field">`;
 
+  const fmtSize = format?.size || {};
   dots.forEach((dot, i) => {
     const xPct = rangeX > 0 ? ((dot.x - calcMinX) / rangeX) * 100 : 0;
     const yPct = rangeY > 0 ? ((dot.y - calcMinY) / rangeY) * 100 : 0;
@@ -130,10 +150,22 @@ export function renderScatter(config) {
     const seriesClass = `chart-series-${slugify(dot.series)}`;
     const fmtXVal = formatNumber(dot.x, fmtX) || dot.x;
     const fmtYVal = formatNumber(dot.y, fmtY) || dot.y;
-    const tooltipText = dot.label ? `${dot.label}: (${fmtXVal}, ${fmtYVal})` : `(${fmtXVal}, ${fmtYVal})`;
+
+    // Build tooltip with optional size value
+    let tooltipText = dot.label ? `${dot.label}: (${fmtXVal}, ${fmtYVal})` : `(${fmtXVal}, ${fmtYVal})`;
+    if (sizeKey && dot.rawSize !== null) {
+      const fmtSizeVal = formatNumber(dot.rawSize, fmtSize) || dot.rawSize;
+      tooltipText += ` [${fmtSizeVal}]`;
+    }
+
+    // Build style string with optional size scale
+    let styleStr = `--dot-index: ${i}; --x: ${xPct.toFixed(2)}%; --value: ${yPct.toFixed(2)}%`;
+    if (sizeKey) {
+      styleStr += `; --size-scale: ${dot.sizeScale.toFixed(4)}`;
+    }
 
     html += `<div class="dot ${colorClass} ${seriesClass}" `;
-    html += `style="--dot-index: ${i}; --x: ${xPct.toFixed(2)}%; --value: ${yPct.toFixed(2)}%" `;
+    html += `style="${styleStr}" `;
     html += `title="${escapeHtml(tooltipText)}"`;
     html += `></div>`;
   });
@@ -153,6 +185,41 @@ export function renderScatter(config) {
 
   html += `</div>`;
   html += `</div>`;
+
+  // Legend (if multiple series or legendTitle specified)
+  if (seriesList.length > 1 || legend || legendTitle) {
+    const legendLabels = legend ?? seriesList;
+    if (legendTitle) {
+      html += `<span class="chart-legend-title">${escapeHtml(legendTitle)}</span>`;
+    }
+    html += `<ul class="chart-legend">`;
+    seriesList.forEach((series, i) => {
+      const label = legendLabels[i] ?? series;
+      const colorClass = `chart-color-${i + 1}`;
+      const seriesClass = `chart-series-${slugify(series)}`;
+      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
+    });
+    html += `</ul>`;
+  }
+
+  // Size legend (when sizeTitle is specified and size column exists)
+  if (sizeTitle && sizeKey) {
+    const sizeValues = dots.map(d => d.rawSize).filter(v => v > 0);
+    const minSizeVal = sizeValues.length ? Math.min(...sizeValues) : 0;
+    const maxSizeVal = sizeValues.length ? Math.max(...sizeValues) : 0;
+    const fmtSizeLegend = format?.size || format || {};
+    const minFormatted = formatNumber(minSizeVal, fmtSizeLegend) || minSizeVal;
+    const maxFormatted = formatNumber(maxSizeVal, fmtSizeLegend) || maxSizeVal;
+
+    html += `<div class="chart-size-legend">`;
+    html += `<span class="chart-legend-title">${escapeHtml(sizeTitle)}</span>`;
+    html += `<div class="size-legend-items">`;
+    html += `<span class="size-legend-item"><span class="size-dot size-dot-min"></span><span class="size-value">${minFormatted}</span></span>`;
+    html += `<span class="size-legend-item"><span class="size-dot size-dot-max"></span><span class="size-value">${maxFormatted}</span></span>`;
+    html += `</div>`;
+    html += `</div>`;
+  }
+
   html += renderDownloadLink(downloadDataUrl, downloadData);
   html += `</figure>`;
 

package/src/renderers/stacked-bar.js

@@ -13,7 +13,7 @@ import { formatNumber } from '../formatters.js';
  * @returns {string} - HTML string
  */
 export function renderStackedBar(config) {
-  const { title, subtitle, data, max, legend, animate, format, id, downloadData, downloadDataUrl } = config;
+  const { title, subtitle, data, max, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked bar chart: no data provided -->`;
@@ -46,7 +46,10 @@ export function renderStackedBar(config) {
   }
 
   // Legend
-  if (seriesKeys.length > 0) {
+  if (seriesKeys.length > 0 || legendTitle) {
+    if (legendTitle) {
+      html += `<span class="chart-legend-title">${escapeHtml(legendTitle)}</span>`;
+    }
     html += `<ul class="chart-legend">`;
     seriesKeys.forEach((key, i) => {
       const label = legendLabels[i] ?? key;

package/src/renderers/stacked-column.js

@@ -67,18 +67,6 @@ export function renderStackedColumn(config) {
     html += `</figcaption>`;
   }
 
-  // Legend
-  if (seriesKeys.length > 0) {
-    html += `<ul class="chart-legend">`;
-    seriesKeys.forEach((key, i) => {
-      const label = legendLabels[i] ?? key;
-      const colorClass = `chart-color-${i + 1}`;
-      const seriesClass = `chart-series-${slugify(key)}`;
-      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
-    });
-    html += `</ul>`;
-  }
-
   html += `<div class="chart-body">`;
 
   // Y-axis with --zero-position for label positioning
@@ -192,6 +180,19 @@ export function renderStackedColumn(config) {
 
   html += `</div>`; // close chart-scroll
   html += `</div>`; // close chart-body
+
+  // Legend
+  if (seriesKeys.length > 0) {
+    html += `<ul class="chart-legend">`;
+    seriesKeys.forEach((key, i) => {
+      const label = legendLabels[i] ?? key;
+      const colorClass = `chart-color-${i + 1}`;
+      const seriesClass = `chart-series-${slugify(key)}`;
+      html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
+    });
+    html += `</ul>`;
+  }
+
   html += renderDownloadLink(downloadDataUrl, downloadData);
   html += `</figure>`;