eleventy-plugin-uncharted 0.1.2 → 0.2.1

package/README.md

@@ -48,6 +48,61 @@ If you set `injectCss: false`, you'll need to manually include the stylesheet in
 | `dot` | Categorical dot chart with Y-axis positioning | Yes |
 | `scatter` | XY scatter plot with continuous axes | Yes (X and Y) |
 
+## Value Formatting
+
+Format displayed numbers with thousands separators, compact notation, or currency symbols.
+Raw values are preserved for calculations; only display output is affected.
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `thousands` | boolean | Add commas: `1000` → `1,000` |
+| `compact` | boolean | Use suffixes: `1000` → `1K`, `1000000` → `1M` |
+| `decimals` | number | Decimal places (default: 0, or 1 if compact) |
+| `currency.symbol` | string | Currency symbol: `$`, `€`, etc. |
+| `currency.position` | string | `prefix` (default) or `suffix` |
+
+### Examples
+
+**Thousands separators:**
+
+```yaml
+format:
+  thousands: true
+# 1234567 → 1,234,567
+```
+
+**Compact notation:**
+
+```yaml
+format:
+  compact: true
+# 1500 → 1.5K, 2000000 → 2M
+```
+
+**Currency:**
+
+```yaml
+format:
+  thousands: true
+  currency:
+    symbol: "$"
+# 1234 → $1,234
+```
+
+**Scatter charts** support separate X/Y formatting:
+
+```yaml
+format:
+  x:
+    thousands: true
+  y:
+    compact: true
+    currency:
+      symbol: "$"
+```
+
 ## Usage
 
 ### Page Frontmatter
@@ -119,13 +174,24 @@ Sales,16,2
 Core,8,0
 ```
 
-For scatter plots, use `label`, `x`, `y`, and optionally `series`:
+For scatter plots, columns are positional: point label, X value, Y value, and optionally series. Column names become axis labels by default:
 
 ```csv
