eleventy-plugin-uncharted 0.1.0 → 0.1.2

package/README.md

@@ -1,18 +1,18 @@
 # Uncharted
 
-A CSS-based charting plugin for Eleventy. Renders charts as pure HTML/CSS with no JavaScript dependencies.
+A CSS-based chart plugin for Eleventy. Renders charts as pure HTML/CSS with no JavaScript dependencies.
 
 ## Installation
 
 ```bash
-npm install uncharted
+npm install eleventy-plugin-uncharted
 ```
 
 ## Setup
 
 ```javascript
 // eleventy.config.js
-import uncharted from 'uncharted';
+import uncharted from 'eleventy-plugin-uncharted';
 
 export default function(eleventyConfig) {
   eleventyConfig.addPlugin(uncharted);
@@ -40,13 +40,13 @@ If you set `injectCss: false`, you'll need to manually include the stylesheet in
 
 ## Chart Types
 
-| Type | Description |
-|------|-------------|
-| `donut` | Pie/donut chart using conic-gradient |
-| `stacked-bar` | Horizontal bars with stacked segments |
-| `stacked-column` | Vertical columns with stacked segments |
-| `dot` | Categorical dot chart with Y-axis positioning |
-| `scatter` | XY scatter plot with continuous axes |
+| Type | Description | Negative Values |
+|------|-------------|-----------------|
+| `donut` | Pie/donut chart using conic-gradient | No |
+| `stacked-bar` | Horizontal bars with stacked segments | No |
+| `stacked-column` | Vertical columns with stacked segments | Yes |
+| `dot` | Categorical dot chart with Y-axis positioning | Yes |
+| `scatter` | XY scatter plot with continuous axes | Yes (X and Y) |
 
 ## Usage
 
@@ -110,10 +110,10 @@ charts:
 
 ## CSV Format
 
-CSV files use the first column as labels and subsequent columns as data series:
+CSV files use the first column as labels and subsequent columns as data series. The column names can be anything descriptive:
 
 ```csv
-label,existing,new
+department,existing,new
 Finance,11,11
 Sales,16,2
 Core,8,0
@@ -128,6 +128,22 @@ Point B,25,78,alpha
 Point C,15,32,beta
 ```
 
+## Negative Values
+
+Stacked column, dot, and scatter charts support negative values. When negative values are present, a zero axis line appears automatically and values are positioned relative to it.
+
+For stacked columns, positive values stack upward from zero and negative values stack downward:
+
+```csv
+quarter,Cost,Profit
+Q1,20,10
+Q2,25,-10
+Q3,15,25
+Q4,30,-10
+```
+
+The chart automatically calculates the range from the maximum positive stack to the minimum negative stack, ensuring proper scaling.
+
 ## Configuration Options
 
 | Option | Type | Description |
@@ -137,9 +153,12 @@ Point C,15,32,beta
 | `subtitle` | string | Subtitle below title |
 | `file` | string | Path to CSV file (relative to dataDir) |
 | `data` | array | Inline data array |
-| `max` | number | Maximum value for scaling |
+| `max` | number | Maximum Y value for scaling |
+| `min` | number | Minimum Y value for scaling (column, dot) |
 | `maxX` | number | Maximum X value (scatter only) |
 | `maxY` | number | Maximum Y value (scatter only) |
+| `minX` | number | Minimum X value (scatter only) |
+| `minY` | number | Minimum Y value (scatter only) |
 | `legend` | array | Custom legend labels |
 | `center` | object | Donut center content (`value`, `label`) |
 | `animate` | boolean | Override global animation setting |

package/css/uncharted.css

@@ -201,6 +201,7 @@
   height: 100%;
   width: var(--value);
   transition: width 0.3s ease;
+  background-color: var(--color);
 }
 
 .chart-stacked-bar .bar-value {
@@ -243,6 +244,7 @@
   width: 100%;
   height: var(--value);
   transition: height 0.3s ease;
+  background-color: var(--color);
 }
 
 .chart-stacked-column .column-labels {
@@ -381,6 +383,7 @@
   bottom: var(--value);
   transform: translate(-50%, 50%);
   cursor: default;
+  background-color: var(--color);
 }
 
 .chart-dot .dot[title]:hover {
@@ -443,6 +446,7 @@
   bottom: var(--value);
   transform: translate(-50%, 50%);
   cursor: default;
+  background-color: var(--color);
 }
 
 .chart-scatter .dot[title]:hover {

package/package.json

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

package/src/index.js

@@ -1,3 +1,3 @@
 export { renderers } from './renderers/index.js';
 export { loadCSV, parseCSV } from './csv.js';
-export { slugify, calculatePercentages, getSeriesNames, escapeHtml } from './utils.js';
+export { slugify, calculatePercentages, getLabelKey, getValueKey, getSeriesNames, escapeHtml } from './utils.js';

package/src/renderers/donut.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml } from '../utils.js';
+import { slugify, escapeHtml, getLabelKey, getValueKey, getSeriesNames } from '../utils.js';
 
 /**
  * Render a donut/pie chart using conic-gradient
@@ -22,18 +22,22 @@ export function renderDonut(config) {
 
   const animateClass = animate ? ' chart-animate' : '';
 
-  // Extract values - support both {label, value} format and series format
+  // Get column keys positionally
+  const labelKey = getLabelKey(data);
+  const valueKey = getValueKey(data);
+  const seriesKeys = getSeriesNames(data);
+
+  // Extract values - support both label/value format and series format
   let segments = [];
-  if (data[0].value !== undefined) {
-    // Direct {label, value} format
+  if (seriesKeys.length === 1) {
+    // Two columns: first is label, second is value (multiple rows)
     segments = data.map(item => ({
-      label: item.label,
-      value: typeof item.value === 'number' ? item.value : parseFloat(item.value) || 0
+      label: item[labelKey],
+      value: typeof item[valueKey] === 'number' ? item[valueKey] : parseFloat(item[valueKey]) || 0
     }));
   } else {
-    // Series format - first row only for donut
-    const seriesNames = Object.keys(data[0]).filter(k => k !== 'label');
-    segments = seriesNames.map(name => ({
+    // Series format - first row only, columns after the first are series
+    segments = seriesKeys.map(name => ({
       label: name,
       value: typeof data[0][name] === 'number' ? data[0][name] : parseFloat(data[0][name]) || 0
     }));

package/src/renderers/dot.js

@@ -1,4 +1,4 @@
-import { slugify, escapeHtml, getSeriesNames } from '../utils.js';
+import { slugify, escapeHtml, getLabelKey, getSeriesNames } from '../utils.js';
 
 /**
  * Render a categorical dot chart (columns with dots at different Y positions)
@@ -8,18 +8,20 @@ import { slugify, escapeHtml, getSeriesNames } from '../utils.js';
  * @param {string} [config.subtitle] - Chart subtitle
  * @param {Object[]} config.data - Chart data with label column and value columns
  * @param {number} [config.max] - Maximum Y value (defaults to max in data)
+ * @param {number} [config.min] - Minimum Y value (defaults to min in data or 0)
  * @param {string[]} [config.legend] - Legend labels (defaults to series names)
  * @param {boolean} [config.animate] - Enable animations
  * @returns {string} - HTML string
  */
 export function renderDot(config) {
-  const { title, subtitle, data, max, legend, animate } = config;
+  const { title, subtitle, data, max, min, legend, animate } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Dot chart: no data provided -->`;
   }
 
