ggaction 0.0.11 → 0.0.13

package/src/grammar/transforms.js

@@ -1,11 +1,15 @@
 import { isPlainObject } from "../core/immutable.js";
 import { validateBoxTransform } from "./boxPlot.js";
+import { validateBinTransform } from "./bin.js";
 import {
   requestedBin2DTransform,
   validateBin2DTransform
 } from "./bin2d.js";
 import { validateDensityTransform } from "./density.js";
+import { validateECDFTransform } from "./ecdf.js";
+import { validateComputedTransform } from "./computed.js";
 import { validateFilterTransform } from "./filter.js";
+import { validateFoldTransform } from "./fold.js";
 import {
   requestedGradientProfileTransform,
   validateGradientProfileTransform
@@ -19,6 +23,8 @@ import { validateMarkFilterTransform } from "./markFilter.js";
 import { validateRegressionTransform } from "./regression/index.js";
 import { validateWindowTransform } from "./window.js";
 import { validateTimeUnitTransform } from "./timeUnit.js";
+import { validateSummaryTransform } from "./summary.js";
+import { validateStackTransform } from "./stack.js";
 import { findTransformTopology } from "./transformTopology.js";
 
 function requestedDensityTransform(transform) {
@@ -44,12 +50,22 @@ function facetHorizonTransform(transform, { scales = {} } = {}) {
 }
 
 const TRANSFORM_POLICIES = Object.freeze({
+  bin: Object.freeze({
+    ...findTransformTopology("bin"),
+    validate: validateBinTransform,
+    materializeOp: "materializeBinData"
+  }),
   bin2d: Object.freeze({
     ...findTransformTopology("bin2d"),
     validate: validateBin2DTransform,
     materializeOp: "materializeBin2DData",
     replayTransform: requestedBin2DTransform
   }),
+  computed: Object.freeze({
+    ...findTransformTopology("computed"),
+    validate: validateComputedTransform,
+    materializeOp: "materializeComputedData"
+  }),
   boxOutlier: Object.freeze({
     ...findTransformTopology("boxOutlier"),
     validate: validateBoxTransform,
@@ -66,11 +82,21 @@ const TRANSFORM_POLICIES = Object.freeze({
     materializeOp: "materializeDensityData",
     replayTransform: requestedDensityTransform
   }),
+  ecdf: Object.freeze({
+    ...findTransformTopology("ecdf"),
+    validate: validateECDFTransform,
+    materializeOp: "materializeECDFData"
+  }),
   filter: Object.freeze({
     ...findTransformTopology("filter"),
     validate: validateFilterTransform,
     materializeOp: "materializeFilteredData"
   }),
+  fold: Object.freeze({
+    ...findTransformTopology("fold"),
+    validate: validateFoldTransform,
+    materializeOp: "materializeFoldData"
+  }),
   gradientProfile: Object.freeze({
     ...findTransformTopology("gradientProfile"),
     validate: validateGradientProfileTransform,
@@ -99,6 +125,16 @@ const TRANSFORM_POLICIES = Object.freeze({
     validate: validateRegressionTransform,
     materializeOp: "materializeRegressionData"
   }),
+  summary: Object.freeze({
+    ...findTransformTopology("summary"),
+    validate: validateSummaryTransform,
+    materializeOp: "materializeSummaryData"
+  }),
+  stack: Object.freeze({
+    ...findTransformTopology("stack"),
+    validate: validateStackTransform,
+    materializeOp: "materializeStackData"
+  }),
   timeUnit: Object.freeze({
     ...findTransformTopology("timeUnit"),
     validate: validateTimeUnitTransform,

package/src/grammar/valueFormat.js

@@ -0,0 +1,112 @@
+const NUMERIC_FORMAT = /^\.(0?\d|1[0-2])(f|%|e)$/;
+const TIME_DIRECTIVES = new Set(["Y", "m", "d", "b", "%"]);
+const MONTH_NAMES = Object.freeze([
+  "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+  "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
+]);
+
+export function isUtcValueFormat(format) {
+  if (typeof format !== "string") return false;
+  let directives = 0;
+  for (let index = 0; index < format.length; index += 1) {
+    if (format[index] !== "%") continue;
+    const directive = format[index + 1];
+    if (!TIME_DIRECTIVES.has(directive)) return false;
+    if (directive !== "%") directives += 1;
+    index += 1;
+  }
+  return directives > 0;
+}
+
+export function validateValueFormat(format, label = "Label format", {
+  allowDecimalsObject = false
+} = {}) {
+  if (format === undefined || format === "auto") return format ?? "auto";
+  if (
+    format !== null &&
+    typeof format === "object" &&
+    Number.isInteger(format.decimals) &&
+    format.decimals >= 0 &&
+    format.decimals <= 100 &&
+    Object.keys(format).length === 1
+  ) {
+    if (allowDecimalsObject) return format;
+  }
+  if (typeof format === "string" && (
+    NUMERIC_FORMAT.test(format) || isUtcValueFormat(format)
+  )) {
+    return format;
+  }
+  const numericCandidate = typeof format === "string"
+    ? format.match(/^\.(\d+)(f|%|e)$/)
+    : undefined;
+  if (numericCandidate && Number(numericCandidate[1]) > 12) {
+    throw new RangeError(`${label} numeric format supports at most 12 decimals.`);
+  }
+  throw new TypeError(
+    `${label} must be auto${allowDecimalsObject ? ", { decimals }," : ","} or a supported format string (numeric or UTC).`
+  );
+}
+
+function pad(value, length = 2) {
+  return String(value).padStart(length, "0");
+}
+
+function formatUtcValue(value, format, label) {
+  const date = new Date(value);
+  if (!Number.isFinite(date.getTime())) {
+    throw new TypeError(`${label} requires a valid date or timestamp.`);
+  }
+  const values = {
+    Y: pad(date.getUTCFullYear(), 4),
+    m: pad(date.getUTCMonth() + 1),
+    d: pad(date.getUTCDate()),
+    b: MONTH_NAMES[date.getUTCMonth()]
+  };
+  return format.replace(/%([Ymdb%])/g, (_, directive) =>
+    directive === "%" ? "%" : values[directive]
+  );
+}
+
+export function formatValue(value, {
+  format = "auto",
+  valueType,
+  autoFormatter = current => String(current),
+  label = "Label format",
+  allowDecimalsObject = false
+} = {}) {
+  const resolved = validateValueFormat(format, label, {
+    allowDecimalsObject
+  });
+  if (value === undefined || value === null) return undefined;
+  if (resolved === "auto") return autoFormatter(value);
+  if (["nominal", "ordinal", "discrete"].includes(valueType)) {
+    throw new Error('Discrete labels require format "auto".');
+  }
+  const utc = isUtcValueFormat(resolved);
+  if (valueType === "temporal") {
+    if (!utc) throw new Error("Temporal labels require a supported UTC format string.");
+    return formatUtcValue(value, resolved, label);
+  }
+  if (utc) {
+    if (valueType === "quantitative") {
+      throw new Error("Quantitative labels cannot use a UTC format string.");
+    }
+    return formatUtcValue(value, resolved, label);
+  }
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`${label} "${typeof resolved === "string" ? resolved : "decimals"}" requires a finite number.`);
+  }
+  if (typeof resolved === "object") return value.toFixed(resolved.decimals);
+  const match = resolved.match(NUMERIC_FORMAT);
+  const precision = Number(match[1]);
+  if (match[2] === "f") return value.toFixed(precision);
+  if (match[2] === "%") {
+    const percentage = value * 100;
+    if (!Number.isFinite(percentage)) {
+      throw new RangeError(`${label} percent format overflow.`);
+    }
+    return `${percentage.toFixed(precision)}%`;
+  }
+  return value.toExponential(precision);
+}

package/src/grammar/window.js

@@ -336,10 +336,16 @@ function stableWindowOutput(operation, calculate) {
   }
 }
 
+function setWindowOutput(entry, field, value) {
+  Object.defineProperty(entry.row, field, {
+    value, enumerable: true, writable: true, configurable: true
+  });
+}
+
 function applyOperation(partition, operation, sortBy) {
   if (operation.op === "rowNumber") {
     partition.forEach((entry, index) => {
-      entry.row[operation.as] = index + 1;
+      setWindowOutput(entry, operation.as, index + 1);
     });
     return;
   }
@@ -354,7 +360,7 @@ function applyOperation(partition, operation, sortBy) {
         rank = index + 1;
         denseRank += 1;
       }
-      entry.row[operation.as] = operation.op === "rank" ? rank : denseRank;
+      setWindowOutput(entry, operation.as, operation.op === "rank" ? rank : denseRank);
     });
     return;
   }
@@ -364,7 +370,7 @@ function applyOperation(partition, operation, sortBy) {
       stableFinitePrefixSums(values, label)
     );
     partition.forEach((entry, index) => {
-      entry.row[operation.as] = totals[index];
+      setWindowOutput(entry, operation.as, totals[index]);
     });
     return;
   }
@@ -379,18 +385,18 @@ function applyOperation(partition, operation, sortBy) {
         index + operation.frame.following
       );
       const values = operationValues(partition, operation, first, last);
-      entry.row[operation.as] = stableWindowOutput(operation, label =>
+      setWindowOutput(entry, operation.as, stableWindowOutput(operation, label =>
         calculate(values, label)
-      );
+      ));
     });
     return;
   }
   const direction = operation.op === "lag" ? -1 : 1;
   partition.forEach((entry, index) => {
     const peer = partition[index + direction * operation.offset];
-    entry.row[operation.as] = peer === undefined
+    setWindowOutput(entry, operation.as, peer === undefined
       ? operation.default
-      : peer.row[operation.field];
+      : peer.row[operation.field]);
   });
 }
 