-label,x,y,series
-Point A,10,45,alpha
-Point B,25,78,alpha
-Point C,15,32,beta
+country,population,gdp,region
+USA,330,21,Americas
+China,1400,14,Asia
+Germany,83,4,Europe
+```
+
+This displays "population" as the X-axis title and "gdp" as the Y-axis title. Override with explicit titles:
+
+```yaml
+charts:
+  my-scatter:
+    type: scatter
+    file: charts/data.csv
+    titleX: "Population (millions)"
+    titleY: "GDP (trillions)"
 ```
 
 ## Negative Values
@@ -159,15 +225,20 @@ The chart automatically calculates the range from the maximum positive stack to
 | `maxY` | number | Maximum Y value (scatter only) |
 | `minX` | number | Minimum X value (scatter only) |
 | `minY` | number | Minimum Y value (scatter only) |
+| `titleX` | string | X-axis title (scatter only, defaults to column name) |
+| `titleY` | string | Y-axis title (scatter only, defaults to column name) |
 | `legend` | array | Custom legend labels |
 | `center` | object | Donut center content (`value`, `label`) |
+| `showPercentages` | boolean | Show percentages instead of values in donut legend |
 | `animate` | boolean | Override global animation setting |
+| `format` | object | Number formatting options (see Value Formatting) |
+| `rotateLabels` | boolean | Rotate X-axis labels vertically (stacked-column, dot) |
 
 ## Styling
 
 ### CSS Custom Properties
 
-Override the default color palette:
+Override the default color palette and sizing:
 
 ```css
 :root {
@@ -180,6 +251,29 @@ Override the default color palette:
   --chart-color-7: #009688;
   --chart-color-8: #78909c;
   --chart-bg: rgba(128, 128, 128, 0.15);
+  --chart-height: 12rem;           /* Height of bar/column/dot/scatter charts */
+  --chart-column-width: 1rem;      /* Min width per column */
+  --chart-donut-size: 12rem;       /* Donut chart diameter */
+  --chart-donut-thickness: 2.5rem; /* Donut ring thickness */
+}
+```
+
+### Per-Chart Styling
+
+Each chart gets a class based on its ID for targeted styling:
+
+```yaml
+charts:
+  sales-growth:
+    type: stacked-column
+    file: charts/sales.csv
+```
+
+```css
+/* Target this specific chart */
+.chart-sales-growth {
+  --chart-height: 16rem;
+  --chart-color-1: #ff6b6b;
 }
 ```
 

package/css/uncharted.css

@@ -14,7 +14,11 @@
   --chart-color-5: #009688;  /* Teal */
   --chart-color-6: #9c27b0;  /* Purple */
   --chart-color-7: #e91e63;  /* Pink */
-  --chart-color-8: #78909c;  /* Gray */
+  --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 */
 
   /* Backgrounds - neutral with opacity for light/dark adaptability */
   --chart-bg: rgba(128, 128, 128, 0.15);
@@ -22,10 +26,11 @@
   /* Spacing and sizing */
   --chart-gap: 0.5rem;
   --chart-bar-height: 1.5rem;
-  --chart-column-width: 2.5rem;
+  --chart-column-width: 1rem;
   --chart-donut-size: 12rem;
   --chart-donut-thickness: 2.5rem;
   --chart-dot-size: 0.75rem;
+  --chart-height: 12rem;
 }
 
 /* ==========================================================================
@@ -40,6 +45,10 @@
 .chart-color-6 { --color: var(--chart-color-6); background-color: var(--chart-color-6); }
 .chart-color-7 { --color: var(--chart-color-7); background-color: var(--chart-color-7); }
 .chart-color-8 { --color: var(--chart-color-8); background-color: var(--chart-color-8); }
+.chart-color-9 { --color: var(--chart-color-9); background-color: var(--chart-color-9); }
+.chart-color-10 { --color: var(--chart-color-10); background-color: var(--chart-color-10); }
+.chart-color-11 { --color: var(--chart-color-11); background-color: var(--chart-color-11); }
+.chart-color-12 { --color: var(--chart-color-12); background-color: var(--chart-color-12); }
 
 /* ==========================================================================
    Base Chart Styles
@@ -71,7 +80,8 @@
 .chart-legend {
   display: flex;
   flex-wrap: wrap;
-  gap: 1rem;
+  column-gap: 1rem;
+  row-gap: 0.375rem;
   list-style: none;
   padding: 0;
   margin: 0 0 1rem 0;
@@ -115,13 +125,14 @@
 }
 
 .chart-y-axis {
+  position: relative;
   display: flex;
   flex-direction: column;
   justify-content: space-between;
   align-items: flex-end;
   min-width: 2rem;
   box-sizing: border-box;
-  height: 12rem;
+  height: var(--chart-height);
   padding-top: 0.5rem;
   padding-bottom: 0;
 }
@@ -137,12 +148,24 @@
   transform: translateY(-50%);
 }
 
-.chart-y-axis .axis-label:last-child {
+.chart-y-axis .axis-label:nth-child(3) {
   transform: translateY(50%);
 }
 
+.chart-y-axis .axis-title {
+  position: absolute;
+  left: -0.5rem;
+  top: 50%;
+  transform: rotate(-90deg) translateX(-50%);
+  transform-origin: left center;
+  font-size: 0.7rem;
+  opacity: 0.6;
+  white-space: nowrap;
+}
+
 .chart-x-axis {
   display: flex;
+  flex-wrap: wrap;
   justify-content: space-between;
   padding: 0.25rem 0;
   margin-top: 0.25rem;
@@ -159,25 +182,32 @@
   transform: translateX(-50%);
 }
 
-.chart-x-axis .axis-label:last-child {
+.chart-x-axis .axis-label:nth-child(3) {
   transform: translateX(50%);
 }
 
+.chart-x-axis .axis-title {
+  flex-basis: 100%;
+  text-align: center;
+  font-size: 0.7rem;
+  opacity: 0.6;
+  white-space: nowrap;
+  margin-top: 0.5rem;
+}
+
 /* ==========================================================================
    Stacked Bar Chart (Horizontal)
    ========================================================================== */
 
 .chart-stacked-bar .chart-bars {
-  display: flex;
-  flex-direction: column;
-  gap: var(--chart-gap);
+  display: grid;
+  grid-template-columns: auto 1fr auto;
+  gap: var(--chart-gap) 0.75rem;
+  align-items: center;
 }
 
 .chart-stacked-bar .bar-row {
-  display: grid;
-  grid-template-columns: minmax(6rem, auto) 1fr auto;
-  align-items: center;
-  gap: 0.75rem;
+  display: contents;  /* Children participate in parent grid */
 }
 
 .chart-stacked-bar .bar-label {
@@ -218,14 +248,31 @@
   align-items: stretch;
 }
 
-.chart-stacked-column .chart-columns {
-  display: flex;
-  gap: var(--chart-gap);
-  align-items: stretch;
-  height: 12rem;
+.chart-stacked-column .chart-scroll {
   flex: 1;
+  overflow-x: auto;
+  overflow-y: visible;
+  position: relative;
+}
+
+.chart-stacked-column .chart-scroll::before {
+  content: '';
+  position: sticky;
+  left: 0;
+  display: block;
+  height: var(--chart-height);
+  margin-bottom: calc(-1 * var(--chart-height));
   background: var(--chart-bg);
   border-radius: 3px;
+  pointer-events: none;
+}
+
+.chart-stacked-column .chart-columns {
+  position: relative;
+  display: flex;
+  gap: 0.25rem;
+  align-items: stretch;
+  height: var(--chart-height);
   padding: 0.5rem 0.5rem 0 0.5rem;
   box-sizing: border-box;
 }
@@ -249,37 +296,69 @@
 
 .chart-stacked-column .column-labels {
   display: flex;
-  gap: var(--chart-gap);
+  gap: 0.25rem;
   padding: 0.25rem 0.5rem 0;
-  margin-left: 2.5rem;
 }
 
 .chart-stacked-column .column-label {
   flex: 1;
   min-width: var(--chart-column-width);
   max-width: calc(var(--chart-column-width) * 2);
-  font-size: 0.75rem;
+  font-size: 0.7rem;
+  opacity: 0.6;
   text-align: center;
   white-space: nowrap;
   overflow: hidden;
   text-overflow: ellipsis;
 }
 
+/* Rotated column labels (opt-in via rotateLabels config) */
+.chart-stacked-column.rotate-labels .column-labels {
+  padding-top: 0.5rem;
+  align-items: flex-start;
+}
+
+.chart-stacked-column.rotate-labels .column-label {
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+  display: flex;
+  align-items: center;
+  overflow: visible;
+  text-overflow: clip;
+}
+
 /* ==========================================================================
    Donut Chart
    ========================================================================== */
 
 .chart-donut {
   display: flex;
-  flex-direction: column;
+  flex-direction: row;
+  flex-wrap: wrap;
   align-items: flex-start;
+  gap: 1rem;
+  --donut-1: var(--chart-color-1);
+  --donut-2: var(--chart-color-2);
+  --donut-3: var(--chart-color-3);
+  --donut-4: var(--chart-color-4);
+  --donut-5: var(--chart-color-5);
+  --donut-6: var(--chart-color-6);
+  --donut-7: var(--chart-color-7);
+  --donut-8: var(--chart-color-8);
+  --donut-9: var(--chart-color-9);
+  --donut-10: var(--chart-color-10);
+  --donut-11: var(--chart-color-11);
+  --donut-12: var(--chart-color-12);
+}
+
+.chart-donut > .chart-title {
+  flex-basis: 100%;
 }
 
 .chart-donut .donut-container {
   position: relative;
   display: flex;
   justify-content: center;
-  margin-bottom: 1rem;
 }
 
 .chart-donut .donut-ring {
@@ -335,6 +414,20 @@
   min-width: 10rem;
 }
 
+/* Donut legend uses same variables as gradient for consistent overrides */
+.chart-donut .chart-color-1 { --color: var(--donut-1, var(--chart-color-1)); }
+.chart-donut .chart-color-2 { --color: var(--donut-2, var(--chart-color-2)); }
+.chart-donut .chart-color-3 { --color: var(--donut-3, var(--chart-color-3)); }
+.chart-donut .chart-color-4 { --color: var(--donut-4, var(--chart-color-4)); }
+.chart-donut .chart-color-5 { --color: var(--donut-5, var(--chart-color-5)); }
+.chart-donut .chart-color-6 { --color: var(--donut-6, var(--chart-color-6)); }
+.chart-donut .chart-color-7 { --color: var(--donut-7, var(--chart-color-7)); }
+.chart-donut .chart-color-8 { --color: var(--donut-8, var(--chart-color-8)); }
+.chart-donut .chart-color-9 { --color: var(--donut-9, var(--chart-color-9)); }
+.chart-donut .chart-color-10 { --color: var(--donut-10, var(--chart-color-10)); }
+.chart-donut .chart-color-11 { --color: var(--donut-11, var(--chart-color-11)); }
+.chart-donut .chart-color-12 { --color: var(--donut-12, var(--chart-color-12)); }
+
 .chart-donut .chart-legend-item .legend-label {
   flex: 1;
 }
@@ -347,13 +440,29 @@
   align-items: stretch;
 }
 
-.chart-dot .dot-chart {
-  height: 12rem;
+.chart-dot .chart-scroll {
+  flex: 1;
+  overflow-x: auto;
+  overflow-y: visible;
+  position: relative;
+}
+
+.chart-dot .chart-scroll::before {
+  content: '';
+  position: sticky;
+  left: 0;
+  display: block;
+  height: var(--chart-height);
+  margin-bottom: calc(-1 * var(--chart-height));
   background: var(--chart-bg);
   border-radius: 3px;
-  flex: 1;
-  box-sizing: border-box;
+  pointer-events: none;
+}
+
+.chart-dot .dot-chart {
   position: relative;
+  height: var(--chart-height);
+  box-sizing: border-box;
 }
 
 /* Inner field sized to content area - dots position relative to this */
@@ -396,7 +505,6 @@
   gap: 6px;
   padding: 0 0.5rem;
   margin-top: 0.5rem;
-  margin-left: calc(2rem + 0.5rem); /* y-axis width + gap */
 }
 
 .chart-dot .dot-label {
@@ -406,6 +514,21 @@
   min-width: 1.5rem;
 }
 
+/* Rotated dot labels (opt-in via rotateLabels config) */
+.chart-dot.rotate-labels .dot-labels {
+  padding-top: 0.5rem;
+  align-items: flex-start;
+}
+
+.chart-dot.rotate-labels .dot-label {
+  writing-mode: vertical-rl;
+  transform: rotate(180deg);
+  display: flex;
+  align-items: center;
+  overflow: visible;
+  text-overflow: clip;
+}
+
 /* ==========================================================================
    Scatter Chart (Continuous X and Y axes)
    ========================================================================== */
@@ -422,7 +545,7 @@
 
 .chart-scatter .dot-area {
   position: relative;
-  height: 12rem;
+  height: var(--chart-height);
   background: var(--chart-bg);
   border-radius: 3px;
   box-sizing: border-box;
@@ -461,41 +584,13 @@
    ========================================================================== */
 
 /* Row/column index for staggered delays */
-.bar-row:nth-child(1) { --row-index: 0; }
-.bar-row:nth-child(2) { --row-index: 1; }
-.bar-row:nth-child(3) { --row-index: 2; }
-.bar-row:nth-child(4) { --row-index: 3; }
-.bar-row:nth-child(5) { --row-index: 4; }
-.bar-row:nth-child(6) { --row-index: 5; }
-.bar-row:nth-child(7) { --row-index: 6; }
-.bar-row:nth-child(8) { --row-index: 7; }
-
-.column-track:nth-child(1) { --col-index: 0; }
-.column-track:nth-child(2) { --col-index: 1; }
-.column-track:nth-child(3) { --col-index: 2; }
-.column-track:nth-child(4) { --col-index: 3; }
-.column-track:nth-child(5) { --col-index: 4; }
-.column-track:nth-child(6) { --col-index: 5; }
-.column-track:nth-child(7) { --col-index: 6; }
-.column-track:nth-child(8) { --col-index: 7; }
-.column-track:nth-child(9) { --col-index: 8; }
-.column-track:nth-child(10) { --col-index: 9; }
-.column-track:nth-child(11) { --col-index: 10; }
-.column-track:nth-child(12) { --col-index: 11; }
-
-.dot-col:nth-child(1) { --col-index: 0; }
-.dot-col:nth-child(2) { --col-index: 1; }
-.dot-col:nth-child(3) { --col-index: 2; }
-.dot-col:nth-child(4) { --col-index: 3; }
-.dot-col:nth-child(5) { --col-index: 4; }
-.dot-col:nth-child(6) { --col-index: 5; }
-.dot-col:nth-child(7) { --col-index: 6; }
-.dot-col:nth-child(8) { --col-index: 7; }
+/* Row, column, and dot indices set via inline styles in renderers */
 
 /* Bar chart: clip-path on fills wrapper, reveals left-to-right */
 .chart-animate .bar-fills {
+  clip-path: inset(0 100% 0 0);
   animation: bar-reveal 1s cubic-bezier(0.25, 1, 0.5, 1) forwards;
-  animation-delay: calc(var(--row-index, 0) * 0.08s);
+  animation-delay: calc(var(--row-index, 0) * var(--delay-step, 0.08s));
 }
 
 @keyframes bar-reveal {
@@ -505,8 +600,9 @@
 
 /* Column chart: clip-path on track, reveals bottom-to-top */
 .chart-animate .column-track {
+  clip-path: inset(100% 0 0 0);
   animation: column-reveal 0.6s cubic-bezier(0.25, 1, 0.5, 1) forwards;
-  animation-delay: calc(var(--col-index, 0) * 0.05s);
+  animation-delay: calc(var(--col-index, 0) * var(--delay-step, 0.05s));
 }
 
 @keyframes column-reveal {
@@ -518,7 +614,7 @@
 .chart-animate.has-negative-y .column-track {
   --zero-from-top: calc(100% - var(--zero-position, 0%));
   animation: column-expand-from-zero 0.6s cubic-bezier(0.25, 1, 0.5, 1) forwards;
-  animation-delay: calc(var(--col-index, 0) * 0.05s);
+  animation-delay: calc(var(--col-index, 0) * var(--delay-step, 0.05s));
   clip-path: polygon(
     0% var(--zero-from-top),
     100% var(--zero-from-top),
@@ -544,7 +640,7 @@
 /* Dot chart: dots rise from bottom with staggered delays */
 .chart-animate.chart-dot .dot {
   animation: dot-rise 0.8s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
-  animation-delay: calc(var(--col-index, 0) * 0.08s);
+  animation-delay: calc(var(--col-index, 0) * var(--delay-step, 0.08s));
   opacity: 0;
 }
 
@@ -564,7 +660,7 @@
 /* Dot chart with negatives: dots move from zero axis */
 .chart-animate.chart-dot.has-negative-y .dot {
   animation: dot-from-zero 0.8s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
-  animation-delay: calc(var(--col-index, 0) * 0.08s);
+  animation-delay: calc(var(--col-index, 0) * var(--delay-step, 0.08s));
   opacity: 0;
 }
 

package/eleventy.config.js

@@ -101,6 +101,7 @@ export default function(eleventyConfig, options = {}) {
     const animate = chartConfig.animate ?? globalAnimate;
     return renderer({
       ...chartConfig,
+      id: chartId,
       data,
       animate
     });

package/package.json

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

package/src/csv.js

@@ -1,6 +1,51 @@
 import fs from 'fs';
 import path from 'path';
 
+/**
+ * Parse a CSV line handling quoted fields
+ * @param {string} line - CSV line
+ * @returns {string[]} - Array of field values
+ */
+function parseCSVLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const char = line[i];
+    const nextChar = line[i + 1];
+
+    if (inQuotes) {
+      if (char === '"' && nextChar === '"') {
+        // Escaped quote
+        current += '"';
+        i++;
+      } else if (char === '"') {
+        // End of quoted field
+        inQuotes = false;
+      } else {
+        current += char;
+      }
+    } else {
+      if (char === '"') {
+        // Start of quoted field
+        inQuotes = true;
+      } else if (char === ',') {
+        // Field separator
+        fields.push(current.trim());
+        current = '';
+      } else {
+        current += char;
+      }
+    }
+  }
+
+  // Push last field
+  fields.push(current.trim());
+
+  return fields;
+}
+
 /**
  * Parse CSV content into array of objects
  * @param {string} content - Raw CSV content
@@ -14,11 +59,11 @@ export function parseCSV(content) {
 
   if (lines.length < 2) return [];
 
-  const headers = lines[0].split(',').map(h => h.trim());
+  const headers = parseCSVLine(lines[0]);
   const rows = [];
 
   for (let i = 1; i < lines.length; i++) {
-    const values = lines[i].split(',').map(v => v.trim());
+    const values = parseCSVLine(lines[i]);
     const row = {};
 
     headers.forEach((header, index) => {

package/src/formatters.js

@@ -0,0 +1,40 @@
+/**
+ * Format a number according to configuration
+ * @param {number} value - Raw numeric value
+ * @param {Object} config - { thousands, compact, decimals, currency: { symbol, position } }
+ * @returns {string} - Formatted string
+ */
+export function formatNumber(value, config = {}) {
+  if (value == null || isNaN(value)) return '';
+
+  const { thousands, compact, decimals, currency } = config;
+  let num = value;
+  let suffix = '';
+
+  // Compact notation (K/M/B/T)
+  if (compact) {
+    const abs = Math.abs(num);
+    if (abs >= 1e12) { num /= 1e12; suffix = 'T'; }
+    else if (abs >= 1e9) { num /= 1e9; suffix = 'B'; }
+    else if (abs >= 1e6) { num /= 1e6; suffix = 'M'; }
+    else if (abs >= 1e3) { num /= 1e3; suffix = 'K'; }
+  }
+
+  // Decimal places (default: 0, or 1 if compact with suffix)
+  const places = decimals ?? (suffix ? 1 : 0);
+
+  // Format with or without thousands separators
+  let formatted = thousands && !suffix
+    ? num.toLocaleString('en-US', { minimumFractionDigits: places, maximumFractionDigits: places })
+    : num.toFixed(places);
+
+  formatted += suffix;
+
+  // Currency symbol
+  if (currency?.symbol) {
+    const pos = currency.position ?? 'prefix';
+    formatted = pos === 'prefix' ? currency.symbol + formatted : formatted + currency.symbol;
+  }
+
+  return formatted;
+}

package/src/index.js

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

package/src/renderers/donut.js

@@ -1,4 +1,5 @@
 import { slugify, escapeHtml, getLabelKey, getValueKey, getSeriesNames } from '../utils.js';
+import { formatNumber } from '../formatters.js';
 
 /**
  * Render a donut/pie chart using conic-gradient
@@ -11,10 +12,11 @@ import { slugify, escapeHtml, getLabelKey, getValueKey, getSeriesNames } from '.
  * @param {string|number} [config.center.value] - Value to show in center (use "total" for auto-calculated)
  * @param {string} [config.center.label] - Label below the value
  * @param {boolean} [config.animate] - Enable animations
+ * @param {boolean} [config.showPercentages] - Show percentages instead of values in legend
  * @returns {string} - HTML string
  */
 export function renderDonut(config) {
-  const { title, subtitle, data, legend, center, animate } = config;
+  const { title, subtitle, data, legend, center, animate, format, id, showPercentages } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Donut chart: no data provided -->`;
@@ -57,13 +59,15 @@ export function renderDonut(config) {
     const startAngle = currentAngle;
     const endAngle = currentAngle + percentage;
 
-    gradientStops.push(`var(--chart-color-${i + 1}) ${startAngle.toFixed(2)}% ${endAngle.toFixed(2)}%`);
+    // Use segment-specific variable (defaults set in CSS)
+    gradientStops.push(`var(--donut-${i + 1}) ${startAngle.toFixed(2)}% ${endAngle.toFixed(2)}%`);
     currentAngle = endAngle;
   });
 
   const gradient = `conic-gradient(${gradientStops.join(', ')})`;
 
