eleventy-plugin-uncharted 0.5.1 → 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
    ========================================================================== */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-uncharted",
-  "version": "0.5.1",
+  "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

@@ -415,22 +415,6 @@ 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>`;
-    });
-    html += `</ul>`;
-  }
-
   // Build neighbor map for node hover highlighting
   const nodeNeighbors = new Map();
   nodes.forEach(n => nodeNeighbors.set(n, new Set()));
@@ -521,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>`;