decantr 0.9.0

package/src/chart/layouts/_layout-base.js

@@ -0,0 +1,328 @@
+/**
+ * Shared layout contract — base utilities for all layout modules.
+ * Axis/grid scene builders, margin computation, tick formatting.
+ * @module layouts/_layout-base
+ */
+
+import { scaleLinear, scaleBand, scaleTime, extent, unique, padExtent, isDateLike, toDate } from '../_shared.js';
+import { scene, group, line, text, rect, circle, gridLines, axisTicks } from '../_scene.js';
+
+// --- Constants ---
+
+/** Default chart margins (px) */
+export const MARGINS = { top: 24, right: 16, bottom: 40, left: 48 };
+
+/** No-axes margins (sparkline, pie) */
+export const MARGINS_NONE = { top: 0, right: 0, bottom: 0, left: 0 };
+
+/** Pie/donut margins (small padding) */
+export const MARGINS_PIE = { top: 4, right: 4, bottom: 4, left: 4 };
+
+// --- Dimensions ---
+
+/**
+ * Compute inner dimensions from outer + margins.
+ * @param {number} width
+ * @param {number} height
+ * @param {Object} margins
+ * @returns {{ innerW: number, innerH: number, margins: Object }}
+ */
+export function innerDimensions(width, height, margins) {
+  return {
+    innerW: Math.max(0, width - margins.left - margins.right),
+    innerH: Math.max(0, height - margins.top - margins.bottom),
+    margins
+  };
+}
+
+// --- Scale builders ---
+
+/**
+ * Build an X scale from data + field + inner width.
+ * Auto-detects band (categorical) vs linear/time (numeric/date).
+ * @param {Object[]} data
+ * @param {string} xField
+ * @param {number} innerW
+ * @returns {{ scale: Function, type: 'band'|'linear'|'time' }}
+ */
+export function buildXScale(data, xField, innerW) {
+  const values = data.map(d => d[xField]);
+
+  if (isDateLike(values)) {
+    const dates = values.map(toDate);
+    const [min, max] = [Math.min(...dates), Math.max(...dates)];
+    return { scale: scaleTime([new Date(min), new Date(max)], [0, innerW]), type: 'time' };
+  }
+
+  if (typeof values[0] === 'number') {
+    const ext = padExtent(extent(data, xField));
+    return { scale: scaleLinear(ext, [0, innerW]), type: 'linear' };
+  }
+
+  // Categorical
+  const cats = unique(data, xField);
+  return { scale: scaleBand(cats, [0, innerW]), type: 'band' };
+}
+
+/**
+ * Build a Y scale from data + field(s) + inner height.
+ * Always linear, domain goes bottom→top (range inverted).
+ * @param {Object[]} data
+ * @param {string|string[]} yFields
+ * @param {number} innerH
+ * @param {{ stacked?: boolean, padBottom?: boolean, min?: number, max?: number }} opts
+ * @returns {Function}
+ */
+export function buildYScale(data, yFields, innerH, opts = {}) {
+  const fields = Array.isArray(yFields) ? yFields : [yFields];
+  let min = opts.min != null ? opts.min : Infinity;
+  let max = opts.max != null ? opts.max : -Infinity;
+
+  if (min === Infinity || max === -Infinity) {
+    if (opts.stacked) {
+      for (let i = 0; i < data.length; i++) {
+        let sum = 0;
+        for (const f of fields) sum += +data[i][f] || 0;
+        if (sum > max) max = sum;
+      }
+      if (min === Infinity) min = 0;
+    } else {
+      for (const f of fields) {
+        const [lo, hi] = extent(data, f);
+        if (lo < min) min = lo;
+        if (hi > max) max = hi;
+      }
+    }
+  }
+
+  if (opts.padBottom !== false && min > 0) min = 0;
+  const ext = padExtent([min, max], 0.05);
+  if (ext[0] > 0 && min === 0) ext[0] = 0;
+  return scaleLinear(ext, [innerH, 0]);
+}
+
+// --- Formatting ---
+
+/**
+ * Format a number for axis labels.
+ * @param {number} v
+ * @returns {string}
+ */
+export function formatNumber(v) {
+  if (Math.abs(v) >= 1e9) return (v / 1e9).toFixed(1) + 'B';
+  if (Math.abs(v) >= 1e6) return (v / 1e6).toFixed(1) + 'M';
+  if (Math.abs(v) >= 1e3) return (v / 1e3).toFixed(1) + 'K';
+  if (Number.isInteger(v)) return String(v);
+  return v.toFixed(1);
+}
+
+/**
+ * Format a date for axis labels.
+ * @param {Date} d
+ * @returns {string}
+ */
+export function formatDate(d) {
+  if (!(d instanceof Date)) d = new Date(d);
+  return `${d.getMonth() + 1}/${d.getDate()}`;
+}
+
+/**
+ * Format duration (ms) to human-readable.
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (ms < 1000) return ms + 'ms';
+  if (ms < 60000) return (ms / 1000).toFixed(1) + 's';
+  if (ms < 3600000) return (ms / 60000).toFixed(1) + 'm';
+  return (ms / 3600000).toFixed(1) + 'h';
+}
+
+/**
+ * Format percentage.
+ * @param {number} v — 0-100 or 0-1
+ * @returns {string}
+ */
+export function formatPercent(v) {
+  const pct = v > 1 ? v : v * 100;
+  return pct.toFixed(1) + '%';
+}
+
+// --- Tick computation ---
+
+/**
+ * Compute axis tick positions and labels.
+ * @param {Function} scale — scale with .ticks() method
+ * @param {string} type — 'linear'|'time'|'band'
+ * @param {number} [count=5]
+ * @param {Function} [format]
+ * @returns {{ value: any, position: number, label: string }[]}
+ */
+export function computeTicks(scale, type, count = 5, format) {
+  if (type === 'band') return [];
+
+  const ticks = scale.ticks(count);
+  return ticks.map(t => ({
+    value: t,
+    position: scale(t),
+    label: format ? format(t) : (type === 'time' ? formatDate(t) : formatNumber(t))
+  }));
+}
+
+/**
+ * Get chart color for a series index.
+ * Uses CSS custom properties (--d-chart-0 through --d-chart-7).
+ * For 8-31, uses extended palette. For 32+, cycles.
+ * @param {number} index
+ * @returns {string}
+ */
+export function chartColor(index) {
+  return `var(--d-chart-${index % 8})`;
+}
+
+/**
+ * Extended chart color — uses extended palette tokens for 8+ series.
+ * @param {number} index
+ * @returns {string}
+ */
+export function chartColorExtended(index) {
+  if (index < 8) return `var(--d-chart-${index})`;
+  if (index < 32) return `var(--d-chart-${index % 8}-ext-${Math.floor((index - 8) / 8) + 1})`;
+  return `var(--d-chart-${index % 8})`;
+}
+
+/** Total base chart palette size */
+export const PALETTE_SIZE = 8;
+
+// --- Annotation builders ---
+
+/**
+ * Build annotation scene nodes from spec.annotations array.
+ * Supports 3 types: 'line' (horizontal/vertical reference line),
+ * 'band' (shaded range), 'point' (labeled marker).
+ * @param {Object[]} annotations — [{type, axis, value, from, to, x, y, label, color, dash}]
+ * @param {Function} xScale
+ * @param {Function} yScale
+ * @param {string} xType — 'band'|'linear'|'time'
+ * @param {number} innerW
+ * @param {number} innerH
+ * @returns {Object[]} scene graph nodes
+ */
+export function buildAnnotations(annotations, xScale, yScale, xType, innerW, innerH) {
+  if (!annotations || !annotations.length) return [];
+  const nodes = [];
+  for (const a of annotations) {
+    const color = a.color || 'var(--d-muted)';
+    if (a.type === 'line') {
+      if (a.axis === 'y') {
+        const y = yScale(a.value);
+        nodes.push(line({ x1: 0, y1: y, x2: innerW, y2: y, stroke: color, strokeDash: a.dash || '4,3', class: 'd-chart-annotation-line' }));
+        if (a.label) {
+          nodes.push(text({ x: innerW + 4, y: y + 4, content: a.label, anchor: 'start', class: 'd-chart-annotation-label', fill: color }));
+        }
+      } else {
+        const x = xType === 'band' ? xScale(a.value) + (xScale.bandwidth ? xScale.bandwidth() / 2 : 0) : xScale(a.value);
+        nodes.push(line({ x1: x, y1: 0, x2: x, y2: innerH, stroke: color, strokeDash: a.dash || '4,3', class: 'd-chart-annotation-line' }));
+        if (a.label) {
+          nodes.push(text({ x: x, y: -6, content: a.label, anchor: 'middle', class: 'd-chart-annotation-label', fill: color }));
+        }
+      }
+    } else if (a.type === 'band') {
+      if (a.axis === 'y') {
+        const y1 = yScale(a.to);
+        const y2 = yScale(a.from);
+        nodes.push(rect({ x: 0, y: y1, w: innerW, h: y2 - y1, fill: color, class: 'd-chart-annotation-band' }));
+        if (a.label) {
+          nodes.push(text({ x: innerW + 4, y: (y1 + y2) / 2 + 4, content: a.label, anchor: 'start', class: 'd-chart-annotation-label', fill: color }));
+        }
+      } else {
+        const x1 = xType === 'band' ? xScale(a.from) : xScale(a.from);
+        const x2 = xType === 'band' ? xScale(a.to) + (xScale.bandwidth ? xScale.bandwidth() : 0) : xScale(a.to);
+        nodes.push(rect({ x: x1, y: 0, w: x2 - x1, h: innerH, fill: color, class: 'd-chart-annotation-band' }));
+        if (a.label) {
+          nodes.push(text({ x: (x1 + x2) / 2, y: -6, content: a.label, anchor: 'middle', class: 'd-chart-annotation-label', fill: color }));
+        }
+      }
+    } else if (a.type === 'point') {
+      const px = xType === 'band' ? xScale(a.x) + (xScale.bandwidth ? xScale.bandwidth() / 2 : 0) : xScale(a.x);
+      const py = yScale(a.y);
+      nodes.push(circle({ cx: px, cy: py, r: 5, fill: 'none', stroke: color, strokeWidth: 2, class: 'd-chart-annotation-line' }));
+      if (a.label) {
+        nodes.push(text({ x: px, y: py - 10, content: a.label, anchor: 'middle', class: 'd-chart-annotation-label', fill: color }));
+      }
+    }
+  }
+  return nodes;
+}
+
+// --- Scene builders ---
+
+/**
+ * Build X-axis scene nodes.
+ * @param {Function} xScale
+ * @param {string} xType
+ * @param {number} innerH
+ * @param {number} innerW
+ * @param {Object} spec
+ * @param {Object} [layout] — for band labels
+ * @returns {Object[]}
+ */
+export function buildXAxisNodes(xScale, xType, innerH, innerW, spec, layout) {
+  const nodes = [];
+  if (spec.axisLine) {
+    nodes.push(line({ x1: 0, y1: innerH, x2: innerW, y2: innerH, stroke: 'var(--d-border)', class: 'd-chart-axis' }));
+  }
+
+  if (xType === 'band' && layout && layout.categories) {
+    const bandW = xScale.bandwidth();
+    for (const cat of layout.categories) {
+      const x = xScale(cat) + bandW / 2;
+      nodes.push(text({ x, y: innerH + 20, content: String(cat), anchor: 'middle', class: 'd-chart-axis' }));
+    }
+  } else if (xType !== 'band') {
+    const fmt = spec.xFormat || (xType === 'time' ? formatDate : formatNumber);
+    const ticks = computeTicks(xScale, xType, 6, fmt);
+    for (const t of ticks) {
+      nodes.push(text({ x: t.position, y: innerH + 20, content: t.label, anchor: 'middle', class: 'd-chart-axis' }));
+    }
+  }
+
+  return nodes;
+}
+
+/**
+ * Build Y-axis scene nodes.
+ * @param {Function} yScale
+ * @param {number} innerH
+ * @param {Object} spec
+ * @returns {Object[]}
+ */
+export function buildYAxisNodes(yScale, innerH, spec) {
+  const fmt = spec.yFormat || formatNumber;
+  const ticks = yScale.ticks(5);
+  const nodes = [];
+  if (spec.axisLine) {
+    nodes.push(line({ x1: 0, y1: 0, x2: 0, y2: innerH, stroke: 'var(--d-border)', class: 'd-chart-axis' }));
+  }
+
+  for (const t of ticks) {
+    const y = yScale(t);
+    nodes.push(text({ x: -8, y: y + 4, content: fmt(t), anchor: 'end', class: 'd-chart-axis' }));
+  }
+
+  return nodes;
+}
+
+/**
+ * Build grid line scene nodes.
+ * @param {Function} yScale
+ * @param {number} innerW
+ * @returns {Object[]}
+ */
+export function buildGridNodes(yScale, innerW) {
+  const ticks = yScale.ticks(5);
+  return ticks.map(t => line({
+    x1: 0, y1: yScale(t), x2: innerW, y2: yScale(t),
+    class: 'd-chart-grid'
+  }));
+}

