eleventy-plugin-uncharted 0.6.2 → 0.7.0

package/README.md

@@ -39,4 +39,4 @@ charts:
 
 Chart types: `donut`, `stacked-bar`, `stacked-column`, `dot`, `scatter`
 
-See the [documentation](https://uncharted.docs.seanlunsford.com/) for configuration options, styling, animations, and more.
+See the [documentation](https://uncharted.seanlunsford.com/) for configuration options, styling, animations, and more.

package/eleventy.config.js

@@ -2,6 +2,8 @@ import path from 'path';
 import { fileURLToPath } from 'url';
 import { renderers } from './src/renderers/index.js';
 import { loadCSV } from './src/csv.js';
+import { normalizeConfig } from './src/config.js';
+import { resolveColumns } from './src/columns.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -122,13 +124,20 @@ export default function(eleventyConfig, options = {}) {
       downloadDataUrl = normalizedDataPath + chartConfig.file;
     }
 
+    // Normalize configuration (handles deprecated keys, axis config)
+    const normalizedConfig = normalizeConfig(chartConfig, chartId);
+
+    // Resolve column mappings
+    const columns = resolveColumns(normalizedConfig, data, chartType);
+
     return renderer({
-      ...chartConfig,
+      ...normalizedConfig,
       id: chartId,
       data,
       animate,
       downloadData,
-      downloadDataUrl
+      downloadDataUrl,
+      _columns: columns
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-uncharted",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "An Eleventy plugin that renders CSS-based charts from CSV data using shortcodes",
   "main": "eleventy.config.js",
   "type": "module",
@@ -32,9 +32,9 @@
     "url": "https://github.com/slunsford/uncharted/issues"
   },
   "peerDependencies": {
-    "@11ty/eleventy": ">=2.0.0-0"
+    "@11ty/eleventy": ">=2.0.0 || >=4.0.0-0"
   },
   "devDependencies": {
-    "@11ty/eleventy": "^3.0.0"
+    "@11ty/eleventy": "^3.0.0 || ^4.0.0-0"
   }
 }

package/src/columns.js

@@ -0,0 +1,300 @@
+/**
+ * Column resolution for Uncharted
+ * Handles explicit column mapping and implicit detection
+ * Supports both new unified schema (x.column, y.columns) and deprecated columns key
+ */
+
+import { parseAxisConfig } from './config.js';
+
+/**
+ * Resolve column mappings for chart data
+ *
+ * New unified schema (takes precedence):
+ * - x: { column: "month" } or x: "month"
+ * - y: { columns: ["a", "b"] } or y: { columns: { a: "Label A" } }
+ *
+ * Deprecated schema (fallback):
+ * - columns: { x: "month", y: ["a", "b"] }
+ *
+ * @param {Object} config - Chart configuration with optional columns mapping
+ * @param {Object[]} data - Chart data array
+ * @param {string} chartType - Chart type for context-aware defaults
+ * @returns {Object} - Resolved column keys with labels
+ */
+export function resolveColumns(config, data, chartType) {
+  if (!data || data.length === 0) {
+    return {
+      label: undefined,
+      x: undefined,
+      y: undefined,
+      xLabels: {},
+      yLabels: {},
+      series: undefined,
+      seriesTitle: undefined,
+      size: undefined,
+      sizeTitle: undefined,
+      source: undefined,
+      target: undefined,
+      value: undefined,
+      valueFormat: undefined,
+      values: []
+    };
+  }
+
+  const keys = Object.keys(data[0]);
+  const deprecatedColumns = config.columns || {};
+
+  // Helper to find column by name (case-insensitive)
+  const findKey = name => keys.find(k => k.toLowerCase() === name.toLowerCase()) || null;
+
+  // Helper to validate that a column exists
+  const validateColumn = (configKey, configValue) => {
+    if (configValue === undefined) return undefined;
+
+    // Handle array of column names
+    if (Array.isArray(configValue)) {
+      const valid = configValue.filter(v => keys.includes(v));
+      if (valid.length !== configValue.length) {
+        const missing = configValue.filter(v => !keys.includes(v));
+        console.warn(`[uncharted] ${configKey}: columns not found in data: ${missing.join(', ')}`);
+      }
+      return valid.length > 0 ? valid : undefined;
+    }
+
+    // Handle single column name
+    if (!keys.includes(configValue)) {
+      console.warn(`[uncharted] ${configKey}: column "${configValue}" not found in data`);
+      return undefined;
+    }
+    return configValue;
+  };
+
+  // Parse axis configs using the new helper
+  const xConfig = parseAxisConfig(config.x);
+  const yConfig = parseAxisConfig(config.y);
+  const labelConfig = parseAxisConfig(config.label);
+  const seriesConfig = parseAxisConfig(config.series);
+  const sizeConfig = parseAxisConfig(config.size);
+  const sourceConfig = parseAxisConfig(config.source);
+  const targetConfig = parseAxisConfig(config.target);
+  const valueConfig = parseAxisConfig(config.value);
+
+  // Resolve each column role
+  const resolved = {
+    label: undefined,
+    x: undefined,
+    y: undefined,
+    xLabels: {},
+    yLabels: {},
+    series: undefined,
+    seriesTitle: undefined,
+    size: undefined,
+    sizeTitle: undefined,
+    source: undefined,
+    target: undefined,
+    value: undefined,
+    valueFormat: undefined,
+    values: []
+  };
+
+  // Chart-type specific resolution
+  if (chartType === 'scatter') {
+    // Scatter charts use x, y, label, series, size columns
+    // New schema: x.column, y.column, label.column, series.column, size.column
+    // Deprecated: columns.x, columns.y, columns.label, columns.series, columns.size
+
+    // X column
+    if (xConfig?.columns?.length) {
+      resolved.x = validateColumn('x.column', xConfig.columns[0]);
+    } else if (deprecatedColumns.x) {
+      resolved.x = validateColumn('columns.x', deprecatedColumns.x);
+    }
+
+    // Y column
+    if (yConfig?.columns?.length) {
+      resolved.y = validateColumn('y.column', yConfig.columns[0]);
+    } else if (deprecatedColumns.y) {
+      resolved.y = validateColumn('columns.y', deprecatedColumns.y);
+    }
+
+    // Label column (point identifier)
+    if (labelConfig?.columns?.length) {
+      resolved.label = validateColumn('label.column', labelConfig.columns[0]);
+    } else if (deprecatedColumns.label) {
+      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
+    } else {
+      resolved.label = keys[0];
+    }
+
+    // Series column (for coloring)
+    if (seriesConfig?.columns?.length) {
+      resolved.series = validateColumn('series.column', seriesConfig.columns[0]);
+      resolved.seriesTitle = seriesConfig.title;
+    } else if (deprecatedColumns.series) {
+      resolved.series = validateColumn('columns.series', deprecatedColumns.series);
+      resolved.seriesTitle = config.legendTitle; // deprecated
+    }
+
+    // Size column
+    if (sizeConfig?.columns?.length) {
+      resolved.size = validateColumn('size.column', sizeConfig.columns[0]);
+      resolved.sizeTitle = sizeConfig.title;
+    } else if (deprecatedColumns.size) {
+      resolved.size = validateColumn('columns.size', deprecatedColumns.size);
+      resolved.sizeTitle = config.sizeTitle; // deprecated
+    }
+
+    // Implicit detection for scatter if not explicitly specified
+    if (!resolved.x || !resolved.y) {
+      const namedX = findKey('x');
+      const namedY = findKey('y');
+
+      if (namedX && namedY) {
+        resolved.x = resolved.x ?? namedX;
+        resolved.y = resolved.y ?? namedY;
+      } else {
+        resolved.x = resolved.x ?? keys[1];
+        resolved.y = resolved.y ?? keys[2];
+      }
+    }
+
+    // Implicit series/size detection
+    if (!resolved.series) {
+      resolved.series = findKey('series');
+    }
+    if (!resolved.size) {
+      resolved.size = findKey('size');
+    }
+
+  } else if (chartType === 'sankey') {
+    // Sankey charts use source, target, value columns
+    // New schema: source.column, target.column, value.column
+    // Deprecated: columns.source, columns.target, columns.value
+
+    if (sourceConfig?.columns?.length) {
+      resolved.source = validateColumn('source.column', sourceConfig.columns[0]);
+    } else if (deprecatedColumns.source) {
+      resolved.source = validateColumn('columns.source', deprecatedColumns.source);
+    } else {
+      resolved.source = keys[0];
+    }
+
+    if (targetConfig?.columns?.length) {
+      resolved.target = validateColumn('target.column', targetConfig.columns[0]);
+    } else if (deprecatedColumns.target) {
+      resolved.target = validateColumn('columns.target', deprecatedColumns.target);
+    } else {
+      resolved.target = keys[1];
+    }
+
+    if (valueConfig?.columns?.length) {
+      resolved.value = validateColumn('value.column', valueConfig.columns[0]);
+      resolved.valueFormat = valueConfig.format;
+    } else if (deprecatedColumns.value) {
+      resolved.value = validateColumn('columns.value', deprecatedColumns.value);
+    } else {
+      resolved.value = keys[2];
+    }
+
+  } else if (chartType === 'donut') {
+    // Donut charts use label, value columns
+    // New schema: label.column, value.column
+    // Deprecated: columns.label, columns.value (or implicit first/second columns)
+
+    if (labelConfig?.columns?.length) {
+      resolved.label = validateColumn('label.column', labelConfig.columns[0]);
+      resolved.yLabels = labelConfig.labels || {};
+    } else if (deprecatedColumns.label) {
+      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
+    } else {
+      resolved.label = keys[0];
+    }
+
+    if (valueConfig?.columns?.length) {
+      resolved.values = validateColumn('value.column', valueConfig.columns) || [];
+      if (!Array.isArray(resolved.values)) {
+        resolved.values = [resolved.values];
+      }
+      resolved.valueFormat = valueConfig.format;
+    } else if (deprecatedColumns.value) {
+      const val = validateColumn('columns.value', deprecatedColumns.value);
+      resolved.values = val ? [val] : [];
+    } else {
+      // Default: all columns except label
+      resolved.values = keys.filter(k => k !== resolved.label);
+    }
+
+  } else if (chartType === 'stacked-bar') {
+    // Stacked bar: y = categories (left side), x = value series (bars extend right)
+    // New schema: y.column (categories), x.columns (values with labels)
+    // Deprecated: columns.y (or label), columns.x (or y as values)
+
+    // Category column (on Y axis for stacked-bar)
+    if (yConfig?.columns?.length) {
+      resolved.label = validateColumn('y.column', yConfig.columns[0]);
+    } else if (deprecatedColumns.label) {
+      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
+    } else {
+      resolved.label = keys[0];
+    }
+
+    // Value columns (extend along X axis)
+    if (xConfig?.columns?.length) {
+      resolved.values = validateColumn('x.columns', xConfig.columns) || [];
+      resolved.xLabels = xConfig.labels || {};
+    } else if (deprecatedColumns.y) {
+      // Deprecated: columns.y was used for value columns in stacked-bar
+      const explicitY = validateColumn('columns.y', deprecatedColumns.y);
+      resolved.values = Array.isArray(explicitY) ? explicitY : (explicitY ? [explicitY] : []);
+    } else {
+      // Implicit: all columns except label are values
+      resolved.values = keys.filter(k => k !== resolved.label);
+    }
+
+  } else {
+    // Standard charts (dot, line, stacked-column): x = categories, y = multi-series values
+    // New schema: x.column (categories), y.columns (values with labels)
+    // Deprecated: columns.label (or implicit first), columns.y
+
+    // Label/category column (X axis)
+    if (xConfig?.columns?.length) {
+      resolved.label = validateColumn('x.column', xConfig.columns[0]);
+    } else if (deprecatedColumns.label) {
+      resolved.label = validateColumn('columns.label', deprecatedColumns.label);
+    } else {
+      resolved.label = keys[0];
+    }
+
+    // Value columns (Y axis)
+    if (yConfig?.columns?.length) {
+      resolved.values = validateColumn('y.columns', yConfig.columns) || [];
+      resolved.yLabels = yConfig.labels || {};
+    } else if (deprecatedColumns.y) {
+      const explicitY = validateColumn('columns.y', deprecatedColumns.y);
+      resolved.values = Array.isArray(explicitY) ? explicitY : (explicitY ? [explicitY] : []);
+    } else {
+      // Implicit: all columns except label are values
+      resolved.values = keys.filter(k => k !== resolved.label);
+    }
+  }
+
+  return resolved;
+}
+
+/**
+ * Get series names from resolved columns
+ * @param {Object} resolved - Resolved columns from resolveColumns()
+ * @returns {string[]} - Array of series/value column names
+ */
+export function getResolvedSeriesNames(resolved) {
+  return resolved.values || [];
+}
+
+/**
+ * Get the label key from resolved columns
+ * @param {Object} resolved - Resolved columns from resolveColumns()
+ * @returns {string|undefined} - Label column name
+ */
+export function getResolvedLabelKey(resolved) {
+  return resolved.label;
+}

package/src/config.js

@@ -0,0 +1,260 @@
+/**
+ * Configuration normalization layer for Uncharted
+ * Transforms various config formats into a standardized structure
+ */
+
+// Deprecated keys mapping for deprecation warnings
+const DEPRECATED_KEYS = {
+  maxX: 'x.max',
+  minX: 'x.min',
+  maxY: 'y.max',
+  minY: 'y.min',
+  titleX: 'x.title',
+  titleY: 'y.title',
+  legendTitle: 'series.title',
+  sizeTitle: 'size.title',
+  rotateLabels: 'x.rotateLabels'
+};
+
+// Track which deprecation warnings have been shown to avoid spam
+const warnedConfigs = new Set();
+
+/**
+ * Log a deprecation warning (once per config/key combination)
+ * @param {string} chartId - Chart identifier
+ * @param {string} oldKey - Deprecated key name
+ * @param {string} newKey - New key path
+ */
+function warnDeprecation(chartId, oldKey, newKey) {
+  const key = `${chartId}:${oldKey}`;
+  if (warnedConfigs.has(key)) return;
+  warnedConfigs.add(key);
+  console.warn(`[uncharted] Chart "${chartId}": "${oldKey}" is deprecated, use "${newKey}" instead`);
+}
+
+/**
+ * Normalize chart configuration to standardized structure
+ *
+ * Precedence for axis properties (highest to lowest):
+ * 1. x.max / y.max (new nested format)
+ * 2. maxX / maxY (deprecated suffixed format)
+ * 3. max (global fallback)
+ *
+ * Format precedence:
+ * 1. x.format / y.format (new nested format)
+ * 2. format.x / format.y (deprecated nested format)
+ * 3. format (global fallback)
+ *
+ * Column mapping precedence:
+ * 1. x.column / x.columns / y.column / y.columns (new unified format)
+ * 2. columns.x / columns.y (deprecated format)
+ *
+ * Legend precedence:
+ * 1. y.columns: { key: "Label" } or x.columns (for stacked-bar)
+ * 2. legend: ["Label1", "Label2"] (deprecated)
+ *
+ * @param {Object} config - Raw chart configuration
+ * @param {string} [chartId] - Chart ID for deprecation warnings
+ * @returns {Object} - Normalized configuration
+ */
+export function normalizeConfig(config, chartId = 'unknown') {
+  if (!config) return config;
+
+  const normalized = { ...config };
+
+  // Build x axis config
+  normalized.x = buildAxisConfig('x', config, chartId);
+
+  // Build y axis config
+  normalized.y = buildAxisConfig('y', config, chartId);
+
+  // Warn for deprecated columns key
+  if (config.columns) {
+    warnDeprecation(chartId, 'columns', 'x.column / y.columns');
+  }
+
+  // Warn for deprecated legend array (when used for labels, not boolean)
+  if (Array.isArray(config.legend)) {
+    warnDeprecation(chartId, 'legend (array)', 'y.columns: { key: "Label" }');
+  }
+
+  // Warn for deprecated scatter-specific keys
+  if (config.legendTitle !== undefined) {
+    warnDeprecation(chartId, 'legendTitle', 'series.title');
+  }
+  if (config.sizeTitle !== undefined) {
+    warnDeprecation(chartId, 'sizeTitle', 'size.title');
+  }
+
+  // Clean up deprecated top-level keys (keep them for backwards compat but don't pass to renderers)
+  // The renderers will use normalized.x and normalized.y instead
+
+  return normalized;
+}
+
+/**
+ * Build normalized axis configuration
+ * @param {'x' | 'y'} axis - Axis name
+ * @param {Object} config - Raw config
+ * @param {string} chartId - Chart ID for warnings
+ * @returns {Object} - Normalized axis config
+ */
+function buildAxisConfig(axis, config, chartId) {
+  const axisUpper = axis.toUpperCase();
+  const existingAxisConfig = config[axis] || {};
+
+  // Start with existing axis config if present
+  const axisConfig = { ...existingAxisConfig };
+
+  // max: x.max > maxX > max
+  if (axisConfig.max === undefined) {
+    const deprecatedKey = `max${axisUpper}`;
+    if (config[deprecatedKey] !== undefined) {
+      warnDeprecation(chartId, deprecatedKey, `${axis}.max`);
+      axisConfig.max = config[deprecatedKey];
+    } else if (config.max !== undefined) {
+      axisConfig.max = config.max;
+    }
+  }
+
+  // min: x.min > minX > min
+  if (axisConfig.min === undefined) {
+    const deprecatedKey = `min${axisUpper}`;
+    if (config[deprecatedKey] !== undefined) {
+      warnDeprecation(chartId, deprecatedKey, `${axis}.min`);
+      axisConfig.min = config[deprecatedKey];
+    } else if (config.min !== undefined) {
+      axisConfig.min = config.min;
+    }
+  }
+
+  // title: x.title > titleX
+  if (axisConfig.title === undefined) {
+    const deprecatedKey = `title${axisUpper}`;
+    if (config[deprecatedKey] !== undefined) {
+      warnDeprecation(chartId, deprecatedKey, `${axis}.title`);
+      axisConfig.title = config[deprecatedKey];
+    }
+  }
+
+  // format: x.format > format.x > format
+  if (axisConfig.format === undefined) {
+    const globalFormat = config.format || {};
+    if (globalFormat[axis] !== undefined) {
+      // format.x or format.y (deprecated nested format)
+      warnDeprecation(chartId, `format.${axis}`, `${axis}.format`);
+      axisConfig.format = globalFormat[axis];
+    } else if (typeof globalFormat === 'object' && !globalFormat.x && !globalFormat.y) {
+      // Global format object (no x/y nesting) - use as fallback
+      axisConfig.format = globalFormat;
+    }
+  }
+
+  return axisConfig;
+}
+
+/**
+ * Get effective max value for an axis
+ * @param {Object} normalizedConfig - Normalized config
+ * @param {'x' | 'y'} axis - Axis name
+ * @returns {number|undefined} - Max value or undefined
+ */
+export function getAxisMax(normalizedConfig, axis) {
+  return normalizedConfig[axis]?.max;
+}
+
+/**
+ * Get effective min value for an axis
+ * @param {Object} normalizedConfig - Normalized config
+ * @param {'x' | 'y'} axis - Axis name
+ * @returns {number|undefined} - Min value or undefined
+ */
+export function getAxisMin(normalizedConfig, axis) {
+  return normalizedConfig[axis]?.min;
+}
+
+/**
+ * Get effective title for an axis
+ * @param {Object} normalizedConfig - Normalized config
+ * @param {'x' | 'y'} axis - Axis name
+ * @param {string} [fallback] - Fallback title (e.g., column name)
+ * @returns {string} - Axis title
+ */
+export function getAxisTitle(normalizedConfig, axis, fallback = '') {
+  return normalizedConfig[axis]?.title ?? fallback;
+}
+
+/**
+ * Get effective format config for an axis
+ * @param {Object} normalizedConfig - Normalized config
+ * @param {'x' | 'y'} axis - Axis name
+ * @returns {Object} - Format config
+ */
+export function getAxisFormat(normalizedConfig, axis) {
+  return normalizedConfig[axis]?.format || normalizedConfig.format || {};
+}
+
+/**
+ * Parse axis configuration with column definitions
+ * Handles shorthand and full formats:
+ * - String: "column" -> { columns: ["column"], labels: {} }
+ * - Array: ["a", "b"] -> { columns: ["a", "b"], labels: {} }
+ * - Object with column: { column: "x" } -> { columns: ["x"], labels: {}, ...rest }
+ * - Object with columns array: { columns: ["a", "b"] } -> { columns: ["a", "b"], labels: {}, ...rest }
+ * - Object with columns object: { columns: { a: "Label A" } } -> { columns: ["a"], labels: { a: "Label A" }, ...rest }
+ *
+ * @param {string|string[]|Object} axisConfig - Axis config in any supported format
+ * @returns {{ columns: string[], labels: object, column?: string, title?: string, ... }|null}
+ */
+export function parseAxisConfig(axisConfig) {
+  if (axisConfig === undefined || axisConfig === null) return null;
+
+  // Handle shorthand: y: "revenue" or y: ["a", "b"]
+  if (typeof axisConfig === 'string') {
+    return { column: axisConfig, columns: [axisConfig], labels: {} };
+  }
+  if (Array.isArray(axisConfig)) {
+    return { columns: axisConfig, labels: {} };
+  }
+
+  // Handle object format
+  const { column, columns, ...rest } = axisConfig;
+
+  // Parse columns definition
+  let parsedColumns = [];
+  let labels = {};
+
+  if (column) {
+    parsedColumns = [column];
+  } else if (columns) {
+    if (typeof columns === 'string') {
+      parsedColumns = [columns];
+    } else if (Array.isArray(columns)) {
+      parsedColumns = columns;
+    } else if (typeof columns === 'object') {
+      parsedColumns = Object.keys(columns);
+      labels = columns;  // { columnName: "Display Label" }
+    }
+  }
+
+  return { columns: parsedColumns, labels, column, ...rest };
+}
+
+/**
+ * Get rotateLabels setting from axis config or deprecated top-level
+ * @param {Object} config - Normalized config
+ * @param {string} chartId - Chart ID for deprecation warnings
+ * @returns {boolean} - Whether to rotate labels
+ */
+export function getRotateLabels(config, chartId) {
+  // New schema: x.rotateLabels
+  if (config.x?.rotateLabels !== undefined) {
+    return config.x.rotateLabels;
+  }
+  // Deprecated: top-level rotateLabels
+  if (config.rotateLabels !== undefined) {
+    warnDeprecation(chartId, 'rotateLabels', 'x.rotateLabels');
+    return config.rotateLabels;
+  }
+  return false;
+}

package/src/renderers/donut.js

@@ -3,7 +3,7 @@ import { formatNumber } from '../formatters.js';
 
 /**
  * Render a donut/pie chart using conic-gradient
- * @param {Object} config - Chart configuration
+ * @param {Object} config - Chart configuration (normalized)
  * @param {string} config.title - Chart title
  * @param {string} [config.subtitle] - Chart subtitle
  * @param {Object[]} config.data - Chart data (with label and value properties)
@@ -13,10 +13,11 @@ import { formatNumber } from '../formatters.js';
  * @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
+ * @param {Object} [config._columns] - Resolved column mappings
  * @returns {string} - HTML string
  */
 export function renderDonut(config) {
-  const { title, subtitle, data, legend, center, animate, format, id, showPercentages, downloadData, downloadDataUrl } = config;
+  const { title, subtitle, data, legend, center, animate, format, id, showPercentages, downloadData, downloadDataUrl, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Donut chart: no data provided -->`;
@@ -24,10 +25,10 @@ export function renderDonut(config) {
 
   const animateClass = animate ? ' chart-animate' : '';
 
-  // Get column keys positionally
-  const labelKey = getLabelKey(data);
-  const valueKey = getValueKey(data);
-  const seriesKeys = getSeriesNames(data);
+  // Get column keys (use resolved columns if available)
+  const labelKey = _columns?.label ?? getLabelKey(data);
+  const valueKey = _columns?.values?.[0] ?? getValueKey(data);
+  const seriesKeys = _columns?.values?.length > 0 ? _columns.values : getSeriesNames(data);
 
   // Extract values - support both label/value format and series format
   let segments = [];
@@ -102,25 +103,39 @@ export function renderDonut(config) {
 
   html += `</div>`; // Close donut-body
 
+  // Build label lookup from: 1) yLabels (new schema), 2) legend array (deprecated), 3) segment labels
+  const labelMap = _columns?.yLabels || {};
+  const getSegmentLabel = (segment, index) => {
+    if (labelMap[segment.label]) return labelMap[segment.label];
+    if (Array.isArray(legend)) return legend[index] ?? segment.label;
+    return segment.label;
+  };
+
+  // Get value format from resolved columns or global format
+  const valueFormat = _columns?.valueFormat ?? format;
+
   // 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;
-    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">${escapeHtml(String(displayValue))}</span>`;
-    html += `</li>`;
-  });
-  html += `</ul>`;
+  // Show if legend !== false (donut always shows legend by default)
+  const showLegend = config.legend !== false;
+  if (showLegend) {
+    html += `<ul class="chart-legend">`;
+    segments.forEach((segment, i) => {
+      const label = getSegmentLabel(segment, i);
+      let displayValue;
+      if (showPercentages) {
+        displayValue = ((segment.value / total) * 100).toFixed(1) + '%';
+      } else {
+        displayValue = formatNumber(segment.value, valueFormat) || 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">${escapeHtml(String(displayValue))}</span>`;
+      html += `</li>`;
+    });
+    html += `</ul>`;
+  }
 
   html += renderDownloadLink(downloadDataUrl, downloadData);
   html += `</figure>`;

package/src/renderers/dot.js

@@ -1,31 +1,44 @@
 import { slugify, escapeHtml, getLabelKey, getSeriesNames, renderDownloadLink } from '../utils.js';
 import { formatNumber } from '../formatters.js';
+import { getAxisMax, getAxisMin, getAxisFormat, getRotateLabels } from '../config.js';
 
 /**
  * Render a categorical dot chart (columns with dots at different Y positions)
  * Like atlas-wrapped's adoption chart - discrete X axis, continuous Y axis
- * @param {Object} config - Chart configuration
+ * @param {Object} config - Chart configuration (normalized)
  * @param {string} config.title - Chart title
  * @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 {Object} [config.y] - Y-axis configuration { max, min, format }
  * @param {string[]} [config.legend] - Legend labels (defaults to series names)
  * @param {boolean} [config.animate] - Enable animations
+ * @param {Object} [config._columns] - Resolved column mappings
  * @returns {string} - HTML string
  */
 export function renderDot(config) {
-  const { title, subtitle, data, max, min, legend, legendTitle, animate, format, id, rotateLabels, downloadData, downloadDataUrl, connectDots, dots: showDots = true, chartType = 'dot' } = config;
+  const { title, subtitle, data, max, min, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, connectDots, dots: showDots = true, chartType = 'dot', _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Dot chart: no data provided -->`;
   }
 
-  // Get label key (first column) and series keys (remaining columns)
-  const labelKey = getLabelKey(data);
-  const seriesKeys = getSeriesNames(data);
-  const legendLabels = legend ?? seriesKeys;
+  // Get label key and series keys (use resolved columns if available)
+  const labelKey = _columns?.label ?? getLabelKey(data);
+  const seriesKeys = _columns?.values?.length > 0 ? _columns.values : getSeriesNames(data);
+
+  // Build legend labels from: 1) yLabels (new), 2) legend array (deprecated), 3) column names
+  const yLabels = _columns?.yLabels || {};
+  const getSeriesLabel = (key, index) => {
+    if (yLabels[key]) return yLabels[key];
+    if (Array.isArray(legend)) return legend[index] ?? key;
+    return key;
+  };
+
   const animateClass = animate ? ' chart-animate' : '';
+  const rotateLabels = getRotateLabels(config, config.id);
+
+  // Get Y-axis format
+  const yFormat = getAxisFormat(config, 'y');
 
   // Calculate min and max values for Y scaling
   const allValues = data.flatMap(row =>
@@ -36,8 +49,10 @@ export function renderDot(config) {
   );
   const dataMax = Math.max(...allValues);
   const dataMin = Math.min(...allValues);
-  const maxValue = max ?? dataMax;
-  const minValue = min ?? (dataMin < 0 ? dataMin : 0);
+
+  // Use normalized axis config, fall back to legacy top-level max/min
+  const maxValue = getAxisMax(config, 'y') ?? max ?? dataMax;
+  const minValue = getAxisMin(config, 'y') ?? min ?? (dataMin < 0 ? dataMin : 0);
   const range = maxValue - minValue;
   const hasNegativeY = minValue < 0;
 
@@ -63,10 +78,10 @@ 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">${formatNumber(maxValue, format) || maxValue}</span>`;
+  html += `<span class="axis-label">${formatNumber(maxValue, yFormat) || maxValue}</span>`;
   const midLabelY = hasNegativeY ? 0 : Math.round((maxValue + minValue) / 2);
-  html += `<span class="axis-label">${formatNumber(midLabelY, format) || midLabelY}</span>`;
-  html += `<span class="axis-label">${formatNumber(minValue, format) || minValue}</span>`;
+  html += `<span class="axis-label">${formatNumber(midLabelY, yFormat) || midLabelY}</span>`;
+  html += `<span class="axis-label">${formatNumber(minValue, yFormat) || minValue}</span>`;
   html += `</div>`;
 
   // Scroll wrapper for chart + labels
@@ -117,11 +132,11 @@ export function renderDot(config) {
         const yPct = range > 0 ? ((value - minValue) / range) * 100 : 0;
         const colorClass = `chart-color-${i + 1}`;
         const seriesClass = `chart-series-${slugify(key)}`;
-        const tooltipLabel = legendLabels[i] ?? key;
+        const tooltipLabel = getSeriesLabel(key, i);
 
         html += `<div class="dot ${colorClass} ${seriesClass}" `;
         html += `style="--value: ${yPct.toFixed(2)}%" `;
-        html += `title="${escapeHtml(tooltipLabel)}: ${formatNumber(value, format) || value}"`;
+        html += `title="${escapeHtml(tooltipLabel)}: ${formatNumber(value, yFormat) || value}"`;
         html += `></div>`;
       });
 
@@ -143,14 +158,15 @@ export function renderDot(config) {
   html += `</div>`; // close chart-scroll
   html += `</div>`; // close chart-body
 
-  // Legend
-  if (seriesKeys.length > 0 || legendTitle) {
+  // Legend (show if legend !== false and we have series keys or legendTitle)
+  const showLegend = config.legend !== false && (seriesKeys.length > 0 || legendTitle);
+  if (showLegend) {
     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 label = getSeriesLabel(key, i);
       const colorClass = `chart-color-${i + 1}`;
       const seriesClass = `chart-series-${slugify(key)}`;
       html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;

package/src/renderers/sankey.js

@@ -3,7 +3,7 @@ import { formatNumber } from '../formatters.js';
 
 /**
  * Render a Sankey diagram
- * @param {Object} config - Chart configuration
+ * @param {Object} config - Chart configuration (normalized)
  * @param {string} config.title - Chart title
  * @param {string} [config.subtitle] - Chart subtitle
  * @param {Object[]} config.data - Chart data (source, target, value columns)
@@ -13,10 +13,11 @@ import { formatNumber } from '../formatters.js';
  * @param {number} [config.nodePadding] - Vertical gap between nodes in pixels (default: 10)
  * @param {boolean} [config.endLabelsOutside] - Position last level labels outside/right (default: false)
  * @param {boolean} [config.proportional] - Force proportional node heights for data integrity (default: false)
+ * @param {Object} [config._columns] - Resolved column mappings
  * @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 } = config;
+  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, nodeWidth = 20, nodePadding = 10, endLabelsOutside = false, proportional = false, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Sankey chart: no data provided -->`;
@@ -24,11 +25,14 @@ export function renderSankey(config) {
 
   const animateClass = animate ? ' chart-animate' : '';
 
-  // Get column keys positionally
+  // Get column keys (use resolved columns if available)
   const keys = Object.keys(data[0]);
-  const sourceKey = keys[0];  // First column: source
-  const targetKey = keys[1];  // Second column: target
-  const valueKey = keys[2];   // Third column: value
+  const sourceKey = _columns?.source ?? keys[0];  // First column: source
+  const targetKey = _columns?.target ?? keys[1];  // Second column: target
+  const valueKey = _columns?.value ?? keys[2];    // Third column: value
+
+  // Get value format from resolved columns (new schema) or global format
+  const valueFormat = _columns?.valueFormat ?? format;
 
   // Parse edges and build node set
   const edges = [];
@@ -445,7 +449,7 @@ export function renderSankey(config) {
   flows.forEach((flow, i) => {
     const sourceColor = nodeColors.get(flow.source);
     const targetColor = nodeColors.get(flow.target);
-    const tooltipText = `${flow.source} → ${flow.target}: ${formatNumber(flow.value, format) || flow.value}`;
+    const tooltipText = `${flow.source} → ${flow.target}: ${formatNumber(flow.value, valueFormat) || flow.value}`;
 
     // Flow spans from after source node column to target node column
     const colStart = flow.fromLevel * 2 + 2;
@@ -493,7 +497,7 @@ export function renderSankey(config) {
       const colorClass = `chart-color-${colorIndex}`;
       const seriesClass = `chart-series-${slugify(node)}`;
       const throughput = nodeThroughput.get(node);
-      const tooltipText = `${node}: ${formatNumber(throughput, format) || throughput}`;
+      const tooltipText = `${node}: ${formatNumber(throughput, valueFormat) || throughput}`;
 
       html += `<div class="chart-sankey-node ${colorClass} ${seriesClass}" `;
       html += `style="--top: ${pos.top.toFixed(2)}%; --height: ${pos.height.toFixed(2)}%" `;
@@ -514,8 +518,8 @@ export function renderSankey(config) {
       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>`;
+      if (valueFormat) {
+        html += ` <span class="legend-value">${formatNumber(throughput, valueFormat) || throughput}</span>`;
       }
       html += `</li>`;
     });

package/src/renderers/scatter.js

@@ -1,30 +1,28 @@
 import { slugify, escapeHtml, renderDownloadLink } from '../utils.js';
 import { formatNumber } from '../formatters.js';
+import { getAxisMax, getAxisMin, getAxisTitle, getAxisFormat } from '../config.js';
 
 /**
  * Render a scatter plot (continuous X and Y axes)
- * @param {Object} config - Chart configuration
+ * @param {Object} config - Chart configuration (normalized)
  * @param {string} config.title - Chart title
  * @param {string} [config.subtitle] - Chart subtitle
  * @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 {Object} [config.x] - X-axis configuration { max, min, title, format }
+ * @param {Object} [config.y] - Y-axis configuration { max, min, title, format }
  * @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)
+ * @param {Object} [config._columns] - Resolved column mappings
  * @returns {string} - HTML string
  */
 export function renderScatter(config) {
-  const { title, subtitle, data, maxX, maxY, minX, minY, legend, legendTitle, sizeTitle, animate, format, titleX, titleY, id, downloadData, downloadDataUrl, proportional } = config;
+  const { title, subtitle, data, legend, animate, format, id, downloadData, downloadDataUrl, proportional, _columns } = config;
 
-  // Handle nested X/Y format for scatter charts
-  const fmtX = format?.x || format || {};
-  const fmtY = format?.y || format || {};
+  // Get axis-specific format configs (normalized config provides x.format/y.format)
+  const fmtX = getAxisFormat(config, 'x');
+  const fmtY = getAxisFormat(config, 'y');
 
   if (!data || data.length === 0) {
     return `<!-- Scatter chart: no data provided -->`;
@@ -32,26 +30,37 @@ export function renderScatter(config) {
 
   const animateClass = animate ? ' chart-animate' : '';
 
-  // Named column detection (case-insensitive), with positional fallback for x/y
+  // Use resolved columns if available, otherwise fall back to implicit detection
   const keys = Object.keys(data[0]);
   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];
+  let labelKey, xKey, yKey, sizeKey, seriesKey;
+
+  if (_columns) {
+    // Use pre-resolved columns from config normalization
+    labelKey = _columns.label;
+    xKey = _columns.x;
+    yKey = _columns.y;
+    sizeKey = _columns.size;
+    seriesKey = _columns.series;
+  } else {
+    // Fallback: implicit detection (for backwards compatibility)
+    labelKey = keys[0];
+    const namedX = findKey('x');
+    const namedY = findKey('y');
+    xKey = (namedX && namedY) ? namedX : keys[1];
+    yKey = (namedX && namedY) ? namedY : keys[2];
+    sizeKey = findKey('size');
+    seriesKey = findKey('series');
+  }
 
-  // Size and series: named only (no positional fallback)
-  const sizeKey = findKey('size');
-  const seriesKey = findKey('series');
+  // Get legend/size titles from resolved columns (new schema) or deprecated top-level
+  const legendTitle = _columns?.seriesTitle ?? config.legendTitle;
+  const sizeTitle = _columns?.sizeTitle ?? config.sizeTitle;
 
-  // Axis titles: explicit config overrides column names
-  const xAxisTitle = titleX ?? xKey;
-  const yAxisTitle = titleY ?? yKey;
+  // Axis titles: use normalized config, fall back to column names
+  const xAxisTitle = getAxisTitle(config, 'x', xKey);
+  const yAxisTitle = getAxisTitle(config, 'y', yKey);
 
   // Map data to dots
   const dots = data.map(item => ({
@@ -78,7 +87,7 @@ export function renderScatter(config) {
     });
   }
 
-  // Calculate bounds
+  // Calculate bounds using normalized axis config
   const xValues = dots.map(d => d.x);
   const yValues = dots.map(d => d.y);
   const dataMaxX = Math.max(...xValues);
@@ -86,10 +95,10 @@ export function renderScatter(config) {
   const dataMaxY = Math.max(...yValues);
   const dataMinY = Math.min(...yValues);
 
-  const calcMaxX = maxX ?? dataMaxX;
-  const calcMaxY = maxY ?? dataMaxY;
-  const calcMinX = minX ?? (dataMinX < 0 ? dataMinX : 0);
-  const calcMinY = minY ?? (dataMinY < 0 ? dataMinY : 0);
+  const calcMaxX = getAxisMax(config, 'x') ?? dataMaxX;
+  const calcMaxY = getAxisMax(config, 'y') ?? dataMaxY;
+  const calcMinX = getAxisMin(config, 'x') ?? (dataMinX < 0 ? dataMinX : 0);
+  const calcMinY = getAxisMin(config, 'y') ?? (dataMinY < 0 ? dataMinY : 0);
   const rangeX = calcMaxX - calcMinX;
   const rangeY = calcMaxY - calcMinY;
   const dataAspectRatio = rangeY > 0 ? rangeX / rangeY : 1;

package/src/renderers/stacked-bar.js

@@ -1,33 +1,47 @@
 import { slugify, calculatePercentages, getLabelKey, getSeriesNames, escapeHtml, renderDownloadLink } from '../utils.js';
 import { formatNumber } from '../formatters.js';
+import { getAxisMax, getAxisFormat } from '../config.js';
 
 /**
  * Render a stacked bar chart (horizontal)
- * @param {Object} config - Chart configuration
+ * @param {Object} config - Chart configuration (normalized)
  * @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 {Object} [config.x] - X-axis configuration { max, format } (bars extend along X)
  * @param {string[]} [config.legend] - Legend labels (defaults to series names)
  * @param {boolean} [config.animate] - Enable animations
+ * @param {Object} [config._columns] - Resolved column mappings
  * @returns {string} - HTML string
  */
 export function renderStackedBar(config) {
-  const { title, subtitle, data, max, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl } = config;
+  const { title, subtitle, data, max, legend, legendTitle, animate, format, id, downloadData, downloadDataUrl, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked bar chart: no data provided -->`;
   }
 
-  // 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;
+  // Get label key and series keys (use resolved columns if available)
+  const labelKey = _columns?.label ?? getLabelKey(data);
+  const seriesKeys = _columns?.values?.length > 0 ? _columns.values : getSeriesNames(data);
+
+  // Build legend labels from: 1) xLabels (new - stacked-bar uses x for values), 2) legend array (deprecated), 3) column names
+  const xLabels = _columns?.xLabels || {};
+  const getSeriesLabel = (key, index) => {
+    if (xLabels[key]) return xLabels[key];
+    if (Array.isArray(legend)) return legend[index] ?? key;
+    return key;
+  };
+
   const animateClass = animate ? ' chart-animate' : '';
 
+  // Get X-axis format (bars extend along X)
+  const xFormat = getAxisFormat(config, 'x');
+
   // Calculate max total across all rows if not provided
-  const calculatedMax = max ?? Math.max(...data.map(row => {
+  // Use normalized x.max, fall back to legacy top-level max
+  const configMax = getAxisMax(config, 'x') ?? max;
+  const calculatedMax = configMax ?? Math.max(...data.map(row => {
     return seriesKeys.reduce((sum, key) => {
       const val = row[key];
       return sum + (typeof val === 'number' ? val : parseFloat(val) || 0);
@@ -45,14 +59,15 @@ export function renderStackedBar(config) {
     html += `</figcaption>`;
   }
 
-  // Legend
-  if (seriesKeys.length > 0 || legendTitle) {
+  // Legend (show if legend !== false and we have series keys or legendTitle)
+  const showLegend = config.legend !== false && (seriesKeys.length > 0 || legendTitle);
+  if (showLegend) {
     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 label = getSeriesLabel(key, i);
       const colorClass = `chart-color-${i + 1}`;
       const seriesClass = `chart-series-${slugify(key)}`;
       html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;
@@ -74,12 +89,11 @@ export function renderStackedBar(config) {
     });
     const total = values.reduce((sum, v) => sum + v, 0);
     const percentages = calculatePercentages(values, calculatedMax);
-    const seriesLabels = legendLabels ?? seriesKeys;
 
     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)}: ${formatNumber(total, format) || total}">`;
+    html += `<div class="bar-fills" title="${escapeHtml(label)}: ${formatNumber(total, xFormat) || total}">`;
 
     seriesKeys.forEach((key, i) => {
       const pct = percentages[i];
@@ -87,8 +101,8 @@ export function renderStackedBar(config) {
       if (pct > 0) {
         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)}: ${formatNumber(value, format) || value}"></div>`;
+        const seriesLabel = getSeriesLabel(key, i);
+        html += `<div class="bar-fill ${colorClass} ${seriesClass}" style="--value: ${pct.toFixed(2)}%" title="${escapeHtml(seriesLabel)}: ${formatNumber(value, xFormat) || value}"></div>`;
       }
     });
 
@@ -96,7 +110,7 @@ export function renderStackedBar(config) {
     html += `</div>`;
 
     // Show total value
-    html += `<span class="bar-value">${formatNumber(total, format) || total}</span>`;
+    html += `<span class="bar-value">${formatNumber(total, xFormat) || total}</span>`;
     html += `</div>`;
   });
 

package/src/renderers/stacked-column.js

@@ -1,31 +1,43 @@
 import { slugify, getLabelKey, getSeriesNames, escapeHtml, renderDownloadLink } from '../utils.js';
 import { formatNumber } from '../formatters.js';
+import { getAxisMax, getAxisMin, getAxisFormat, getRotateLabels } from '../config.js';
 
 /**
  * Render a stacked column chart (vertical)
- * @param {Object} config - Chart configuration
+ * @param {Object} config - Chart configuration (normalized)
  * @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 Y-axis scaling
- * @param {number} [config.min] - Minimum value for Y-axis scaling (for negative values)
+ * @param {Object} [config.y] - Y-axis configuration { max, min, format }
  * @param {string[]} [config.legend] - Legend labels (defaults to series names)
  * @param {boolean} [config.animate] - Enable animations
+ * @param {Object} [config._columns] - Resolved column mappings
  * @returns {string} - HTML string
  */
 export function renderStackedColumn(config) {
-  const { title, subtitle, data, max, min, legend, animate, format, id, rotateLabels, downloadData, downloadDataUrl } = config;
+  const { title, subtitle, data, max, min, legend, animate, format, id, downloadData, downloadDataUrl, _columns } = config;
 
   if (!data || data.length === 0) {
     return `<!-- Stacked column chart: no data provided -->`;
   }
 
-  // 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;
+  // Get label key and series keys (use resolved columns if available)
+  const labelKey = _columns?.label ?? getLabelKey(data);
+  const seriesKeys = _columns?.values?.length > 0 ? _columns.values : getSeriesNames(data);
+
+  // Build legend labels from: 1) yLabels (new), 2) legend array (deprecated), 3) column names
+  const yLabels = _columns?.yLabels || {};
+  const getSeriesLabel = (key, index) => {
+    if (yLabels[key]) return yLabels[key];
+    if (Array.isArray(legend)) return legend[index] ?? key;
+    return key;
+  };
+
   const animateClass = animate ? ' chart-animate' : '';
+  const rotateLabels = getRotateLabels(config, config.id);
+
+  // Get Y-axis format
+  const yFormat = getAxisFormat(config, 'y');
 
   // Calculate stacked totals for positive and negative values separately
   // Positives stack up from zero, negatives stack down from zero
@@ -48,9 +60,12 @@ export function renderStackedColumn(config) {
     minNegativeStack = Math.min(minNegativeStack, negativeSum);
   });
 
-  const hasNegativeY = minNegativeStack < 0 || min < 0;
-  const maxValue = max ?? maxPositiveStack;
-  const minValue = min ?? minNegativeStack;
+  // Use normalized axis config, fall back to legacy top-level max/min
+  const configMaxY = getAxisMax(config, 'y') ?? max;
+  const configMinY = getAxisMin(config, 'y') ?? min;
+  const hasNegativeY = minNegativeStack < 0 || configMinY < 0;
+  const maxValue = configMaxY ?? maxPositiveStack;
+  const minValue = configMinY ?? minNegativeStack;
   const range = maxValue - minValue;
   const zeroPct = hasNegativeY ? ((0 - minValue) / range) * 100 : 0;
 
@@ -72,11 +87,11 @@ 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">${formatNumber(maxValue, format) || maxValue}</span>`;
+  html += `<span class="axis-label">${formatNumber(maxValue, yFormat) || maxValue}</span>`;
   const midLabelY = hasNegativeY ? 0 : Math.round(maxValue / 2);
-  html += `<span class="axis-label">${formatNumber(midLabelY, format) || midLabelY}</span>`;
+  html += `<span class="axis-label">${formatNumber(midLabelY, yFormat) || midLabelY}</span>`;
   const minLabelY = hasNegativeY ? minValue : 0;
-  html += `<span class="axis-label">${formatNumber(minLabelY, format) || minLabelY}</span>`;
+  html += `<span class="axis-label">${formatNumber(minLabelY, yFormat) || minLabelY}</span>`;
   html += `</div>`;
 
   // Scroll wrapper for columns + labels
@@ -107,7 +122,7 @@ export function renderStackedColumn(config) {
         const value = typeof val === 'number' ? val : parseFloat(val) || 0;
         const colorClass = `chart-color-${i + 1}`;
         const seriesClass = `chart-series-${slugify(key)}`;
-        const seriesLabel = legendLabels[i] ?? key;
+        const seriesLabel = getSeriesLabel(key, i);
         const segmentHeight = range > 0 ? (Math.abs(value) / range) * 100 : 0;
 
         if (value >= 0) {
@@ -115,7 +130,7 @@ export function renderStackedColumn(config) {
             classes: `column-segment ${colorClass} ${seriesClass}`,
             bottom: positiveBottom,
             height: segmentHeight,
-            title: `${escapeHtml(seriesLabel)}: ${formatNumber(value, format) || value}`,
+            title: `${escapeHtml(seriesLabel)}: ${formatNumber(value, yFormat) || value}`,
             isNegative: false
           });
           lastPositiveIdx = segments.length - 1;
@@ -126,7 +141,7 @@ export function renderStackedColumn(config) {
             classes: `column-segment ${colorClass} ${seriesClass} is-negative`,
             bottom: negativeTop,
             height: segmentHeight,
-            title: `${escapeHtml(seriesLabel)}: ${formatNumber(value, format) || value}`,
+            title: `${escapeHtml(seriesLabel)}: ${formatNumber(value, yFormat) || value}`,
             isNegative: true
           });
           lastNegativeIdx = segments.length - 1;
@@ -157,11 +172,11 @@ export function renderStackedColumn(config) {
       segmentData.forEach((seg, idx) => {
         const colorClass = `chart-color-${seg.i + 1}`;
         const seriesClass = `chart-series-${slugify(seg.key)}`;
-        const seriesLabel = legendLabels[seg.i] ?? seg.key;
+        const seriesLabel = getSeriesLabel(seg.key, seg.i);
         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)}: ${formatNumber(seg.value, format) || seg.value}"></div>`;
+        html += `title="${escapeHtml(seriesLabel)}: ${formatNumber(seg.value, yFormat) || seg.value}"></div>`;
       });
     }
 
@@ -181,11 +196,12 @@ export function renderStackedColumn(config) {
   html += `</div>`; // close chart-scroll
   html += `</div>`; // close chart-body
 
-  // Legend
-  if (seriesKeys.length > 0) {
+  // Legend (show if legend !== false and we have series keys)
+  const showLegend = config.legend !== false && seriesKeys.length > 0;
+  if (showLegend) {
     html += `<ul class="chart-legend">`;
     seriesKeys.forEach((key, i) => {
-      const label = legendLabels[i] ?? key;
+      const label = getSeriesLabel(key, i);
       const colorClass = `chart-color-${i + 1}`;
       const seriesClass = `chart-series-${slugify(key)}`;
       html += `<li class="chart-legend-item ${colorClass} ${seriesClass}">${escapeHtml(label)}</li>`;