ggaction 0.0.17 → 0.0.19

package/src/materialization/bars/resolve.js

@@ -1,3 +1,24 @@
+import { readScaleField } from "../../grammar/scales/index.js";
+import { mapScaleConsumerValues } from "../scales/map.js";
+
+// Appearance belongs to a final bar cell and never introduces another group.
+export function resolveBarCellOpacities(program, layer, rowsByCell) {
+  const encoding = layer.encoding?.opacity;
+  if (encoding === undefined) return undefined;
+  const scale = program.resolvedScales[encoding.scale];
+  const values = rowsByCell.map(rows => {
+    const values = readScaleField(rows, encoding.field, encoding.fieldType, {
+      allowUnknown: Object.hasOwn(scale, "unknown")
+    });
+    if (new Set(values).size !== 1) {
+      throw new Error("Bar opacity requires one value within each final cell.");
+    }
+    return values[0];
+  });
+  return mapScaleConsumerValues(values, scale, "opacity");
+}
+
+import { hasRectRadius } from "../../grammar/roundedRect.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
@@ -45,7 +66,7 @@ export function requireCompleteBar(program, id) {
   const dataset = applyItemMissingPolicy(layer, sourceDataset);
   const graphic = program.graphicSpec.objects[id];
   const roundedCollection = graphic?.type === "collection" &&
-    Object.hasOwn(program.markConfigs[id]?.barAppearance ?? {}, "cornerRadius") &&
+    hasRectRadius(program.markConfigs[id]?.barAppearance) &&
     graphic.items?.every(child => ["rect", "path"].includes(child.type));
   if (graphic?.type !== "rect" && !roundedCollection) {
     throw new Error(`Bar mark "${id}" requires rect graphics.`);

package/src/materialization/compositionSnapshot.js

@@ -1,4 +1,6 @@
 import { cloneAndFreeze, freezeOwned, isPlainObject } from "../core/immutable.js";
+import { namespaceGraphicId } from "../selectors/graphicCapacity.js";
+export { namespaceGraphicId } from "../selectors/graphicCapacity.js";
 import {
   requireSingleOrderedGraphicByType,
   walkGraphicTreeEvents
@@ -28,13 +30,6 @@ function validateCanvas(canvas, id) {
   }
 }
 
-export function namespaceGraphicId(namespace, id) {
-  const encode = value => Array.from(value, character =>
-    character.codePointAt(0).toString(16).padStart(6, "0")
-  ).join("");
-  return `g${encode(namespace)}_${id}`;
-}
-
 function rewriteItem(item, namespace) {
   if (!isPlainObject(item) || typeof item.id !== "string" || item.id.length === 0) {
     throw new TypeError("Graphic snapshot items require non-empty string ids.");

package/src/materialization/coordinateBounds.js

@@ -1,3 +1,4 @@
+import { cartesianAxisOwners } from "../selectors/axes.js";
 import { isSourceOwnedText } from "../grammar/text.js";
 import { resolvePolarFrame } from "../grammar/polar.js";
 import { resolveEffectiveBounds } from "../layout/aspect.js";
@@ -202,3 +203,23 @@ export function resolveGuideCoordinateBounds(program, {
   }
   return resolveCoordinateBounds(program, target, { resolvedScales });
 }
+
+// Axis consumers use a displaced frame; marks and grids retain the plot.
+export function resolveCartesianAxisFrameBounds(program, channel, position, scale, axisId = channel) {
+  const plot = resolveGuideCoordinateBounds(program, {
+    coordinate: program.semanticSpec.guides.axis?.[axisId]?.coordinate, scale, channel
+  });
+  if (plot === undefined) return undefined;
+  const offset = program.guideConfigs.axis?.[axisId]?.frame?.offset ?? 0;
+  if (offset === 0) return plot;
+  const shift = ["bottom", "right"].includes(position) ? offset : -offset;
+  return channel === "x" ? { ...plot, y: plot.y + shift } : { ...plot, x: plot.x + shift };
+}
+
+// Cartesian guide bindings are semantic scale consumers without data rows.
+export function axisScaleBindings(program, id) {
+  return cartesianAxisOwners(program).flatMap(owner =>
+    owner.scale === id && owner.coordinate !== undefined &&
+      owner.config?.binding?.standalone === true
+      ? [{ channel: owner.channel, coordinate: owner.coordinate }] : []);
+}

package/src/materialization/dependencies.js

@@ -1,6 +1,5 @@
 import { withGuideLayoutTransaction } from "./guides/layout.js";
 import {
-  canDeferScaleConsumerApplication,
   getLayerScaleIds,
   getExistingMarkRematerializationStep,
   getMarkMaterializationStep,
@@ -13,54 +12,13 @@ import {
   applyMaterializationPlan as executeMaterializationPlan,
   buildMaterializationPlan
 } from "./planner.js";
-import { hasMaterializedLegend } from "./legends.js";
 import {
-  needsCanvasScaleRematerialization,
   planScaleGuideRematerialization
 } from "./scaleGuideDependencies.js";
 import { planLayoutRematerialization } from "./layout.js";
 import { requireCoordinate } from "../selectors/coordinates.js";
 
-export function planCanvasRematerialization(program) {
-  const marks = [];
-  for (const layer of program.semanticSpec.layers) {
-    const step = getMarkMaterializationStep(program, layer);
-    if (step !== undefined) marks.push(step);
-  }
-  const deferredMarkIds = new Set(
-    marks
-      .map(step => step.args.id)
-  );
-  const scales = [];
-  for (const scale of program.semanticSpec.scales) {
-    if (needsCanvasScaleRematerialization(program, scale)) {
-      const deferredConsumers = program.semanticSpec.layers.filter(layer =>
-        canDeferScaleConsumerApplication(layer) &&
-        getLayerScaleIds(layer).includes(scale.id)
-      );
-      const canDeferMarks = deferredConsumers.length === 0 ||
-        deferredConsumers.every(layer => deferredMarkIds.has(layer.id));
-      scales.push({
-        op: "rematerializeScale",
-        args: {
-          id: scale.id,
-          guides: false,
-          ...(canDeferMarks ? { marks: false } : {})
-        }
-      });
-    }
-  }
-  const guides = program.semanticSpec.scales.flatMap(scale =>
-    needsCanvasScaleRematerialization(program, scale)
-      ? planScaleGuideRematerialization(program, scale.id)
-      : []
-  );
-  if (hasMaterializedLegend(program)) {
-    guides.push({ op: "rematerializeLegend" });
-  }
-  const layout = planLayoutRematerialization(program);
-  return buildMaterializationPlan({ scales, marks, guides, layout });
-}
+export { planCanvasRematerialization } from "./layout.js";
 
 export function planCoordinateRematerialization(program, target) {
   requireCoordinate(program, target);
@@ -74,7 +32,9 @@ export function planCoordinateRematerialization(program, target) {
     ...(layer.encoding?.parallel?.dimensions ?? []).map(
       dimension => dimension.scale
     )
-  ]).filter(id => id !== undefined))];
+  ]).filter(id => id !== undefined)),
+    ...Object.values(program.semanticSpec.guides.axis ?? {}).filter(guide => guide.coordinate === target)
+      .map(guide => guide.scale).filter(id => id !== undefined)];
   const directMarks = layers
     .map(layer => getMarkMaterializationStep(program, layer))
     .filter(step => step !== undefined);

