decantr 0.9.0

package/src/chart/_scene.js

@@ -0,0 +1,262 @@
+/**
+ * Scene Graph — renderer-agnostic intermediate representation.
+ * Plain objects with `type` discriminant. Serializable, diffable, minimal.
+ * All layout functions produce scene nodes; renderers consume them.
+ * @module _scene
+ */
+
+/**
+ * Root scene node — container for all chart elements.
+ * @param {number} width
+ * @param {number} height
+ * @param {Object[]} children
+ * @param {Object} [meta] — chart-level metadata (type, margins, scales)
+ * @returns {Object}
+ */
+export function scene(width, height, children, meta) {
+  return { type: 'scene', width, height, children: children || [], meta: meta || {} };
+}
+
+/**
+ * Group node — logical grouping with optional transform.
+ * @param {Object} attrs — { transform, class, clip, opacity }
+ * @param {Object[]} children
+ * @returns {Object}
+ */
+export function group(attrs, children) {
+  return { type: 'group', ...attrs, children: children || [] };
+}
+
+/**
+ * Path node — arbitrary SVG path data.
+ * @param {Object} attrs — { d, fill, stroke, strokeWidth, strokeDash, strokeLinecap, strokeLinejoin, class, data, key, opacity }
+ * @returns {Object}
+ */
+export function path(attrs) {
+  return { type: 'path', ...attrs };
+}
+
+/**
+ * Rectangle node.
+ * @param {Object} attrs — { x, y, w, h, rx, ry, fill, stroke, strokeWidth, class, data, key, opacity }
+ * @returns {Object}
+ */
+export function rect(attrs) {
+  return { type: 'rect', ...attrs };
+}
+
+/**
+ * Circle node.
+ * @param {Object} attrs — { cx, cy, r, fill, stroke, strokeWidth, class, data, key, opacity }
+ * @returns {Object}
+ */
+export function circle(attrs) {
+  return { type: 'circle', ...attrs };
+}
+
+/**
+ * Text node.
+ * @param {Object} attrs — { x, y, content, anchor, baseline, fill, class, fontSize, fontWeight, rotate }
+ * @returns {Object}
+ */
+export function text(attrs) {
+  return { type: 'text', ...attrs };
+}
+
+/**
+ * Line node.
+ * @param {Object} attrs — { x1, y1, x2, y2, stroke, strokeWidth, strokeDash, class }
+ * @returns {Object}
+ */
+export function line(attrs) {
+  return { type: 'line', ...attrs };
+}
+
+/**
+ * Arc node — for pie/donut/gauge/radial charts.
+ * @param {Object} attrs — { cx, cy, innerR, outerR, startAngle, endAngle, fill, stroke, class, data, key, opacity }
+ * @returns {Object}
+ */
+export function arc(attrs) {
+  return { type: 'arc', ...attrs };
+}
+
+/**
+ * Polygon node — closed shape from point array.
+ * @param {Object} attrs — { points: [{x,y}], fill, stroke, strokeWidth, class, data, key, opacity }
+ * @returns {Object}
+ */
+export function polygon(attrs) {
+  return { type: 'polygon', ...attrs };
+}
+
+/**
+ * Image node — for embedding icons/images in charts.
+ * @param {Object} attrs — { x, y, w, h, href, class, data, key }
+ * @returns {Object}
+ */
+export function image(attrs) {
+  return { type: 'image', ...attrs };
+}
+
+// --- Utility builders ---
+
+/**
+ * Build axis tick scene nodes.
+ * @param {Array} ticks — [{ value, position, label }]
+ * @param {'x'|'y'} axis
+ * @param {number} innerW
+ * @param {number} innerH
+ * @returns {Object[]} scene nodes
+ */
+export function axisTicks(ticks, axis, innerW, innerH) {
+  const nodes = [];
+  if (axis === 'x') {
+    for (const t of ticks) {
+      nodes.push(line({ x1: t.position, y1: innerH, x2: t.position, y2: innerH + 4, stroke: 'var(--d-border)', class: 'd-chart-tick' }));
+      nodes.push(text({ x: t.position, y: innerH + 18, content: t.label, anchor: 'middle', class: 'd-chart-axis' }));
+    }
+  } else {
+    for (const t of ticks) {
+      nodes.push(line({ x1: -4, y1: t.position, x2: 0, y2: t.position, stroke: 'var(--d-border)', class: 'd-chart-tick' }));
+      nodes.push(text({ x: -8, y: t.position + 4, content: t.label, anchor: 'end', class: 'd-chart-axis' }));
+    }
+  }
+  return nodes;
+}
+
+/**
+ * Build grid line scene nodes from Y ticks.
+ * @param {Array} ticks — [{ position }]
+ * @param {number} innerW
+ * @returns {Object[]}
+ */
+export function gridLines(ticks, innerW) {
+  return ticks.map(t => line({ x1: 0, y1: t.position, x2: innerW, y2: t.position, class: 'd-chart-grid' }));
+}
+
+/**
+ * Convert arc params to SVG path data string.
+ * @param {number} cx
+ * @param {number} cy
+ * @param {number} outerR
+ * @param {number} innerR
+ * @param {number} startAngle
+ * @param {number} endAngle
+ * @returns {string}
+ */
+export function arcToPath(cx, cy, outerR, innerR, startAngle, endAngle) {
+  const x1 = cx + outerR * Math.cos(startAngle);
+  const y1 = cy + outerR * Math.sin(startAngle);
+  const x2 = cx + outerR * Math.cos(endAngle);
+  const y2 = cy + outerR * Math.sin(endAngle);
+  const largeArc = endAngle - startAngle > Math.PI ? 1 : 0;
+
+  let d = `M${x1},${y1}A${outerR},${outerR},0,${largeArc},1,${x2},${y2}`;
+
+  if (innerR > 0) {
+    const x3 = cx + innerR * Math.cos(endAngle);
+    const y3 = cy + innerR * Math.sin(endAngle);
+    const x4 = cx + innerR * Math.cos(startAngle);
+    const y4 = cy + innerR * Math.sin(startAngle);
+    d += `L${x3},${y3}A${innerR},${innerR},0,${largeArc},0,${x4},${y4}Z`;
+  } else {
+    d += `L${cx},${cy}Z`;
+  }
+
+  return d;
+}
+
+/**
+ * Convert points array to SVG path data string (M/L commands).
+ * @param {{x:number, y:number}[]} points
+ * @returns {string}
+ */
+export function pointsToPathD(points) {
+  if (!points.length) return '';
+  let d = `M${points[0].x},${points[0].y}`;
+  for (let i = 1; i < points.length; i++) d += `L${points[i].x},${points[i].y}`;
+  return d;
+}
+
+/**
+ * Convert points to smooth Catmull-Rom spline path.
+ * @param {{x:number, y:number}[]} points
+ * @param {number} [tension=0.5]
+ * @returns {string}
+ */
+export function smoothPathD(points, tension = 0.5) {
+  if (points.length < 2) return pointsToPathD(points);
+  if (points.length === 2) return pointsToPathD(points);
+
+  let d = `M${points[0].x},${points[0].y}`;
+  for (let i = 0; i < points.length - 1; i++) {
+    const p0 = points[Math.max(0, i - 1)];
+    const p1 = points[i];
+    const p2 = points[i + 1];
+    const p3 = points[Math.min(points.length - 1, i + 2)];
+
+    const cp1x = p1.x + (p2.x - p0.x) / 6 * tension;
+    const cp1y = p1.y + (p2.y - p0.y) / 6 * tension;
+    const cp2x = p2.x - (p3.x - p1.x) / 6 * tension;
+    const cp2y = p2.y - (p3.y - p1.y) / 6 * tension;
+
+    d += `C${cp1x},${cp1y},${cp2x},${cp2y},${p2.x},${p2.y}`;
+  }
+  return d;
+}
+
+/**
+ * Convert area points (with y0/y1) to closed polygon path data.
+ * @param {{x:number, y0:number, y1:number}[]} points — y0=top, y1=bottom
+ * @returns {string}
+ */
+export function areaPathD(points) {
+  if (!points.length) return '';
+  let d = `M${points[0].x},${points[0].y0}`;
+  for (let i = 1; i < points.length; i++) d += `L${points[i].x},${points[i].y0}`;
+  for (let i = points.length - 1; i >= 0; i--) d += `L${points[i].x},${points[i].y1}`;
+  d += 'Z';
+  return d;
+}
+
+/**
+ * Convert area points to smooth closed polygon path.
+ * Top edge uses Catmull-Rom spline, bottom edge stays straight.
+ * @param {{x:number, y0:number, y1:number}[]} points — y0=top, y1=bottom
+ * @param {number} [tension=0.5]
+ * @returns {string}
+ */
+export function smoothAreaPathD(points, tension = 0.5) {
+  if (!points.length) return '';
+  // Top edge — smooth Catmull-Rom
+  const topPts = points.map(p => ({ x: p.x, y: p.y0 }));
+  let d = smoothPathD(topPts, tension);
+  // Bottom edge — straight, reversed
+  for (let i = points.length - 1; i >= 0; i--) d += `L${points[i].x},${points[i].y1}`;
+  d += 'Z';
+  return d;
+}
+
+/**
+ * Gradient scene node — for SVG <linearGradient> definitions.
+ * @param {Object} attrs — { id, x1, y1, x2, y2, stops: [{ offset, color, opacity }] }
+ * @returns {Object}
+ */
+export function gradient(attrs) {
+  return { type: 'gradient', ...attrs };
+}
+
+/**
+ * Step path (horizontal-first, for step line charts).
+ * @param {{x:number, y:number}[]} points
+ * @returns {string}
+ */
+export function stepPathD(points) {
+  if (points.length < 2) return pointsToPathD(points);
+  let d = `M${points[0].x},${points[0].y}`;
+  for (let i = 1; i < points.length; i++) {
+    d += `H${points[i].x}V${points[i].y}`;
+  }
+  return d;
+}

