ggaction 0.0.12 → 0.0.15

package/src/layout/labels.js

@@ -19,6 +19,349 @@ const MAX_EXHAUSTIVE_OFFSET_STEPS = 28;
 const MAX_SEARCH_DISPLACEMENT = 1_000_000;
 const DISTANT_RING_COUNT = 16;
 const DISTANT_ANGLE_COUNT = 32;
+const PLACEMENT_OPTIONS = Object.freeze([
+  "anchor", "gap", "overflow", "leader"
+]);
+const PLACEMENT_LEADER_OPTIONS = Object.freeze(["stroke", "strokeWidth"]);
+const SEMANTIC_ANCHORS = new Set([
+  "center", "insideStart", "insideEnd", "outsideStart", "outsideEnd"
+]);
+const OVERFLOW_POLICIES = new Set(["hide", "outside", "allow"]);
+
+export const DEFAULT_MARK_LABEL_PLACEMENT = cloneAndFreeze({
+  gap: 4,
+  overflow: "hide",
+  leader: false
+});
+
+export function markLabelPlacementLeaderId(target) {
+  return `${target}-placement-leaders`;
+}
+
+function normalizePlacementLeader(value) {
+  if (value === undefined || value === false) return false;
+  validateOptionObject(value, PLACEMENT_LEADER_OPTIONS, "mark label placement leader");
+  const leader = { stroke: "#94a3b8", strokeWidth: 1, ...value };
+  if (typeof leader.stroke !== "string" || leader.stroke.length === 0) {
+    throw new TypeError("Mark label placement leader stroke must be a non-empty string.");
+  }
+  validateNonNegativeFinite(
+    leader.strokeWidth,
+    "Mark label placement leader strokeWidth"
+  );
+  return leader;
+}
+
+export function normalizeMarkLabelPlacement(value) {
+  validateOptionObject(value, PLACEMENT_OPTIONS, "mark label placement", {
+    allowEmpty: false,
+    emptyError: TypeError
+  });
+  if (!SEMANTIC_ANCHORS.has(value.anchor)) {
+    throw new Error(`Unsupported mark label anchor "${value.anchor}".`);
+  }
+  const gap = value.gap ?? DEFAULT_MARK_LABEL_PLACEMENT.gap;
+  const overflowPolicy = value.overflow ?? DEFAULT_MARK_LABEL_PLACEMENT.overflow;
+  validateNonNegativeFinite(gap, "Mark label placement gap");
+  if (!OVERFLOW_POLICIES.has(overflowPolicy)) {
+    throw new Error(`Unsupported mark label overflow "${overflowPolicy}".`);
+  }
+  return cloneAndFreeze({
+    anchor: value.anchor,
+    gap,
+    overflow: overflowPolicy,
+    leader: normalizePlacementLeader(value.leader)
+  });
+}
+
+function finitePoint(value, label) {
+  if (
+    !isPlainObject(value) ||
+    !Number.isFinite(value.x) ||
+    !Number.isFinite(value.y)
+  ) {
+    throw new TypeError(`${label} requires finite x and y.`);
+  }
+  return value;
+}
+
+function unitVector(value, label) {
+  finitePoint(value, label);
+  const length = Math.hypot(value.x, value.y);
+  if (!Number.isFinite(length) || length <= 0) {
+    throw new RangeError(`${label} requires a non-zero direction.`);
+  }
+  return { x: value.x / length, y: value.y / length };
+}
+
+function validateIntervalBounds(bounds) {
+  if (
+    !isPlainObject(bounds) ||
+    ![bounds.left, bounds.right, bounds.top, bounds.bottom].every(Number.isFinite) ||
+    bounds.right < bounds.left ||
+    bounds.bottom < bounds.top
+  ) {
+    throw new RangeError("Interval label placement requires ordered finite bounds.");
+  }
+}
+
+function validatePlacementGeometry(geometry, anchor) {
+  if (!isPlainObject(geometry)) {
+    throw new TypeError("Mark label placement requires source geometry.");
+  }
+  if (geometry.kind === "interval") {
+    finitePoint(geometry.center, "Interval label center");
+    for (const role of ["start", "end"]) {
+      finitePoint(geometry[role]?.point, `Interval label ${role}`);
+      unitVector(geometry[role]?.outward, `Interval label ${role}`);
+    }
+    validateIntervalBounds(geometry.bounds);
+    return;
+  }
+  if (geometry.kind === "arc") {
+    if (![geometry.centerX, geometry.centerY, geometry.startTheta,
+      geometry.endTheta, geometry.innerRadius, geometry.outerRadius]
+      .every(Number.isFinite)) {
+      throw new TypeError("Arc label placement requires finite sector geometry.");
+    }
+    if (
+      geometry.innerRadius < 0 ||
+      geometry.outerRadius <= geometry.innerRadius ||
+      geometry.startTheta === geometry.endTheta ||
+      Math.abs(geometry.endTheta - geometry.startTheta) > 360
+    ) {
+      throw new RangeError("Arc label placement requires an ordered annular sector.");
+    }
+    return;
+  }
+  if (geometry.kind === "point") {
+    finitePoint(geometry.center, "Point label center");
+    if (anchor === "outsideEnd") {
+      finitePoint(geometry.end?.point, "Polar Point label boundary");
+      unitVector(geometry.end?.outward, "Polar Point label direction");
+    }
+    return;
+  }
+  throw new Error(`Unsupported mark label placement geometry "${geometry.kind}".`);
+}
+
+export function assertMarkLabelPlacementSupport({ markType, coordinateType, intervalAxis }, placement) {
+  const anchor = placement.anchor;
+  if (markType === "bar" || markType === "arc") return placement;
+  if (markType === "rect") {
+    if (anchor === "center" || intervalAxis !== undefined) return placement;
+    throw new Error("Rect semantic label placement requires one explicit interval axis.");
+  }
+  if (markType === "point") {
+    if (anchor === "center" || (coordinateType === "polar" && anchor === "outsideEnd")) {
+      return placement;
+    }
+    throw new Error(
+      coordinateType === "polar"
+        ? `Polar Point does not support mark label anchor "${anchor}".`
+        : `Point does not support mark label anchor "${anchor}".`
+    );
+  }
+  if (markType === "line") {
+    throw new Error("Line labels retain the endpoint API and do not accept semantic placement objects.");
+  }
+  if (markType === "rule") {
+    throw new Error("Rule labels do not support semantic placement objects.");
+  }
+  throw new Error(`Mark type "${markType}" does not support semantic label placement.`);
+}
+
+function localTextBounds(text) {
+  return resolveTextBounds({ ...text, x: 0, y: 0 });
+}
+
+function projectionRange(bounds, direction) {
+  const values = [
+    { x: bounds.left, y: bounds.top },
+    { x: bounds.right, y: bounds.top },
+    { x: bounds.right, y: bounds.bottom },
+    { x: bounds.left, y: bounds.bottom }
+  ].map(point => point.x * direction.x + point.y * direction.y);
+  return { minimum: Math.min(...values), maximum: Math.max(...values) };
+}
+
+function boundaryCandidate(boundary, direction, gap, text) {
+  const resolvedDirection = unitVector(direction, "Mark label placement direction");
+  const support = projectionRange(localTextBounds(text), resolvedDirection);
+  const distance = gap - support.minimum;
+  return {
+    x: boundary.x + resolvedDirection.x * distance + (text.dx ?? 0),
+    y: boundary.y + resolvedDirection.y * distance + (text.dy ?? 0),
+    sourceX: boundary.x,
+    sourceY: boundary.y
+  };
+}
+
+function centerCandidate(center, text) {
+  return {
+    x: center.x + (text.dx ?? 0),
+    y: center.y + (text.dy ?? 0),
+    sourceX: center.x,
+    sourceY: center.y
+  };
+}
+
+function candidateBounds(candidate, text) {
+  return resolveTextBounds({ ...text, x: candidate.x, y: candidate.y });
+}
+
+function intervalContains(bounds, container) {
+  const epsilon = 1e-9;
+  return bounds.left >= container.left - epsilon &&
+    bounds.right <= container.right + epsilon &&
+    bounds.top >= container.top - epsilon &&
+    bounds.bottom <= container.bottom + epsilon;
+}
+
+function distanceToRectangle(centerX, centerY, bounds) {
+  const x = Math.max(bounds.left, Math.min(centerX, bounds.right));
+  const y = Math.max(bounds.top, Math.min(centerY, bounds.bottom));
+  return Math.hypot(x - centerX, y - centerY);
+}
+
+function thetaForPoint(point, geometry) {
+  return Math.atan2(point.x - geometry.centerX, geometry.centerY - point.y) *
+    180 / Math.PI;
+}
+
+function angleWithin(theta, start, end) {
+  const sweep = end - start;
+  if (Math.abs(sweep) >= 360 - 1e-9) return true;
+  const direction = Math.sign(sweep);
+  const progress = ((direction * (theta - start)) % 360 + 360) % 360;
+  return progress <= Math.abs(sweep) + 1e-9;
+}
+
+function arcContains(bounds, geometry) {
+  const points = [
+    { x: bounds.left, y: bounds.top },
+    { x: bounds.right, y: bounds.top },
+    { x: bounds.right, y: bounds.bottom },
+    { x: bounds.left, y: bounds.bottom },
+    { x: (bounds.left + bounds.right) / 2, y: bounds.top },
+    { x: bounds.right, y: (bounds.top + bounds.bottom) / 2 },
+    { x: (bounds.left + bounds.right) / 2, y: bounds.bottom },
+    { x: bounds.left, y: (bounds.top + bounds.bottom) / 2 }
+  ];
+  const minimumRadius = distanceToRectangle(
+    geometry.centerX,
+    geometry.centerY,
+    bounds
+  );
+  const maximumRadius = Math.max(...points.slice(0, 4).map(point =>
+    Math.hypot(point.x - geometry.centerX, point.y - geometry.centerY)
+  ));
+  const epsilon = 1e-9;
+  return minimumRadius >= geometry.innerRadius - epsilon &&
+    maximumRadius <= geometry.outerRadius + epsilon &&
+    points.every(point => angleWithin(
+      thetaForPoint(point, geometry),
+      geometry.startTheta,
+      geometry.endTheta
+    ));
+}
+
+function arcRole(geometry, role) {
+  const theta = geometry.startTheta +
+    (geometry.endTheta - geometry.startTheta) / 2;
+  const radians = theta * Math.PI / 180;
+  const radial = { x: Math.sin(radians), y: -Math.cos(radians) };
+  const radius = role === "start" ? geometry.innerRadius : geometry.outerRadius;
+  return {
+    point: {
+      x: geometry.centerX + radial.x * radius,
+      y: geometry.centerY + radial.y * radius
+    },
+    outward: role === "start"
+      ? { x: -radial.x, y: -radial.y }
+      : radial
+  };
+}
+
+function geometryRole(geometry, role) {
+  return geometry.kind === "arc" ? arcRole(geometry, role) : geometry[role];
+}
+
+function geometryCenter(geometry) {
+  if (geometry.kind !== "arc") return geometry.center;
+  const role = arcRole(geometry, "end");
+  const radius = (geometry.innerRadius + geometry.outerRadius) / 2;
+  return {
+    x: geometry.centerX + role.outward.x * radius,
+    y: geometry.centerY + role.outward.y * radius
+  };
+}
+
+function candidateForAnchor(anchor, geometry, placement, text) {
+  if (anchor === "center") return centerCandidate(geometryCenter(geometry), text);
+  const roleName = anchor.endsWith("Start") ? "start" : "end";
+  const role = geometryRole(geometry, roleName);
+  const outside = anchor.startsWith("outside");
+  const direction = outside
+    ? role.outward
+    : { x: -role.outward.x, y: -role.outward.y };
+  return boundaryCandidate(role.point, direction, placement.gap, text);
+}
+
+function arcOutsideStartCrossesCenter(candidate, geometry, text) {
+  if (geometry.kind !== "arc") return false;
+  const radial = arcRole(geometry, "end").outward;
+  const projections = projectionRange(candidateBounds(candidate, text), radial);
+  const centerProjection = geometry.centerX * radial.x + geometry.centerY * radial.y;
+  return projections.minimum < centerProjection - 1e-9;
+}
+
+function fitsSource(candidate, geometry, text) {
+  if (geometry.kind === "point") return true;
+  const bounds = candidateBounds(candidate, text);
+  return geometry.kind === "arc"
+    ? arcContains(bounds, geometry)
+    : intervalContains(bounds, geometry.bounds);
+}
+
+function outsideFallback(anchor) {
+  return anchor === "insideStart" ? "outsideStart" : "outsideEnd";
+}
+
+export function resolveMarkLabelPlacement({ placement, geometry, text } = {}) {
+  const normalized = normalizeMarkLabelPlacement(placement);
+  validatePlacementGeometry(geometry, normalized.anchor);
+  let anchor = normalized.anchor;
+  let candidate = candidateForAnchor(anchor, geometry, normalized, text);
+  const requiresFit = anchor === "center" || anchor.startsWith("inside");
+  if (requiresFit && !fitsSource(candidate, geometry, text)) {
+    if (normalized.overflow === "hide") {
+      return cloneAndFreeze({ visible: false, anchor, fallback: false });
+    }
+    if (normalized.overflow === "outside") {
+      anchor = outsideFallback(anchor);
+      candidate = candidateForAnchor(anchor, geometry, normalized, text);
+    }
+  }
+  if (
+    anchor === "outsideStart" &&
+    normalized.overflow !== "allow" &&
+    arcOutsideStartCrossesCenter(candidate, geometry, text)
+  ) {
+    return cloneAndFreeze({
+      visible: false,
+      anchor,
+      fallback: anchor !== normalized.anchor
+    });
+  }
+  return cloneAndFreeze({
+    visible: true,
+    anchor,
+    fallback: anchor !== normalized.anchor,
+    ...candidate,
+    bounds: candidateBounds(candidate, text)
+  });
+}
 
 export const DEFAULT_LABEL_LAYOUT_GEOMETRY = cloneAndFreeze({
   axis: "both",

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