package/src/materialization/facetGuides/edit.js

@@ -0,0 +1,30 @@
+import { prepareSharedFacetLegend } from "./preparation.js";
+import { facetLegendIntent, intrinsicFacetLegendSource, restoreFacetLegendIntent,
+  prepareAuthoredFacetLegend } from "./owner.js";
+
+export function editFacetParentLegend(program, operation, args) {
+  if (program.compositionSpec?.type !== "facet") {
+    throw new Error(`${operation} supports only a unit chart or a facet parent shared legend.`);
+  }
+  const current = program.compositionSpec.facet.guides.legend;
+  if (current === false) throw new Error(`${operation} requires an existing facet parent legend.`);
+  const prepared = current === "shared" ? prepareSharedFacetLegend(program) : prepareAuthoredFacetLegend(program);
+  let source;
+  if (prepared.source !== undefined) {
+    source = restoreFacetLegendIntent(intrinsicFacetLegendSource(program), facetLegendIntent(prepared.source));
+  } else {
+    const entries = prepared.compatibility.entries;
+    if (entries.length !== 1) throw new Error("Facet parent inferred legend requires an unambiguous native owner.");
+    const config = entries[0].config;
+    source = intrinsicFacetLegendSource(program).createLegend({ target: config.target, channels: ["color"],
+      itemGap: 26, titleStyle: { fontSize: 12, fontWeight: 700 },
+      ...(prepared.legend.mark === "point" ? { symbol: { layers: [{ type: "point", size: 5.5, stroke: "#ffffff", strokeWidth: 0.35 }] } } : {}) });
+  }
+  source = source[operation](args);
+  const intent = Object.keys(source.guideConfigs.legend ?? {}).length === 0 ? false : facetLegendIntent(source);
+  const spec = program.compositionSpec;
+  return program._clone({ trace: source.trace, actionStack: source.actionStack, actionSequence: source._actionSequence })
+    ._withCompositionState({ children: program.children,
+      compositionSpec: { ...spec, facet: { ...spec.facet, guides: { ...spec.facet.guides, legend: intent } } } })
+    .materializeComposition();
+}

package/src/materialization/facetGuides/layout.js

