ggaction 0.0.12 → 0.0.15

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

@@ -1,14 +1,29 @@
+import { TEXT_LABEL_LAYOUT_OPTIONS } from "./layout.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   DEFAULT_TEXT_MARK,
+  isSourceOwnedText,
   normalizeTextMarkConfig
 } from "../../../grammar/text.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
 import {
   canMaterializeArc,
-  canMaterializeText
+  canMaterializeRect,
+  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,
@@ -18,6 +33,10 @@ import {
   resolveMarkId,
   validateMarkOptions
 } from "../shared.js";
+import {
+  resolveFacadeData,
+  resolveFacadeId
+} from "../../charts/shared.js";
 import { resolveMarkGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
@@ -25,10 +44,9 @@ const STYLE_OPTIONS = Object.freeze([
   "fill", "opacity", "fontSize", "fontFamily", "fontWeight",
   "align", "baseline", "rotation", "dx", "dy"
 ]);
-const CREATE_OPTIONS = Object.freeze(["id", "data", "text", ...STYLE_OPTIONS]);
+const CREATE_OPTIONS = Object.freeze(["id", "data", "source", "text", ...STYLE_OPTIONS]);
 const EDIT_OPTIONS = Object.freeze(["target", ...STYLE_OPTIONS]);
 const REMATERIALIZE_OPTIONS = Object.freeze(["id", "replayLayout"]);
-const SOURCE_TYPES = new Set(["point", "bar", "rule", "rect", "arc"]);
 
 function sourceMatchesData(program, layer, requestedData) {
   if (requestedData === undefined || layer?.data === requestedData) return true;
@@ -37,16 +55,34 @@ function sourceMatchesData(program, layer, requestedData) {
 
 function eligibleSource(program, layer, requestedData) {
   if (
-    !SOURCE_TYPES.has(layer?.mark?.type) ||
-    layer.data === undefined ||
+    !isTextSource(layer) ||
     !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");
   return encodings.x !== undefined && encodings.y !== undefined;
 }
 
 function resolveTextInheritance(program, args) {
+  if (Object.hasOwn(args, "source")) {
+    if (Object.hasOwn(args, "data")) {
+      throw new Error("createTextMark source and data are mutually exclusive.");
+    }
+    return textInheritance(program, resolveEligibleLayer(program, {
+      target: validateUserId(args.source, "Text source id"),
+      predicate: isTextSource,
+      label: "text source"
+    }));
+  }
   if (Object.hasOwn(args, "data")) return undefined;
   const requestedData = program.context.currentData;
   const candidates = program.semanticSpec.layers.filter(layer =>
@@ -60,15 +96,21 @@ function resolveTextInheritance(program, args) {
       : undefined;
   if (source === undefined && candidates.length > 1) {
     throw new Error(
-      "Text source inference is ambiguous; provide data and encode its position explicitly."
+      "Text source inference is ambiguous; provide source, or data and encode its position explicitly."
     );
   }
   if (source === undefined) return undefined;
+  return textInheritance(program, source);
+}
+
+function textInheritance(program, source) {
   return {
     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")
   };
@@ -136,6 +178,240 @@ const createTextMark = action(
   }
 );
 
+const LABEL_OPTIONS = Object.freeze([
+  "id", "source", "field", "value", "content", "normalizeBy", "format", "layout",
+  "select", "selection", "placement",
+  ...STYLE_OPTIONS
+]);
+
+const ANNOTATION_OPTIONS = Object.freeze([
+  "id", "text", "format", "x", "y", "space", "source", "data", "coordinate", "layout",
+  ...STYLE_OPTIONS
+]);
+
+function annotationLayout(value) {
+  const layout = value === undefined || value === false ? undefined : value;
+  if (layout !== undefined && Object.hasOwn(layout ?? {}, "target")) {
+    throw new Error("createAnnotation layout target is owned by the created text layer.");
+  }
+  if (layout !== undefined) {
+    validateMarkOptions(layout, TEXT_LABEL_LAYOUT_OPTIONS, "createAnnotation layout");
+  }
+  return layout;
+}
+
+function resolveAnnotationBinding(program, args) {
+  const hasX = Object.hasOwn(args, "x");
+  const hasY = Object.hasOwn(args, "y");
+  if (!hasX && !hasY) {
+    if (["space", "data", "coordinate"].some(option => Object.hasOwn(args, option))) {
+      throw new Error("createAnnotation mark anchor accepts source but not space, data, or coordinate.");
+    }
+    return { mode: "mark" };
+  }
+  if (!hasX || !hasY) {
+    throw new Error("createAnnotation coordinate anchor requires both x and y.");
+  }
+  const space = args.space ?? "data";
+  if (space !== "data" && space !== "plot") {
+    throw new Error("createAnnotation space must be data or plot.");
+  }
+  if (space === "plot") {
+    if (Object.hasOwn(args, "source")) {
+      throw new Error("createAnnotation plot anchor does not accept source.");
+    }
+    if (![args.x, args.y].every(value => Number.isFinite(value) && value >= 0 && value <= 1)) {
+      throw new Error("createAnnotation plot coordinates must be finite numbers in [0, 1].");
+    }
+    return {
+      mode: "plot",
+      data: resolveFacadeData(program, args.data, "createAnnotation"),
+      coordinate: args.coordinate
+    };
+  }
+  if (Object.hasOwn(args, "data") || Object.hasOwn(args, "coordinate")) {
+    throw new Error("createAnnotation data anchor uses source data and coordinate.");
+  }
+  const source = resolveEligibleLayer(program, {
+    target: args.source === undefined
+      ? undefined
+      : validateUserId(args.source, "createAnnotation source"),
+    predicate: layer =>
+      !isSourceOwnedText(layer) &&
+      layer.data !== undefined &&
+      layer.encoding?.x?.scale !== undefined &&
+      layer.encoding?.y?.scale !== undefined &&
+      findCoordinate(program, layer.coordinate)?.type === "cartesian",
+    label: "createAnnotation Cartesian layer",
+    targetOption: "source"
+  });
+  return {
+    mode: "data",
+    data: source.data,
+    coordinate: source.coordinate,
+    x: source.encoding.x,
+    y: source.encoding.y
+  };
+}
+
+const createAnnotation = action(
+  {
+    op: "createAnnotation",
+    description: "Create text at a final mark, data, or plot anchor."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, ANNOTATION_OPTIONS, "createAnnotation");
+    if (!Object.hasOwn(args, "text")) {
+      throw new Error("createAnnotation requires text.");
+    }
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "annotation",
+      operation: "createAnnotation"
+    });
+    const binding = resolveAnnotationBinding(this, args);
+    const layout = annotationLayout(args.layout);
+    const style = Object.fromEntries(STYLE_OPTIONS
+      .filter(option => Object.hasOwn(args, option))
+      .map(option => [option, args[option]]));
+    const text = {
+      value: args.text,
+      ...(args.format === undefined ? {} : { format: args.format })
+    };
+    const apply = program => {
+      if (binding.mode === "mark") {
+        return program.createMarkLabels({
+          id,
+          ...(args.source === undefined ? {} : { source: args.source }),
+          ...style,
+          ...text,
+          ...(layout === undefined ? {} : { layout })
+        });
+      }
+      const xScale = binding.mode === "plot" ? `${id}-x` : binding.x.scale;
+      const yScale = binding.mode === "plot" ? `${id}-y` : binding.y.scale;
+      let next = binding.mode === "plot"
+        ? program
+          .createScale({ id: xScale, type: "linear", domain: [0, 1] })
+          .createScale({ id: yScale, type: "linear", domain: [0, 1] })
+        : program;
+      next = next
+        .createTextMark({ id, data: binding.data, ...style })
+        .encodeText({ target: id, ...text })
+        .encodeX({
+          target: id,
+          datum: args.x,
+          fieldType: binding.mode === "plot" ? "quantitative" : binding.x.fieldType,
+          scale: { id: xScale },
+          ...(binding.coordinate === undefined ? {} : { coordinate: binding.coordinate }),
+          ...(binding.mode === "data" && binding.x.temporalUnit !== undefined
+            ? { temporalUnit: binding.x.temporalUnit }
+            : {})
+        })
+        .encodeY({
+          target: id,
+          datum: args.y,
+          fieldType: binding.mode === "plot" ? "quantitative" : binding.y.fieldType,
+          scale: { id: yScale },
+          ...(binding.coordinate === undefined ? {} : { coordinate: binding.coordinate }),
+          ...(binding.mode === "data" && binding.y.temporalUnit !== undefined
+            ? { temporalUnit: binding.y.temporalUnit }
+            : {})
+        });
+      return layout === undefined
+        ? next
+        : next.layoutLabels({ ...layout, target: id });
+    };
+    // Validate the full lower action chain before committing any child effect.
+    apply(this);
+    return apply(this);
+  }
+);
+
+const createMarkLabels = action(
+  {
+    op: "createMarkLabels",
+    description: "Create final-item text labels attached to an existing mark."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, LABEL_OPTIONS, "createMarkLabels");
+    const inherited = resolveTextInheritance(this, args);
+    if (inherited === undefined) {
+      throw new Error("createMarkLabels requires an eligible source mark; provide source explicitly.");
+    }
+    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]]));
+    normalizeTextMarkConfig(style);
+    const encoding = Object.fromEntries(
+      ["field", "value", "content", "normalizeBy", "format"]
+        .filter(option => Object.hasOwn(args, option))
+        .map(option => [option, args[option]])
+    );
+    if (!["field", "value", "content"].some(option => Object.hasOwn(args, option))) {
+      encoding.content = "value";
+    }
+    const layout = args.layout === undefined || args.layout === false ? undefined : args.layout;
+    if (layout !== undefined && Object.hasOwn(layout ?? {}, "target")) {
+      throw new Error("createMarkLabels layout target is owned by the created label layer.");
+    }
+    const apply = program => {
+      let next = program.createTextMark({
+        id, source: inherited.source, align: "center", baseline: "middle", ...style
+      });
+      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) {
+      // Validate object shape before spreading it into the child action's options.
+      validateMarkOptions(layout, TEXT_LABEL_LAYOUT_OPTIONS, "createMarkLabels layout");
+    }
+    // Validate all child effects on a discarded immutable branch, as scale edits do.
+    apply(this);
+    return apply(this);
+  }
+);
+
 const rematerializeTextMark = action(
   {
     op: "rematerializeTextMark",
@@ -160,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(
@@ -171,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 });
   }
 );
 
@@ -209,6 +490,8 @@ const editTextMark = action(
 export function registerTextMarkActions(ProgramClass) {
   Object.assign(ProgramClass.prototype, {
     createTextMark,
+    createMarkLabels,
+    createAnnotation,
     editTextMark,
     rematerializeTextMark
   });

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,25 +2,33 @@ 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";
 
-const LAYOUT_OPTIONS = Object.freeze([
+export const TEXT_LABEL_LAYOUT_OPTIONS = Object.freeze([
   "target", "axis", "padding", "maxDisplacement", "bounds", "leader"
 ]);
 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 });
   }
 );
 
@@ -252,9 +332,15 @@ const layoutLabels = action(
     description: "Assign deterministic collision-aware layout to a text mark."
   },
   function (args = {}) {
-    validateOptionObject(args, LAYOUT_OPTIONS, "layoutLabels");
+    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
   });
 }