ggaction 0.0.12 → 0.0.15

package/src/actions/guides/legends/target.js

@@ -1,4 +1,20 @@
 import { validateUserId } from "../../../core/identifiers.js";
+import {
+  LEGEND_CHANNELS,
+  LEGEND_CONFIG_KINDS
+} from "../../../core/vocabulary.js";
+import { isDiscreteSizeScaleType } from "../../../grammar/scales/index.js";
+
+export function validateLegendChannels(channels, operation) {
+  if (!Array.isArray(channels)) throw new TypeError(`${operation} channels must be an array.`);
+  if (channels.length === 0) throw new Error(`${operation} channels must select at least one channel.`);
+  const seen = new Set();
+  for (const channel of channels) {
+    if (!LEGEND_CHANNELS.includes(channel)) throw new Error(`Unsupported legend channel "${channel}".`);
+    if (seen.has(channel)) throw new Error(`${operation} channels contains duplicate "${channel}".`);
+    seen.add(channel);
+  }
+}
 
 export function legendTargets(program) {
   return [...new Set(Object.values(program.guideConfigs.legend ?? {})
@@ -23,3 +39,110 @@ export function resolveLegendTarget(program, requested, operation) {
   }
   return targets[0];
 }
+
+const CATEGORICAL_KINDS = Object.freeze(["series", "color", "stroke"]);
+const SINGLE_CHANNELS = Object.freeze({
+  size: "size",
+  opacity: "opacity",
+  strokeWidth: "strokeWidth",
+  gradient: "color",
+  interval: "color",
+  strokeGradient: "stroke",
+  strokeInterval: "stroke"
+});
+
+const asciiCompare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+
+export function legendBlockChannels(kind, config) {
+  const channels = CATEGORICAL_KINDS.includes(kind)
+    ? config?.channels
+    : SINGLE_CHANNELS[kind] === undefined
+      ? undefined
+      : [SINGLE_CHANNELS[kind]];
+  if (!Array.isArray(channels) || channels.length === 0) {
+    throw new Error(`Legend block ${kind} requires at least one channel.`);
+  }
+  validateLegendChannels(channels, `Legend block ${kind}`);
+  return Object.freeze([...channels].sort(asciiCompare));
+}
+
+export function legendBlockKey(channels) {
+  if (!Array.isArray(channels) || channels.length === 0) {
+    throw new TypeError("Legend block key requires a non-empty channel array.");
+  }
+  return JSON.stringify([...channels].sort(asciiCompare));
+}
+
+export function describeLegendBlock(program, kind, config) {
+  if (!LEGEND_CONFIG_KINDS.includes(kind)) {
+    throw new Error(`Unknown legend block kind "${kind}".`);
+  }
+  const channels = legendBlockChannels(kind, config);
+  const scaleIds = CATEGORICAL_KINDS.includes(kind)
+    ? config?.scales
+    : [config?.scale];
+  if (!Array.isArray(scaleIds) || scaleIds.length === 0 ||
+    scaleIds.some(id => typeof id !== "string" || program.resolvedScales[id] === undefined)) {
+    throw new Error(`Legend block ${kind} requires resolved scales.`);
+  }
+  const family = CATEGORICAL_KINDS.includes(kind)
+    ? "categorical"
+    : kind === "size"
+      ? isDiscreteSizeScaleType(program.resolvedScales[scaleIds[0]].type)
+        ? "discrete-size"
+        : "sampled"
+      : ["opacity", "strokeWidth"].includes(kind)
+        ? "sampled"
+        : ["gradient", "strokeGradient"].includes(kind)
+          ? "gradient"
+          : "interval";
+  return Object.freeze({
+    target: config.target,
+    kind,
+    family,
+    key: legendBlockKey(channels),
+    channels,
+    scaleIds: Object.freeze([...scaleIds]),
+    config
+  });
+}
+
+export function legendBlockDescriptors(program, target) {
+  const requested = validateUserId(target, "Legend target id");
+  const descriptors = LEGEND_CONFIG_KINDS.flatMap(kind => {
+    const config = program.guideConfigs.legend?.[kind];
+    return config?.target === requested
+      ? [describeLegendBlock(program, kind, config)]
+      : [];
+  });
+  const seen = new Set();
+  for (const descriptor of descriptors) {
+    if (seen.has(descriptor.key)) {
+      throw new Error(
+        `Legend target "${requested}" has ambiguous block key ${descriptor.key}.`
+      );
+    }
+    seen.add(descriptor.key);
+  }
+  return Object.freeze(descriptors);
+}
+
+export function resolveLegendBlock(program, { target, channel }, operation = "editLegendBlock") {
+  const requested = resolveLegendTarget(program, target, operation);
+  if (!LEGEND_CHANNELS.includes(channel)) {
+    throw new Error(`${operation} has unsupported legend channel "${channel}".`);
+  }
+  const matches = legendBlockDescriptors(program, requested)
+    .filter(descriptor => descriptor.channels.includes(channel));
+  if (matches.length === 0) {
+    throw new Error(
+      `${operation} target "${requested}" has no legend block for channel "${channel}".`
+    );
+  }
+  if (matches.length !== 1) {
+    throw new Error(
+      `${operation} target "${requested}" has ambiguous channel "${channel}".`
+    );
+  }
+  return matches[0];
+}

package/src/actions/guides/legends/transition.js

@@ -0,0 +1,192 @@
+import { isDiscretizedColorScaleType } from "../../../grammar/scales/types.js";
+import { normalizeContinuousLegend } from "./continuous/common.js";
+import { DEFAULT_GRADIENT_SIZE } from "./continuous/gradient.js";
+import { normalizeIntervalLegend } from "./continuous/interval.js";
+import {
+  describeLegendBlock,
+  legendBlockDescriptors,
+  resolveLegendBlock
+} from "./target.js";
+import { validateLegendBlockOverride } from "./blocks.js";
+
+const family = (channel, type) => type === "sequential"
+  ? channel === "stroke" ? "strokeGradient" : "gradient"
+  : isDiscretizedColorScaleType(type)
+    ? channel === "stroke" ? "strokeInterval" : "interval"
+    : type === "ordinal"
+      ? channel === "stroke" ? "stroke" : "color"
+    : undefined;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+function categoricalFamilyCustom(program, kind, stored) {
+  const side = ["left", "right"].includes(stored.position);
+  const direction = side ? "vertical" : "horizontal";
+  const itemGap = side ? 28 : stored.position === "top" ? 24 : 20;
+  const order = program.semanticSpec.guides.legend?.[kind]?.order;
+  return stored.inferredSymbol !== true ||
+    stored.direction !== direction ||
+    (stored.columns !== undefined && !(side && stored.columns === 1)) ||
+    stored.itemGap !== itemGap || stored.layout !== "edge" ||
+    order !== undefined;
+}
+
+function planChannelLegendTransition(program, scale, nextType, channel) {
+  const from = family(channel, scale.type), to = family(channel, nextType);
+  if (from === undefined || to === undefined || from === to) return undefined;
+  const stored = program.guideConfigs.legend?.[from];
+  if ((stored?.scale ?? stored?.scales?.[0]) !== scale.id) return undefined;
+  const oldDescriptor = describeLegendBlock(program, from, stored);
+  const overrideKeys = Object.keys(stored.blockOverrides ?? {});
+  if (overrideKeys.some(key => key !== oldDescriptor.key)) {
+    throw new Error(`${channel} legend transition found stale legend block overrides.`);
+  }
+  const blockOverride = stored.blockOverrides?.[oldDescriptor.key];
+  const side = ["left", "right"].includes(stored.position);
+  const categorical = ["color", "stroke"].includes(from);
+  const gradientFamily = from.toLowerCase().endsWith("gradient");
+  const defaults = gradientFamily ? normalizeContinuousLegend({ position: stored.position }, "gradient")
+    : normalizeIntervalLegend({ position: stored.position });
+  const comparableSymbol = channel === "stroke" && stored.inferredStrokeWidth === true
+    ? { ...stored.symbol, strokeWidth: defaults.symbol?.strokeWidth }
+    : stored.symbol;
+  const custom = categorical
+    ? categoricalFamilyCustom(program, from, stored)
+    : gradientFamily
+    ? stored.count !== defaults.count || !same(stored.gradient, DEFAULT_GRADIENT_SIZE) || stored.itemGap !== defaults.itemGap
+    : !same(comparableSymbol, defaults.symbol) || stored.itemGap !== defaults.itemGap ||
+      stored.direction !== defaults.direction || (stored.columns !== undefined && !(side && stored.columns === 1));
+  if (custom) {
+    throw new Error(`${channel} legend transition cannot discard custom family settings; remove and recreate the legend explicitly.`);
+  }
+  if (blockOverride?.title !== undefined) {
+    throw new Error(`${channel} legend transition cannot distribute a legend block title; edit the destination block explicitly.`);
+  }
+  if (blockOverride?.labelMap !== undefined) {
+    throw new Error(`${channel} legend transition cannot distribute a legend block labelMap; edit the destination block explicitly.`);
+  }
+  if (blockOverride?.symbol !== undefined && ["gradient", "strokeGradient"].includes(to)) {
+    throw new Error(`${channel} legend transition cannot apply symbol overrides to a gradient block.`);
+  }
+  const args = {
+    target: stored.target, channels: [channel], position: stored.position,
+    labels: stored.labels, titleStyle: stored.titleStyle, border: stored.border,
+    align: stored.align, offset: stored.offset, titlePosition: stored.titlePosition,
+    ...(stored.inferredTitle ? {} : { title: stored.title })
+  };
+  try {
+    if (["interval", "strokeInterval"].includes(to)) {
+      normalizeIntervalLegend({ ...args, channels: undefined });
+    }
+    else if (["gradient", "strokeGradient"].includes(to)) {
+      normalizeContinuousLegend(args, "gradient");
+    }
+  } catch (error) {
+    throw new Error(`${channel} legend transition has incompatible layout or style: ${error.message}`);
+  }
+  return { args, channel, titleVisible: stored.titleVisible !== false, blockOverride };
+}
+
+export function planColorLegendTransitions(program, scale, nextType) {
+  return ["color", "stroke"].flatMap(channel => {
+    const plan = planChannelLegendTransition(program, scale, nextType, channel);
+    return plan === undefined ? [] : [plan];
+  });
+}
+
+export function applyColorLegendTransition(program, plan) {
+  let next = program.createLegend(plan.args);
+  if (!plan.titleVisible) {
+    next = next.editLegend({ target: plan.args.target, title: false });
+  }
+  if (plan.blockOverride === undefined) return next;
+  const descriptor = resolveLegendBlock(next, {
+    target: plan.args.target,
+    channel: plan.channel
+  }, `${plan.channel} legend transition`);
+  validateLegendBlockOverride(descriptor, plan.blockOverride);
+  next = next._withLegendConfig(descriptor.kind, {
+    ...descriptor.config,
+    blockOverrides: { [descriptor.key]: plan.blockOverride }
+  });
+  return next.rematerializeLegend();
+}
+
+function intersects(left, right) {
+  return left.channels.some(channel => right.channels.includes(channel));
+}
+
+function explicitOrder(program, descriptor) {
+  if (descriptor.family !== "categorical") return undefined;
+  return program.semanticSpec.guides.legend?.[descriptor.kind]?.order;
+}
+
+function sameBlockValue(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length &&
+      left.every((value, index) => sameBlockValue(value, right[index]));
+  }
+  if (left !== null && right !== null &&
+    typeof left === "object" && typeof right === "object" &&
+    !Array.isArray(left) && !Array.isArray(right)) {
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length &&
+      leftKeys.every((key, index) => key === rightKeys[index] &&
+        sameBlockValue(left[key], right[key]));
+  }
+  return false;
+}
+
+function transitionError(target, oldDescriptors, nextDescriptor, field) {
+  const oldKeys = oldDescriptors.map(item => item.key).join(", ");
+  throw new Error(
+    `Legend block transition for target "${target}" from ${oldKeys} to ${nextDescriptor.key} conflicts on ${field}.`
+  );
+}
+
+function withoutBlockOverrides(config) {
+  const { blockOverrides: _removed, ...rest } = config;
+  return rest;
+}
+
+export function planLegendBlockTransitions(program, target, plans) {
+  const oldDescriptors = legendBlockDescriptors(program, target);
+  const nextDescriptors = plans.map(plan =>
+    describeLegendBlock(program, plan.kind, plan.config));
+  return plans.map((plan, index) => {
+    const descriptor = nextDescriptors[index];
+    const incoming = oldDescriptors.filter(old => intersects(old, descriptor));
+    let override;
+    if (incoming.length === 1 && incoming[0].key === descriptor.key) {
+      override = incoming[0].config.blockOverrides?.[incoming[0].key];
+    } else if (incoming.length === 1) {
+      const old = incoming[0];
+      override = old.config.blockOverrides?.[old.key];
+      if (override?.title !== undefined) {
+        transitionError(target, incoming, descriptor, "title");
+      }
+      if (override?.labelMap !== undefined) {
+        transitionError(target, incoming, descriptor, "labelMap");
+      }
+    } else if (incoming.length > 1) {
+      const overrides = incoming.map(old => old.config.blockOverrides?.[old.key]);
+      if (!overrides.every(value => sameBlockValue(value, overrides[0]))) {
+        transitionError(target, incoming, descriptor, "block override");
+      }
+      const orders = incoming.map(old => explicitOrder(program, old));
+      if (!orders.every(value => sameBlockValue(value, orders[0]))) {
+        transitionError(target, incoming, descriptor, "order");
+      }
+      override = overrides[0];
+    }
+    if (override !== undefined) validateLegendBlockOverride(descriptor, override);
+    const config = withoutBlockOverrides(plan.config);
+    return {
+      ...plan,
+      config: override === undefined
+        ? config
+        : { ...config, blockOverrides: { [descriptor.key]: override } }
+    };
+  });
+}

package/src/actions/guides/polar/axes/facade.js

@@ -1,7 +1,14 @@
 import { action } from "../../../../core/action.js";
-import { polarGuideNames, resolvePolarGuideResources } from "../resolve.js";
+import { resolvePolarGuideResources } from "../resolve.js";
 import {
-  LABEL_EDIT_OPTIONS,
+  AXIS_COMPONENTS,
+  assertRemovableAxisComponent,
+  hasAxisComponent,
+  removeAxisComponent,
+  validateEnabledAxisComponents
+} from "../../axes/components.js";
+import {
+  labelEditOptions,
   LINE_EDIT_OPTIONS,
   prefix,
   resolveAngle,
@@ -22,12 +29,15 @@ const AXIS_EDIT_OPTIONS = Object.freeze([
   "angle", "line", "ticks", "labels", "ticksAndLabels", "title"
 ]);
 
-function validateAxisArgs(kind, args, operation) {
-  validateObject(args, AXIS_OPTIONS, operation);
-  if (Object.hasOwn(args, "line")) {
+export function validatePolarAxisArgs(kind, args, operation) {
+  validateObject(args, kind === "theta"
+    ? AXIS_OPTIONS.filter(option => option !== "angle")
+    : AXIS_OPTIONS, operation);
+  validateEnabledAxisComponents(args, operation);
+  if (Object.hasOwn(args, "line") && args.line !== false) {
     validateObject(args.line, LINE_EDIT_OPTIONS, `${operation}.line`);
   }
-  if (Object.hasOwn(args, "ticksAndLabels")) {
+  if (Object.hasOwn(args, "ticksAndLabels") && args.ticksAndLabels !== false) {
     validateObject(
       args.ticksAndLabels,
       TICK_GROUP_OPTIONS,
@@ -44,7 +54,7 @@ function validateAxisArgs(kind, args, operation) {
     if (Object.hasOwn(args.ticksAndLabels, "labels")) {
       validateObject(
         args.ticksAndLabels.labels,
-        LABEL_EDIT_OPTIONS.filter(key => !["count", "values"].includes(key)),
+        labelEditOptions(kind).filter(key => !["count", "values"].includes(key)),
         `${operation}.ticksAndLabels.labels`
       );
     }
@@ -68,7 +78,7 @@ function makeCreateAxis(kind) {
     op: operation,
     description: `Create the complete Polar ${kind} axis.`
   }, function (args = {}) {
-    validateAxisArgs(kind, args, operation);
+    validatePolarAxisArgs(kind, args, operation);
     const resources = resolvePolarGuideResources(this, kind, args, operation);
     const angle = resolveAngle(this, kind, args);
     const shared = {
@@ -82,21 +92,16 @@ function makeCreateAxis(kind) {
       ...(Object.hasOwn(group, "values") ? { values: group.values } : {})
     };
     let next = this;
-    if (kind === "radius") {
-      next = next._withGuideConfig("radius", "layout", { angle });
+    if (args.line !== false) {
+      next = next[`create${prefix(kind)}AxisLine`]({ ...shared, ...(args.line ?? {}) });
     }
-    next = next
-      [`create${prefix(kind)}AxisLine`]({ ...shared, ...(args.line ?? {}) })
-      [`create${prefix(kind)}AxisTicks`]({
-        ...shared,
-        ...mode,
-        ...(group.ticks ?? {})
-      })
-      [`create${prefix(kind)}AxisLabels`]({
-        ...shared,
-        ...mode,
-        ...(group.labels ?? {})
+    if (args.ticksAndLabels !== false) {
+      next = next[`create${prefix(kind)}AxisTicks`]({
+        ...shared, ...mode, ...(group.ticks ?? {})
+      })[`create${prefix(kind)}AxisLabels`]({
+        ...shared, ...mode, ...(group.labels ?? {})
       });
+    }
     return args.title === false
       ? next
       : next[`create${prefix(kind)}AxisTitle`]({
@@ -118,29 +123,28 @@ function validateAxisEditArgs(kind, args, operation) {
     throw new Error(`${operation} requires at least one axis change.`);
   }
   if (Object.hasOwn(args, "angle")) validateAngle(args.angle);
-  if (Object.hasOwn(args, "line")) {
+  if (Object.hasOwn(args, "line") && args.line !== false) {
     validateObject(args.line, LINE_EDIT_OPTIONS, `${operation}.line`);
   }
-  if (Object.hasOwn(args, "ticks")) {
+  if (Object.hasOwn(args, "ticks") && args.ticks !== false) {
     validateObject(args.ticks, TICK_EDIT_OPTIONS, `${operation}.ticks`);
     validateModeOptions(args.ticks, `${operation}.ticks`);
   }
-  if (Object.hasOwn(args, "labels")) {
-    validateObject(args.labels, LABEL_EDIT_OPTIONS, `${operation}.labels`);
+  if (Object.hasOwn(args, "labels") && args.labels !== false) {
+    validateObject(args.labels, labelEditOptions(kind), `${operation}.labels`);
     validateModeOptions(args.labels, `${operation}.labels`);
   }
-  if (Object.hasOwn(args, "ticksAndLabels")) {
+  if (args.ticksAndLabels !== undefined &&
+      (args.ticks !== undefined || args.labels !== undefined)) {
+    throw new Error(`${operation} cannot combine ticksAndLabels with ticks or labels.`);
+  }
+  if (Object.hasOwn(args, "ticksAndLabels") && args.ticksAndLabels !== false) {
     validateObject(
       args.ticksAndLabels,
       TICK_GROUP_OPTIONS,
       `${operation}.ticksAndLabels`
     );
     validateModeOptions(args.ticksAndLabels, `${operation}.ticksAndLabels`);
-    if (args.ticks !== undefined || args.labels !== undefined) {
-      throw new Error(
-        `${operation} cannot combine ticksAndLabels with ticks or labels.`
-      );
-    }
     if (args.ticksAndLabels.ticks !== undefined) {
       validateObject(
         args.ticksAndLabels.ticks,
@@ -151,12 +155,12 @@ function validateAxisEditArgs(kind, args, operation) {
     if (args.ticksAndLabels.labels !== undefined) {
       validateObject(
         args.ticksAndLabels.labels,
-        LABEL_EDIT_OPTIONS.filter(key => !["count", "values"].includes(key)),
+        labelEditOptions(kind).filter(key => !["count", "values"].includes(key)),
         `${operation}.ticksAndLabels.labels`
       );
     }
   }
-  if (Object.hasOwn(args, "title")) {
+  if (Object.hasOwn(args, "title") && args.title !== false) {
     validateObject(
       args.title,
       kind === "theta"
@@ -167,6 +171,41 @@ function validateAxisEditArgs(kind, args, operation) {
   }
 }
 
+function applyAxisEdit(program, kind, args) {
+  const angleChanged = Object.hasOwn(args, "angle");
+  let next = angleChanged
+    ? program._withGuideConfig("radius", "layout", { angle: args.angle })
+    : program;
+  const edit = (component, options) => {
+    if (options === false) {
+      next = removeAxisComponent(next, kind, component);
+    } else if (options !== undefined || angleChanged && hasAxisComponent(next, kind, component)) {
+      next = next[`edit${prefix(kind)}Axis${component[0].toUpperCase() + component.slice(1)}`](options ?? {});
+    }
+  };
+  edit("line", args.line);
+  if (args.ticksAndLabels === false) {
+    edit("ticks", false);
+    edit("labels", false);
+  } else if (args.ticksAndLabels !== undefined) {
+    const group = args.ticksAndLabels;
+    const mode = {
+      ...(Object.hasOwn(group, "count") ? { count: group.count } : {}),
+      ...(Object.hasOwn(group, "values") ? { values: group.values } : {})
+    };
+    edit("ticks", { ...mode, ...(group.ticks ?? {}) });
+    edit("labels", { ...mode, ...(group.labels ?? {}) });
+  } else {
+    edit("ticks", args.ticks);
+    edit("labels", args.labels);
+  }
+  edit("title", args.title);
+  if (!AXIS_COMPONENTS.some(component => hasAxisComponent(next, kind, component))) {
+    next = next[`remove${prefix(kind)}Axis`]();
+  }
+  return next;
+}
+
 function makeEditAxis(kind) {
   const operation = `edit${prefix(kind)}Axis`;
   return action({
@@ -174,42 +213,18 @@ function makeEditAxis(kind) {
     description: `Edit selected Polar ${kind}-axis components.`
   }, function (args = {}) {
     validateAxisEditArgs(kind, args, operation);
-    const names = polarGuideNames(kind);
-    const angleChanged = Object.hasOwn(args, "angle");
-    let next = angleChanged
-      ? this._withGuideConfig("radius", "layout", { angle: args.angle })
-      : this;
-    const has = component =>
-      next.graphicSpec.objects[names[component]] !== undefined;
-    if (args.line !== undefined || (angleChanged && has("line"))) {
-      next = next[`edit${prefix(kind)}AxisLine`](args.line ?? {});
+    if (!AXIS_COMPONENTS.some(component => hasAxisComponent(this, kind, component))) {
+      throw new Error(`${operation} requires an existing ${kind}-axis component.`);
     }
-    if (args.ticksAndLabels !== undefined) {
-      const group = args.ticksAndLabels;
-      const mode = {
-        ...(Object.hasOwn(group, "count") ? { count: group.count } : {}),
-        ...(Object.hasOwn(group, "values") ? { values: group.values } : {})
-      };
-      next = next[`edit${prefix(kind)}AxisTicks`]({
-        ...mode,
-        ...(group.ticks ?? {})
-      });
-      next = next[`edit${prefix(kind)}AxisLabels`]({
-        ...mode,
-        ...(group.labels ?? {})
-      });
-    } else {
-      if (args.ticks !== undefined || (angleChanged && has("ticks"))) {
-        next = next[`edit${prefix(kind)}AxisTicks`](args.ticks ?? {});
+    for (const component of AXIS_COMPONENTS) {
+      if (args[component] === false ||
+          args.ticksAndLabels === false && ["ticks", "labels"].includes(component)) {
+        assertRemovableAxisComponent(this, kind, component, operation);
       }
-      if (args.labels !== undefined || (angleChanged && has("labels"))) {
-        next = next[`edit${prefix(kind)}AxisLabels`](args.labels ?? {});
-      }
-    }
-    if (args.title !== undefined || (angleChanged && has("title"))) {
-      next = next[`edit${prefix(kind)}AxisTitle`](args.title ?? {});
     }
-    return next;
+    // Validate the whole proposal on an immutable branch before returning changes.
+    applyAxisEdit(this, kind, args);
+    return applyAxisEdit(this, kind, args);
   });
 }
 

package/src/actions/guides/polar/axes/labels.js

@@ -20,18 +20,21 @@ import {
 } from "../resolve.js";
 import {
   componentResources,
-  LABEL_CREATE_OPTIONS,
-  LABEL_EDIT_OPTIONS,
+  labelCreateOptions,
+  labelEditOptions,
   operations,
   prefix,
   resolveAngle,
   validateModeOptions,
+  validateComponentCreateArgs,
   validateObject,
   withAxisSemantics
 } from "./shared.js";
+import { normalizeDisplayLabelMap } from
+  "../../../../grammar/displayLabels.js";
 
-function labelGeometry(program, kind, config) {
-  const frame = resolvePolarFrameForProgram(program);
+function labelGeometry(program, kind, config, angle = resolveAngle(program, kind, {})) {
+  const frame = resolvePolarFrameForProgram(program, config.coordinate);
   const mapped = mapPolarGuideValues(program, config);
   const text = formatPolarGuideValues(program, config, mapped.values);
   const geometry = {
@@ -45,7 +48,7 @@ function labelGeometry(program, kind, config) {
         })
       : resolveRadialAxisLabels({
           frame,
-          angle: resolveAngle(program, kind, {}),
+          angle,
           radii: mapped.positions,
           offset: config.offset
         }))
@@ -114,6 +117,23 @@ function resolveLabelConfig(program, kind, args, resources, previous) {
     fontWeight: args.fontWeight ?? previous?.fontWeight ??
       POLAR_AXIS_DEFAULTS.labels.fontWeight
   };
+  const labelScale = program.resolvedScales[resources.scale];
+  if (Object.hasOwn(args, "labelMap")) {
+    if (kind !== "theta" || !["ordinal", "band", "point"].includes(labelScale?.type)) {
+      throw new Error(`${prefix(kind)} axis labelMap requires a categorical theta scale.`);
+    }
+    if (args.labelMap === "auto") delete config.labelMap;
+    else {
+      config.labelMap = normalizeDisplayLabelMap(
+        args.labelMap,
+        `${prefix(kind)} axis labelMap`
+      );
+    }
+  }
+  if (config.labelMap !== undefined &&
+      (kind !== "theta" || !["ordinal", "band", "point"].includes(labelScale?.type))) {
+    throw new Error(`${prefix(kind)} axis labelMap requires a categorical theta scale.`);
+  }
   validatePolarTickConfig(config, `${kind}-axis labels`);
   validateNonNegativeFinite(config.offset, "Polar axis label offset");
   validatePolarLabelFormat(config.format);
@@ -127,7 +147,7 @@ function makeEditLabels(kind) {
     op: operation.edit,
     description: `Edit the Polar ${kind}-axis labels.`
   }, function (args = {}) {
-    validateObject(args, LABEL_EDIT_OPTIONS, operation.edit);
+    validateObject(args, labelEditOptions(kind), operation.edit);
     validateModeOptions(args, operation.edit);
     const names = polarGuideNames(kind);
     const previous = this.guideConfigs.axis?.[kind]?.labels;
@@ -171,7 +191,7 @@ function makeCreateLabels(kind) {
     op: operation.create,
     description: `Create the Polar ${kind}-axis labels.`
   }, function (args = {}) {
-    validateObject(args, LABEL_CREATE_OPTIONS, operation.create);
+    validateComponentCreateArgs(kind, args, labelCreateOptions(kind), operation.create);
     validateModeOptions(args, operation.create);
     const names = polarGuideNames(kind);
     if (this.graphicSpec.objects[names.labels] !== undefined) {
@@ -180,7 +200,7 @@ function makeCreateLabels(kind) {
     const resources = componentResources(this, kind, args, operation.create);
     const angle = resolveAngle(this, kind, args);
     const config = resolveLabelConfig(this, kind, args, resources);
-    labelGeometry(this, kind, config);
+    labelGeometry(this, kind, config, angle);
     let next = withAxisSemantics(this, kind, resources);
     if (kind === "radius" &&
         next.guideConfigs.axis?.radius?.layout === undefined) {