-  let html = `<figure class="chart chart-donut${animateClass}">`;
+  const idClass = id ? ` chart-${id}` : '';
+  let html = `<figure class="chart chart-donut${animateClass}${idClass}">`;
 
   if (title) {
     html += `<figcaption class="chart-title">${escapeHtml(title)}`;
@@ -82,7 +86,8 @@ export function renderDonut(config) {
   if (center) {
     const centerValue = center.value === 'total' ? total : center.value;
     if (centerValue !== undefined) {
-      html += `<span class="donut-value">${escapeHtml(String(centerValue))}</span>`;
+      const displayValue = typeof centerValue === 'number' ? (formatNumber(centerValue, format) || centerValue) : centerValue;
+      html += `<span class="donut-value">${escapeHtml(String(displayValue))}</span>`;
     }
     if (center.label) {
       html += `<span class="donut-label">${escapeHtml(center.label)}</span>`;
@@ -92,17 +97,22 @@ export function renderDonut(config) {
   html += `</div>`;
   html += `</div>`;
 
-  // Legend with percentages
+  // Legend with values (or percentages if showPercentages is true)
   const legendLabels = legend ?? segments.map(s => s.label);
   html += `<ul class="chart-legend">`;
   segments.forEach((segment, i) => {
     const label = legendLabels[i] ?? segment.label;
-    const percentage = ((segment.value / total) * 100).toFixed(1);
+    let displayValue;
+    if (showPercentages) {
+      displayValue = ((segment.value / total) * 100).toFixed(1) + '%';
+    } else {
+      displayValue = formatNumber(segment.value, format) || segment.value;
+    }
     const colorClass = `chart-color-${i + 1}`;
     const seriesClass = `chart-series-${slugify(segment.label)}`;
     html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">`;
     html += `<span class="legend-label">${escapeHtml(label)}</span>`;
-    html += `<span class="legend-value">${percentage}%</span>`;
+    html += `<span class="legend-value">${escapeHtml(String(displayValue))}</span>`;
     html += `</li>`;
   });
   html += `</ul>`;

package/src/renderers/dot.js

@@ -1,4 +1,5 @@
 import { slugify, escapeHtml, getLabelKey, getSeriesNames } from '../utils.js';
+import { formatNumber } from '../formatters.js';
 
 /**
  * Render a categorical dot chart (columns with dots at different Y positions)
@@ -14,7 +15,7 @@ import { slugify, escapeHtml, getLabelKey, getSeriesNames } from '../utils.js';
  * @returns {string} - HTML string
  */
 export function renderDot(config) {
-  const { title, subtitle, data, max, min, legend, animate } = config;
+  const { title, subtitle, data, max, min, legend, animate, format, id, rotateLabels } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Dot chart: no data provided -->`;
@@ -44,7 +45,9 @@ export function renderDot(config) {
   const zeroPct = hasNegativeY ? ((0 - minValue) / range) * 100 : 0;
 
   const negativeClass = hasNegativeY ? ' has-negative-y' : '';
-  let html = `<figure class="chart chart-dot${animateClass}${negativeClass}">`;
+  const idClass = id ? ` chart-${id}` : '';
+  const rotateClass = rotateLabels ? ' rotate-labels' : '';
+  let html = `<figure class="chart chart-dot${animateClass}${negativeClass}${idClass}${rotateClass}">`;
 
   if (title) {
     html += `<figcaption class="chart-title">${escapeHtml(title)}`;
@@ -71,21 +74,29 @@ export function renderDot(config) {
   // Y-axis
   const yAxisStyle = hasNegativeY ? ` style="--zero-position: ${zeroPct.toFixed(2)}%"` : '';
   html += `<div class="chart-y-axis"${yAxisStyle}>`;
-  html += `<span class="axis-label">${maxValue}</span>`;
+  html += `<span class="axis-label">${formatNumber(maxValue, format) || maxValue}</span>`;
   const midLabelY = hasNegativeY ? 0 : Math.round((maxValue + minValue) / 2);
-  html += `<span class="axis-label">${midLabelY}</span>`;
-  html += `<span class="axis-label">${minValue}</span>`;
+  html += `<span class="axis-label">${formatNumber(midLabelY, format) || midLabelY}</span>`;
+  html += `<span class="axis-label">${formatNumber(minValue, format) || minValue}</span>`;
   html += `</div>`;
 
-  const zeroStyle = hasNegativeY ? ` style="--zero-position: ${zeroPct.toFixed(2)}%"` : '';
-  html += `<div class="dot-chart"${zeroStyle}>`;
+  // Scroll wrapper for chart + labels
+  html += `<div class="chart-scroll">`;
+
+  // Calculate delay step to cap total stagger at 1s
+  const maxStagger = 1; // seconds
+  const defaultDelay = 0.08; // seconds
+  const delayStep = data.length > 1 ? Math.min(defaultDelay, maxStagger / (data.length - 1)) : 0;
+  const styleVars = [`--delay-step: ${delayStep.toFixed(3)}s`];
+  if (hasNegativeY) styleVars.push(`--zero-position: ${zeroPct.toFixed(2)}%`);
+  html += `<div class="dot-chart" style="${styleVars.join('; ')}">`;
   html += `<div class="dot-field">`;
 
   // Each row becomes a column with dots for each series
-  data.forEach(row => {
+  data.forEach((row, colIndex) => {
     const label = row[labelKey] ?? '';
 
-    html += `<div class="dot-col">`;
+    html += `<div class="dot-col" style="--col-index: ${colIndex}">`;
 
     seriesKeys.forEach((key, i) => {
       const val = row[key];
@@ -97,14 +108,13 @@ export function renderDot(config) {
 
       html += `<div class="dot ${colorClass} ${seriesClass}" `;
       html += `style="--value: ${yPct.toFixed(2)}%" `;
-      html += `title="${escapeHtml(label)}: ${value} ${escapeHtml(tooltipLabel)}"`;
+      html += `title="${escapeHtml(tooltipLabel)}: ${formatNumber(value, format) || value}"`;
       html += `></div>`;
     });
 
     html += `</div>`;
   });
 
-  html += `</div>`;
   html += `</div>`;
   html += `</div>`;
 
@@ -116,6 +126,8 @@ export function renderDot(config) {
   });
   html += `</div>`;
 
+  html += `</div>`; // close chart-scroll
+  html += `</div>`; // close chart-body
   html += `</figure>`;
 
   return html;

package/src/renderers/scatter.js

@@ -1,21 +1,28 @@
 import { slugify, escapeHtml } from '../utils.js';
+import { formatNumber } from '../formatters.js';
 
 /**
  * Render a scatter plot (continuous X and Y axes)
  * @param {Object} config - Chart configuration
  * @param {string} config.title - Chart title
  * @param {string} [config.subtitle] - Chart subtitle
- * @param {Object[]} config.data - Chart data (with label, x, y, and optionally series)
+ * @param {Object[]} config.data - Chart data (positional: label, x, y, 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
+ * @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 } = config;
+  const { title, subtitle, data, maxX, maxY, minX, minY, legend, animate, format, titleX, titleY, id } = config;
+
+  // Handle nested X/Y format for scatter charts
+  const fmtX = format?.x || format || {};
+  const fmtY = format?.y || format || {};
 
   if (!data || data.length === 0) {
     return `<!-- Scatter chart: no data provided -->`;
@@ -23,25 +30,24 @@ export function renderScatter(config) {
 
   const animateClass = animate ? ' chart-animate' : '';
 
-  // Normalize data format
-  let dots = [];
-  if (data[0].x !== undefined && data[0].y !== undefined) {
-    // Direct {label, x, y, series?} format
-    dots = data.map(item => ({
-      label: item.label ?? '',
-      x: typeof item.x === 'number' ? item.x : parseFloat(item.x) || 0,
-      y: typeof item.y === 'number' ? item.y : parseFloat(item.y) || 0,
-      series: item.series ?? 'default'
-    }));
-  } else if (data[0].value !== undefined) {
-    // Simple {label, value} format - use index as x, value as y
-    dots = data.map((item, i) => ({
-      label: item.label ?? '',
-      x: i,
-      y: typeof item.value === 'number' ? item.value : parseFloat(item.value) || 0,
-      series: 'default'
-    }));
-  }
+  // Get column keys positionally
+  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
+
+  // Axis titles: explicit config overrides column names
+  const xAxisTitle = titleX ?? xKey;
+  const yAxisTitle = titleY ?? yKey;
+
+  // Map data to dots using positional columns
+  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,
+    series: seriesKey ? (item[seriesKey] ?? 'default') : 'default'
+  }));
 
   // Calculate bounds
   const xValues = dots.map(d => d.x);
@@ -71,7 +77,8 @@ export function renderScatter(config) {
   const seriesIndex = new Map(seriesList.map((s, i) => [s, i]));
 
   const negativeClasses = (hasNegativeX ? ' has-negative-x' : '') + (hasNegativeY ? ' has-negative-y' : '');
-  let html = `<figure class="chart chart-scatter${animateClass}${negativeClasses}">`;
+  const idClass = id ? ` chart-${id}` : '';
+  let html = `<figure class="chart chart-scatter${animateClass}${negativeClasses}${idClass}">`;
 
   if (title) {
     html += `<figcaption class="chart-title">${escapeHtml(title)}`;
@@ -99,10 +106,11 @@ export function renderScatter(config) {
   // Y-axis
   const yAxisStyle = hasNegativeY ? ` style="--zero-position-y: ${zeroPctY.toFixed(2)}%"` : '';
   html += `<div class="chart-y-axis"${yAxisStyle}>`;
-  html += `<span class="axis-label">${calcMaxY}</span>`;
+  html += `<span class="axis-label">${formatNumber(calcMaxY, fmtY) || calcMaxY}</span>`;
   const midLabelY = hasNegativeY ? 0 : Math.round((calcMaxY + calcMinY) / 2);
-  html += `<span class="axis-label">${midLabelY}</span>`;
-  html += `<span class="axis-label">${calcMinY}</span>`;
+  html += `<span class="axis-label">${formatNumber(midLabelY, fmtY) || midLabelY}</span>`;
+  html += `<span class="axis-label">${formatNumber(calcMinY, fmtY) || calcMinY}</span>`;
+  html += `<span class="axis-title">${escapeHtml(yAxisTitle)}</span>`;
   html += `</div>`;
 
   // Container gets zero position variables for axis line CSS
@@ -120,7 +128,9 @@ export function renderScatter(config) {
     const colorIndex = seriesIndex.get(dot.series) + 1;
     const colorClass = `chart-color-${colorIndex}`;
     const seriesClass = `chart-series-${slugify(dot.series)}`;
-    const tooltipText = dot.label ? `${dot.label}: (${dot.x}, ${dot.y})` : `(${dot.x}, ${dot.y})`;
+    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})`;
 
     html += `<div class="dot ${colorClass} ${seriesClass}" `;
     html += `style="--dot-index: ${i}; --x: ${xPct.toFixed(2)}%; --value: ${yPct.toFixed(2)}%" `;
@@ -134,10 +144,11 @@ export function renderScatter(config) {
   // X-axis
   const xAxisStyle = hasNegativeX ? ` style="--zero-position-x: ${zeroPctX.toFixed(2)}%"` : '';
   html += `<div class="chart-x-axis"${xAxisStyle}>`;
-  html += `<span class="axis-label">${calcMinX}</span>`;
+  html += `<span class="axis-label">${formatNumber(calcMinX, fmtX) || calcMinX}</span>`;
   const midLabelX = hasNegativeX ? 0 : Math.round((calcMaxX + calcMinX) / 2);
-  html += `<span class="axis-label">${midLabelX}</span>`;
-  html += `<span class="axis-label">${calcMaxX}</span>`;
+  html += `<span class="axis-label">${formatNumber(midLabelX, fmtX) || midLabelX}</span>`;
+  html += `<span class="axis-label">${formatNumber(calcMaxX, fmtX) || calcMaxX}</span>`;
+  html += `<span class="axis-title">${escapeHtml(xAxisTitle)}</span>`;
   html += `</div>`;
 
   html += `</div>`;

package/src/renderers/stacked-bar.js

@@ -1,4 +1,5 @@
 import { slugify, calculatePercentages, getLabelKey, getSeriesNames, escapeHtml } from '../utils.js';
+import { formatNumber } from '../formatters.js';
 
 /**
  * Render a stacked bar chart (horizontal)
@@ -12,7 +13,7 @@ import { slugify, calculatePercentages, getLabelKey, getSeriesNames, escapeHtml
  * @returns {string} - HTML string
  */
 export function renderStackedBar(config) {
-  const { title, subtitle, data, max, legend, animate } = config;
+  const { title, subtitle, data, max, legend, animate, format, id } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked bar chart: no data provided -->`;
@@ -25,7 +26,16 @@ export function renderStackedBar(config) {
   const legendLabels = legend ?? seriesKeys;
   const animateClass = animate ? ' chart-animate' : '';
 
-  let html = `<figure class="chart chart-stacked-bar${animateClass}">`;
+  // Calculate max total across all rows if not provided
+  const calculatedMax = max ?? Math.max(...data.map(row => {
+    return seriesKeys.reduce((sum, key) => {
+      const val = row[key];
+      return sum + (typeof val === 'number' ? val : parseFloat(val) || 0);
+    }, 0);
+  }));
+
+  const idClass = id ? ` chart-${id}` : '';
+  let html = `<figure class="chart chart-stacked-bar${animateClass}${idClass}">`;
 
   if (title) {
     html += `<figcaption class="chart-title">${escapeHtml(title)}`;
@@ -47,22 +57,26 @@ export function renderStackedBar(config) {
     html += `</ul>`;
   }
 
-  html += `<div class="chart-bars">`;
+  // Calculate delay step to cap total stagger at 1s
+  const maxStagger = 1; // seconds
+  const defaultDelay = 0.08; // seconds
+  const delayStep = data.length > 1 ? Math.min(defaultDelay, maxStagger / (data.length - 1)) : 0;
+  html += `<div class="chart-bars" style="--delay-step: ${delayStep.toFixed(3)}s">`;
 
-  data.forEach(row => {
+  data.forEach((row, rowIndex) => {
     const label = row[labelKey] ?? '';
     const values = seriesKeys.map(key => {
       const val = row[key];
       return typeof val === 'number' ? val : parseFloat(val) || 0;
     });
     const total = values.reduce((sum, v) => sum + v, 0);
-    const percentages = calculatePercentages(values, max);
+    const percentages = calculatePercentages(values, calculatedMax);
     const seriesLabels = legendLabels ?? seriesKeys;
 
-    html += `<div class="bar-row">`;
+    html += `<div class="bar-row" style="--row-index: ${rowIndex}">`;
     html += `<span class="bar-label">${escapeHtml(label)}</span>`;
     html += `<div class="bar-track">`;
-    html += `<div class="bar-fills" title="${escapeHtml(label)}: ${total}">`;
+    html += `<div class="bar-fills" title="${escapeHtml(label)}: ${formatNumber(total, format) || total}">`;
 
     seriesKeys.forEach((key, i) => {
       const pct = percentages[i];
@@ -71,7 +85,7 @@ export function renderStackedBar(config) {
         const colorClass = `chart-color-${i + 1}`;
         const seriesClass = `chart-series-${slugify(key)}`;
         const seriesLabel = seriesLabels[i] ?? key;
-        html += `<div class="bar-fill ${colorClass} ${seriesClass}" style="--value: ${pct.toFixed(2)}%" title="${escapeHtml(seriesLabel)}: ${value}"></div>`;
+        html += `<div class="bar-fill ${colorClass} ${seriesClass}" style="--value: ${pct.toFixed(2)}%" title="${escapeHtml(seriesLabel)}: ${formatNumber(value, format) || value}"></div>`;
       }
     });
 
@@ -79,7 +93,7 @@ export function renderStackedBar(config) {
     html += `</div>`;
 
     // Show total value
-    html += `<span class="bar-value">${total}</span>`;
+    html += `<span class="bar-value">${formatNumber(total, format) || total}</span>`;
     html += `</div>`;
   });
 

package/src/renderers/stacked-column.js

@@ -1,4 +1,5 @@
 import { slugify, getLabelKey, getSeriesNames, escapeHtml } from '../utils.js';
+import { formatNumber } from '../formatters.js';
 
 /**
  * Render a stacked column chart (vertical)
@@ -13,7 +14,7 @@ import { slugify, getLabelKey, getSeriesNames, escapeHtml } from '../utils.js';
  * @returns {string} - HTML string
  */
 export function renderStackedColumn(config) {
-  const { title, subtitle, data, max, min, legend, animate } = config;
+  const { title, subtitle, data, max, min, legend, animate, format, id, rotateLabels } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked column chart: no data provided -->`;
@@ -54,7 +55,9 @@ export function renderStackedColumn(config) {
   const zeroPct = hasNegativeY ? ((0 - minValue) / range) * 100 : 0;
 
   const negativeClass = hasNegativeY ? ' has-negative-y' : '';
-  let html = `<figure class="chart chart-stacked-column${animateClass}${negativeClass}">`;
+  const idClass = id ? ` chart-${id}` : '';
+  const rotateClass = rotateLabels ? ' rotate-labels' : '';
+  let html = `<figure class="chart chart-stacked-column${animateClass}${negativeClass}${idClass}${rotateClass}">`;
 
   if (title) {
     html += `<figcaption class="chart-title">${escapeHtml(title)}`;
@@ -81,18 +84,27 @@ export function renderStackedColumn(config) {
   // Y-axis with --zero-position for label positioning
   const yAxisStyle = hasNegativeY ? ` style="--zero-position: ${zeroPct.toFixed(2)}%"` : '';
   html += `<div class="chart-y-axis"${yAxisStyle}>`;
-  html += `<span class="axis-label">${maxValue}</span>`;
+  html += `<span class="axis-label">${formatNumber(maxValue, format) || maxValue}</span>`;
   const midLabelY = hasNegativeY ? 0 : Math.round(maxValue / 2);
-  html += `<span class="axis-label">${midLabelY}</span>`;
-  html += `<span class="axis-label">${hasNegativeY ? minValue : 0}</span>`;
+  html += `<span class="axis-label">${formatNumber(midLabelY, format) || midLabelY}</span>`;
+  const minLabelY = hasNegativeY ? minValue : 0;
+  html += `<span class="axis-label">${formatNumber(minLabelY, format) || minLabelY}</span>`;
   html += `</div>`;
 
-  const columnsStyle = hasNegativeY ? ` style="--zero-position: ${zeroPct.toFixed(2)}%"` : '';
-  html += `<div class="chart-columns"${columnsStyle}>`;
+  // Scroll wrapper for columns + labels
+  html += `<div class="chart-scroll">`;
 
-  data.forEach(row => {
+  // Calculate delay step to cap total stagger at 1s
+  const maxStagger = 1; // seconds
+  const defaultDelay = 0.05; // seconds
+  const delayStep = data.length > 1 ? Math.min(defaultDelay, maxStagger / (data.length - 1)) : 0;
+  const styleVars = [`--delay-step: ${delayStep.toFixed(3)}s`];
+  if (hasNegativeY) styleVars.push(`--zero-position: ${zeroPct.toFixed(2)}%`);
+  html += `<div class="chart-columns" style="${styleVars.join('; ')}">`;
+
+  data.forEach((row, colIndex) => {
     const label = row[labelKey] ?? '';
-    html += `<div class="column-track" title="${escapeHtml(label)}">`;
+    html += `<div class="column-track" style="--col-index: ${colIndex}" title="${escapeHtml(label)}">`;
 
     if (hasNegativeY) {
       // Build segments first to identify stack ends
@@ -115,7 +127,7 @@ export function renderStackedColumn(config) {
             classes: `column-segment ${colorClass} ${seriesClass}`,
             bottom: positiveBottom,
             height: segmentHeight,
-            title: `${escapeHtml(seriesLabel)}: ${value}`,
+            title: `${escapeHtml(seriesLabel)}: ${formatNumber(value, format) || value}`,
             isNegative: false
           });
           lastPositiveIdx = segments.length - 1;
@@ -126,7 +138,7 @@ export function renderStackedColumn(config) {
             classes: `column-segment ${colorClass} ${seriesClass} is-negative`,
             bottom: negativeTop,
             height: segmentHeight,
-            title: `${escapeHtml(seriesLabel)}: ${value}`,
+            title: `${escapeHtml(seriesLabel)}: ${formatNumber(value, format) || value}`,
             isNegative: true
           });
           lastNegativeIdx = segments.length - 1;
@@ -161,14 +173,13 @@ export function renderStackedColumn(config) {
         const endClass = idx === lastIdx ? ' is-stack-end' : '';
         html += `<div class="column-segment ${colorClass} ${seriesClass}${endClass}" `;
         html += `style="--value: ${seg.pct.toFixed(2)}%" `;
-        html += `title="${escapeHtml(seriesLabel)}: ${seg.value}"></div>`;
+        html += `title="${escapeHtml(seriesLabel)}: ${formatNumber(seg.value, format) || seg.value}"></div>`;
       });
     }
 
     html += `</div>`;
   });
 
-  html += `</div>`;
   html += `</div>`;
 
   // X-axis labels
@@ -178,6 +189,9 @@ export function renderStackedColumn(config) {
     html += `<span class="column-label">${escapeHtml(label)}</span>`;
   });
   html += `</div>`;
+
+  html += `</div>`; // close chart-scroll
+  html += `</div>`; // close chart-body
   html += `</figure>`;
 
   return html;