ggaction 0.0.12 → 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

@@ -23,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;
@@ -43,10 +66,12 @@ export function resolveFacetLayout({
   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);
@@ -79,12 +104,17 @@ export function resolveFacetLayout({
   const legendLane = sharedLegend
     ? legendGap + (sideLegend ? legendWidth : legendHeight)
     : 0;
-  const rowCount = Math.ceil(resolvedChildren.length / resolvedColumns);
+  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);
   });
@@ -97,8 +127,12 @@ 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],

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 };
+}

package/src/layout/legendLane.js

@@ -4,6 +4,28 @@ export const SIDE_LEGEND_SYMBOL_CENTER = 16;
 export const SIDE_LEGEND_LABEL_START = 44;
 export const HORIZONTAL_LEGEND_TITLE_ELEMENT_GAP = 12;
 
+export function isHorizontalEdgeLegend(config) {
+  return config !== undefined &&
+    ["top", "bottom"].includes(config.position) &&
+    config.layout !== "legacy-bottom";
+}
+
+export function resolveSingleHorizontalLegendPlacement({ plot, canvas, config, bounds }) {
+  if (!isHorizontalEdgeLegend(config)) {
+    throw new Error("Single legend placement requires a horizontal edge layout.");
+  }
+  const dx = config.align === "left" ? plot.x - bounds.left
+    : config.align === "right" ? plot.x + plot.width - bounds.right
+      : plot.x + plot.width / 2 - midpoint(bounds.left, bounds.right);
+  const dy = config.position === "top" ? plot.y - config.offset - bounds.bottom
+    : plot.y + plot.height + config.offset - bounds.top;
+  const occupied = translateBounds(bounds, dx, dy);
+  if (occupied.left < 0 || occupied.right > canvas.width || occupied.top < 0 || occupied.bottom > canvas.height) {
+    throw new Error(`Legend layout requires more ${config.position}-margin or Canvas space.`);
+  }
+  return { dx, dy, occupied };
+}
+
 function midpoint(start, end) {
   const sum = start + end;
   const result = Number.isFinite(sum) ? sum / 2 : start / 2 + end / 2;
@@ -25,24 +47,25 @@ function decoration(border) {
     : border.padding + border.lineWidth / 2;
 }
 
-function horizontalExtent(blocks) {
+function horizontalExtent(blocks, labelStart) {
   let left = 0;
   let right = 0;
   for (const block of blocks) {
-    if (block.title !== undefined) right = Math.max(right, block.title.width);
+    const inset = block.inset ?? 0;
+    if (block.title !== undefined) right = Math.max(right, block.title.width + inset);
     left = Math.min(left,
-      SIDE_LEGEND_SYMBOL_CENTER + block.symbol.left - block.symbol.centerX
+      SIDE_LEGEND_SYMBOL_CENTER + block.symbol.left - block.symbol.centerX - inset
     );
     right = Math.max(
       right,
-      SIDE_LEGEND_SYMBOL_CENTER + block.symbol.right - block.symbol.centerX,
-      SIDE_LEGEND_LABEL_START + block.labels.width
+      SIDE_LEGEND_SYMBOL_CENTER + block.symbol.right - block.symbol.centerX + inset,
+      labelStart + block.labels.width + inset
     );
   }
   return { left, right };
 }
 
-function placeBlock(block, cursor) {
+function placeBlock(block, cursor, labelStart) {
   let dy;
   if (block.title === undefined) {
     dy = cursor - block.bounds.top;
@@ -65,7 +88,7 @@ function placeBlock(block, cursor) {
       ? undefined
       : -block.title.x,
     symbolDx: SIDE_LEGEND_SYMBOL_CENTER - block.symbol.centerX,
-    labelDx: SIDE_LEGEND_LABEL_START - block.labels.x,
+    labelDx: labelStart - block.labels.x,
     bounds
   };
 }
@@ -87,7 +110,10 @@ export function resolveSideLegendLane({
   }
   const blocks = groups.flatMap(group => group.blocks);
   if (blocks.length < 2) return undefined;
-  const laneExtent = horizontalExtent(blocks);
+  const labelStart = Math.max(SIDE_LEGEND_LABEL_START, ...blocks.map(
+    block => SIDE_LEGEND_SYMBOL_CENTER + Math.abs(block.labels.x - block.symbol.centerX)
+  ));
+  const laneExtent = horizontalExtent(blocks, labelStart);
   const offset = blocks.reduce(
     (maximum, block) => Math.max(maximum, block.offset),
     -Infinity
@@ -96,7 +122,7 @@ export function resolveSideLegendLane({
     ? plot.x + plot.width + offset
     : plot.x - offset - laneExtent.right;
   const symbolCenterX = titleStartX + SIDE_LEGEND_SYMBOL_CENTER;
-  const labelStartX = titleStartX + SIDE_LEGEND_LABEL_START;
+  const labelStartX = titleStartX + labelStart;
   const first = blocks[0];
   let cursor = first.title === undefined
     ? plot.y + 12
@@ -110,7 +136,7 @@ export function resolveSideLegendLane({
     if (occupiedGroups.length > 0) cursor += inset;
     const groupPlacements = [];
     for (const block of group.blocks) {
-      const placement = placeBlock(block, cursor);
+      const placement = placeBlock(block, cursor, labelStart);
       groupPlacements.push(placement);
       placements.push({
         ...placement,
@@ -123,7 +149,7 @@ export function resolveSideLegendLane({
       cursor = placement.bounds.bottom + SIDE_LEGEND_BLOCK_GAP;
     }
     const vertical = unionBounds(groupPlacements.map(item => item.bounds));
-    const groupExtent = horizontalExtent(group.blocks);
+    const groupExtent = horizontalExtent(group.blocks, labelStart);
     const foreground = {
       left: titleStartX + groupExtent.left,
       right: titleStartX + groupExtent.right,
@@ -232,6 +258,13 @@ function normalizeHorizontalRow(entries) {
       )
     : commonTitleY + titleDescent + HORIZONTAL_LEGEND_TITLE_ELEMENT_GAP;
   return entries.map(({ group, dx }) => {
+    if (group.atomic) {
+      const contentDy = elementAnchor - group.element.top;
+      const foreground = translateBounds(group.content, dx, contentDy);
+      return { id: group.id, dx, titleDy: contentDy, contentDy, foreground,
+        occupied: expandBounds(foreground, group.inset), padding: group.padding,
+        backgroundId: group.backgroundId };
+    }
     const contentDy = commonTitleY === undefined
       ? elementAnchor - midpoint(
           group.element.top,
@@ -350,3 +383,59 @@ export function resolveHorizontalLegendLane({
     rowCount: packed.length
   };
 }
+
+// Compose independently measured content blocks before the outer edge lane
+// treats the whole group as one indivisible item.
+export function resolveHorizontalLegendGroup({ edge, plot, canvas, groups,
+  align, offset, border, backgroundId, collisionBounds = [] }) {
+  const inset = decoration(border);
+  const innerPlot = { ...plot, x: plot.x + inset, width: plot.width - inset * 2 };
+  const packed = packHorizontalRows(groups, innerPlot);
+  const rows = packed.map(normalizeHorizontalRow);
+  let cursor = 0;
+  const placements = [];
+  for (const row of rows) {
+    const bounds = unionBounds(row.map(item => item.occupied));
+    const dy = edge === "top" ? cursor - bounds.bottom : cursor - bounds.top;
+    const translated = row.map(item => translateHorizontalPlacement(item, dy));
+    placements.push(...translated);
+    const occupied = unionBounds(translated.map(item => item.occupied));
+    cursor = edge === "top" ? occupied.top - HORIZONTAL_LEGEND_BLOCK_GAP
+      : occupied.bottom + HORIZONTAL_LEGEND_BLOCK_GAP;
+  }
+  const foreground = unionBounds(placements.map(item => item.occupied));
+  const occupied = expandBounds(foreground, inset);
+  const width = occupied.right - occupied.left;
+  const x = align === "left" ? plot.x : align === "right" ? plot.x + plot.width - width
+    : plot.x + (plot.width - width) / 2;
+  const dx = x - occupied.left;
+  const dy = edge === "top" ? plot.y - offset - occupied.bottom
+    : plot.y + plot.height + offset - occupied.top;
+  const finalBounds = translateBounds(occupied, dx, dy);
+  if (finalBounds.left < 0 || finalBounds.right > canvas.width ||
+    finalBounds.top < 0 || finalBounds.bottom > canvas.height) {
+    throw new Error(`Combined legend requires more ${edge}-margin or Canvas space.`);
+  }
+  if (collisionBounds.some(bounds => overlap(finalBounds, bounds))) {
+    throw new Error(`Combined ${edge} legend and ${edge === "top" ? "chart titles" : "x-axis guides"} require more margin space.`);
+  }
+  return {
+    placements: placements.map(item => ({ ...item, dx: item.dx + dx,
+      titleDy: item.titleDy + dy, contentDy: item.contentDy + dy,
+      ...(item.backgroundId === undefined ? {} : { background: {
+        id: item.backgroundId,
+        x: item.foreground.left + dx - item.padding,
+        y: item.foreground.top + dy - item.padding,
+        width: item.foreground.right - item.foreground.left + item.padding * 2,
+        height: item.foreground.bottom - item.foreground.top + item.padding * 2
+      } }) })),
+    occupied: finalBounds,
+    background: backgroundId === undefined ? undefined : {
+      id: backgroundId,
+      x: foreground.left + dx - border.padding,
+      y: foreground.top + dy - border.padding,
+      width: foreground.right - foreground.left + border.padding * 2,
+      height: foreground.bottom - foreground.top + border.padding * 2
+    }
+  };
+}