@@ -0,0 +1 @@
+import{resolveAuthoredFacetLegendLayout as p}from"./ownerLayout.js";import{cartesianAxisOwners as B}from"../../selectors/axes.js";import{PLOT_LEGEND_POSITIONS as F}from"../../layout/legend.js";import{resolveConcreteGraphicBounds as G}from"../../grammar/schemas/graphicBounds.js";import{resolveFacetOuterSides as I}from"../../grammar/facets/guides.js";import{resolveTextBounds as P,textBoundsIntersect as C}from"../../core/textMetrics.js";import{axisGraphicIds as E}from"../guides/resources.js";import{resolveFacetHeaderItems as T}from"../facetHeaders.js";function b(o,t,e){return{left:o.left+t,right:o.right+t,top:o.top+e,bottom:o.bottom+e}}function M(o,t,e,f){const r=o.materializationConfigs.textMetrics,h=I({placements:t.children}),i=[];for(const s of t.children){const m=o.children[s.id];for(const a of B(m))for(const[g,w]of[[2,"labels"],[3,"title"]]){const n=a.config?.[w]?.position;if(o.compositionSpec.facet.guides.axes==="outer"&&!h[n]?.includes(s.id))continue;const u=E(a.channel,a.id)[g];if(m.graphicSpec.objects[u]===void 0)continue;const x=G(m.graphicSpec,u,r);x!==void 0&&i.push(b(x,s.x,s.y))}}const{items:d}=T(t,e,f);for(const s of d)s.properties.text!==""&&i.push(P(s.properties,r));return i}function O(o,t,e,f,r){const h=o.right-o.left,i=o.bottom-o.top,d=e==="right"?t.x+t.width+r:e==="left"?t.x-r-h:f==="left"?t.x:f==="right"?t.x+t.width-h:t.x+(t.width-h)/2,s=["left","right"].includes(e)?t.y:e==="top"?t.y-r-i:t.y+t.height+r;return{left:d,right:d+h,top:s,bottom:s+i}}function q(o,{layout:t,plot:e,plots:f,title:r,preparedHeaders:h,prepared:i}){if(i?.mode==="authored")return p(o,{layout:t,plot:e,title:r,prepared:i,guides:M(o,t,f,h)});if(i?.mode!=="promoted")return{layout:t,plot:e};const d=i.occupiedGroup;if(d?.placement.at!==void 0||F.includes(d?.placement.position))return{layout:t,plot:e};const s=i.reservation.position,m=i.reservation.align,a=i.kinds.map(c=>i.source.guideConfigs.legend[c]),g=i.reservation.gap,w=d===void 0?a.every(c=>c.inferredOffset===!0):d.inferredOffset===!0;let n=O(i.bounds,e,s,m,g);const u=M(o,t,f,h),x=u.map(c=>s==="right"?c.right-(e.x+e.width):s==="left"?e.x-c.left:s==="top"?e.y-c.top:c.bottom-(e.y+e.height));if(w)n=O(i.bounds,e,s,m,Math.max(g,...x.map(c=>c+g)));else if(u.some(c=>C(n,c)))throw new Error("Facet shared legend overlaps retained axes or headers.");const l=Math.max(0,t.padding.left-n.left),v=Math.max(0,r.height+t.padding.top-n.top),L=t.children.map(c=>({...c,x:c.x+l,y:c.y+v})),S={...e,x:e.x+l,y:e.y+v};return n=b(n,l,v),{plot:S,layout:{...t,children:L,width:Math.ceil(Math.max(t.width+l,n.right+t.padding.right)),height:Math.ceil(Math.max(t.height+v,n.bottom+t.padding.bottom)),legend:{position:s,x:n.left,y:n.top,width:n.right-n.left,height:n.bottom-n.top,translation:{x:n.left-i.bounds.left,y:n.top-i.bounds.top}}}}}export{q as resolvePromotedFacetLegendLayout};

package/src/materialization/facetGuides/owner.js

