ggaction 0.0.23 → 0.0.26

package/src/actions/overlays/index.js

@@ -0,0 +1,168 @@
+import { closedAction } from "../../core/action.js";
+import { normalizeOverlayBinding, overlayGroupFields, overlayPositionEncoding } from "../../grammar/overlay.js";
+import { requireLayer, resolveEligibleLayer } from "../../selectors/layers.js";
+import { resolveOverlaySeries, overlaySegments } from "../../materialization/overlayItems.js";
+import { resolveFacadeId } from "../charts/shared.js";
+import { buildCurvePathCommands } from "../../grammar/curveCommands.js";
+import { mapScaleConsumerValues } from "../../materialization/scales/map.js";
+import { createPointShapeGraphic } from "../../grammar/pointShapes.js";
+import { editMarkGraphic } from "../marks/shared.js";
+import { rematerializeHighlightBaseline } from "../marks/lifecycle.js";
+import { detachOverlay } from "./snapshot.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { requestedStrokeDetails, STROKE_STYLE_PROPERTIES } from "../../grammar/strokeStyle.js";
+import { resolveDirectionValues } from "../../grammar/direction.js";
+
+function positionBindings(program, id, source) {
+  let next = program.editSemantic({ property: `layer[${id}].data`, value: source.data });
+  next = next.editSemantic({ property: `layer[${id}].coordinate`, value: source.coordinate });
+  for (const channel of ["x", "y"]) {
+    const encoding = overlayPositionEncoding(source, channel);
+    if (requireLayer(next, id).encoding?.[channel]) {
+      next = next.editSemantic({ property: `layer[${id}].encoding.${channel}`, remove: true });
+    }
+    for (const property of ["field", "fieldType", "scale", "temporalUnit"]) {
+      if (encoding?.[property] !== undefined) next = next.editSemantic({
+        property: `layer[${id}].encoding.${channel}.${property}`, value: encoding[property]
+      });
+    }
+  }
+  return next;
+}
+
+function mappedAppearance(program, layer, channel, members, fallback) {
+  const encoding = layer.encoding?.[channel];
+  if (!encoding?.scale) return fallback;
+  const values = [...new Set(members.map(row => row[encoding.field]).filter(value => value != null))];
+  if (!values.length) return fallback;
+  if (values.length > 1) {
+    throw new Error(`Overlay ${channel} requires one value per visible item or series; choose a grouping field.`);
+  }
+  return mapScaleConsumerValues([values[0]], program.resolvedScales[encoding.scale], channel)[0];
+}
+
+function synchronizeSourceAppearance(program, id, source, binding) {
+  let next = program;
+  const fields = binding.series === "source" ? overlayGroupFields(source) : [];
+  if (requireLayer(next, id).encoding?.group) next = next.editSemantic({ property: `layer[${id}].encoding.group`, remove: true });
+  if (fields.length) next = next.editSemantic({ property: `layer[${id}].encoding.group.fields`, value: fields })
+    .editSemantic({ property: `layer[${id}].encoding.group.fieldType`, value: "nominal" });
+  if (!binding.inheritColor) return next;
+  if (requireLayer(next, id).encoding?.color) next = next.editSemantic({ property: `layer[${id}].encoding.color`, remove: true });
+  const color = source.encoding?.color;
+  if (binding.series === "source" && color?.scale &&
+      (requireLayer(next, id).mark.type === "point" || fields.includes(color.field))) {
+    for (const key of ["field", "fieldType", "scale", "temporalUnit"]) {
+      if (color[key] !== undefined) next = next.editSemantic({ property: `layer[${id}].encoding.color.${key}`, value: color[key] });
+    }
+  }
+  return next;
+}
+
+export const rematerializeOverlay = /* @__PURE__ */ closedAction({
+  op: "rematerializeOverlay", description: "Rebuild an overlay from its source's final visible items."
+}, ["id"], function ({ id } = {}) {
+  const highlighted = rematerializeHighlightBaseline(this, { target: id,
+    operation: "rematerializeOverlay", resetProperty: "items", resetValue: [] });
+  if (highlighted !== undefined) return highlighted;
+  const previous = requireLayer(this, id);
+  const binding = normalizeOverlayBinding(previous.derivedBindings?.overlay);
+  const source = requireLayer(this, binding.source);
+  const series = resolveOverlaySeries(this, binding);
+  let next = synchronizeSourceAppearance(positionBindings(this, id, source), id, source, binding);
+  for (const [channel, encoding] of Object.entries(requireLayer(next, id).encoding)) {
+    if (["x", "y"].includes(channel) || channel === "color" && binding.inheritColor || !encoding.scale) continue;
+    next = next.rematerializeScale({ id: encoding.scale, marks: false, guides: false });
+  }
+  const layer = requireLayer(next, id), config = next.markConfigs[id];
+  const color = (members, fallback) => mappedAppearance(next, layer, "color", members, fallback);
+  if (layer.mark.type === "line") {
+    const entries = series.flatMap(group => {
+      return overlaySegments(group, binding).map(points => {
+        const positions = points.map(({ x, y }) => ({ x, y }));
+        return { type: "path", properties: {
+          commands: [...(positions.length === 1 ? [{ op: "M", ...positions[0] }]
+            : buildCurvePathCommands(positions, config.curve ?? "linear", config.tension)),
+            ...(config.closed ? [{ op: "Z" }] : [])],
+          stroke: mappedAppearance(next, layer, "stroke", group.members,
+            config.stroke ?? color(group.members, "#4c78a8")),
+          strokeWidth: mappedAppearance(next, layer, "strokeWidth", group.members, config.strokeWidth ?? 2),
+          strokeDash: mappedAppearance(next, layer, "strokeDash", group.members, config.strokeDash ?? []),
+          ...requestedStrokeDetails(config, "Overlay line"),
+          ...(config.opacity === undefined && !layer.encoding.opacity ? {} : {
+            opacity: mappedAppearance(next, layer, "opacity", group.members, config.opacity ?? 1) })
+        } };
+      });
+    });
+    next = next.editGraphics({ target: id, property: "items", value: entries });
+  } else {
+    const items = series.flatMap(group => group.points.map(point => ({
+      ...createPointShapeGraphic({
+        shape: mappedAppearance(next, layer, "shape", [point.fields], config.shape ?? "circle"),
+        x: point.x, y: point.y,
+        angle: resolveDirectionValues([point.fields], layer.encoding.angle)?.[0],
+        area: mappedAppearance(next, layer, "size", [point.fields], Math.PI * (config.radius ?? 3) ** 2),
+        fill: color([point.fields], config.fill ?? "#4c78a8"),
+        stroke: mappedAppearance(next, layer, "stroke", [point.fields], config.stroke === false ? "transparent" : config.stroke),
+        strokeWidth: mappedAppearance(next, layer, "strokeWidth", [point.fields], config.stroke === false ? 0 : config.strokeWidth),
+        opacity: mappedAppearance(next, layer, "opacity", [point.fields], config.opacity),
+        ...requestedStrokeDetails(config, "Overlay point")
+      })
+    })));
+    next = next.editGraphics({ target: id, property: "items", value: items });
+  }
+  return editMarkGraphic(next, id, {});
+});
+
+const createOverlay = /* @__PURE__ */ closedAction({
+  op: "createOverlay", description: "Add a line or points that follow another mark's visible results."
+}, ["id", "source", "type", "basis", "series", "missing", "orderBy", "line", "point"], function (args = {}) {
+  if (!["line", "point"].includes(args.type ?? "line")) throw new Error("Overlay type must be line or point.");
+  const type = args.type ?? "line";
+  if (args[type] !== undefined) validateOptionObject(args[type], ["clip", "opacity", "stroke", "strokeWidth", ...STROKE_STYLE_PROPERTIES,
+    ...(type === "line" ? ["curve", "tension", "closed"] : ["shape", "fill"])], `createOverlay ${type}`);
+  if (type === "line" && args.point !== undefined || type === "point" && args.line !== undefined) {
+    throw new Error("Overlay appearance must match its type.");
+  }
+  const source = resolveEligibleLayer(this, { target: args.source,
+    predicate: layer => ["bar", "line", "area", "point"].includes(layer.mark?.type) && !layer.derivedBindings?.overlay,
+    label: "overlay source", targetOption: "source" });
+  const binding = normalizeOverlayBinding({ source: source.id, basis: args.basis ?? "visibleItems", mode: "follow",
+    series: args.series ?? "source", missing: args.missing ?? "break",
+    inheritColor: args[type]?.[type === "line" ? "stroke" : "fill"] === undefined,
+    ...(args.orderBy === undefined ? type === "point" && source.mark.type === "point" ? { orderBy: "x" } : {} : { orderBy: args.orderBy }) });
+  resolveOverlaySeries(this, binding);
+  const id = resolveFacadeId(this, args.id, { defaultId: "overlay", operation: "createOverlay" });
+  let next = this[type === "line" ? "createLineMark" : "createPointMark"]({
+    ...(args[type] ?? {}), id, data: source.data
+  });
+  next = positionBindings(next, id, source).editSemantic({
+    property: `layer[${id}].derivedBindings.overlay`, value: binding
+  });
+  return next.rematerializeOverlay({ id });
+});
+
+const editOverlay = /* @__PURE__ */ closedAction({
+  op: "editOverlay", description: "Edit the source, series, ordering, or gaps of a linked overlay."
+}, ["target", "source", "series", "missing", "orderBy", "follow"], function (args = {}) {
+  const layer = resolveEligibleLayer(this, { target: args.target,
+    predicate: layer => Boolean(layer.derivedBindings?.overlay), label: "overlay" });
+  if (!Object.keys(args).some(key => key !== "target")) throw new Error("editOverlay requires an edit.");
+  if (args.follow !== undefined && typeof args.follow !== "boolean") throw new TypeError("Overlay follow must be boolean.");
+  if (args.follow === false) {
+    if (Object.keys(args).some(key => !["target", "follow"].includes(key))) throw new Error("Detach cannot be combined with source edits.");
+    return detachOverlay(this, layer);
+  }
+  const { target, follow, ...patch } = args;
+  const binding = normalizeOverlayBinding({ ...layer.derivedBindings.overlay, ...patch });
+  if (binding.source === layer.id) throw new Error("An overlay cannot follow itself.");
+  resolveOverlaySeries(this, binding);
+  return this.editSemantic({ property: `layer[${layer.id}].derivedBindings.overlay`, value: binding })
+    .rematerializeOverlay({ id: layer.id });
+});
+
+export function registerOverlayActions(ProgramClass) {
+  ProgramClass.prototype.createOverlay = createOverlay;
+  ProgramClass.prototype.editOverlay = editOverlay;
+  ProgramClass.prototype.rematerializeOverlay = rematerializeOverlay;
+}