package/src/chart/_shared.js

@@ -0,0 +1,371 @@
+import { createEffect } from '../state/index.js';
+import { getTheme } from '../css/theme-registry.js';
+
+/**
+ * Resolve a prop that may be a signal getter or a static value.
+ * @template T
+ * @param {T|Function} prop
+ * @returns {T}
+ */
+export function resolve(prop) {
+  return typeof prop === 'function' ? prop() : prop;
+}
+
+// --- Scales ---
+
+/**
+ * Linear scale: maps [domainMin, domainMax] → [rangeMin, rangeMax].
+ * @param {number[]} domain — [min, max]
+ * @param {number[]} range — [min, max] in pixels
+ * @returns {{ (v: number) => number, ticks: (count?: number) => number[], invert: (px: number) => number }}
+ */
+export function scaleLinear(domain, range) {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  const span = d1 - d0 || 1;
+  const rSpan = r1 - r0;
+
+  function scale(v) {
+    return r0 + ((v - d0) / span) * rSpan;
+  }
+
+  scale.invert = function (px) {
+    return d0 + ((px - r0) / rSpan) * span;
+  };
+
+  scale.ticks = function (count = 5) {
+    const step = niceStep(span / count);
+    const start = Math.ceil(d0 / step) * step;
+    const result = [];
+    for (let v = start; v <= d1; v += step) {
+      result.push(+v.toPrecision(12));
+    }
+    return result;
+  };
+
+  return scale;
+}
+
+/**
+ * Band scale: maps discrete values → pixel bands with padding.
+ * @param {any[]} domain — discrete values
+ * @param {number[]} range — [min, max] in pixels
+ * @param {number} padding — 0..1, space between bands
+ * @returns {{ (v: any) => number, bandwidth: () => number }}
+ */
+export function scaleBand(domain, range, padding = 0.2) {
+  const [r0, r1] = range;
+  const n = domain.length || 1;
+  const totalPad = padding * (n + 1);
+  const bandWidth = (r1 - r0) / (n + totalPad);
+  const step = bandWidth * (1 + padding);
+  const offset = bandWidth * padding;
+  const map = new Map();
+  for (let i = 0; i < domain.length; i++) {
+    map.set(domain[i], r0 + offset + i * step);
+  }
+
+  function scale(v) {
+    return map.get(v) ?? r0;
+  }
+
+  scale.bandwidth = function () {
+    return bandWidth;
+  };
+
+  return scale;
+}
+
+/**
+ * Time scale: maps Date values → pixel positions.
+ * @param {Date[]} domain — [min, max] dates
+ * @param {number[]} range — [min, max] in pixels
+ * @returns {{ (v: Date|number) => number, ticks: (count?: number) => Date[] }}
+ */
+export function scaleTime(domain, range) {
+  const d0 = +domain[0];
+  const d1 = +domain[1];
+  const inner = scaleLinear([d0, d1], range);
+
+  function scale(v) {
+    return inner(+v);
+  }
+
+  scale.invert = function (px) {
+    return new Date(inner.invert(px));
+  };
+
+  scale.ticks = function (count = 5) {
+    return inner.ticks(count).map(t => new Date(t));
+  };
+
+  return scale;
+}
+
+// --- Extended scales ---
+
+/**
+ * Logarithmic scale.
+ * @param {number[]} domain
+ * @param {number[]} range
+ * @param {number} [base=10]
+ * @returns {Function}
+ */
+export function scaleLog(domain, range, base = 10) {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  const logBase = Math.log(base);
+  const ld0 = Math.log(Math.max(1e-10, d0)) / logBase;
+  const ld1 = Math.log(Math.max(1e-10, d1)) / logBase;
+  const span = ld1 - ld0 || 1;
+  const rSpan = r1 - r0;
+
+  function scale(v) {
+    const lv = Math.log(Math.max(1e-10, v)) / logBase;
+    return r0 + ((lv - ld0) / span) * rSpan;
+  }
+  scale.invert = px => Math.pow(base, ld0 + ((px - r0) / rSpan) * span);
+  scale.ticks = (count = 5) => {
+    const result = [];
+    const start = Math.ceil(ld0);
+    const end = Math.floor(ld1);
+    for (let i = start; i <= end; i++) result.push(Math.pow(base, i));
+    return result;
+  };
+  return scale;
+}
+
+/**
+ * Square root scale.
+ * @param {number[]} domain
+ * @param {number[]} range
+ * @returns {Function}
+ */
+export function scaleSqrt(domain, range) {
+  const [d0, d1] = domain;
+  const [r0, r1] = range;
+  const sd0 = Math.sqrt(Math.max(0, d0));
+  const sd1 = Math.sqrt(Math.max(0, d1));
+  const span = sd1 - sd0 || 1;
+  const rSpan = r1 - r0;
+
+  function scale(v) {
+    const sv = Math.sqrt(Math.max(0, v));
+    return r0 + ((sv - sd0) / span) * rSpan;
+  }
+  scale.invert = px => Math.pow(sd0 + ((px - r0) / rSpan) * span, 2);
+  scale.ticks = (count = 5) => scaleLinear(domain, range).ticks(count);
+  return scale;
+}
+
+/**
+ * Point scale — discrete values → evenly spaced points.
+ * @param {any[]} domain
+ * @param {number[]} range
+ * @param {number} [padding=0.5]
+ * @returns {Function}
+ */
+export function scalePoint(domain, range, padding = 0.5) {
+  const [r0, r1] = range;
+  const n = domain.length || 1;
+  const step = (r1 - r0) / (n - 1 + padding * 2) || 0;
+  const offset = r0 + step * padding;
+  const map = new Map();
+  for (let i = 0; i < domain.length; i++) {
+    map.set(domain[i], offset + i * step);
+  }
+  function scale(v) { return map.get(v) ?? r0; }
+  scale.step = () => step;
+  return scale;
+}
+
+/**
+ * Ordinal scale — discrete → discrete mapping.
+ * @param {any[]} domain
+ * @param {any[]} range
+ * @returns {Function}
+ */
+export function scaleOrdinal(domain, range) {
+  const map = new Map();
+  for (let i = 0; i < domain.length; i++) {
+    map.set(domain[i], range[i % range.length]);
+  }
+  return function scale(v) { return map.get(v) ?? range[0]; };
+}
+
+/**
+ * Diverging scale — maps a domain with a midpoint.
+ * @param {number[]} domain — [min, mid, max]
+ * @param {any[]} range — [minVal, midVal, maxVal]
+ * @returns {Function}
+ */
+export function scaleDiverging(domain, range) {
+  const [d0, dMid, d1] = domain;
+  const [r0, rMid, r1] = range;
+
+  return function scale(v) {
+    if (v <= dMid) {
+      const t = (v - d0) / (dMid - d0 || 1);
+      return typeof r0 === 'number' ? r0 + (rMid - r0) * t : r0;
+    }
+    const t = (v - dMid) / (d1 - dMid || 1);
+    return typeof rMid === 'number' ? rMid + (r1 - rMid) * t : rMid;
+  };
+}
+
+// --- Nice step for axis ticks ---
+
+function niceStep(rawStep) {
+  const mag = Math.pow(10, Math.floor(Math.log10(rawStep)));
+  const norm = rawStep / mag;
+  let nice;
+  if (norm <= 1.5) nice = 1;
+  else if (norm <= 3) nice = 2;
+  else if (norm <= 7) nice = 5;
+  else nice = 10;
+  return nice * mag;
+}
+
+// --- Data utilities ---
+
+/**
+ * Compute extent (min, max) of a numeric field.
+ * @param {Object[]} data
+ * @param {string} field
+ * @returns {[number, number]}
+ */
+export function extent(data, field) {
+  let min = Infinity, max = -Infinity;
+  for (let i = 0; i < data.length; i++) {
+    const v = +data[i][field];
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  return [min, max];
+}
+
+/**
+ * Get unique values of a field (preserving order).
+ * @param {Object[]} data
+ * @param {string} field
+ * @returns {any[]}
+ */
+export function unique(data, field) {
+  const seen = new Set();
+  const result = [];
+  for (let i = 0; i < data.length; i++) {
+    const v = data[i][field];
+    if (!seen.has(v)) {
+      seen.add(v);
+      result.push(v);
+    }
+  }
+  return result;
+}
+
+/**
+ * Group data by a field value.
+ * @param {Object[]} data
+ * @param {string} field
+ * @returns {Map<any, Object[]>}
+ */
+export function groupBy(data, field) {
+  const groups = new Map();
+  for (let i = 0; i < data.length; i++) {
+    const key = data[i][field];
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(data[i]);
+  }
+  return groups;
+}
+
+/**
+ * LTTB downsampling — Largest Triangle Three Buckets.
+ * Preserves visual shape of time series for line/area charts.
+ * @param {Object[]} data — sorted by x
+ * @param {string} xField
+ * @param {string} yField
+ * @param {number} targetCount — desired output length
+ * @returns {Object[]}
+ */
+export function downsampleLTTB(data, xField, yField, targetCount) {
+  if (data.length <= targetCount) return data;
+
+  const result = [data[0]]; // Always keep first
+  const bucketSize = (data.length - 2) / (targetCount - 2);
+
+  let prevIndex = 0;
+  for (let i = 1; i < targetCount - 1; i++) {
+    const bucketStart = Math.floor((i - 1) * bucketSize) + 1;
+    const bucketEnd = Math.min(Math.floor(i * bucketSize) + 1, data.length - 1);
+    const nextBucketStart = Math.min(Math.floor(i * bucketSize) + 1, data.length - 1);
+    const nextBucketEnd = Math.min(Math.floor((i + 1) * bucketSize) + 1, data.length - 1);
+
+    // Average of next bucket
+    let avgX = 0, avgY = 0, count = 0;
+    for (let j = nextBucketStart; j <= nextBucketEnd; j++) {
+      avgX += +data[j][xField];
+      avgY += +data[j][yField];
+      count++;
+    }
+    avgX /= count;
+    avgY /= count;
+
+    // Find point in current bucket with largest triangle area
+    let maxArea = -1;
+    let maxIndex = bucketStart;
+    const px = +data[prevIndex][xField];
+    const py = +data[prevIndex][yField];
+
+    for (let j = bucketStart; j <= bucketEnd; j++) {
+      const area = Math.abs(
+        (px - avgX) * (+data[j][yField] - py) -
+        (px - +data[j][xField]) * (avgY - py)
+      );
+      if (area > maxArea) {
+        maxArea = area;
+        maxIndex = j;
+      }
+    }
+
+    result.push(data[maxIndex]);
+    prevIndex = maxIndex;
+  }
+
+  result.push(data[data.length - 1]); // Always keep last
+  return result;
+}
+
+/**
+ * Pad a numeric extent by a fraction for visual breathing room.
+ * @param {[number, number]} ext
+ * @param {number} fraction — default 0.05 (5%)
+ * @returns {[number, number]}
+ */
+export function padExtent(ext, fraction = 0.05) {
+  const span = ext[1] - ext[0] || 1;
+  const pad = span * fraction;
+  return [ext[0] - pad, ext[1] + pad];
+}
+
+/**
+ * Detect if values look like dates.
+ * @param {any[]} values
+ * @returns {boolean}
+ */
+export function isDateLike(values) {
+  if (!values.length) return false;
+  const v = values[0];
+  if (v instanceof Date) return true;
+  if (typeof v === 'string' && !isNaN(Date.parse(v))) return true;
+  return false;
+}
+
+/**
+ * Parse a value as a Date if needed.
+ * @param {any} v
+ * @returns {Date}
+ */
+export function toDate(v) {
+  return v instanceof Date ? v : new Date(v);
+}