@@ -0,0 +1,125 @@
+import { findLayer } from "../../selectors/layers.js";
+import { isAuthoredFacetLegend } from "../../grammar/facets/legendIntent.js";
+export { isAuthoredFacetLegend };
+import { freezeOwned } from "../../core/immutable.js";
+import { unionConcreteGraphicBounds } from "../../grammar/schemas/graphicBounds.js";
+import { describeLegendBlock } from "../../grammar/legendBlocks.js";
+import { legendResourcePolicy, allLegendGraphicIds } from "../guides/resources.js";
+import { resolveSharedFacetLegends, sameFacetGuideValue } from "../../grammar/facets/guides.js";
+
+export function facetLegendIntent(source) {
+  return freezeOwned({ type: "authored-legend", blocks: Object.fromEntries(
+    Object.entries(source.guideConfigs.legend ?? {}).map(([kind, config]) => [kind, {
+      config,
+      ...(source.semanticSpec.guides.legend?.[legendResourcePolicy(kind).semanticKind] === undefined ? {} : {
+        guide: source.semanticSpec.guides.legend[legendResourcePolicy(kind).semanticKind]
+      })
+    }])
+  ), groups: source.guideConfigs.legendGroups ?? {} });
+}
+
+export function intrinsicFacetLegendSource(program) {
+  const first = program.children[program.compositionSpec.children[0]];
+  let source = new program.constructor({
+    semanticSpec: first.semanticSpec, graphicSpec: first.graphicSpec,
+    resolvedScales: first.resolvedScales, materializationConfigs: first.materializationConfigs,
+    context: { ...first.context, deferGuideLayoutValidation: true, facetLegendIntrinsic: true },
+    trace: program.trace, actionStack: program.actionStack, actionSequence: program._actionSequence
+  });
+  for (const id of allLegendGraphicIds(Object.keys(source.guideConfigs.legend ?? {}))) {
+    if (source.graphicSpec.objects[id] !== undefined) source = source.editGraphics({ target: id, remove: true });
+  }
+  for (const key of Object.keys(source.semanticSpec.guides.legend ?? {})) {
+    source = source.editSemantic({ property: `guide.legend.${key}`, remove: true });
+  }
+  return source._withoutMaterializationConfig(["guides", "legend"])
+    ._withoutMaterializationConfig(["guides", "legendGroups"]);
+}
+
+export function restoreFacetLegendIntent(source, intent) {
+  const scaffolds = [];
+  for (const [kind, { config }] of Object.entries(intent.blocks)) {
+    const descriptor = describeLegendBlock(source, kind, config);
+    const entry = { target: config.target, channels: [...descriptor.channels] };
+    if (descriptor.channels.includes("shape") && descriptor.channels.includes("size")) entry.combine = "size-shape";
+    if (kind === "colorSize") entry.combine = "color-size";
+    if (descriptor.family === "categorical" && config.inferredSymbol === false && entry.combine === undefined) entry.symbol = config.symbol;
+    if (kind === "gradient" && config.representation === "symbols") entry.representation = "symbols";
+    scaffolds.push(entry);
+  }
+  // Build unclipped resources first; each authored block restores its own window below.
+  // A global scaffold option would also reach gradient strips or overwrite sibling windows.
+  for (const args of scaffolds) source = source.createLegend(args);
+  for (const [kind, { config, guide }] of Object.entries(intent.blocks)) {
+    source = source._withLegendConfig(kind, config);
+    const background = legendResourcePolicy(kind).graphicIds.find(id => id.endsWith("Background"));
+    if (config.border === false && source.graphicSpec.objects[background] !== undefined) {
+      source = source.editGraphics({ target: background, remove: true });
+    } else if (config.border !== false && background !== undefined && source.graphicSpec.objects[background] === undefined) {
+      const roots = new Set(legendResourcePolicy(kind).graphicIds);
+      const before = source.graphicSpec.objects.canvas.children.find(id => roots.has(id));
+      source = source.createGraphics({ id: background, type: "rect", parent: "canvas", ...(before === undefined ? {} : { before }) });
+    }
+    if (guide !== undefined) {
+      for (const [property, value] of Object.entries(guide)) {
+        source = source.editSemantic({ property: `guide.legend.${legendResourcePolicy(kind).semanticKind}.${property}`, value });
+      }
+    }
+  }
+  source = source._withMaterializationConfig(["guides", "legendGroups"], intent.groups);
+  return source.rematerializeLegend();
+}
+
+export function prepareAuthoredFacetLegend(program, intent = program.compositionSpec.facet.guides.legend) {
+  let source = intrinsicFacetLegendSource(program);
+  source = isAuthoredFacetLegend(intent) ? restoreFacetLegendIntent(source, intent) : source.createLegend(intent);
+  const kinds = Object.keys(source.guideConfigs.legend ?? {});
+  for (const [kind, config] of Object.entries(source.guideConfigs.legend)) {
+    const descriptor = describeLegendBlock(source, kind, config);
+    const owner = findLayer(source, config.target);
+    for (const channel of descriptor.channels) {
+      if (program.compositionSpec.facet.scales[channel] === "independent") {
+        throw new Error("Facet parent legend requires shared encoded scales.");
+      }
+    }
+    for (const child of Object.values(program.children)) {
+      const candidate = findLayer(child, config.target);
+      if (candidate === undefined || candidate.mark.type !== owner.mark.type ||
+          descriptor.channels.some(channel => !sameFacetGuideValue(candidate.encoding?.[channel], owner.encoding?.[channel])) ||
+          !sameFacetGuideValue(child.markConfigs[config.target], source.markConfigs[config.target])) {
+        throw new Error("Facet parent legend requires compatible source mark bindings and recipes in every child.");
+      }
+    }
+  }
+  const compatibility = resolveSharedFacetLegends(program.compositionSpec.children.map(id => ({
+    id, guideConfigs: source.guideConfigs, resolvedScales: program.children[id].resolvedScales
+  })));
+  const blocks = kinds.map(kind => {
+    const ids = new Set(allLegendGraphicIds([kind]));
+    const roots = source.graphicSpec.objects.canvas.children.filter(id => ids.has(id));
+    const bounds = unionConcreteGraphicBounds(source.graphicSpec, roots, source.materializationConfigs.textMetrics);
+    if (bounds === undefined) throw new Error("Facet parent legend requires measurable block bounds.");
+    return { kind, roots, bounds, config: source.guideConfigs.legend[kind] };
+  });
+  return { mode: "authored", source, kinds, blocks, compatibility,
+    intent: facetLegendIntent(source),
+    roots: blocks.flatMap(block => block.roots),
+    bounds: unionConcreteGraphicBounds(source.graphicSpec, blocks.flatMap(block => block.roots), source.materializationConfigs.textMetrics),
+    reservation: { position: "right", align: "center", gap: 0, width: 0, height: 0 } };
+}
+
+// Theme reconciliation changes the derived native appearance in one transaction.
+// Adopt only that transaction's configs; ordinary layout/data replay reads intent.
+export function synchronizeFacetLegendAppearance(program) {
+  const intent = program.compositionSpec?.type === "facet" ? program.compositionSpec.facet.guides.legend : undefined;
+  if (!isAuthoredFacetLegend(intent)) return program;
+  const blocks = Object.fromEntries(Object.entries(intent.blocks).map(([kind, block]) => {
+    const config = program.guideConfigs.legend?.[kind];
+    if (config === undefined || config.target !== block.config.target) throw new Error("Parent theme reconciliation lost its legend owner.");
+    return [kind, { ...block, config }];
+  }));
+  const spec = program.compositionSpec;
+  return program._withCompositionState({ children: program.children,
+    compositionSpec: { ...spec, facet: { ...spec.facet,
+      guides: { ...spec.facet.guides, legend: { ...intent, blocks, groups: program.guideConfigs.legendGroups ?? {} } } } } });
+}

