eleventy-plugin-uncharted 1.0.0-beta.2 → 1.0.0-beta.4

package/css/uncharted.css

@@ -1674,8 +1674,11 @@
    Download Link
    ========================================================================== */
 
-.chart-download {
-  display: block;
+.chart-downloads {
   font-size: 0.75em;
   margin-block-start: 0.5em;
 }
+
+.chart-download-sep {
+  opacity: 0.5;
+}

package/eleventy.config.js

@@ -28,9 +28,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * @param {boolean} [options.dataPassthrough] - Copy CSV files to public dataPath (default: false)
  * @param {string} [options.dataPath] - Public URL path for CSV files (default: '/data/')
  * @param {boolean|string} [options.downloadData] - Enable download links globally (individual charts can override)
+ * @param {boolean|string} [options.downloadImage] - Enable image download links globally (requires image generation)
  * @param {Object} [options.image] - Image generation options
  * @param {boolean} [options.image.enabled=false] - Enable PNG image generation
- * @param {string} [options.image.outputDir='/images/charts/'] - Output directory for images
+ * @param {string} [options.image.outputDir='/images/charts/'] - Output directory for images (URL path)
+ * @param {string} [options.image.cacheDir] - Source directory for cached images (enables caching when set)
  * @param {number} [options.image.width=800] - Default image width in pixels
  * @param {number} [options.image.height=400] - Default image height in pixels
  * @param {number} [options.image.scale=2] - Device scale factor (2 for retina)
@@ -66,6 +68,7 @@ export default function(eleventyConfig, options = {}) {
   const dataPassthrough = options.dataPassthrough ?? false;
   const dataPath = options.dataPath || '/data/';
   const globalDownloadData = options.downloadData ?? false;
+  const globalDownloadImage = options.downloadImage ?? false;
 
   // Image generation options
   const imageOptions = normalizeImageOptions(options.image);
@@ -123,6 +126,15 @@ export default function(eleventyConfig, options = {}) {
     });
   }
 