-  // Get series keys from data columns (excluding 'label')
+  // Get label key (first column) and series keys (remaining columns)
+  const labelKey = getLabelKey(data);
   const seriesKeys = getSeriesNames(data);
   const legendLabels = legend ?? seriesKeys;
   const animateClass = animate ? ' chart-animate' : '';
@@ -34,7 +36,7 @@ export function renderDot(config) {
   const dataMax = Math.max(...allValues);
   const dataMin = Math.min(...allValues);
   const maxValue = max ?? dataMax;
-  const minValue = dataMin < 0 ? dataMin : 0;
+  const minValue = min ?? (dataMin < 0 ? dataMin : 0);
   const range = maxValue - minValue;
   const hasNegativeY = minValue < 0;
 
@@ -81,7 +83,7 @@ export function renderDot(config) {
 
   // Each row becomes a column with dots for each series
   data.forEach(row => {
-    const label = row.label ?? '';
+    const label = row[labelKey] ?? '';
 
     html += `<div class="dot-col">`;
 
@@ -109,7 +111,7 @@ export function renderDot(config) {
   // X-axis labels
   html += `<div class="dot-labels">`;
   data.forEach(row => {
-    const label = row.label ?? '';
+    const label = row[labelKey] ?? '';
     html += `<span class="dot-label">${escapeHtml(label)}</span>`;
   });
   html += `</div>`;

package/src/renderers/scatter.js

@@ -8,12 +8,14 @@ import { slugify, escapeHtml } from '../utils.js';
  * @param {Object[]} config.data - Chart data (with label, x, y, and optionally 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 {boolean} [config.animate] - Enable animations
  * @returns {string} - HTML string
  */
 export function renderScatter(config) {
-  const { title, subtitle, data, maxX, maxY, legend, animate } = config;
+  const { title, subtitle, data, maxX, maxY, minX, minY, legend, animate } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Scatter chart: no data provided -->`;
@@ -51,8 +53,8 @@ export function renderScatter(config) {
 
   const calcMaxX = maxX ?? dataMaxX;
   const calcMaxY = maxY ?? dataMaxY;
-  const calcMinX = dataMinX < 0 ? dataMinX : 0;
-  const calcMinY = dataMinY < 0 ? dataMinY : 0;
+  const calcMinX = minX ?? (dataMinX < 0 ? dataMinX : 0);
+  const calcMinY = minY ?? (dataMinY < 0 ? dataMinY : 0);
   const rangeX = calcMaxX - calcMinX;
   const rangeY = calcMaxY - calcMinY;
 

package/src/renderers/stacked-bar.js

@@ -1,4 +1,4 @@
-import { slugify, calculatePercentages, getSeriesNames, escapeHtml } from '../utils.js';
+import { slugify, calculatePercentages, getLabelKey, getSeriesNames, escapeHtml } from '../utils.js';
 
 /**
  * Render a stacked bar chart (horizontal)
@@ -18,7 +18,8 @@ export function renderStackedBar(config) {
     return `<!-- Stacked bar chart: no data provided -->`;
   }
 
-  // Get actual data keys from the first row (excluding 'label')
+  // Get label key (first column) and series keys (remaining columns)
+  const labelKey = getLabelKey(data);
   const seriesKeys = getSeriesNames(data);
   // Use legend for display labels, fall back to data keys
   const legendLabels = legend ?? seriesKeys;
@@ -49,7 +50,7 @@ export function renderStackedBar(config) {
   html += `<div class="chart-bars">`;
 
   data.forEach(row => {
-    const label = row.label ?? '';
+    const label = row[labelKey] ?? '';
     const values = seriesKeys.map(key => {
       const val = row[key];
       return typeof val === 'number' ? val : parseFloat(val) || 0;

package/src/renderers/stacked-column.js

@@ -1,4 +1,4 @@
-import { slugify, getSeriesNames, escapeHtml } from '../utils.js';
+import { slugify, getLabelKey, getSeriesNames, escapeHtml } from '../utils.js';
 
 /**
  * Render a stacked column chart (vertical)
@@ -6,19 +6,21 @@ import { slugify, getSeriesNames, escapeHtml } from '../utils.js';
  * @param {string} config.title - Chart title
  * @param {string} [config.subtitle] - Chart subtitle
  * @param {Object[]} config.data - Chart data
- * @param {number} [config.max] - Maximum value for percentage calculation
+ * @param {number} [config.max] - Maximum value for Y-axis scaling
+ * @param {number} [config.min] - Minimum value for Y-axis scaling (for negative values)
  * @param {string[]} [config.legend] - Legend labels (defaults to series names)
  * @param {boolean} [config.animate] - Enable animations
  * @returns {string} - HTML string
  */
 export function renderStackedColumn(config) {
-  const { title, subtitle, data, max, legend, animate } = config;
+  const { title, subtitle, data, max, min, legend, animate } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked column chart: no data provided -->`;
   }
 
-  // Get actual data keys from the first row (excluding 'label')
+  // Get label key (first column) and series keys (remaining columns)
+  const labelKey = getLabelKey(data);
   const seriesKeys = getSeriesNames(data);
   // Use legend for display labels, fall back to data keys
   const legendLabels = legend ?? seriesKeys;
@@ -45,9 +47,9 @@ export function renderStackedColumn(config) {
     minNegativeStack = Math.min(minNegativeStack, negativeSum);
   });
 
-  const hasNegativeY = minNegativeStack < 0;
+  const hasNegativeY = minNegativeStack < 0 || min < 0;
   const maxValue = max ?? maxPositiveStack;
-  const minValue = minNegativeStack;
+  const minValue = min ?? minNegativeStack;
   const range = maxValue - minValue;
   const zeroPct = hasNegativeY ? ((0 - minValue) / range) * 100 : 0;
 
@@ -89,7 +91,7 @@ export function renderStackedColumn(config) {
   html += `<div class="chart-columns"${columnsStyle}>`;
 
   data.forEach(row => {
-    const label = row.label ?? '';
+    const label = row[labelKey] ?? '';
     html += `<div class="column-track" title="${escapeHtml(label)}">`;
 
     if (hasNegativeY) {
@@ -172,7 +174,7 @@ export function renderStackedColumn(config) {
   // X-axis labels
   html += `<div class="column-labels">`;
   data.forEach(row => {
-    const label = row.label ?? '';
+    const label = row[labelKey] ?? '';
     html += `<span class="column-label">${escapeHtml(label)}</span>`;
   });
   html += `</div>`;

package/src/utils.js

@@ -25,13 +25,33 @@ export function calculatePercentages(values, max) {
 }
 
 /**
- * Extract series names from CSV data (all columns except 'label')
+ * Get the label key (first column name) from CSV data
+ * @param {Object[]} data - Array of data objects
+ * @returns {string|undefined} - The first column name, or undefined if no data
+ */
+export function getLabelKey(data) {
+  if (!data || data.length === 0) return undefined;
+  return Object.keys(data[0])[0];
+}
+
+/**
+ * Get the value key (second column name) from CSV data
+ * @param {Object[]} data - Array of data objects
+ * @returns {string|undefined} - The second column name, or undefined if no data
+ */
+export function getValueKey(data) {
+  if (!data || data.length === 0) return undefined;
+  return Object.keys(data[0])[1];
+}
+
+/**
+ * Extract series names from CSV data (all columns except the first)
  * @param {Object[]} data - Array of data objects
  * @returns {string[]} - Array of series names
  */
 export function getSeriesNames(data) {
   if (!data || data.length === 0) return [];
-  return Object.keys(data[0]).filter(key => key !== 'label');
+  return Object.keys(data[0]).slice(1);
 }
 
 /**