ggaction 0.0.13 → 0.0.15

package/src/actions/marks/remove.js

@@ -5,10 +5,15 @@ import { validateKeys } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
 import { applyDetachedScaleRematerialization } from "../../materialization/dependencies.js";
+import { markLabelPlacementLeaderId } from "../../layout/labels.js";
 import {
   getPositionChannelDefinition,
   POSITION_CHANNELS
 } from "../../core/vocabulary.js";
+import {
+  canonicalResourcePath,
+  collectResourceReferences
+} from "../../core/resourceReferences.js";
 
 const OPTIONS = Object.freeze(["target"]);
 const REMOVE_AXIS = Object.freeze({
@@ -40,6 +45,12 @@ function ownedChildren(program, id) {
     program.semanticSpec.layers
       .filter(layer => layer.source === id)
       .map(layer => layer.id)
+  ).concat(
+    program.semanticSpec.layers
+      .filter(layer =>
+        program.markConfigs[layer.id]?.statisticalReference?.source === id
+      )
+      .map(layer => layer.id)
   ).filter(child => child !== undefined && child !== id && findLayer(program, child) !== undefined);
 }
 
@@ -47,6 +58,9 @@ function ownership(program) {
   const ownerByChild = new Map();
   for (const layer of program.semanticSpec.layers) {
     for (const child of ownedChildren(program, layer.id)) {
+      if (program.markConfigs[child]?.statisticalReference !== undefined) {
+        continue;
+      }
       ownerByChild.set(child, layer.id);
     }
   }
@@ -86,6 +100,37 @@ function collectClosure(program, root) {
   return result;
 }
 
+function externalMarkReferences(program, ids) {
+  const closure = new Set(ids);
+  const references = ids.flatMap(id => collectResourceReferences(program, {
+    kind: "mark",
+    id
+  })).filter(reference => {
+    if (reference.strength === "context") return false;
+    if (["layer", "markConfig"].includes(reference.ownerKind)) {
+      return !closure.has(reference.ownerId);
+    }
+    if (["selection", "highlight", "legend"].includes(reference.ownerKind)) {
+      return false;
+    }
+    if (
+      reference.ownerKind === "axis" &&
+      reference.ownerId === "parallel.axes"
+    ) {
+      return false;
+    }
+    return true;
+  });
+  const unique = new Map(references.map(reference => [[
+    reference.ownerKind,
+    reference.ownerId,
+    canonicalResourcePath(reference.path)
+  ].join("\u0000"), reference]));
+  return [...unique.entries()]
+    .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+    .map(([, reference]) => reference);
+}
+
 function ownedDerivedData(program, ids) {
   const candidates = new Set();
   for (const id of ids) {
@@ -100,7 +145,8 @@ function ownedDerivedData(program, ids) {
       config.gradientPlot?.profileId,
       config.violinPlot?.materialized === true ? layer?.data : undefined,
       config.ecdfPlot?.data,
-      config.endpointPlot?.data
+      config.endpointPlot?.data,
+      config.statisticalReference?.dataId
     ]) {
       if (candidate !== undefined) candidates.add(candidate);
     }
@@ -208,11 +254,26 @@ export const removeMark = action(
     validateKeys(args, OPTIONS, "removeMark");
     const owner = resolveOwner(this, args.target);
     const ids = collectClosure(this, owner.id);
+    const external = externalMarkReferences(this, ids);
+    if (external.length > 0) {
+      throw new Error(
+        `removeMark cannot remove externally referenced marks: ${external.map(
+          reference => `${reference.ownerKind} "${reference.ownerId}" at ` +
+            canonicalResourcePath(reference.path)
+        ).join("; ")}.`
+      );
+    }
     const previousLayers = ids.map(id => findLayer(this, id));
     const derived = ownedDerivedData(this, ids);
     const positionScales = usedPositionScales(this, ids);
     let next = this;
 
+    if (ids.includes(next.guideConfigs.axis?.parallel?.axes?.target)) {
+      next = next.removeParallelAxes({
+        target: next.guideConfigs.axis.parallel.axes.target
+      });
+    }
+
     const legendTargets = [...new Set(Object.values(next.guideConfigs.legend ?? {})
       .filter(config => ids.includes(config?.target))
       .map(config => config.target))];
@@ -230,6 +291,15 @@ export const removeMark = action(
       ) {
         next = next.editGraphics({ target: labelLayout.leaderId, remove: true });
       }
+      const placement = next.markConfigs[id]?.labelAuthoring?.placement;
+      const placementLeaderId = markLabelPlacementLeaderId(id);
+      if (
+        placement?.leader !== undefined &&
+        placement.leader !== false &&
+        next.graphicSpec.objects[placementLeaderId] !== undefined
+      ) {
+        next = next.editGraphics({ target: placementLeaderId, remove: true });
+      }
       if (findLayer(next, id) !== undefined) {
         next = next.editSemantic({ property: `layer[${id}]`, remove: true });
       }

package/src/actions/marks/rule/actions.js

@@ -9,11 +9,13 @@ import {
   normalizeStrokeDashPattern
 } from "../../../grammar/scales/index.js";
 import { deriveRuleValues, resolveRuleMode } from "../../../grammar/rules.js";
-import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { resolveCoordinateBounds } from "../../../materialization/coordinateBounds.js";
+import { readRectItemGeometry } from "../../../grammar/roundedRect.js";
 import { findDataset } from "../../../selectors/datasets.js";
 import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
 import { applyRuleAppearance, planRuleAppearance } from "./appearance.js";
 import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+import { rematerializeExistingLegend } from "../../encodings/shared.js";
 import {
   assertMarkAvailable,
   applyLayeredMarkInheritance,
@@ -31,9 +33,19 @@ import { applyOffsetPositionValues } from
   "../../../materialization/rowEncoding.js";
 import { resolveCategorySlotOffset } from
   "../../../materialization/categorySlotOffset.js";
+import { mapScaleConsumerValues } from
+  "../../../materialization/scales/map.js";
+import {
+  requestedStrokeDetails,
+  STROKE_STYLE_PROPERTIES
+} from "../../../grammar/strokeStyle.js";
 
-const CREATE_OPTIONS = Object.freeze(["id", "data", "stroke", "strokeWidth", "strokeDash", "opacity"]);
-const EDIT_OPTIONS = Object.freeze(["target", "stroke", "strokeWidth", "strokeDash", "opacity"]);
+const APPEARANCE_OPTIONS = Object.freeze([
+  "stroke", "strokeWidth", "strokeDash", "opacity",
+  ...STROKE_STYLE_PROPERTIES
+]);
+const CREATE_OPTIONS = Object.freeze(["id", "data", ...APPEARANCE_OPTIONS]);
+const EDIT_OPTIONS = Object.freeze(["target", ...APPEARANCE_OPTIONS]);
 const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
 const SPAN_OPTIONS = Object.freeze(["id", "orientation", "size"]);
 const DEFAULT_RULE_CONFIG = Object.freeze({
@@ -87,6 +99,7 @@ const createRuleMark = action(
   },
   function (args = {}) {
     validateMarkOptions(args, CREATE_OPTIONS, "createRuleMark");
+    const strokeDetails = requestedStrokeDetails(args, "createRuleMark");
     const id = resolveMarkId(this, args.id, {
       defaultId: "rule",
       label: "Rule mark id",
@@ -115,6 +128,7 @@ const createRuleMark = action(
       })
       ._withMarkConfig(id, {
         ...DEFAULT_RULE_CONFIG,
+        ...strokeDetails,
         ...(inherited === undefined
           ? {}
           : {
@@ -132,6 +146,7 @@ const editRuleMark = action(
   { op: "editRuleMark", description: "Edit constant rule appearance through its encoding owners." },
   function (args = {}) {
     validateMarkOptions(args, EDIT_OPTIONS, "editRuleMark");
+    const strokeDetails = requestedStrokeDetails(args, "editRuleMark");
     if (args.target !== undefined) validateUserId(args.target, "Rule mark id");
     const layer = resolveEligibleLayer(this, {
       target: args.target,
@@ -139,8 +154,17 @@ const editRuleMark = action(
       label: "rule mark"
     });
     const appearance = planRuleAppearance(args, layer);
-    if (appearance.length === 0) throw new Error("editRuleMark requires an appearance change.");
-    return applyRuleAppearance(this, layer.id, appearance);
+    if (appearance.length === 0 && Object.keys(strokeDetails).length === 0) {
+      throw new Error("editRuleMark requires an appearance change.");
+    }
+    const configured = this._withMarkConfig(layer.id, {
+      ...this.markConfigs[layer.id],
+      ...strokeDetails
+    });
+    const materialized = appearance.length === 0
+      ? configured.rematerializeRuleMark({ id: layer.id })
+      : applyRuleAppearance(configured, layer.id, appearance);
+    return rematerializeExistingLegend(materialized);
   }
 );
 
@@ -180,7 +204,7 @@ const rematerializeRuleMark = action(
     const scaleIds = [...new Set(
       [
         "x", "y", "x2", "y2", "xOffset", "yOffset",
-        "strokeDash", "strokeWidth", "opacity"
+        "stroke", "strokeDash", "strokeWidth", "opacity"
       ]
         .map(channel => layer.encoding?.[channel]?.scale)
         .filter(scale => scale !== undefined)
@@ -224,7 +248,7 @@ const rematerializeRuleMark = action(
         channel
       });
     }
-    const bounds = resolveGraphicBounds(resolved);
+    const bounds = resolveCoordinateBounds(resolved, layer.coordinate);
     const x1 = [];
     const y1 = [];
     const x2 = [];
@@ -252,7 +276,11 @@ const rematerializeRuleMark = action(
         startY = endY = mapped.y[index];
       } else if (mode === "box-span") {
         const owner = resolved.graphicSpec.objects[boxSpan];
-        const box = owner?.items?.[index]?.properties;
+        const item = owner?.items?.[index];
+        const box = readRectItemGeometry({
+          type: item?.type ?? owner?.type,
+          properties: item?.properties
+        });
         if (box === undefined) throw new Error(`Rule mark "${id}" requires box span owner "${boxSpan}".`);
         if (layer.encoding?.x?.fieldType === "quantitative") {
           startX = endX = mapped.x[index];
@@ -299,6 +327,7 @@ const rematerializeRuleMark = action(
       ...resolved.markConfigs[id]
     };
     const dashEncoding = layer.encoding?.strokeDash;
+    const strokeEncoding = layer.encoding?.stroke;
     const opacityEncoding = layer.encoding?.opacity;
     const strokeWidthEncoding = layer.encoding?.strokeWidth;
     const strokeDash = dashEncoding?.scale === undefined
@@ -325,6 +354,13 @@ const rematerializeRuleMark = action(
           derived.values.strokeWidth,
           resolved.resolvedScales[strokeWidthEncoding.scale]
         );
+    const stroke = strokeEncoding?.scale === undefined
+      ? resolvedConfig.stroke
+      : mapScaleConsumerValues(
+          derived.values.stroke,
+          resolved.resolvedScales[strokeEncoding.scale],
+          "stroke"
+        );
 
     return editMarkGraphic(resolved, id, {
       length: derived.length,
@@ -332,10 +368,11 @@ const rematerializeRuleMark = action(
       y1,
       x2,
       y2,
-      stroke: resolvedConfig.stroke,
+      stroke,
       strokeWidth,
       strokeDash,
-      opacity
+      opacity,
+      ...requestedStrokeDetails(resolvedConfig, "Rule mark")
     });
   }
 );

package/src/actions/marks/shared.js

@@ -29,7 +29,7 @@ export function resolveMarkData(program, requested) {
   }
 
   const dataset = requireMaterializedDataset(program, data);
-  return { data, dataset };
+  return { data: dataset.id, dataset };
 }
 
 export function resolveMarkId(program, requested, {

package/src/actions/marks/text/actions.js

@@ -13,7 +13,17 @@ import {
   canMaterializeText,
   isTextSource
 } from "../../../materialization/marks/index.js";
-import { resolveTextGraphicItems } from "../../../materialization/text.js";
+import {
+  resolveTextGraphicItems,
+  validateSourceMarkLabelPlacement
+} from "../../../materialization/text.js";
+import { markLabelPlacementLeaderId } from "../../../layout/labels.js";
+import { resolveMarkSelection } from
+  "../../../materialization/selection/state.js";
+import { rematerializeLabelsBeforeHighlights } from
+  "../../selection/actions.js";
+import { normalizeLabelSelectionCreate } from
+  "../../../grammar/markLabelSelection.js";
 import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
 import {
   applyLayeredMarkInheritance,
@@ -49,6 +59,13 @@ function eligibleSource(program, layer, requestedData) {
     !sourceMatchesData(program, layer, requestedData)
   ) return false;
   if (layer.mark.type === "arc") return canMaterializeArc(program, layer);
+  if (
+    layer.mark.type === "point" &&
+    findCoordinate(program, layer.coordinate)?.type === "polar"
+  ) {
+    return layer.encoding?.theta?.scale !== undefined &&
+      layer.encoding?.radius?.scale !== undefined;
+  }
   if (layer.mark.type === "rect" && (canMaterializeRect(program, layer) ||
     program.markConfigs[layer.id]?.gradientPlot?.materialized === true)) return true;
   const encodings = resolveCompatibleEncodings(program, layer, "text");
@@ -91,7 +108,9 @@ function textInheritance(program, source) {
     source: source.id,
     data: source.data,
     coordinate: source.coordinate,
-    encoding: source.mark.type === "arc"
+    encoding: source.mark.type === "arc" ||
+      (source.mark.type === "point" &&
+        findCoordinate(program, source.coordinate)?.type === "polar")
       ? {}
       : resolveCompatibleEncodings(program, source, "text")
   };
@@ -161,6 +180,7 @@ const createTextMark = action(
 
 const LABEL_OPTIONS = Object.freeze([
   "id", "source", "field", "value", "content", "normalizeBy", "format", "layout",
+  "select", "selection", "placement",
   ...STYLE_OPTIONS
 ]);
 
@@ -320,6 +340,32 @@ const createMarkLabels = action(
     }
     const id = validateUserId(args.id === undefined ? `${inherited.source}-labels` : args.id, "Text mark id");
     assertMarkAvailable(this, id);
+    const selection = normalizeLabelSelectionCreate(args);
+    const placement = args.placement === undefined
+      ? undefined
+      : validateSourceMarkLabelPlacement(this, inherited.source, args.placement);
+    if (
+      placement?.leader !== undefined && placement.leader !== false &&
+      this.graphicSpec.objects[markLabelPlacementLeaderId(id)] !== undefined
+    ) {
+      throw new Error(
+        `Mark label placement leader graphic "${markLabelPlacementLeaderId(id)}" already exists.`
+      );
+    }
+    if (selection.kind === "inline") {
+      resolveMarkSelection(this, inherited.source, selection.selector);
+    } else if (selection.kind === "named") {
+      const definition = this.materializationConfigs.selections?.[selection.id];
+      if (definition === undefined) {
+        throw new Error(`Unknown label selection "${selection.id}".`);
+      }
+      if (definition.target !== inherited.source) {
+        throw new Error(
+          `Label selection "${selection.id}" must target source mark "${inherited.source}".`
+        );
+      }
+      resolveMarkSelection(this, inherited.source, definition.selector);
+    }
     const style = Object.fromEntries(STYLE_OPTIONS
       .filter(option => Object.hasOwn(args, option))
       .map(option => [option, args[option]]));
@@ -337,9 +383,23 @@ const createMarkLabels = action(
       throw new Error("createMarkLabels layout target is owned by the created label layer.");
     }
     const apply = program => {
-      const next = program.createTextMark({
+      let next = program.createTextMark({
         id, source: inherited.source, align: "center", baseline: "middle", ...style
-      }).encodeText({ target: id, ...encoding });
+      });
+      next = next._withMarkConfig(id, {
+        ...next.markConfigs[id],
+        labelAuthoring: {
+          selection,
+          ...(placement === undefined ? {} : { placement })
+        }
+      });
+      next = next.encodeText({ target: id, ...encoding });
+      next = rematerializeLabelsBeforeHighlights(
+        next,
+        inherited.source,
+        [id],
+        { skipWithoutHighlights: true }
+      );
       return layout === undefined ? next : next.layoutLabels({ ...layout, target: id });
     };
     if (layout !== undefined) {
@@ -376,9 +436,11 @@ const rematerializeTextMark = action(
         : this.editGraphics({ target: id, property: "length", value: 0 });
       return replayLayout && next.materializationConfigs.labelLayouts?.[id] !== undefined
         ? next.materializeLabelLayout({ id, rematerializeBase: false })
-        : next;
+        : layer.source === undefined
+          ? next
+          : next.materializeMarkLabelPlacement({ id });
     }
-    const next = this.editGraphics({
+    let next = this.editGraphics({
       target: id,
       property: "items",
       value: resolveTextGraphicItems(
@@ -387,9 +449,12 @@ const rematerializeTextMark = action(
         this.markConfigs[id] ?? DEFAULT_TEXT_MARK
       )
     });
-    return replayLayout && next.materializationConfigs.labelLayouts?.[id] !== undefined
-      ? next.materializeLabelLayout({ id, rematerializeBase: false })
-      : next;
+    if (replayLayout && next.materializationConfigs.labelLayouts?.[id] !== undefined) {
+      return next.materializeLabelLayout({ id, rematerializeBase: false });
+    }
+    return layer.source === undefined
+      ? next
+      : next.materializeMarkLabelPlacement({ id });
   }
 );
 

package/src/actions/marks/text/index.js

@@ -1,7 +1,11 @@
 import { registerTextMarkActions as registerTextCoreActions } from "./actions.js";
 import { registerTextLabelLayoutActions } from "./layout.js";
+import { registerTextLabelRemovalActions } from "./removal.js";
+import { registerTextLabelSelectionActions } from "./selection.js";
 
 export function registerTextMarkActions(ProgramClass) {
   registerTextCoreActions(ProgramClass);
   registerTextLabelLayoutActions(ProgramClass);
+  registerTextLabelRemovalActions(ProgramClass);
+  registerTextLabelSelectionActions(ProgramClass);
 }

package/src/actions/marks/text/layout.js

@@ -2,17 +2,23 @@ import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import { validateOptionObject } from "../../../core/validation.js";
 import { DEFAULT_TEXT_MARK } from "../../../grammar/text.js";
+import { isSourceOwnedText } from "../../../grammar/text.js";
 import { findGraphicParent } from "../../../grammar/schemas/graphicTree.js";
 import { validateConcreteGraphicValue } from
   "../../../grammar/schemas/concreteGraphic.js";
 import {
+  markLabelPlacementLeaderId,
   normalizeLabelLayoutGeometry,
   resolveLabelLayout,
   resolveLabelLeader
 } from "../../../layout/labels.js";
+import { resolveTextBounds } from "../../../core/textMetrics.js";
 import { resolveGraphicBounds } from "../../../layout/canvas.js";
 import { canMaterializeText } from "../../../materialization/marks/index.js";
-import { resolveTextGraphicEntries } from "../../../materialization/text.js";
+import {
+  resolveTextGraphicEntries,
+  validateSourceMarkLabelPlacement
+} from "../../../materialization/text.js";
 import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
 import { editMarkGraphic } from "../shared.js";
 
@@ -21,6 +27,8 @@ export const TEXT_LABEL_LAYOUT_OPTIONS = Object.freeze([
 ]);
 const REMOVE_OPTIONS = Object.freeze(["target"]);
 const MATERIALIZE_OPTIONS = Object.freeze(["id", "rematerializeBase"]);
+const MATERIALIZE_PLACEMENT_OPTIONS = Object.freeze(["id"]);
+const EDIT_PLACEMENT_OPTIONS = Object.freeze(["target", "placement"]);
 const LEADER_OPTIONS = Object.freeze([
   "stroke", "strokeWidth", "strokeDash", "opacity"
 ]);
@@ -166,10 +174,10 @@ function removeLeaderGraphic(program, id) {
     : program.editGraphics({ target: id, remove: true });
 }
 
-function materializeLeaders(program, layer, config, resolved) {
+function materializeLeaders(program, layer, config, items) {
   let next = removeLeaderGraphic(program, config.leaderId);
   if (config.leader === false) return { program: next, count: 0 };
-  const leaders = resolved.items.map(resolveLabelLeader).filter(Boolean);
+  const leaders = items.map(resolveLabelLeader).filter(Boolean);
   if (leaders.length === 0) return { program: next, count: 0 };
   next = next.createGraphics({
       id: config.leaderId,
@@ -190,6 +198,75 @@ function materializeLeaders(program, layer, config, resolved) {
   return { program: next, count: leaders.length };
 }
 
+function placementLeaderItems(program, layer) {
+  const entries = resolveTextGraphicEntries(
+    program,
+    layer,
+    program.markConfigs[layer.id] ?? DEFAULT_TEXT_MARK
+  );
+  const graphic = program.graphicSpec.objects[layer.id];
+  if (graphic?.type !== "text" || !Array.isArray(graphic.items)) {
+    throw new Error(`Text mark "${layer.id}" requires text collection graphics.`);
+  }
+  if (entries.length !== graphic.items.length) {
+    throw new Error(`Text mark "${layer.id}" placement materialization is inconsistent.`);
+  }
+  return entries.map((entry, index) => {
+    const properties = graphic.items[index].properties;
+    return {
+      id: graphic.items[index].id,
+      x: properties.x,
+      y: properties.y,
+      sourceX: entry.anchor.x,
+      sourceY: entry.anchor.y,
+      dx: properties.x - entry.anchor.x,
+      dy: properties.y - entry.anchor.y,
+      bounds: resolveTextBounds(properties)
+    };
+  });
+}
+
+const materializeMarkLabelPlacement = action(
+  {
+    op: "materializeMarkLabelPlacement",
+    description: "Reconcile semantic attached-label placement leaders."
+  },
+  function (args = {}) {
+    validateOptionObject(
+      args,
+      MATERIALIZE_PLACEMENT_OPTIONS,
+      "materializeMarkLabelPlacement"
+    );
+    const id = validateUserId(args.id, "Attached label id");
+    const layer = findLayer(this, id);
+    if (!isSourceOwnedText(layer)) {
+      throw new Error(`Unknown attached label target "${id}".`);
+    }
+    const leaderId = markLabelPlacementLeaderId(id);
+    const placement = this.markConfigs[id]?.labelAuthoring?.placement;
+    if (placement?.leader === undefined || placement.leader === false) {
+      return this;
+    }
+    const layout = this.materializationConfigs.labelLayouts?.[id];
+    if (layout !== undefined && layout.leader !== false) {
+      throw new Error(
+        "Semantic label placement leader conflicts with the active collision-layout leader."
+      );
+    }
+    if (!canMaterializeText(this, layer)) {
+      return removeLeaderGraphic(this, leaderId);
+    }
+    return materializeLeaders(this, layer, {
+      leaderId,
+      leader: {
+        ...placement.leader,
+        strokeDash: [],
+        opacity: 1
+      }
+    }, placementLeaderItems(this, layer)).program;
+  }
+);
+
 const materializeLabelLayout = action(
   {
     op: "materializeLabelLayout",
@@ -222,9 +299,9 @@ const materializeLabelLayout = action(
       x: resolved.items.map(item => item.x),
       y: resolved.items.map(item => item.y)
     });
-    const leaders = materializeLeaders(next, layer, config, resolved);
+    const leaders = materializeLeaders(next, layer, config, resolved.items);
     next = leaders.program;
-    return next._withMaterializationConfig(["labelLayouts", id], {
+    next = next._withMaterializationConfig(["labelLayouts", id], {
       axis: config.axis,
       padding: config.padding,
       maxDisplacement: config.maxDisplacement,
@@ -243,6 +320,9 @@ const materializeLabelLayout = action(
         warnings: resolved.warnings
       }
     });
+    return layer.source === undefined
+      ? next
+      : next.materializeMarkLabelPlacement({ id });
   }
 );
 
@@ -255,6 +335,12 @@ const layoutLabels = action(
     validateOptionObject(args, TEXT_LABEL_LAYOUT_OPTIONS, "layoutLabels");
     const layer = requireCompleteText(this, args.target, "layoutLabels");
     const policy = normalizePolicy(args);
+    const placement = this.markConfigs[layer.id]?.labelAuthoring?.placement;
+    if (policy.leader !== false && placement?.leader !== false && placement?.leader !== undefined) {
+      throw new Error(
+        "Collision-layout leader conflicts with the active semantic label placement leader."
+      );
+    }
     const generatedId = leaderId(layer.id);
     const existingConfig = this.materializationConfigs.labelLayouts?.[layer.id];
     if (
@@ -272,6 +358,66 @@ const layoutLabels = action(
   }
 );
 
+const editMarkLabelPlacement = action(
+  {
+    op: "editMarkLabelPlacement",
+    description: "Replace or reset semantic placement for one attached label layer."
+  },
+  function (args = {}) {
+    validateOptionObject(args, EDIT_PLACEMENT_OPTIONS, "editMarkLabelPlacement", {
+      allowEmpty: false,
+      emptyError: Error
+    });
+    if (!Object.hasOwn(args, "target") || !Object.hasOwn(args, "placement")) {
+      throw new Error("editMarkLabelPlacement requires target and placement.");
+    }
+    const id = validateUserId(args.target, "Attached label id");
+    const layer = findLayer(this, id);
+    if (!isSourceOwnedText(layer)) {
+      throw new Error(`Unknown attached label target "${id}".`);
+    }
+    let placement;
+    if (args.placement !== "auto") {
+      placement = validateSourceMarkLabelPlacement(this, layer.source, args.placement);
+      if (
+        placement.leader !== false &&
+        this.materializationConfigs.labelLayouts?.[id]?.leader !== false &&
+        this.materializationConfigs.labelLayouts?.[id]?.leader !== undefined
+      ) {
+        throw new Error(
+          "Semantic label placement leader conflicts with the active collision-layout leader."
+        );
+      }
+      const generatedId = markLabelPlacementLeaderId(id);
+      const previous = this.markConfigs[id]?.labelAuthoring?.placement;
+      if (
+        placement.leader !== false &&
+        this.graphicSpec.objects[generatedId] !== undefined &&
+        (previous?.leader === undefined || previous.leader === false)
+      ) {
+        throw new Error(`Mark label placement leader graphic "${generatedId}" already exists.`);
+      }
+    }
+    const config = this.markConfigs[id] ?? DEFAULT_TEXT_MARK;
+    const previousPlacement = config.labelAuthoring?.placement;
+    let base = this;
+    if (
+      previousPlacement?.leader !== undefined &&
+      previousPlacement.leader !== false &&
+      (placement === undefined || placement.leader === false)
+    ) {
+      base = removeLeaderGraphic(base, markLabelPlacementLeaderId(id));
+    }
+    const labelAuthoring = { ...config.labelAuthoring };
+    if (placement === undefined) delete labelAuthoring.placement;
+    else labelAuthoring.placement = placement;
+    const next = base._withMarkConfig(id, { ...config, labelAuthoring });
+    return canMaterializeText(next, layer)
+      ? next.rematerializeTextMark({ id })
+      : next.materializeMarkLabelPlacement({ id });
+  }
+);
+
 const removeLabelLayout = action(
   {
     op: "removeLabelLayout",
@@ -292,6 +438,8 @@ export function registerTextLabelLayoutActions(ProgramClass) {
   Object.assign(ProgramClass.prototype, {
     layoutLabels,
     removeLabelLayout,
-    materializeLabelLayout
+    materializeLabelLayout,
+    editMarkLabelPlacement,
+    materializeMarkLabelPlacement
   });
 }