package/src/materialization/facetGuides/ownerLayout.js

@@ -0,0 +1,71 @@
+import { localLegendPlacement } from "../../grammar/legendGroups.js";
+import { PLOT_LEGEND_POSITIONS } from "../../core/vocabulary.js";
+import { resolveLegendGroupPlacement } from "../../layout/legendGroup.js";
+import { textBoundsIntersect } from "../../core/textMetrics.js";
+
+const shift = (bounds, x, y) => ({ left: bounds.left + x, right: bounds.right + x,
+  top: bounds.top + y, bottom: bounds.bottom + y });
+
+function nativeGroup(blocks) {
+  const config = blocks[0].config;
+  const positions = new Set(blocks.map(block => block.config.position));
+  if (positions.size > 1) throw new Error("Parent legend inherited blocks require one common anchor.");
+  const placement = { position: config.position ?? "right", align: config.align ?? "center",
+    offset: Math.max(...blocks.map(block => block.config.offset ?? 0)) };
+  return { placement, blockLayout: "wrap", inferredOffset: blocks.every(block => block.config.inferredOffset === true) };
+}
+
+export function resolveAuthoredFacetLegendLayout(program, { layout, plot, title, prepared, guides }) {
+  const partitions = [];
+  const targets = [...new Set(prepared.blocks.map(block => block.config.target))];
+  for (const target of targets) {
+    const owned = prepared.blocks.filter(block => block.config.target === target);
+    const inherited = owned.filter(block => localLegendPlacement(block.config) === undefined);
+    if (inherited.length) partitions.push({ blocks: inherited,
+      group: prepared.source.guideConfigs.legendGroups?.[target] ?? nativeGroup(inherited) });
+    for (const block of owned) {
+      const placement = localLegendPlacement(block.config);
+      if (placement !== undefined) partitions.push({ blocks: [block],
+        group: { placement, blockLayout: "column", inferredOffset: placement.inferredOffset } });
+    }
+  }
+  const placements = [];
+  for (const { blocks, group } of partitions) {
+    const position = group.placement.position;
+    const inside = group.placement.at !== undefined || PLOT_LEGEND_POSITIONS.includes(position);
+    let effective = group;
+    if (!inside && group.inferredOffset === true) {
+      const base = group.placement.offset;
+      const distances = guides.map(bound => position === "right" ? bound.right - plot.x - plot.width
+        : position === "left" ? plot.x - bound.left : position === "top" ? plot.y - bound.top
+        : bound.bottom - plot.y - plot.height);
+      effective = { ...group, placement: { ...group.placement, offset: Math.max(base, ...distances.map(value => value + base)) } };
+    }
+    const plans = resolveLegendGroupPlacement({ blocks: blocks.map(block => ({ id: block.kind, bounds: block.bounds })),
+      group: effective, plot, canvas: layout, deferCanvasFit: true });
+    for (const plan of plans) {
+      const block = blocks.find(block => block.kind === plan.id);
+      const bounds = shift(block.bounds, plan.dx, plan.dy);
+      if (inside && (bounds.left < plot.x || bounds.right > plot.x + plot.width ||
+          bounds.top < plot.y || bounds.bottom > plot.y + plot.height)) {
+        throw new Error("Facet parent legend does not fit the final plot union.");
+      }
+      if (guides.some(bound => textBoundsIntersect(bounds, bound))) {
+        throw new Error("Facet parent legend overlaps retained axes or headers.");
+      }
+      if (placements.some(other => textBoundsIntersect(bounds, other.bounds))) {
+        throw new Error("Facet parent legend blocks overlap.");
+      }
+      placements.push({ kind: block.kind, dx: plan.dx, dy: plan.dy, bounds, inside });
+    }
+  }
+  const dx = Math.max(0, ...placements.map(item => layout.padding.left - item.bounds.left));
+  const dy = Math.max(0, ...placements.map(item => title.height + layout.padding.top - item.bounds.top));
+  const moved = placements.map(item => ({ ...item, dx: item.dx + dx, dy: item.dy + dy,
+    bounds: shift(item.bounds, dx, dy) }));
+  return { plot: { ...plot, x: plot.x + dx, y: plot.y + dy },
+    layout: { ...layout, children: layout.children.map(cell => ({ ...cell, x: cell.x + dx, y: cell.y + dy })),
+      width: Math.ceil(Math.max(layout.width + dx, ...moved.map(item => item.bounds.right + layout.padding.right))),
+      height: Math.ceil(Math.max(layout.height + dy, ...moved.map(item => item.bounds.bottom + layout.padding.bottom))),
+      parentLegendPlacements: moved } };
+}