package/src/layout/facets.js

@@ -9,6 +9,11 @@ import {
 
 export const DEFAULT_FACET_LEGEND_GAP = 18;
 export const DEFAULT_FACET_LEGEND_WIDTH = 132;
+export const DEFAULT_FACET_LEGEND_HEIGHT = 0;
+
+const FACET_LEGEND_POSITIONS = Object.freeze([
+  "right", "left", "top", "bottom"
+]);
 
 function resolveColumns(columns, count) {
   const value = columns ?? count;
@@ -18,6 +23,29 @@ function resolveColumns(columns, count) {
   return Math.min(value, count);
 }
 
+function resolveGridCoordinates(children, columns) {
+  const requested = children.some(child => child.row !== undefined || child.column !== undefined);
+  if (!requested) return undefined;
+  if (children.some(child => !(
+    Number.isInteger(child.row) && child.row >= 0 &&
+    Number.isInteger(child.column) && child.column >= 0
+  ))) {
+    throw new RangeError("Facet grid children require non-negative integer row and column coordinates.");
+  }
+  const keys = children.map(child => `${child.row}:${child.column}`);
+  if (new Set(keys).size !== keys.length) {
+    throw new Error("Facet grid children must occupy unique row and column coordinates.");
+  }
+  const requiredColumns = Math.max(...children.map(child => child.column)) + 1;
+  if (columns !== undefined && columns !== requiredColumns) {
+    throw new RangeError("Facet grid columns must match the declared column domain.");
+  }
+  return {
+    columns: requiredColumns,
+    rows: Math.max(...children.map(child => child.row)) + 1
+  };
+}
+
 function alignedOffset(remaining, align) {
   if (align === "start") return 0;
   if (align === "end") return remaining;
@@ -33,13 +61,17 @@ export function resolveFacetLayout({
   titleHeight = 0,
   sharedLegend = false,
   sharedLegendGap = DEFAULT_FACET_LEGEND_GAP,
-  sharedLegendWidth = DEFAULT_FACET_LEGEND_WIDTH
+  sharedLegendWidth = DEFAULT_FACET_LEGEND_WIDTH,
+  sharedLegendHeight = DEFAULT_FACET_LEGEND_HEIGHT,
+  sharedLegendPosition = "right"
 } = {}) {
   const values = children?.map(child => child?.value);
+  const coordinates = resolveGridCoordinates(children ?? [], columns);
   const resolvedChildren = normalizeCompositionChildren(children?.map(
-    ({ value: _value, ...child }) => child
+    ({ value: _value, row: _row, column: _column, ...child }) => child
   ));
-  const resolvedColumns = resolveColumns(columns, resolvedChildren.length);
+  const resolvedColumns = coordinates?.columns ??
+    resolveColumns(columns, resolvedChildren.length);
   const resolvedGap = validateCompositionSpacing(gap, "Facet gap");
   const resolvedAlign = normalizeCompositionAlign(align);
   const resolvedPadding = normalizeCompositionPadding(padding);
@@ -58,12 +90,31 @@ export function resolveFacetLayout({
     sharedLegendWidth,
     "Facet shared legend width"
   );
-  const rowCount = Math.ceil(resolvedChildren.length / resolvedColumns);
+  const legendHeight = validateCompositionSpacing(
+    sharedLegendHeight,
+    "Facet shared legend height"
+  );
+  if (!FACET_LEGEND_POSITIONS.includes(sharedLegendPosition)) {
+    throw new Error(
+      `Unknown facet shared legend position "${sharedLegendPosition}".`
+    );
+  }
+  const sideLegend = ["right", "left"].includes(sharedLegendPosition);
+  const beforeGrid = ["left", "top"].includes(sharedLegendPosition);
+  const legendLane = sharedLegend
+    ? legendGap + (sideLegend ? legendWidth : legendHeight)
+    : 0;
+  const rowCount = coordinates?.rows ??
+    Math.ceil(resolvedChildren.length / resolvedColumns);
   const columnWidths = Array(resolvedColumns).fill(-Infinity);
   const rowHeights = Array(rowCount).fill(-Infinity);
   resolvedChildren.forEach((child, index) => {
-    const column = index % resolvedColumns;
-    const row = Math.floor(index / resolvedColumns);
+    const column = coordinates === undefined
+      ? index % resolvedColumns
+      : children[index].column;
+    const row = coordinates === undefined
+      ? Math.floor(index / resolvedColumns)
+      : children[index].row;
     columnWidths[column] = Math.max(columnWidths[column], child.width);
     rowHeights[row] = Math.max(rowHeights[row], child.height);
   });
@@ -76,21 +127,27 @@ export function resolveFacetLayout({
       .reduce((sum, height) => sum + height, 0) + resolvedGap * row
   );
   const placements = resolvedChildren.map((child, index) => {
-    const column = index % resolvedColumns;
-    const row = Math.floor(index / resolvedColumns);
+    const column = coordinates === undefined
+      ? index % resolvedColumns
+      : children[index].column;
+    const row = coordinates === undefined
+      ? Math.floor(index / resolvedColumns)
+      : children[index].row;
     return {
       id: child.id,
       value: values[index],
       column,
       row,
-      x: columnStarts[column] + alignedOffset(
-        columnWidths[column] - child.width,
-        resolvedAlign
-      ),
-      y: rowStarts[row] + alignedOffset(
-        rowHeights[row] - child.height,
-        resolvedAlign
-      ),
+      x: columnStarts[column] + (beforeGrid && sideLegend ? legendLane : 0) +
+        alignedOffset(
+          columnWidths[column] - child.width,
+          resolvedAlign
+        ),
+      y: rowStarts[row] + (beforeGrid && !sideLegend ? legendLane : 0) +
+        alignedOffset(
+          rowHeights[row] - child.height,
+          resolvedAlign
+        ),
       width: child.width,
       height: child.height
     };
@@ -111,16 +168,22 @@ export function resolveFacetLayout({
     padding: resolvedPadding,
     titleHeight: resolvedTitleHeight,
     gridWidth,
-    width: gridWidth + (sharedLegend
-      ? legendGap + legendWidth
-      : 0),
-    height: gridHeight,
+    width: gridWidth + (sideLegend ? legendLane : 0),
+    height: gridHeight + (sideLegend ? 0 : legendLane),
     children: placements,
     ...(sharedLegend ? {
       legend: {
-        x: gridWidth + legendGap,
-        y: resolvedTitleHeight + resolvedPadding.top + 30,
-        width: legendWidth
+        position: sharedLegendPosition,
+        x: sharedLegendPosition === "right"
+          ? gridWidth + legendGap
+          : 0,
+        y: sharedLegendPosition === "bottom"
+          ? gridHeight + legendGap
+          : sharedLegendPosition === "top"
+            ? resolvedTitleHeight
+            : resolvedTitleHeight + resolvedPadding.top + 30,
+        width: legendWidth,
+        height: legendHeight
       }
     } : {})
   });

package/src/layout/guideCollisions.js

@@ -0,0 +1,12 @@
+export function assertGuideCollisionBlocks(blocks) {
+  for (let index = 0; index < blocks.length; index += 1) {
+    const a = blocks[index];
+    for (const b of blocks.slice(index + 1)) {
+      if (a.position !== b.position || a.kind === "axis" && b.kind === "axis") continue;
+      if (a.bounds.left < b.bounds.right && a.bounds.right > b.bounds.left &&
+        a.bounds.top < b.bounds.bottom && a.bounds.bottom > b.bounds.top) {
+        throw new Error(`The ${a.position} ${a.id} and ${b.id} overlap; guides require more margin space or different offsets.`);
+      }
+    }
+  }
+}

package/src/layout/legend.js

@@ -3,19 +3,11 @@ import {
   measureTextWidth
 } from "../core/textMetrics.js";
 
-export function measureLegendSymbolHeight(config) {
-  return Math.max(...config.symbol.layers.map(layer => {
-    if (layer.type === "swatch") return layer.height;
-    if (layer.type === "point") return layer.size * 2;
-    return layer.lineWidth;
-  }));
-}
-
 export function measureLegendTextWidth(value, style = { fontSize: 12 }) {
   return measureTextWidth(formatVisibleText(value), style);
 }
 
-export function resolveLegendGrid(config, width, count) {
+export function resolveLegendGrid(config, width, count, symbolHeight) {
   const labels = config.domain.map(formatVisibleText);
   const itemWidths = labels.map(
     label => width + config.labels.offset +
@@ -39,7 +31,7 @@ export function resolveLegendGrid(config, width, count) {
     config.itemGap * Math.max(0, actualColumns - 1);
   const rowHeight = Math.max(
     config.labels.fontSize,
-    measureLegendSymbolHeight(config)
+    symbolHeight
   );
   const gridHeight = rowHeight * rowCount +
     config.itemGap * Math.max(0, rowCount - 1);

package/src/layout/legendItems.js

@@ -0,0 +1,102 @@
+import { measureTextWidth, resolveTextBounds } from "../core/textMetrics.js";
+import { alignLegendStart, resolveLegendGrid } from "./legend.js";
+
+// Measure item content before choosing its edge. Family owners supply the
+// sample dimensions and formatted labels; this module does not inspect scales.
+export function resolveLegendItemLayout(plot, config, labels, symbol, canvas) {
+  const strokes = labels.map((_, index) => Array.isArray(symbol.strokeWidth)
+    ? symbol.strokeWidth[index] : symbol.strokeWidth ?? 0);
+  const sampleBounds = labels.map((_, index) => symbol.itemBounds?.[index] ?? {
+    left: -strokes[index] / 2, right: symbol.width + strokes[index] / 2,
+    top: -symbol.height / 2 - strokes[index] / 2,
+    bottom: symbol.height / 2 + strokes[index] / 2
+  });
+  // Retain a family's minimum slot while reserving its complete painted extent.
+  const sampleLeft = Math.min(0, ...sampleBounds.map(bounds => bounds.left));
+  const sampleRight = Math.max(symbol.width, ...sampleBounds.map(bounds => bounds.right));
+  const sampleWidth = sampleRight - sampleLeft;
+  const sampleHeight = Math.max(symbol.height,
+    ...sampleBounds.map(bounds => 2 * Math.max(-bounds.top, bounds.bottom)));
+  const side = ["left", "right"].includes(config.position);
+  const titleVisible = config.titleVisible !== false;
+  const titleWidth = titleVisible ? measureTextWidth(config.title, config.titleStyle) : 0;
+  const titleHeight = titleVisible ? config.titleStyle.fontSize : 0;
+  const itemWidth = sampleWidth + config.labels.offset + Math.max(...labels.map(
+    text => measureTextWidth(text, config.labels)
+  ));
+  let symbolX;
+  let labelX;
+  let itemY;
+  let title;
+  if (config.layout === "legacy-bottom") {
+    const widths = labels.map(text => sampleWidth + config.labels.offset + measureTextWidth(text, config.labels));
+    const width = widths.reduce((sum, value) => sum + value, 0) + config.itemGap * (labels.length - 1);
+    const x = config.align === "center" ? (canvas.width - width) / 2 : alignLegendStart(plot, width, config.align);
+    let cursor = x;
+    symbolX = widths.map(width => {
+      const start = cursor - sampleLeft;
+      cursor += width + config.itemGap;
+      return start;
+    });
+    labelX = symbolX.map(value => value + sampleRight + config.labels.offset);
+    itemY = labels.map(() => canvas.height - 28);
+    title = { x: x + width / 2, y: canvas.height - 52, align: "center" };
+  } else if (side) {
+    const width = Math.max(itemWidth, titleWidth);
+    const x = config.position === "right" ? plot.x + plot.width + config.offset
+      : plot.x - config.offset - width;
+    const itemHeight = Math.max(sampleHeight, config.labels.fontSize);
+    const pitch = Math.max(config.itemGap, itemHeight);
+    symbolX = labels.map(() => x - sampleLeft);
+    labelX = labels.map(() => x + sampleWidth + config.labels.offset);
+    const firstY = Math.max(plot.y + 52, titleVisible
+      ? plot.y + 20 + titleHeight / 2 + 12 + itemHeight / 2 : plot.y + 52);
+    itemY = labels.map((_, index) => firstY + index * pitch);
+    title = { x, y: plot.y + 20, align: "left" };
+  } else {
+    const grid = resolveLegendGrid({ ...config, domain: labels }, sampleWidth, labels.length, sampleHeight);
+    const inline = config.titlePosition === "left" && titleVisible;
+    const prefix = inline ? titleWidth + 20 : 0;
+    const width = inline ? prefix + grid.gridWidth : Math.max(titleWidth, grid.gridWidth);
+    const top = !inline && titleVisible ? titleHeight + 12 : 0;
+    const height = inline ? Math.max(titleHeight, grid.gridHeight) : top + grid.gridHeight;
+    const x = alignLegendStart(plot, width, config.align);
+    const y = config.position === "top" ? plot.y - config.offset - height
+      : plot.y + plot.height + config.offset;
+    const gridX = inline ? x + prefix : x + (width - grid.gridWidth) / 2;
+    const gridY = inline ? y + (height - grid.gridHeight) / 2 : y + top;
+    let cursor = 0;
+    const columns = grid.columnWidths.map(width => {
+      const start = cursor;
+      cursor += width + config.itemGap;
+      return start;
+    });
+    symbolX = grid.cells.map(cell => gridX + columns[cell.column] - sampleLeft);
+    labelX = symbolX.map(value => value + sampleRight + config.labels.offset);
+    itemY = grid.cells.map(cell => gridY + grid.rowHeight / 2 + cell.row * (grid.rowHeight + config.itemGap));
+    title = inline ? { x, y: y + height / 2, align: "left" }
+      : { x: x + width / 2, y: y + titleHeight / 2, align: "center" };
+  }
+  const textBounds = (x, y, text, style, align = "left") => resolveTextBounds({
+    x, y, text, ...style, textAlign: align, textBaseline: "middle"
+  });
+  const bounds = [
+    ...(titleVisible ? [textBounds(title.x, title.y, config.title, config.titleStyle, title.align)] : []),
+    ...labels.map((label, index) => textBounds(labelX[index], itemY[index], label, config.labels)),
+    ...symbolX.map((x, index) => {
+      const local = sampleBounds[index];
+      return { left: x + local.left, right: x + local.right,
+        top: itemY[index] + local.top, bottom: itemY[index] + local.bottom };
+    })
+  ];
+  if (config.layout === "legacy-bottom") {
+    const itemBounds = titleVisible ? bounds.slice(1) : bounds;
+    if (titleVisible && itemBounds.some(bound => bound.top < bounds[0].bottom)) {
+      throw new Error("Legacy bottom legend requires more space between its fixed title and item rows.");
+    }
+    if (bounds.some(bound => bound.top <= plot.y + plot.height)) {
+      throw new Error("Legacy bottom legend requires more bottom-margin space.");
+    }
+  }
+  return { symbolX, labelX, itemY, title, bounds };
+}