+  // Image cache passthrough - copies cached images to output
+  if (imageOptions.cacheDir) {
+    const cacheDirClean = imageOptions.cacheDir.replace(/^\/|\/$/g, '');
+    const outputDirClean = imageOptions.outputDir.replace(/^\/|\/$/g, '');
+    eleventyConfig.addPassthroughCopy({
+      [cacheDirClean]: outputDirClean
+    });
+  }
+
   eleventyConfig.addShortcode('chart', function(chartId) {
     // Get resolved data directory (from Eleventy config or plugin options)
     const resolvedDataDir = getDataDir();
@@ -174,6 +186,7 @@ export default function(eleventyConfig, options = {}) {
     // Render the chart (chart-specific settings override global)
     const animate = chartConfig.animate ?? globalAnimate;
     const downloadData = chartConfig.downloadData ?? globalDownloadData;
+    const downloadImage = chartConfig.downloadImage ?? globalDownloadImage;
 
     // Calculate download URL if download is enabled and file is specified
     let downloadDataUrl = null;
@@ -182,6 +195,13 @@ export default function(eleventyConfig, options = {}) {
       downloadDataUrl = normalizedDataPath + chartConfig.file;
     }
 
+    // Calculate image download URL if enabled and image generation is active
+    const chartImageEnabled = chartConfig.image?.enabled ?? imageOptions.enabled;
+    let downloadImageUrl = null;
+    if (downloadImage && chartImageEnabled) {
+      downloadImageUrl = getImageUrl(chartId, chartConfig, imageOptions);
+    }
+
     // Normalize configuration (handles deprecated keys, axis config)
     const normalizedConfig = normalizeConfig(chartConfig, chartId);
 
@@ -196,6 +216,8 @@ export default function(eleventyConfig, options = {}) {
       animate,
       downloadData,
       downloadDataUrl,
+      downloadImage,
+      downloadImageUrl,
       _columns: columns
     });
 
@@ -207,7 +229,6 @@ export default function(eleventyConfig, options = {}) {
     );
 
     // Handle image generation
-    const chartImageEnabled = chartConfig.image?.enabled ?? imageOptions.enabled;
     if (chartImageEnabled && !skipImageGeneration && eleventyDirs?.output) {
       // Queue chart for image generation
       queueChartForImage(chartId, chartHtml, chartConfig, imageOptions, eleventyDirs.output);

package/package.json

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

package/src/image/index.js

@@ -15,6 +15,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
  * @typedef {Object} ImageOptions
  * @property {boolean} [enabled=false] - Enable image generation
  * @property {string} [outputDir='/images/charts/'] - Output directory for images (URL path)
+ * @property {string} [cacheDir=null] - Source directory for cached images (enables caching when set)
  * @property {number} [width=800] - Default image width
  * @property {number} [height=400] - Default image height
  * @property {number} [scale=2] - Device scale factor (2 for retina)
@@ -33,6 +34,7 @@ const imageUrls = new Map();
 const defaultOptions = {
   enabled: false,
   outputDir: '/images/charts/',
+  cacheDir: null,
   width: 800,
   height: 400,
   scale: 2,
@@ -83,6 +85,23 @@ export function getImageUrl(chartId, chartConfig, globalOptions) {
   return `${dir}${filename}.png`;
 }
 
+/**
+ * Get the cache file path for a chart image.
+ * @param {string} chartId - Chart identifier
+ * @param {Object} chartConfig - Chart configuration
+ * @param {ImageOptions} globalOptions - Global image options
+ * @returns {string|null} Absolute cache path, or null if caching disabled
+ */
+export function getCachePath(chartId, chartConfig, globalOptions) {
+  if (!globalOptions.cacheDir) return null;
+
+  const imageConfig = chartConfig.image || {};
+  const filename = imageConfig.filename || chartId;
+  const cacheDir = globalOptions.cacheDir.replace(/\/$/, '');
+
+  return path.resolve(process.cwd(), cacheDir, `${filename}.png`);
+}
+
 /**
  * Store the image URL for a chart (for shortcode lookup).
  * @param {string} chartId
@@ -143,6 +162,7 @@ export function queueChartForImage(chartId, chartHtml, chartConfig, globalOption
 
   const outputPath = getImageOutputPath(chartId, chartConfig, globalOptions, outputDir);
   const url = getImageUrl(chartId, chartConfig, globalOptions);
+  const cachePath = getCachePath(chartId, chartConfig, globalOptions);
 
   // Store URL for shortcode lookup
   storeImageUrl(chartId, url);
@@ -152,7 +172,8 @@ export function queueChartForImage(chartId, chartHtml, chartConfig, globalOption
     id: chartId,
     html: chartHtml,
     config,
-    outputPath
+    outputPath,
+    cachePath
   });
 }
 
@@ -171,7 +192,10 @@ export async function processQueue(options) {
   if (!available) {
     const count = getQueueSize();
     clearQueue();
-    console.warn(`[uncharted] Puppeteer not installed. Skipped ${count} chart image(s).`);
+    // Suppress warning if cacheDir is set (cached images will be used via passthrough)
+    if (!options.cacheDir) {
+      console.warn(`[uncharted] Puppeteer not installed. Skipped ${count} chart image(s).`);
+    }
     return { success: [], failed: [], skipped: true };
   }
 

package/src/image/renderer.js

@@ -170,7 +170,8 @@ ${stylesheetLinks}
  * @param {Object} chart - Chart data
  * @param {string} chart.html - Chart HTML
  * @param {Object} chart.config - Image configuration
- * @param {string} chart.outputPath - Output file path
+ * @param {string} chart.outputPath - Output file path (_site)
+ * @param {string} [chart.cachePath] - Cache file path (source directory, if caching enabled)
  * @param {string} css - Chart CSS content
  * @param {Object} defaults - Default image options
  * @returns {Promise<void>}
@@ -183,6 +184,9 @@ async function renderChart(page, chart, css, defaults) {
   const background = config.background || '#ffffff';
   const stylesheets = config.stylesheets || defaults.stylesheets || [];
 
+  // Use cache path if provided, otherwise write directly to output
+  const writePath = chart.cachePath || chart.outputPath;
+
   // Set viewport
   await page.setViewport({
     width,
@@ -206,14 +210,14 @@ async function renderChart(page, chart, css, defaults) {
     }
 
     // Ensure output directory exists
-    const outputDir = path.dirname(chart.outputPath);
+    const outputDir = path.dirname(writePath);
     if (!fs.existsSync(outputDir)) {
       fs.mkdirSync(outputDir, { recursive: true });
     }
 
     // Take screenshot
     await page.screenshot({
-      path: chart.outputPath,
+      path: writePath,
       type: 'png',
       omitBackground: background === 'transparent'
     });

package/src/renderers/bubble.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, renderDownloadLink } from '../utils.js';
+import { slugify, escapeHtml, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 import { getAxisMax, getAxisMin, getAxisTitle, getAxisFormat, getRotateLabels } from '../config.js';
 
@@ -17,7 +17,7 @@ import { getAxisMax, getAxisMin, getAxisTitle, getAxisFormat, getRotateLabels }
  * @returns {string} - HTML string
  */
 export function renderBubble(config) {
-  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, icons, _columns } = config;
+  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, icons, _columns } = config;
 
   // Get axis-specific format configs
   const fmtY = getAxisFormat(config, 'y');
@@ -262,7 +262,7 @@ export function renderBubble(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/donut.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, getLabelKey, getValueKey, getSeriesNames, renderDownloadLink } from '../utils.js';
+import { slugify, escapeHtml, getLabelKey, getValueKey, getSeriesNames, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 
 /**
@@ -17,7 +17,7 @@ import { formatNumber } from '../formatters.js';
  * @returns {string} - HTML string
  */
 export function renderDonut(config) {
-  const { title, subtitle, data, legend, center, animate, format, id, showPercentages, downloadData, downloadDataUrl, _columns } = config;
+  const { title, subtitle, data, legend, center, animate, format, id, showPercentages, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Donut chart: no data provided -->`;
@@ -136,7 +136,7 @@ export function renderDonut(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/line.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, getLabelKey, getSeriesNames, renderDownloadLink } from '../utils.js';
+import { slugify, escapeHtml, getLabelKey, getSeriesNames, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 import { getAxisMax, getAxisMin, getAxisFormat, getAxisTitle, getRotateLabels } from '../config.js';
 
@@ -17,7 +17,7 @@ import { getAxisMax, getAxisMin, getAxisFormat, getAxisTitle, getRotateLabels }
  * @returns {string} - HTML string
  */
 export function renderLine(config) {
-  const { title, subtitle, data, max, min, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, icons, _columns } = config;
+  const { title, subtitle, data, max, min, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, icons, _columns } = config;
 
   // Line-specific options
   const showLines = config.lines !== false; // default true
@@ -211,7 +211,7 @@ export function renderLine(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/sankey.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, renderDownloadLink } from '../utils.js';
+import { slugify, escapeHtml, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 
 /**
@@ -17,7 +17,7 @@ import { formatNumber } from '../formatters.js';
  * @returns {string} - HTML string
  */
 export function renderSankey(config) {
-  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, nodeWidth = 20, nodePadding = 10, endLabelsOutside = false, proportional = false, _columns } = config;
+  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, nodeWidth = 20, nodePadding = 10, endLabelsOutside = false, proportional = false, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Sankey chart: no data provided -->`;
@@ -526,7 +526,7 @@ export function renderSankey(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/scatter.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, renderDownloadLink } from '../utils.js';
+import { slugify, escapeHtml, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 import { getAxisMax, getAxisMin, getAxisTitle, getAxisFormat } from '../config.js';
 
@@ -18,7 +18,7 @@ import { getAxisMax, getAxisMin, getAxisTitle, getAxisFormat } from '../config.j
  * @returns {string} - HTML string
  */
 export function renderScatter(config) {
-  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, proportional, icons, _columns } = config;
+  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, proportional, icons, _columns } = config;
 
   // Get axis-specific format configs (normalized config provides x.format/y.format)
   const fmtX = getAxisFormat(config, 'x');
@@ -259,7 +259,7 @@ export function renderScatter(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/stacked-bar.js

@@ -1,4 +1,4 @@
-import { slugify, calculatePercentages, getLabelKey, getSeriesNames, escapeHtml, renderDownloadLink } from '../utils.js';
+import { slugify, calculatePercentages, getLabelKey, getSeriesNames, escapeHtml, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 import { getAxisMax, getAxisFormat } from '../config.js';
 
@@ -15,7 +15,7 @@ import { getAxisMax, getAxisFormat } from '../config.js';
  * @returns {string} - HTML string
  */
 export function renderStackedBar(config) {
-  const { title, subtitle, data, max, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, _columns } = config;
+  const { title, subtitle, data, max, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked bar chart: no data provided -->`;
@@ -114,7 +114,7 @@ export function renderStackedBar(config) {
   });
 
   html += `</div>`;
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/stacked-column.js

@@ -1,4 +1,4 @@
-import { slugify, getLabelKey, getSeriesNames, escapeHtml, renderDownloadLink } from '../utils.js';
+import { slugify, getLabelKey, getSeriesNames, escapeHtml, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 import { getAxisMax, getAxisMin, getAxisFormat, getRotateLabels } from '../config.js';
 
@@ -15,7 +15,7 @@ import { getAxisMax, getAxisMin, getAxisFormat, getRotateLabels } from '../confi
  * @returns {string} - HTML string
  */
 export function renderStackedColumn(config) {
-  const { title, subtitle, data, max, min, legend, animate, format, id, downloadData, downloadDataUrl, _columns } = config;
+  const { title, subtitle, data, max, min, legend, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked column chart: no data provided -->`;
@@ -208,7 +208,7 @@ export function renderStackedColumn(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/renderers/timeseries.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, getLabelKey, getSeriesNames, renderDownloadLink } from '../utils.js';
+import { slugify, escapeHtml, getLabelKey, getSeriesNames, renderDownloadLinks } from '../utils.js';
 import { formatNumber } from '../formatters.js';
 import { getAxisMax, getAxisMin, getAxisTitle, getAxisFormat, getRotateLabels } from '../config.js';
 
@@ -237,7 +237,7 @@ function getAxisTicks(min, max, isDate) {
  * @returns {string} - HTML string
  */
 export function renderTimeseries(config) {
-  const { title, subtitle, data, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, dots: showDots = false, icons, _columns } = config;
+  const { title, subtitle, data, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, downloadImage, downloadImageUrl, dots: showDots = false, icons, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Timeseries chart: no data provided -->`;
@@ -498,7 +498,7 @@ export function renderTimeseries(config) {
     html += `</div>`;
   }
 
-  html += renderDownloadLink(downloadDataUrl, downloadData);
+  html += renderDownloadLinks(downloadDataUrl, downloadData, downloadImageUrl, downloadImage);
   html += `</figure>`;
 
   return html;

package/src/utils.js

@@ -82,3 +82,31 @@ export function renderDownloadLink(url, label) {
   return `<a href="${escapeHtml(url)}" class="chart-download" download>${escapeHtml(text)}</a>`;
 }
 
+/**
+ * Render a download link for chart image
+ * @param {string} url - URL to the image file
+ * @param {boolean|string} label - true for default label, or custom string
+ * @returns {string} - HTML string for the download link, or empty string if no URL
+ */
+export function renderDownloadImageLink(url, label) {
+  if (!url) return '';
+  const text = typeof label === 'string' ? label : '↓ Download image';
+  return `<a href="${escapeHtml(url)}" class="chart-download" download>${escapeHtml(text)}</a>`;
+}
+
+/**
+ * Render download links container (wraps data and image download links)
+ * @param {string} dataUrl - URL to the CSV file
+ * @param {boolean|string} dataLabel - true for default label, or custom string
+ * @param {string} imageUrl - URL to the image file
+ * @param {boolean|string} imageLabel - true for default label, or custom string
+ * @returns {string} - HTML string for the download links container, or empty string if no URLs
+ */
+export function renderDownloadLinks(dataUrl, dataLabel, imageUrl, imageLabel) {
+  const dataLink = renderDownloadLink(dataUrl, dataLabel);
+  const imageLink = renderDownloadImageLink(imageUrl, imageLabel);
+  if (!dataLink && !imageLink) return '';
+  const separator = dataLink && imageLink ? ' <span class="chart-download-sep">•</span> ' : '';
+  return `<div class="chart-downloads">${dataLink}${separator}${imageLink}</div>`;
+}
+