package/src/materialization/facetGuides/placement.js

@@ -1,3 +1,6 @@
+import { translateGraphic } from "../graphicTranslation.js";
+import { cartesianAxisOwners } from "../../selectors/axes.js";
+import { resolveLegendGroupPlacement } from "../../layout/legendGroup.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { resolveConcreteGraphicBounds } from
   "../../grammar/schemas/graphicBounds.js";
@@ -18,6 +21,9 @@ function copyLegendConfig(program, source) {
   for (const [kind, config] of Object.entries(source.guideConfigs.legend ?? {})) {
     next = next._withLegendConfig(kind, config);
   }
+  for (const [target, group] of Object.entries(source.guideConfigs.legendGroups ?? {})) {
+    next = next._withMaterializationConfig(["guides", "legendGroups", target], group);
+  }
   return next;
 }
 
@@ -33,6 +39,12 @@ function removeNamespacedGraphics(program, namespace, ids) {
 }
 
 function legendTranslation(prepared, plot, layout) {
+  if (layout.legend?.translation !== undefined) return layout.legend.translation;
+  if (prepared.occupiedGroup !== undefined) {
+    const [placement] = resolveLegendGroupPlacement({ blocks: [{ id: "shared", bounds: prepared.bounds }],
+      group: prepared.occupiedGroup, plot, canvas: layout });
+    return { x: placement.dx, y: placement.dy };
+  }
   const position = prepared.reservation.position;
   if (["top", "bottom"].includes(position)) {
     const width = prepared.bounds.right - prepared.bounds.left;
@@ -55,18 +67,16 @@ function legendTranslation(prepared, plot, layout) {
   const strips = prepared.source.graphicSpec.objects[`${prefix}Strips`];
   if (strips?.items?.[0] !== undefined) {
     const properties = strips.items[0].properties;
-    const length = prepared.source.guideConfigs.legend[gradientKind].gradient.length;
     return {
       x: layout.legend.x - (position === "left"
         ? prepared.bounds.left
         : properties.x),
-      y: plot.y + (plot.height - length) / 2 - properties.y
+      y: plot.y - prepared.bounds.top
     };
   }
-  const height = prepared.bounds.bottom - prepared.bounds.top;
   return {
     x: layout.legend.x - prepared.bounds.left,
-    y: plot.y + Math.max(0, (plot.height - height) / 2) - prepared.bounds.top
+    y: plot.y - prepared.bounds.top
   };
 }
 
@@ -91,7 +101,7 @@ function attachParentLegend(program, prepared, plot, layout) {
   return next;
 }
 
-function assertSharedLegendFits(program, id, layout, plot) {
+function assertSharedLegendFits(program, id, layout, plot, occupiedGroup) {
   const bounds = resolveConcreteGraphicBounds(program.graphicSpec, id, program.materializationConfigs.textMetrics);
   if (bounds === undefined) {
     throw new Error("Facet shared legend requires measurable concrete bounds.");
@@ -102,7 +112,7 @@ function assertSharedLegendFits(program, id, layout, plot) {
       Math.max(bounds.left, plot.x) &&
     Math.min(bounds.bottom, plot.y + plot.height) >
       Math.max(bounds.top, plot.y);
-  if (outside || overlapsPlot) {
+  if (outside || overlapsPlot && occupiedGroup === undefined) {
     throw new Error(
       "Facet shared legend requires more space than the composed Canvas provides."
     );
@@ -110,7 +120,32 @@ function assertSharedLegendFits(program, id, layout, plot) {
   return program;
 }
 
-export function applyFacetGuideComposition(program, { layout, plot } = {}) {
+function attachAuthoredParentLegend(program, prepared, layout, synchronizeColorSizeMeaning) {
+  const meaning = prepared.source.semanticSpec.guides.legend?.colorSize;
+  if (meaning !== undefined || program.semanticSpec.guides.legend?.colorSize !== undefined) {
+    program = synchronizeColorSizeMeaning(program, meaning);
+  }
+  const id = `${program.compositionSpec.id}-shared-legend`;
+  let next = program._withoutMaterializationConfig(["guides", "legend"])
+    ._withoutMaterializationConfig(["guides", "legendGroups"]);
+  next = copyLegendConfig(next, prepared.source).createGraphics({ id, type: "canvas", parent: "canvas" });
+  for (const [property, value] of Object.entries({ x: 0, y: 0, width: layout.width, height: layout.height, background: "transparent" })) {
+    next = next.editGraphics({ target: id, property, value });
+  }
+  for (const block of prepared.blocks) {
+    const placement = layout.parentLegendPlacements.find(item => item.kind === block.kind);
+    for (const root of block.roots) {
+      next = attachSnapshotObject(next, prepared.source.graphicSpec, root, id);
+      next = translateGraphic(next, root, placement.dx, placement.dy);
+    }
+  }
+  if (prepared.keepShared === true) return next;
+  const spec = next.compositionSpec;
+  return next._withCompositionState({ children: next.children,
+    compositionSpec: { ...spec, facet: { ...spec.facet, guides: { ...spec.facet.guides, legend: prepared.intent } } } });
+}
+
+export function applyFacetGuideComposition(program, { layout, plot, synchronizeColorSizeMeaning } = {}) {
   if (!isPlainObject(layout) || !Array.isArray(layout.children)) {
     throw new TypeError("Facet guide composition requires a resolved layout.");
   }
@@ -122,8 +157,10 @@ export function applyFacetGuideComposition(program, { layout, plot } = {}) {
     const child = program.children[cell.id];
     return {
       id: cell.id,
-      axes: Object.keys(child.guideConfigs.axis ?? {})
-        .filter(channel => ["x", "y"].includes(channel)),
+      axes: cartesianAxisOwners(child).map(owner => owner.id),
+      axisOwners: cartesianAxisOwners(child).map(owner => ({ id: owner.id, channel: owner.channel,
+        components: Object.fromEntries(["line", "ticks", "labels", "title"].flatMap(component =>
+          owner.config?.[component] === undefined ? [] : [[component, owner.config[component].position]])) })),
       legendKinds: legendKinds(child)
     };
   });
@@ -138,8 +175,15 @@ export function applyFacetGuideComposition(program, { layout, plot } = {}) {
   for (const cell of layout.children) {
     const namespace = `${program.compositionSpec.id}-${cell.id}`;
     const childPlan = ownership.children[cell.id];
-    for (const channel of childPlan.removeAxes) {
-      next = removeNamespacedGraphics(next, namespace, axisGraphicIds(channel));
+    const axisOwners = cartesianAxisOwners(program.children[cell.id]);
+    for (const axisId of childPlan.removeAxes) {
+      const owner = axisOwners.find(owner => owner.id === axisId);
+      next = removeNamespacedGraphics(next, namespace, axisGraphicIds(owner.channel, axisId));
+    }
+    for (const [axisId, components] of Object.entries(childPlan.removeAxisComponents ?? {})) {
+      const owner = axisOwners.find(owner => owner.id === axisId);
+      const ids = axisGraphicIds(owner.channel, axisId);
+      next = removeNamespacedGraphics(next, namespace, components.map(component => ids[["line", "ticks", "labels", "title"].indexOf(component)]));
     }
     if (childPlan.removeLegends.length > 0) {
       next = removeNamespacedGraphics(
@@ -149,14 +193,27 @@ export function applyFacetGuideComposition(program, { layout, plot } = {}) {
       );
     }
   }
-  if (prepared === undefined) return next;
+  if (prepared === undefined) {
+    if (next.semanticSpec.guides.legend?.colorSize !== undefined) {
+      next = synchronizeColorSizeMeaning(next, undefined);
+    }
+    return next._withoutMaterializationConfig(["guides", "legend"])
+      ._withoutMaterializationConfig(["guides", "legendGroups"]);
+  }
+  if (prepared.mode === "authored") {
+    next = attachAuthoredParentLegend(next, prepared, layout, synchronizeColorSizeMeaning);
+    return assertSharedLegendFits(next, `${program.compositionSpec.id}-shared-legend`, layout, plot, {});
+  }
   let id;
   if (prepared.mode === "legacyCategorical") {
     id = `${program.compositionSpec.id}-legend`;
-    next = materializeLegacyCategoricalLegend(next, prepared, layout);
+    next = materializeLegacyCategoricalLegend(next, prepared, {
+      ...layout,
+      legend: { ...layout.legend, y: plot.y }
+    });
   } else {
     id = `${program.compositionSpec.id}-shared-legend`;
     next = attachParentLegend(next, prepared, plot, layout);
   }
-  return assertSharedLegendFits(next, id, layout, plot);
+  return assertSharedLegendFits(next, id, layout, plot, prepared.occupiedGroup);
 }

package/src/materialization/facetGuides/preparation.js

@@ -1,3 +1,8 @@
+import { localLegendPosition } from "../../grammar/legendGroups.js";
+import { prepareAuthoredFacetLegend, facetLegendIntent } from "./owner.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { PLOT_LEGEND_POSITIONS } from "../../layout/legend.js";
+import { isContinuousColorScaleType } from "../../grammar/scales/types.js";
 import {
   unionConcreteGraphicBounds
 } from "../../grammar/schemas/graphicBounds.js";
@@ -109,7 +114,7 @@ function prepareAutoLegendSource(child) {
       request.channels.includes("color") ? "color" : "stroke"
     ]?.scale
   );
-  const gradient = scale?.type === "sequential";
+  const gradient = isContinuousColorScaleType(scale?.type);
   const gradientPrefix = request.channels.includes("color")
     ? "colorGradient"
     : "strokeGradient";
@@ -123,7 +128,7 @@ function prepareAutoLegendSource(child) {
       titleStyle: { color: DEFAULT_COLORS.strongText, fontSize: 11 }
     } : {})
   });
-  if (gradient) {
+  if (gradient && scale.type === "sequential") {
     const resolved = source.resolvedScales[scale.id];
     source = source
       .editGraphics({
@@ -176,6 +181,7 @@ function promotedLegendPlacement(source, kinds) {
 }
 
 export function prepareSharedFacetLegend(program) {
+  if (isPlainObject(program.compositionSpec.facet.guides.legend)) return prepareAuthoredFacetLegend(program);
   if (program.compositionSpec.facet.guides.legend !== "shared") {
     return undefined;
   }
@@ -188,6 +194,9 @@ export function prepareSharedFacetLegend(program) {
   }
   const source = inferred ? prepareAutoLegendSource(first) : first;
   const kinds = legendKinds(source);
+  if (kinds.some(kind => localLegendPosition(source.guideConfigs.legend[kind]) !== undefined)) {
+    return { ...prepareAuthoredFacetLegend(program, facetLegendIntent(source)), keepShared: true };
+  }
   const compatibility = resolveSharedFacetLegends(
     compatibleLegendChildren(program, source, inferred)
   );
@@ -201,8 +210,13 @@ export function prepareSharedFacetLegend(program) {
   if (bounds === undefined) {
     throw new Error("Shared facet legend has no measurable concrete bounds.");
   }
-  const gradient = kinds.some(kind => ["gradient", "strokeGradient"].includes(kind));
-  const placement = promotedLegendPlacement(source, kinds);
+  const targets = new Set(kinds.map(kind => source.guideConfigs.legend[kind].target));
+  const group = targets.size === 1 ? source.guideConfigs.legendGroups?.[[...targets][0]] : undefined;
+  const insideGroup = group !== undefined && (group.placement.at !== undefined || PLOT_LEGEND_POSITIONS.includes(group.placement.position));
+  const placement = group === undefined ? promotedLegendPlacement(source, kinds)
+    : { position: insideGroup ? "right" : group.placement.position,
+        align: group.placement.align ?? "left" };
+
   const width = Math.ceil(bounds.right - bounds.left);
   return {
     mode: "promoted",
@@ -212,11 +226,12 @@ export function prepareSharedFacetLegend(program) {
     roots,
     bounds,
     compatibility,
+    ...(group === undefined ? {} : { occupiedGroup: group }),
     reservation: {
       ...placement,
-      gap: gradient ? 24 : 18,
-      width: Math.max(gradient ? 112 : 132, width),
-      height: Math.ceil(bounds.bottom - bounds.top)
+      gap: insideGroup ? 0 : group?.placement.offset ?? Math.max(...kinds.map(kind => source.guideConfigs.legend[kind].offset)),
+      width: insideGroup ? 0 : width,
+      height: insideGroup ? 0 : Math.ceil(bounds.bottom - bounds.top)
     }
   };
 }