package/src/actions/overlays/snapshot.js

@@ -0,0 +1,45 @@
+import { requireSemanticScale } from "../../selectors/scales.js";
+import { resolveOverlaySeries, overlaySegments } from "../../materialization/overlayItems.js";
+import { resolveCoordinateBounds } from "../../materialization/coordinateBounds.js";
+import { requireLayer } from "../../selectors/layers.js";
+
+function availableName(base, taken) {
+  let name = base, index = 2;
+  while (taken.has(name)) name = `${base}-${index++}`;
+  taken.add(name);
+  return name;
+}
+
+// Detaching explicitly freezes the current visible results. Normalized plot
+// coordinates retain offsets/dodging exactly and still respond to Canvas resize.
+export function detachOverlay(program, layer) {
+  const binding = layer.derivedBindings.overlay;
+  const groups = resolveOverlaySeries(program, binding);
+  const frame = resolveCoordinateBounds(program, layer.coordinate);
+  const fields = new Set(groups.flatMap(group => group.points.flatMap(point => Object.keys(point.fields))));
+  const x = availableName("__overlay_x", fields), y = availableName("__overlay_y", fields);
+  const series = availableName("__overlay_series", fields);
+  const values = groups.flatMap(group => overlaySegments(group, binding).flatMap((points, segment) =>
+    points.map(point => ({ ...point.fields, [x]: (point.x - frame.x) / frame.width,
+      [y]: 1 - (point.y - frame.y) / frame.height, [series]: JSON.stringify([group.key, segment]) }))));
+  const data = availableName(`${layer.id}-snapshot`, new Set(program.semanticSpec.datasets.map(dataset => dataset.id)));
+  const scales = new Set(program.semanticSpec.scales.map(scale => scale.id));
+  let next = program.createData({ id: data, values })
+    .editSemantic({ property: `layer[${layer.id}].derivedBindings.overlay`, remove: true })
+    .editSemantic({ property: `layer[${layer.id}].data`, value: data });
+  for (const channel of ["x", "y", "group"]) {
+    if (requireLayer(next, layer.id).encoding[channel]) next = next.editSemantic({ property: `layer[${layer.id}].encoding.${channel}`, remove: true });
+  }
+  // Appearance shares no mutable scale identity with the former source.
+  for (const [channel, encoding] of Object.entries(layer.encoding)) {
+    if (["x", "y"].includes(channel) || !encoding.scale) continue;
+    const definition = requireSemanticScale(program, encoding.scale);
+    const id = availableName(`${layer.id}-${channel}-snapshot`, scales);
+    next = next.createScale({ ...definition, id })
+      .editSemantic({ property: `layer[${layer.id}].encoding.${channel}.scale`, value: id });
+  }
+  return next.encodeChannels({ target: layer.id, channels: {
+    x: { field: x, fieldType: "quantitative", scale: { id: availableName(`${layer.id}-snapshot-x`, scales), type: "linear", domain: [0, 1], zero: false, nice: false } },
+    y: { field: y, fieldType: "quantitative", scale: { id: availableName(`${layer.id}-snapshot-y`, scales), type: "linear", domain: [0, 1], zero: false, nice: false } },
+    ...(layer.mark.type === "line" ? { group: { fields: [series] } } : {}) } });
+}

