ggaction 0.0.13 → 0.0.16

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

@@ -1,10 +1,14 @@
-import { action } from "../../../core/action.js";
+import { action, closedAction } from "../../../core/action.js";
 import {
-  validateGeneratedItemLimit,
   validateNonEmptyString,
   validateKeys
 } from "../../../core/validation.js";
-import { mapLinearValues } from "../../../grammar/scales/index.js";
+import {
+  formatDiscretizedIntervals,
+  isDiscreteSizeScaleType,
+  isSizeScaleType,
+  mapSizeValues
+} from "../../../grammar/scales/index.js";
 import { resolveLegendItemLayout } from "../../../layout/legendItems.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
@@ -13,7 +17,8 @@ import { resolveLegendGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 import {
   assertLegendBoundsInsideCanvas,
-  editLegendBackground,
+  materializeItemLegend,
+  createItemLegendGraphics,
   normalizeItemLegendLayout,
   normalizeLegendBorder,
   normalizeLegendTextOptions,
@@ -21,13 +26,17 @@ import {
   resolveContinuousBounds,
   resolveLegendBackgroundFromBounds,
   formatContinuousValues,
-  sampleContinuousValues,
-  selectLegendLayer,
-  styleContinuousText
+  selectLegendLayer
 } from "./continuous/common.js";
 import { legendResourcePolicies } from "../../../materialization/guides/resources.js";
+import {
+  normalizeLegendSampling,
+  readLegendSampling,
+  resolveLegendSampleValues
+} from "./sampling.js";
+import { resolveEffectiveLegendBlockConfig } from "./blocks.js";
 
-const SIZE_OPTIONS = Object.freeze(["target", "count", "position", "layout", "align",
+const SIZE_OPTIONS = Object.freeze(["target", "count", "values", "position", "layout", "align",
   "direction", "columns", "titlePosition", "offset", "itemGap", "title", "labels", "titleStyle", "border"]);
 
 export const SIZE_LEGEND_LABELS = Object.freeze({
@@ -61,21 +70,32 @@ export function resolveSizeLegendPoint(program, requested) {
   return layer;
 }
 
-function requireScale(program, id, type) {
+function requireScale(program, id) {
   const scale = program.resolvedScales[id];
-  if (scale?.type !== type) {
-    throw new Error(`Legend requires resolved ${type} scale "${id}".`);
+  if (!isSizeScaleType(scale?.type)) {
+    throw new Error(`Legend requires resolved size scale "${id}".`);
   }
   return scale;
 }
 
 export function resolveSizeLegendLayout(program, config) {
-  const scale = requireScale(program, config.scale, "linear");
-  const categorical = [program.guideConfigs.legend?.series, program.guideConfigs.legend?.color]
+  const scale = requireScale(program, config.scale);
+  const categorical = [
+    program.guideConfigs.legend?.series,
+    program.guideConfigs.legend?.color,
+    program.guideConfigs.legend?.stroke
+  ]
     .find(candidate => candidate?.target === config.target);
   const inherit = config.inheritAppearance === true && categorical !== undefined;
-  const labels = inherit ? { ...categorical.labels, offset: config.labels.offset } : config.labels;
-  const titleStyle = inherit ? categorical.titleStyle : config.titleStyle;
+  const inheritedLabels = inherit ? { ...categorical.labels, offset: config.labels.offset } : config.labels;
+  const inheritedTitleStyle = inherit ? categorical.titleStyle : config.titleStyle;
+  const effective = resolveEffectiveLegendBlockConfig(program, "size", {
+    ...config,
+    labels: inheritedLabels,
+    titleStyle: inheritedTitleStyle
+  });
+  const labels = effective.labels;
+  const titleStyle = effective.titleStyle;
   const position = categorical?.position ?? config.position;
   if (categorical?.layout === "legacy-bottom") {
     throw new Error('Combined size legends require layout "edge".');
@@ -84,36 +104,54 @@ export function resolveSizeLegendLayout(program, config) {
   const geometry = horizontal ? {
     position, align: categorical.align, direction: categorical.direction,
     columns: categorical.columns, titlePosition: categorical.titlePosition,
-    offset: categorical.offset, itemGap: categorical.itemGap
+    offset: categorical.offset, itemGap: effective.blockGap ?? categorical.itemGap
   } : { position };
-  const values = sampleContinuousValues(scale.domain, config.count);
-  const areas = mapLinearValues(values, scale.domain, scale.range, { clamp: scale.clamp ?? false });
+  const discrete = isDiscreteSizeScaleType(scale.type);
+  if (discrete && readLegendSampling(config).mode === "values") {
+    throw new Error("Discrete size legends do not support exact values.");
+  }
+  const values = discrete
+    ? undefined
+    : resolveLegendSampleValues(effective, scale, "Size legend");
+  const areas = discrete
+    ? scale.range
+    : mapSizeValues(values, scale);
   const radii = areas.map(area => Math.sqrt(area / Math.PI));
   const radius = Math.max(...radii);
   const width = Math.max(32, radius * 2);
   const { plot, canvas } = resolveContinuousBounds(program);
-  const text = formatContinuousValues(
-    values,
-    scale.domain,
-    "quantitative",
-    config.labels.format
-  );
-  const layout = resolveLegendItemLayout(plot, { ...config, ...geometry, labels, titleStyle }, text, {
-    width, height: radius * 2,
-    itemBounds: radii.map(r => ({ left: width / 2 - r, right: width / 2 + r, top: -r, bottom: r }))
-  });
-  assertLegendBoundsInsideCanvas(layout.bounds, canvas, "Size legend layout", { ...config, ...geometry });
-  const background = resolveLegendBackgroundFromBounds(layout.bounds, config.border, canvas, "Size legend", { ...config, ...geometry });
-  return { ...layout, symbolX: layout.symbolX.map(x => x + width / 2), radii, text, labels, titleStyle, background };
+  const text = discrete
+    ? formatDiscretizedIntervals(scale.thresholds, config.labels.format)
+    : formatContinuousValues(
+        values,
+        scale.domain,
+        "quantitative",
+        config.labels.format
+      );
+  const symbolStroke = effective.blockSymbol?.strokeWidth ?? 0;
+  const symbolExtent = symbolStroke / 2;
+  const sampleWidth = width + symbolStroke;
+  const layout = resolveLegendItemLayout(plot, { ...effective, ...geometry, labels, titleStyle }, text, {
+    width: sampleWidth, height: radius * 2 + symbolStroke,
+    itemBounds: radii.map(r => ({
+      left: sampleWidth / 2 - r - symbolExtent,
+      right: sampleWidth / 2 + r + symbolExtent,
+      top: -r - symbolExtent,
+      bottom: r + symbolExtent
+    }))
+  }, undefined, program.materializationConfigs.textMetrics);
+  assertLegendBoundsInsideCanvas(layout.bounds, canvas, "Size legend layout", { ...effective, ...geometry });
+  const background = resolveLegendBackgroundFromBounds(layout.bounds, effective.border, canvas, "Size legend", { ...effective, ...geometry });
+  return { ...layout, symbolX: layout.symbolX.map(x => x + sampleWidth / 2), radii, text,
+    labels, titleStyle, background, config: effective };
 }
 
-export const rematerializeSizeLegend = action(
+export const rematerializeSizeLegend = /* @__PURE__ */ closedAction(
   {
     op: "rematerializeSizeLegend",
     description: "Rematerialize a quantitative point-size legend."
-  },
+  }, [],
   function (args = {}) {
-    validateKeys(args, [], "rematerializeSizeLegend");
     const config = this.guideConfigs.legend?.size;
     if (config === undefined) throw new Error("Size legend requires stored configuration.");
     const layer = findLayer(this, config.target);
@@ -121,7 +159,7 @@ export const rematerializeSizeLegend = action(
     if (encoding?.scale === undefined) {
       throw new Error("Size legend target requires a size encoding.");
     }
-    const scale = requireScale(this, encoding.scale, "linear");
+    const scale = requireScale(this, encoding.scale);
     const title = config.inferredTitle === true ? encoding.field : config.title;
     const currentConfig = {
       ...config,
@@ -130,41 +168,18 @@ export const rematerializeSizeLegend = action(
       domain: scale.domain
     };
     const layout = resolveSizeLegendLayout(this, currentConfig);
-    const { itemY, symbolX, labelX, radii, labels, titleStyle } = layout;
-    let next = this
-      .editSemantic({ property: "guide.legend.size.scale", value: encoding.scale })
-      .editSemantic({ property: "guide.legend.size.title", value: title })
-      ._withLegendConfig("size", currentConfig)
-      .editGraphics({ target: "sizeLegendSymbols", property: "length", value: radii.length })
-      .editGraphics({ target: "sizeLegendSymbols", property: "x", value: symbolX })
-      .editGraphics({ target: "sizeLegendSymbols", property: "y", value: itemY })
-      .editGraphics({
-        target: "sizeLegendSymbols",
-        property: "radius",
-        value: radii
-      })
-      .editGraphics({
-        target: "sizeLegendSymbols",
-        property: "fill",
-        value: DEFAULT_COLORS.sizeSymbol
-      })
-      .editGraphics({ target: "sizeLegendSymbols", property: "opacity", value: 0.7 })
-      .editGraphics({ target: "sizeLegendLabels", property: "length", value: radii.length })
-      .editGraphics({ target: "sizeLegendLabels", property: "x", value: labelX })
-      .editGraphics({ target: "sizeLegendLabels", property: "y", value: itemY })
-      .editGraphics({
-        target: "sizeLegendLabels",
-        property: "text",
-        value: layout.text
-      });
-    next = editLegendBackground(next, "sizeLegendBackground", layout.background, currentConfig.border);
-    next = styleContinuousText(next, "sizeLegendLabels", labels);
-    if (currentConfig.titleVisible === false) return next;
-    next = next
-      .editGraphics({ target: "sizeLegendTitle", property: "x", value: layout.title.x })
-      .editGraphics({ target: "sizeLegendTitle", property: "y", value: layout.title.y })
-      .editGraphics({ target: "sizeLegendTitle", property: "text", value: title });
-    return styleContinuousText(next, "sizeLegendTitle", titleStyle, { align: layout.title.align });
+    return materializeItemLegend(this, "size", currentConfig, layout, {
+      text: layout.text, labels: layout.labels, titleStyle: layout.titleStyle,
+      symbols: {
+        x: layout.symbolX, y: layout.itemY, radius: layout.radii,
+        fill: layout.config.blockSymbol?.fill ?? DEFAULT_COLORS.sizeSymbol,
+        opacity: layout.config.blockSymbol?.opacity ?? 0.7
+      },
+      optional: {
+        stroke: layout.config.blockSymbol?.stroke,
+        strokeWidth: layout.config.blockSymbol?.strokeWidth
+      }
+    });
   }
 );
 
@@ -177,12 +192,16 @@ export function resolveSizeLegendConfig(program, args = {}) {
   if (encoding?.scale === undefined) {
     throw new Error(`Point mark "${layer.id}" requires a size encoding.`);
   }
-  const scale = requireScale(program, encoding.scale, "linear");
-  const count = args.count ?? 5;
-  if (!Number.isInteger(count) || count < 2) {
-    throw new RangeError("Size legend count must be an integer of at least 2.");
+  const scale = requireScale(program, encoding.scale);
+  const discrete = isDiscreteSizeScaleType(scale.type);
+  if (discrete && (Object.hasOwn(args, "count") || Object.hasOwn(args, "values"))) {
+    throw new Error("Discrete size legends do not support count or exact values.");
   }
-  validateGeneratedItemLimit(count, "Size legend count");
+  const sampling = discrete ? undefined : normalizeLegendSampling(args, {
+    operation: "create",
+    label: "Size legend"
+  });
+  const count = discrete ? scale.range.length : undefined;
   return {
     target: layer.id,
     scale: encoding.scale,
@@ -190,7 +209,7 @@ export function resolveSizeLegendConfig(program, args = {}) {
     title: args.title ?? encoding.field,
     inferredTitle: args.title === undefined,
     domain: scale.domain,
-    count,
+    ...(discrete ? { count } : { sampling }),
     inheritAppearance: args.inheritAppearance === true,
     labels: normalizeLegendTextOptions(args.labels, "createLegend.labels", SIZE_LEGEND_LABELS),
     titleStyle: normalizeLegendTitleOptions(args.titleStyle, "createLegend.titleStyle", SIZE_LEGEND_TITLE_STYLE),
@@ -200,48 +219,21 @@ export function resolveSizeLegendConfig(program, args = {}) {
 }
 
 export function createSizeLegendFromConfig(program, config) {
-  resolveSizeLegendLayout(program, config);
-  const { count } = config;
+  const { radii } = resolveSizeLegendLayout(program, config);
+  const count = radii.length;
   const following = new Set(legendResourcePolicies().filter(policy =>
     policy.kind !== "size" && policy.family !== "categorical" &&
     program.guideConfigs.legend?.[policy.kind] !== undefined
   ).flatMap(policy => policy.graphicIds));
   const before = program.graphicSpec.objects.canvas?.children?.find(id => following.has(id));
   const placement = resolveLegendGraphicPlacement(program, before === undefined ? {} : { before });
-  let next = program
-    .editSemantic({ property: "guide.legend.size.scale", value: config.scale })
-    .editSemantic({ property: "guide.legend.size.title", value: config.title })
-    ._withLegendConfig("size", config);
-  if (config.border !== false) {
-    next = next.createGraphics({ id: "sizeLegendBackground", type: "rect",
-      ...placement });
-  }
-  next = next.createGraphics({
-      id: "sizeLegendSymbols",
-      type: "circle",
-      length: count,
-      ...placement
-    })
-    .createGraphics({
-      id: "sizeLegendLabels",
-      type: "text",
-      length: count,
-      ...placement
-    });
-  if (config.titleVisible !== false) {
-    next = next.createGraphics({
-      id: "sizeLegendTitle",
-      type: "text",
-      ...placement
-    });
-  }
-  return next.rematerializeSizeLegend();
+  return createItemLegendGraphics(program, "size", config, count, "circle", placement).rematerializeSizeLegend();
 }
 
-export const createSizeLegend = action(
+export const createSizeLegend = /* @__PURE__ */ action(
   {
     op: "createSizeLegend",
-    description: "Create a quantitative equal-area point-size legend."
+    description: "Create an equal-area point-size legend."
   },
   function (args = {}) {
     const config = resolveSizeLegendConfig(this, args);

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

@@ -1,6 +1,5 @@
-import { action } from "../../../core/action.js";
+import { action, closedAction } from "../../../core/action.js";
 import {
-  validateGeneratedItemLimit,
   validateNonEmptyString,
   validateKeys
 } from "../../../core/validation.js";
@@ -13,7 +12,8 @@ import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
 import {
   assertLegendBoundsInsideCanvas,
-  editLegendBackground,
+  materializeItemLegend,
+  createItemLegendGraphics,
   normalizeItemLegendLayout,
   normalizeLegendBorder,
   normalizeLegendTextOptions,
@@ -21,12 +21,15 @@ import {
   resolveContinuousBounds,
   resolveLegendBackgroundFromBounds,
   formatContinuousValues,
-  sampleContinuousValues,
-  selectLegendLayer,
-  styleContinuousText
+  selectLegendLayer
 } from "./continuous/common.js";
+import {
+  normalizeLegendSampling,
+  resolveLegendSampleValues
+} from "./sampling.js";
+import { resolveEffectiveLegendBlockConfig } from "./blocks.js";
 
-const OPTIONS = Object.freeze(["target", "count", "position", "layout", "align",
+const OPTIONS = Object.freeze(["target", "count", "values", "position", "layout", "align",
   "direction", "columns", "titlePosition", "offset", "itemGap", "title", "labels", "titleStyle", "border"]);
 
 export const STROKE_WIDTH_LEGEND_LABELS = Object.freeze({
@@ -74,29 +77,29 @@ function requireScale(program, id) {
 }
 
 export function resolveStrokeWidthLegendLayout(program, config) {
+  const effective = resolveEffectiveLegendBlockConfig(program, "strokeWidth", config);
   const scale = requireScale(program, config.scale);
   const { plot, canvas } = resolveContinuousBounds(program);
-  const values = sampleContinuousValues(scale.domain, config.count);
+  const values = resolveLegendSampleValues(effective, scale, "Stroke-width legend");
   const widths = mapContinuousScaleValues(values, scale);
   const labels = formatContinuousValues(
     values,
     scale.domain,
     "quantitative",
-    config.labels.format
+    effective.labels.format
   );
-  const layout = resolveLegendItemLayout(plot, config, labels, { width: 32, height: 0, strokeWidth: widths });
-  assertLegendBoundsInsideCanvas(layout.bounds, canvas, "Stroke-width legend layout", config);
-  const background = resolveLegendBackgroundFromBounds(layout.bounds, config.border, canvas, "Stroke-width legend", config);
-  return { ...layout, widths, labels, background };
+  const layout = resolveLegendItemLayout(plot, effective, labels, { width: 32, height: 0, strokeWidth: widths }, undefined, program.materializationConfigs.textMetrics);
+  assertLegendBoundsInsideCanvas(layout.bounds, canvas, "Stroke-width legend layout", effective);
+  const background = resolveLegendBackgroundFromBounds(layout.bounds, effective.border, canvas, "Stroke-width legend", effective);
+  return { ...layout, widths, labels, background, config: effective };
 }
 
-export const rematerializeStrokeWidthLegend = /* @__PURE__ */ action(
+export const rematerializeStrokeWidthLegend = /* @__PURE__ */ closedAction(
   {
     op: "rematerializeStrokeWidthLegend",
     description: "Rematerialize a quantitative stroke-width legend."
-  },
+  }, [],
   function (args = {}) {
-    validateKeys(args, [], "rematerializeStrokeWidthLegend");
     const stored = this.guideConfigs.legend?.strokeWidth;
     if (stored === undefined) {
       throw new Error("Stroke-width legend requires stored configuration.");
@@ -114,44 +117,17 @@ export const rematerializeStrokeWidthLegend = /* @__PURE__ */ action(
     }
     const scale = requireScale(this, encoding.scale);
     const title = config.inferredTitle === true ? encoding.field : config.title;
-    const layout = resolveStrokeWidthLegendLayout(this, { ...config, scale: encoding.scale, title });
-    const { itemY: y, widths } = layout;
-    let next = this
-      .editSemantic({ property: "guide.legend.strokeWidth.scale", value: encoding.scale })
-      .editSemantic({ property: "guide.legend.strokeWidth.title", value: title })
-      ._withLegendConfig("strokeWidth", {
-        ...config,
-        scale: encoding.scale,
-        title,
-        domain: scale.domain
-      })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "length", value: widths.length })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "x1", value: layout.symbolX })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "x2", value: layout.symbolX.map(x => x + 32) })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "y1", value: y })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "y2", value: y })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "stroke", value: DEFAULT_COLORS.mark })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "strokeWidth", value: widths })
-      .editGraphics({ target: "strokeWidthLegendLabels", property: "length", value: widths.length })
-      .editGraphics({
-        target: "strokeWidthLegendLabels",
-        property: "x",
-        value: layout.labelX
-      })
-      .editGraphics({ target: "strokeWidthLegendLabels", property: "y", value: y })
-      .editGraphics({
-        target: "strokeWidthLegendLabels",
-        property: "text",
-        value: layout.labels
-      });
-    next = editLegendBackground(next, "strokeWidthLegendBackground", layout.background, config.border);
-    next = styleContinuousText(next, "strokeWidthLegendLabels", config.labels);
-    if (config.titleVisible === false) return next;
-    next = next
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "x", value: layout.title.x })
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "y", value: layout.title.y })
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "text", value: title });
-    return styleContinuousText(next, "strokeWidthLegendTitle", config.titleStyle, { align: layout.title.align });
+    const currentConfig = { ...config, scale: encoding.scale, title };
+    const layout = resolveStrokeWidthLegendLayout(this, currentConfig);
+    return materializeItemLegend(this, "strokeWidth", { ...currentConfig, domain: scale.domain }, layout, {
+      symbols: {
+        x1: layout.symbolX, x2: layout.symbolX.map(x => x + 32),
+        y1: layout.itemY, y2: layout.itemY,
+        stroke: layout.config.blockSymbol?.stroke ?? DEFAULT_COLORS.mark,
+        strokeWidth: layout.widths
+      },
+      optional: { opacity: layout.config.blockSymbol?.opacity }
+    });
   }
 );
 
@@ -162,20 +138,17 @@ export function resolveStrokeWidthLegendConfig(program, args = {}) {
   const layer = resolveLayer(program, args.target);
   const encoding = layer.encoding.strokeWidth;
   requireScale(program, encoding.scale);
-  const count = args.count ?? 5;
-  if (!Number.isInteger(count) || count < 2) {
-    throw new RangeError(
-      "Stroke-width legend count must be an integer of at least 2."
-    );
-  }
-  validateGeneratedItemLimit(count, "Stroke-width legend count");
+  const sampling = normalizeLegendSampling(args, {
+    operation: "create",
+    label: "Stroke-width legend"
+  });
   return {
     target: layer.id,
     scale: encoding.scale,
     ...normalizeItemLegendLayout({ ...args, itemGap: args.itemGap ?? 32 }),
     title: args.title ?? encoding.field,
     inferredTitle: args.title === undefined,
-    count,
+    sampling,
     labels: normalizeLegendTextOptions(args.labels, "createLegend.labels", STROKE_WIDTH_LEGEND_LABELS),
     titleStyle: normalizeLegendTitleOptions(args.titleStyle, "createLegend.titleStyle", STROKE_WIDTH_LEGEND_TITLE_STYLE),
     border: normalizeLegendBorder(args.border),
@@ -184,36 +157,9 @@ export function resolveStrokeWidthLegendConfig(program, args = {}) {
 }
 
 export function createStrokeWidthLegendFromConfig(program, config) {
-  resolveStrokeWidthLegendLayout(program, config);
-  const { count } = config;
-  let next = program
-    .editSemantic({ property: "guide.legend.strokeWidth.scale", value: config.scale })
-    .editSemantic({ property: "guide.legend.strokeWidth.title", value: config.title })
-    ._withLegendConfig("strokeWidth", config);
-  if (config.border !== false) {
-    next = next.createGraphics({ id: "strokeWidthLegendBackground", type: "rect",
-      ...resolveLegendGraphicPlacement(program) });
-  }
-  next = next.createGraphics({
-      id: "strokeWidthLegendSymbols",
-      type: "line",
-      length: count,
-      ...resolveLegendGraphicPlacement(program)
-    })
-    .createGraphics({
-      id: "strokeWidthLegendLabels",
-      type: "text",
-      length: count,
-      ...resolveLegendGraphicPlacement(program)
-    });
-  if (config.titleVisible !== false) {
-    next = next.createGraphics({
-      id: "strokeWidthLegendTitle",
-      type: "text",
-      ...resolveLegendGraphicPlacement(program)
-    });
-  }
-  return next.rematerializeStrokeWidthLegend();
+  const layout = resolveStrokeWidthLegendLayout(program, config);
+  const count = layout.widths.length;
+  return createItemLegendGraphics(program, "strokeWidth", config, count, "line", resolveLegendGraphicPlacement(program)).rematerializeStrokeWidthLegend();
 }
 
 export const createStrokeWidthLegend = /* @__PURE__ */ action(

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

@@ -1,5 +1,9 @@
 import { validateUserId } from "../../../core/identifiers.js";
-import { LEGEND_CHANNELS } from "../../../core/vocabulary.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.`);
@@ -35,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];
+}