package/src/chart/layouts/cartesian.js

@@ -0,0 +1,148 @@
+/**
+ * Shared cartesian coordinate layout.
+ * Used by 13 chart types. Handles: margin calculation, x/y scale construction,
+ * axis tick generation, grid lines, horizontal mode, secondary y-axis, zoom viewport.
+ * @module layouts/cartesian
+ */
+
+import { scene, group } from '../_scene.js';
+import {
+  MARGINS, innerDimensions, buildXScale, buildYScale,
+  buildXAxisNodes, buildYAxisNodes, buildGridNodes, chartColor
+} from './_layout-base.js';
+import { scaleBand, scaleLinear, unique, extent, padExtent } from '../_shared.js';
+
+/**
+ * Build a complete cartesian coordinate system.
+ * Returns dimensions, scales, and a scene group with axes + grid.
+ *
+ * @param {Object} spec — chart spec
+ * @param {number} width
+ * @param {number} height
+ * @param {Object} [opts]
+ * @param {boolean} [opts.bandX=false] — force band X scale
+ * @param {boolean} [opts.skipAxes=false] — skip axis/grid generation
+ * @param {Object} [opts.margins] — override margins
+ * @param {Object} [opts.yOpts] — pass to buildYScale
+ * @returns {{ innerW, innerH, margins, xScale, yScale, xType, y2Scale, categories, axisNodes, gridNodes, spec }}
+ */
+export function cartesian(spec, width, height, opts = {}) {
+  const data = Array.isArray(spec.data) ? spec.data : [];
+  const horizontal = !!spec.horizontal;
+  const margins = opts.margins || { ...MARGINS };
+
+  // Increase left margin for horizontal charts (labels on Y axis)
+  if (horizontal) margins.left = Math.max(margins.left, 72);
+
+  // Increase right margin for secondary Y axis
+  if (spec.y2) margins.right = Math.max(margins.right, 48);
+
+  const { innerW, innerH } = innerDimensions(width, height, margins);
+
+  // Resolve field names
+  const xField = spec.x;
+  const yFields = Array.isArray(spec.y) ? spec.y : [spec.y];
+
+  let xScale, xType, yScale, y2Scale, categories;
+
+  if (horizontal) {
+    // Horizontal mode: Y becomes categorical, X becomes value
+    categories = unique(data, xField);
+    xScale = scaleBand(categories, [0, innerH], 0.2);
+    xType = 'band';
+    yScale = buildYScale(data, yFields, innerW, { ...opts.yOpts, padBottom: opts.yOpts?.padBottom });
+    // Swap: yScale maps to horizontal (innerW) but we need it to go left→right
+    const yMin = 0, yMax = extent(data, yFields[0])[1];
+    yScale = scaleLinear(padExtent([yMin, yMax], 0.05), [0, innerW]);
+    if (yScale.ticks) { /* keep ticks */ }
+  } else {
+    // Normal: X is categorical or continuous, Y is value
+    if (opts.bandX) {
+      categories = unique(data, xField);
+      xScale = scaleBand(categories, [0, innerW], 0.2);
+      xType = 'band';
+    } else {
+      const built = buildXScale(data, xField, innerW);
+      xScale = built.scale;
+      xType = built.type;
+      if (xType === 'band') categories = unique(data, xField);
+    }
+
+    yScale = buildYScale(data, yFields, innerH, opts.yOpts || { stacked: !!spec.stacked });
+
+    // Secondary Y axis
+    if (spec.y2) {
+      const y2Fields = Array.isArray(spec.y2) ? spec.y2 : [spec.y2];
+      y2Scale = buildYScale(data, y2Fields, innerH, { padBottom: true });
+    }
+  }
+
+  // Build axis + grid scene nodes
+  let axisNodes = [];
+  let gridNodes = [];
+
+  if (!opts.skipAxes) {
+    if (horizontal) {
+      // Horizontal: value axis on bottom, category axis on left
+      // Value axis (bottom)
+      axisNodes.push(...buildHorizontalValueAxis(yScale, innerW, innerH, spec));
+      // Category axis (left)
+      axisNodes.push(...buildHorizontalCategoryAxis(xScale, categories, innerH));
+      // Grid (vertical lines)
+      gridNodes = buildHorizontalGrid(yScale, innerH);
+    } else {
+      axisNodes.push(...buildXAxisNodes(xScale, xType, innerH, innerW, spec, { categories }));
+      axisNodes.push(...buildYAxisNodes(yScale, innerH, spec));
+      gridNodes = buildGridNodes(yScale, innerW);
+    }
+  }
+
+  return {
+    width, height, innerW, innerH, margins,
+    xScale, yScale, xType, y2Scale,
+    categories, axisNodes, gridNodes,
+    horizontal, data, spec
+  };
+}
+
+// --- Horizontal chart axis helpers ---
+
+import { line, text } from '../_scene.js';
+
+function buildHorizontalValueAxis(valueScale, innerW, innerH, spec) {
+  const nodes = [
+    line({ x1: 0, y1: innerH, x2: innerW, y2: innerH, stroke: 'var(--d-border)', class: 'd-chart-axis' })
+  ];
+  const ticks = valueScale.ticks(5);
+  const fmt = spec.yFormat || (v => {
+    if (Math.abs(v) >= 1e6) return (v / 1e6).toFixed(1) + 'M';
+    if (Math.abs(v) >= 1e3) return (v / 1e3).toFixed(1) + 'K';
+    if (Number.isInteger(v)) return String(v);
+    return v.toFixed(1);
+  });
+  for (const t of ticks) {
+    const x = valueScale(t);
+    nodes.push(text({ x, y: innerH + 20, content: fmt(t), anchor: 'middle', class: 'd-chart-axis' }));
+  }
+  return nodes;
+}
+
+function buildHorizontalCategoryAxis(bandScale, categories, innerH) {
+  const nodes = [
+    line({ x1: 0, y1: 0, x2: 0, y2: innerH, stroke: 'var(--d-border)', class: 'd-chart-axis' })
+  ];
+  const bandW = bandScale.bandwidth();
+  for (const cat of categories) {
+    const y = bandScale(cat) + bandW / 2;
+    nodes.push(text({ x: -8, y: y + 4, content: String(cat), anchor: 'end', class: 'd-chart-axis' }));
+  }
+  return nodes;
+}
+
+function buildHorizontalGrid(valueScale, innerH) {
+  const ticks = valueScale.ticks(5);
+  return ticks.map(t => line({
+    x1: valueScale(t), y1: 0, x2: valueScale(t), y2: innerH,
+    class: 'd-chart-grid'
+  }));
+}