package/src/actions/primitives/editGraphics.js

@@ -13,7 +13,6 @@ import { validateConcreteGraphicValue } from
   "../../grammar/schemas/concreteGraphic.js";
 import {
   collectGraphicSubtreeIds,
-  findGraphicParent,
   requireGraphic,
   resolveGraphicChildOrder
 } from "../../grammar/schemas/graphicTree.js";
@@ -145,28 +144,25 @@ function editItems(owner, property, value, id, program) {
   return changed ? freezeOwned({ ...owner, items: freezeOwned(items) }) : owner;
 }
 
-function removeGraphicTree(graphicSpec, id) {
-  const parent = findGraphicParent(graphicSpec, id);
-  if (
-    graphicSpec.objects[id].type === "canvas" &&
-    parent?.kind !== "parent"
-  ) {
-    throw new Error("The canvas root cannot be removed.");
+function removeGraphicTrees(graphicSpec, targets) {
+  const removedIds = new Set();
+  for (const id of targets) {
+    const found = requireGraphic(graphicSpec, id);
+    if (found.kind === "item") throw new Error("editGraphics cannot remove a generated item independently.");
+    if (found.object.type === "canvas" && graphicSpec.order.includes(id)) throw new Error("The canvas root cannot be removed.");
+    for (const child of collectGraphicSubtreeIds(graphicSpec, id)) removedIds.add(child);
   }
-  const removedIds = new Set(collectGraphicSubtreeIds(graphicSpec, id));
-  const objects = Object.fromEntries(
-    Object.entries(graphicSpec.objects).filter(([objectId]) => !removedIds.has(objectId))
-  );
-  let order = graphicSpec.order;
-  if (parent?.kind === "parent") {
-    objects[parent.id] = freezeOwned({
-      ...objects[parent.id],
-      children: freezeOwned(parent.object.children.filter(childId => childId !== id))
-    });
-  } else {
-    order = freezeOwned(order.filter(objectId => objectId !== id));
+  // One immutable replacement for the complete removal set. Repeated per-root
+  // copying made facet guide cleanup quadratic in the number of panels.
+  const objects = {};
+  for (const id in graphicSpec.objects) {
+    if (removedIds.has(id)) continue;
+    const object = graphicSpec.objects[id];
+    const retained = object.children?.some(child => removedIds.has(child))
+      ? freezeOwned({ ...object, children: freezeOwned(object.children.filter(child => !removedIds.has(child))) }) : object;
+    Object.defineProperty(objects, id, { value: retained, enumerable: true, writable: true, configurable: true });
   }
-  return freezeOwned({ objects: freezeOwned(objects), order });
+  return freezeOwned({ objects: freezeOwned(objects), order: freezeOwned(graphicSpec.order.filter(id => !removedIds.has(id))) });
 }
 
 const editGraphics = /* @__PURE__ */ closedAction(
@@ -177,7 +173,8 @@ const editGraphics = /* @__PURE__ */ closedAction(
   }, ["target", "property", "value", "remove"],
   function (args = {}) {
     const { target, property, value, remove = false } = args;
-    if (typeof target !== "string" || target.length === 0) {
+    const targets = Array.isArray(target) ? target : [target];
+    if (!targets.length || targets.some(id => typeof id !== "string" || id.length === 0) || Array.isArray(target) && !remove) {
       throw new TypeError("editGraphics requires a non-empty target string.");
     }
     if (typeof remove !== "boolean") throw new TypeError("editGraphics remove must be a boolean.");
@@ -186,13 +183,10 @@ const editGraphics = /* @__PURE__ */ closedAction(
     }
     if (!remove && value === undefined) throw new TypeError("editGraphics requires a value.");
 
-    const found = requireGraphic(this.graphicSpec, target);
     if (remove) {
-      if (found.kind === "item") {
-        throw new Error("editGraphics cannot remove a generated item independently.");
-      }
-      return this._clone({ graphicSpec: removeGraphicTree(this.graphicSpec, found.id) });
+      return this._clone({ graphicSpec: removeGraphicTrees(this.graphicSpec, targets) });
     }
+    const found = requireGraphic(this.graphicSpec, target);
 
     if (property === "children") {
       const children = freezeOwned(resolveGraphicChildOrder(this.graphicSpec, target, value));

package/src/actions/primitives/semanticAction.js

@@ -232,7 +232,7 @@ export function withoutPreviewLayerEncodings(program, { id, channels }) {
   return program._clone({ semanticSpec });
 }
 
-// Composition materialization may retain this native two-scale guide meaning.
+// Composition materialization may retain this native combined guide meaning.
 // Use the existing semantic primitives on a private unit adapter; this does not
 // relax the public composition guard or accept arbitrary semantic paths.
 export function synchronizeFacetColorSizeMeaning(program, meaning) {
@@ -240,7 +240,7 @@ export function synchronizeFacetColorSizeMeaning(program, meaning) {
     throw new Error("Color-size parent meaning requires a facet composition.");
   }
   if (meaning !== undefined && (!isPlainObject(meaning) ||
-      Object.keys(meaning).some(key => !["colorScale", "sizeScale", "title"].includes(key)))) {
+      Object.keys(meaning).some(key => !["colorScale", "sizeScale", "shapeScale", "colorChannel", "title"].includes(key)))) {
     throw new Error("Color-size parent meaning requires its native scale bindings and title.");
   }
   let unit = new program.constructor({ semanticSpec: program.semanticSpec, graphicSpec: program.graphicSpec,
@@ -281,11 +281,10 @@ export function createSemanticPrimitiveAction(validateSemanticValue, planNamedRe
       const removesNamedResource = remove && parsed.path.length === 0 &&
         ["dataset", "scale", "coordinate"].includes(parsed.kind);
       if (this.compositionSpec !== undefined && !(
-        this.compositionSpec.type === "facet" &&
-        (parsed.kind === "title" || removesNamedResource)
+        parsed.kind === "title" || (this.compositionSpec.type === "facet" && removesNamedResource)
       )) {
         throw new Error(
-          "editSemantic on a composition parent supports only facet title state and unreferenced named resource removal."
+          "editSemantic on a composition parent supports only title state and unreferenced named resource removal."
         );
       }
       if (remove) {

package/src/actions/primitives/semanticValidation/guide.js

@@ -29,6 +29,7 @@ export function validateGuideSemanticValue(_program, parsed, value) {
   const property = parsed.path.at(-1);
   if (parsed.id === "legend.colorSize") {
     if(property === "title") validateNonEmptySemanticString(value,"Legend title");
+    else if(property === "colorChannel") { if(!["color","stroke"].includes(value))throw new Error("Combined legend colorChannel requires color or stroke."); }
     else validateUserId(value,"Legend scale id");
     return;
   }

package/src/actions/primitives/semanticValidation/layer.js

@@ -23,6 +23,7 @@ import { ITEM_MISSING_MARK_TYPES, validateItemMissing } from
   "../../../grammar/itemMissing.js";
 import { isIndependentText, validateTextOffsetEncoding } from "../../../grammar/text.js";
 import { validateLineMissing, validateLineMissingScope } from "../../../grammar/lineMissing.js";
+import { normalizeOverlayBinding } from "../../../grammar/overlay.js";
 
 function validateLayerSource(program, parsed, value, sourceMarkTypes) {
   validateUserId(value, "Layer source id");
@@ -53,6 +54,12 @@ export function validateLayerSemanticValue(
   } = {}
 ) {
   const property = parsed.path.join(".");
+  if (property === "derivedBindings.overlay") {
+    const binding = normalizeOverlayBinding(value);
+    validateLayerSource(program, parsed, binding.source, ["bar", "line", "area", "point"]);
+    if (findLayer(program, binding.source)?.derivedBindings?.overlay) throw new Error("Overlay source must be independent.");
+    return;
+  }
   if (/^encoding\.(dx|dy)(\.|$)/.test(property)) {
     if (!isIndependentText(findLayer(program, parsed.id))) {
       throw new Error("Numeric text offsets require independent Text marks.");

package/src/actions/scales/consumers/common.js

@@ -9,6 +9,8 @@ import { findDataset } from "../../../selectors/datasets.js";
 import { requireSemanticScale } from "../../../selectors/scales.js";
 import { SCALED_ENCODING_CHANNELS } from "../../../core/vocabulary.js";
 import { applyItemMissingPolicy } from "../../../grammar/itemMissing.js";
+import { resolveOverlaySeries } from "../../../materialization/overlayItems.js";
+import { uniqueFields } from "../../../materialization/selection/items/common.js";
 
 export function findScale(program, id) {
   return requireSemanticScale(program, id);
@@ -19,6 +21,8 @@ export function findScaleConsumers(program, id) {
   for (const layer of program.semanticSpec.layers) {
     if (isSourceOwnedText(layer)) continue;
     for (const channel of SCALED_ENCODING_CHANNELS) {
+      if (layer.derivedBindings?.overlay && ["x", "y", "x2", "y2", "xOffset", "yOffset"].includes(channel)) continue;
+      if (layer.derivedBindings?.overlay?.inheritColor && channel === "color") continue;
       const encoding = layer.encoding?.[channel];
       if (encoding?.scale === id) consumers.push({ layer, channel, encoding });
     }
@@ -59,6 +63,12 @@ export function readConsumerFieldValues(
   scale = findScale(program, consumer.encoding.scale)
 ) {
   const { field, fieldType, temporalUnit } = consumer.encoding;
+  if (consumer.layer.derivedBindings?.overlay) {
+    const groups = resolveOverlaySeries(program, consumer.layer.derivedBindings.overlay, { geometry: false });
+    const rows = consumer.layer.mark.type === "point" ? groups.flatMap(group => group.points.map(point => point.fields))
+      : groups.map(group => uniqueFields(group.points.map(point => point.fields)));
+    return readScaleField(rows, field, fieldType, { allowUnknown: Object.hasOwn(scale, "unknown"), temporalUnit });
+  }
   if (consumer.layer.mark.type === "line" && consumer.layer.mark.missing === "break" &&
       ["x", "y"].includes(consumer.channel)) {
     return readLinePosition(dataset.values, consumer.encoding).filter(value => value !== null);

package/src/actions/scales/consumers/families.js

@@ -60,7 +60,7 @@ export function resolveMarkFamilyConsumerValues(program, consumer, dataset) {
   if (
     layer.mark?.type === "line" &&
     ((["x", "y"].includes(channel) && encoding.x !== undefined &&
-      isAggregate(encoding.y?.aggregate) &&
+      (isAggregate(encoding.y?.aggregate) || isAggregate(encoding.x?.aggregate)) &&
       !(channel === "x" &&
         encoding.x?.bin !== undefined)) ||
       appearance) &&

package/src/actions/scales/preview.js

@@ -63,7 +63,7 @@ function resolveScalePreviewAtBounds(program, id, bounds) {
   const polarFrame = channel === "radius"
     ? resolveSharedRadiusFrame(program, consumers, bounds)
     : undefined;
-  const resolvedScale = resolveScaleMaterialization({ id, scale, channel, consumers, valuesByConsumer,
+  const resolvedScale = resolveScaleMaterialization({ program, id, scale, channel, consumers, valuesByConsumer,
     bounds: ["color", "stroke", "strokeDash", "strokeWidth", "shape", "size", "opacity", "xOffset", "yOffset"].includes(channel)
       ? undefined : bounds,
     resolvedScales: program.resolvedScales, markConfigs: program.markConfigs, polarFrame,

package/src/actions/selection/actions.js

@@ -1,3 +1,4 @@
+import { highlightTargets } from "../../selectors/selectionTargets.js";
 import { action, closedAction } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
@@ -30,7 +31,7 @@ import {
 } from "../theme/state.js";
 
 const SELECTOR_KEYS = Object.freeze([
-  "grain", "field", "channel", "property", "op", "value", "values", "min", "max",
+  "rows", "grain", "field", "channel", "property", "op", "value", "values", "min", "max",
   "inclusive", "count", "groupBy", "ties"
 ]);
 const SELECT_OPTIONS = Object.freeze(["id", "target", ...SELECTOR_KEYS]);
@@ -39,7 +40,7 @@ const REMOVE_SELECTION_OPTIONS = Object.freeze(["selection"]);
 const HIGHLIGHT_OPTIONS = Object.freeze([
   "id", "target", "select", "selection", "color", "opacity", "fill",
   "stroke", "strokeWidth", "strokeDash", "shape", "size", "offset",
-  "dimOthers", "bringToFront"
+  "dimOthers", "bringToFront", "fontSize"
 ]);
 const INTERNAL_SELECTION_OPTIONS = Object.freeze(["selection", "style", "keys"]);
 const INTERNAL_DIM_OPTIONS = Object.freeze(["selection", "opacity", "keys"]);
@@ -59,7 +60,7 @@ function resolveTarget(program, target, label = "mark selection") {
   return resolveEligibleLayer(program, {
     target: requested,
     label,
-    predicate: layer => findSelectionPolicy(layer.mark?.type) !== undefined
+    predicate: layer => findSelectionPolicy(layer.mark?.type) !== undefined && (requested !== undefined || !isSourceOwnedText(layer))
   });
 }
 
@@ -321,7 +322,7 @@ export const removeMarkHighlight = /* @__PURE__ */ closedAction(
     const current = resolveStoredSelection(this, args.selection);
     const dependent = Object.entries(
       this.materializationConfigs.highlights ?? {}
-    ).filter(([, config]) => config.selection === current.id);
+    ).filter(([, config]) => config.selection === current.id || config.groupSelection === current.id);
     if (dependent.length === 0) {
       throw new Error(
         `Selection "${current.id}" has no highlight assignment.`
@@ -331,7 +332,8 @@ export const removeMarkHighlight = /* @__PURE__ */ closedAction(
     for (const [id] of dependent) {
       next = next._withoutMaterializationConfig(["highlights", id]);
     }
-    return rebuildTargetHighlights(next, current.definition.target);
+    for (const target of new Set(dependent.map(([, config]) => config.target))) next = rebuildTargetHighlights(next, target);
+    return next;
   }
 );
 
@@ -342,7 +344,9 @@ export const removeMarkSelection = /* @__PURE__ */ closedAction(
   }, REMOVE_SELECTION_OPTIONS,
   function (args = {}) {
     const current = resolveStoredSelection(this, args.selection);
-    const labelDependents = namedLabelDependents(this, current.id);
+    const componentDependents = Object.entries(this.materializationConfigs.selections ?? {}).filter(([, definition]) => definition.sourceSelection === current.id);
+    const labelDependents = [current.id, ...componentDependents.map(([id]) => id)]
+      .flatMap(id => namedLabelDependents(this, id));
     if (labelDependents.length > 0) {
       throw new Error(
         `Selection "${current.id}" is referenced by attached labels: ${labelDependents.join(", ")}.`
@@ -354,6 +358,7 @@ export const removeMarkSelection = /* @__PURE__ */ closedAction(
     let next = hasDependentHighlight
       ? this.removeMarkHighlight({ selection: current.id })
       : this;
+    for (const [id] of componentDependents) next = next._withoutMaterializationConfig(["selections", id]);
     next = next._withoutMaterializationConfig(["selections", current.id]);
     return this.context.currentSelection === current.id
       ? next._withContext({ currentSelection: undefined })
@@ -540,9 +545,7 @@ export const rematerializeMarkHighlights = /* @__PURE__ */ closedAction(
   }
 );
 
-export const highlightMarks = /* @__PURE__ */ closedAction(
-  { op: "highlightMarks", description: "Select and emphasize final visual mark items." }, HIGHLIGHT_OPTIONS,
-  function (args = {}) {
+function highlightSingle(args = {}) {
     if (args.select !== undefined && args.selection !== undefined) {
       throw new Error("highlightMarks accepts select or selection, not both.");
     }
@@ -564,15 +567,20 @@ export const highlightMarks = /* @__PURE__ */ closedAction(
     if (args.select !== undefined) {
       layer = resolveTarget(this, args.target, "highlight mark");
       resolveMarkSelection(this, layer.id, args.select);
+      if (args.fontSize !== undefined && layer.mark.type !== "text") throw new Error("fontSize highlight requires a text mark.");
       const style = requireSelectionPolicy(
         layer.mark.type
       ).normalizeHighlightStyle(args);
-      next = next.selectMarks({
+      if (args.id !== undefined && next.materializationConfigs.selections?.[args.id]) {
+        if (next.materializationConfigs.selections[args.id].target !== layer.id) throw new Error("Highlight ID belongs to a different target.");
+        if (next.materializationConfigs.highlights?.[args.id]) next = next.removeMarkHighlight({ selection: args.id });
+        next = next.editMarkSelection({ selection: args.id, ...args.select });
+      } else next = next.selectMarks({
         ...(args.id === undefined ? {} : { id: args.id }),
         target: layer.id,
         ...args.select
       });
-      resolved = resolveStoredSelection(next);
+      resolved = resolveStoredSelection(next, args.id);
       resolved = { ...resolved, style };
     } else {
       resolved = resolveStoredSelection(next, args.selection);
@@ -580,6 +588,7 @@ export const highlightMarks = /* @__PURE__ */ closedAction(
         throw new Error("highlightMarks target must match its selection target.");
       }
       layer = resolveTarget(next, resolved.definition.target, "highlight mark");
+      if (args.fontSize !== undefined && layer.mark.type !== "text") throw new Error("fontSize highlight requires a text mark.");
       resolved = {
         ...resolved,
         style: requireSelectionPolicy(
@@ -611,4 +620,47 @@ export const highlightMarks = /* @__PURE__ */ closedAction(
       ? next.rematerializeLegendHighlights()
       : next;
   }
+
+export const highlightMarks = /* @__PURE__ */ closedAction(
+  { op: "highlightMarks", description: "Select and emphasize final visual mark items." }, HIGHLIGHT_OPTIONS,
+  function (args = {}) {
+    if (args.select === undefined && args.id === undefined) {
+      const named = resolveStoredSelection(this, args.selection);
+      if (highlightTargets(this, named.definition.target).length > 1) {
+        if (args.target !== undefined && args.target !== named.definition.target) throw new Error("highlightMarks target must match its selection target.");
+        args = { ...args, id: named.id, target: named.definition.target, select: named.selector };
+        delete args.selection;
+      }
+    }
+    const targets = args.target === undefined ? [] : highlightTargets(this, args.target);
+    if (targets.length <= 1 || args.select === undefined) return highlightSingle.call(this, { ...args, ...(targets[0] ? { target: targets[0] } : {}) });
+    const primary = resolveMarkSelection(this, targets[0], args.select);
+    const selected = new Set(primary.keys);
+    const rows = primary.items.filter(item => selected.has(item.key)).flatMap(item => item.rows);
+    // The oldest explicitly recorded dataset is common to all dependent marks.
+    const datasets = this.semanticSpec.datasets;
+    const source = datasets.find(dataset => primary.items.some(item => item.rows.some(ref => ref.data === dataset.id)));
+    const select = source ? { rows: { data: source.id, indices: [...new Set(rows.filter(ref => ref.data === source.id).map(ref => ref.index))] } } : args.select;
+    const baseId = args.id ?? resolveSelectionCreationId(this, undefined, targets[0]);
+    let next = this;
+    for (const target of targets) {
+      const local = { ...args, id: target === targets[0] ? baseId : `${baseId}-${target}`, target,
+        select: target === targets[0] ? args.select : select };
+      if (target !== targets[0] && args.select.field && !['min', 'max'].includes(args.select.op)) {
+        try { resolveMarkSelection(this, target, args.select); local.select = args.select; } catch { /* Keep the owner's source-row selection for mixed-grain components. */ }
+      }
+      // Common color/opacity propagate; shape and area are component-specific.
+      const type = findLayer(this, target).mark.type;
+      if (type !== 'point') { delete local.size; delete local.shape; }
+      if (!['line', 'rule', 'tick'].includes(type)) delete local.strokeDash;
+      if (type === 'bar') delete local.offset;
+      if (target !== targets[0] && ['line', 'rule', 'tick'].includes(type) && local.fill) { local.color = local.fill; delete local.fill; }
+      next = highlightSingle.call(next, local);
+      if (target !== targets[0] && source) {
+        next = next._withSelectionConfig(local.id, { ...next.materializationConfigs.selections[local.id], sourceSelection: baseId });
+      }
+      next = next._withHighlightConfig(local.id, { ...next.materializationConfigs.highlights[local.id], groupSelection: baseId });
+    }
+    return next._withContext({ currentSelection: baseId });
+  }
 );

package/src/actions/titles/actions.js

@@ -13,14 +13,6 @@ import {
   resolveCanvasGraphicPlacement
 } from "../../materialization/graphicHierarchy.js";
 
-function assertTitleScope(program, operation) {
-  if (
-    program.compositionSpec !== undefined &&
-    program.compositionSpec.type !== "facet"
-  ) {
-    throw new Error(`${operation} is not available on this composition ChartProgram.`);
-  }
-}
 
 function hasRotation(graphic) {
   return (graphic.items ?? [graphic]).some(
@@ -136,7 +128,6 @@ export const createTitle = /* @__PURE__ */ action(
     scope: "any"
   },
   withGuideLayoutValidation(function (args = {}) {
-    assertTitleScope(this, "createTitle");
     const options = normalizeTitleOptions(args);
     if (Object.keys(this.semanticSpec.title).length > 0) {
       throw new Error("createTitle requires missing semantic title state.");
@@ -153,7 +144,7 @@ export const createTitle = /* @__PURE__ */ action(
       next = next.editSemantic({ property: "title.subtitle", value: subtitle });
     }
     next = next._withTitleConfig(config);
-    if (next.compositionSpec?.type === "facet") {
+    if (next.compositionSpec !== undefined) {
       return next.materializeComposition();
     }
     resolveTitleLayout(next, config);
@@ -170,7 +161,6 @@ export const editTitle = /* @__PURE__ */ action(
     scope: "any"
   },
   withGuideLayoutValidation(function (args = {}) {
-    assertTitleScope(this, "editTitle");
     if (this.semanticSpec.title.text === undefined) {
       throw new Error("editTitle requires an existing chart title.");
     }
@@ -193,7 +183,7 @@ export const editTitle = /* @__PURE__ */ action(
       });
     }
     next = next._withTitleConfig(normalized.config);
-    if (next.compositionSpec?.type === "facet") {
+    if (next.compositionSpec !== undefined) {
       return next.materializeComposition();
     }
     resolveTitleLayout(next, normalized.config);
@@ -208,7 +198,6 @@ export const removeTitle = /* @__PURE__ */ action(
     scope: "any"
   },
   withGuideLayoutValidation(function (args = {}) {
-    assertTitleScope(this, "removeTitle");
     noOptions(args, "removeTitle");
     if (
       this.semanticSpec.title.text === undefined &&
@@ -231,7 +220,7 @@ export const removeTitle = /* @__PURE__ */ action(
       }
     }
     next = next._withoutMaterializationConfig(["title"]);
-    return next.compositionSpec?.type === "facet"
+    return next.compositionSpec !== undefined
       ? next.materializeComposition()
       : next;
   })