ggaction 0.0.12 → 0.0.13

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

@@ -1,25 +1,48 @@
 import { action } from "../../../core/action.js";
 import {
   validateGeneratedItemLimit,
+  validateNonEmptyString,
   validateKeys
 } from "../../../core/validation.js";
 import { mapLinearValues } from "../../../grammar/scales/index.js";
-import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { resolveLegendItemLayout } from "../../../layout/legendItems.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
-import { resolveLayout as resolveCategoricalLayout } from
-  "./categorical/layout.js";
 import { findLayer } from "../../../selectors/layers.js";
-import { findCanvasGraphic, resolveLegendGraphicPlacement } from
+import { resolveLegendGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 import {
+  assertLegendBoundsInsideCanvas,
+  editLegendBackground,
+  normalizeItemLegendLayout,
+  normalizeLegendBorder,
+  normalizeLegendTextOptions,
+  normalizeLegendTitleOptions,
+  resolveContinuousBounds,
+  resolveLegendBackgroundFromBounds,
   formatContinuousValues,
   sampleContinuousValues,
   selectLegendLayer,
   styleContinuousText
 } from "./continuous/common.js";
+import { legendResourcePolicies } from "../../../materialization/guides/resources.js";
 
-const SIZE_OPTIONS = Object.freeze(["target", "count"]);
+const SIZE_OPTIONS = Object.freeze(["target", "count", "position", "layout", "align",
+  "direction", "columns", "titlePosition", "offset", "itemGap", "title", "labels", "titleStyle", "border"]);
+
+export const SIZE_LEGEND_LABELS = Object.freeze({
+  offset: 12,
+  color: DEFAULT_COLORS.text,
+  fontSize: 12,
+  fontFamily: DEFAULT_FONT_FAMILY,
+  fontWeight: "normal"
+});
+export const SIZE_LEGEND_TITLE_STYLE = Object.freeze({
+  color: DEFAULT_COLORS.strongText,
+  fontSize: 13,
+  fontFamily: DEFAULT_FONT_FAMILY,
+  fontWeight: 600
+});
 
 export function isSizeLegendPoint(layer) {
   return layer?.mark?.type === "point" &&
@@ -46,17 +69,42 @@ function requireScale(program, id, type) {
   return scale;
 }
 
-function bounds(program) {
-  const value = resolveGraphicBounds(program);
-  const canvas = findCanvasGraphic(program);
-  if (
-    value === undefined ||
-    ![value.x, value.y, value.width, value.height].every(Number.isFinite) ||
-    !Number.isFinite(canvas?.properties.width)
-  ) {
-    throw new Error("Legend layout requires Canvas bounds and width.");
+export function resolveSizeLegendLayout(program, config) {
+  const scale = requireScale(program, config.scale, "linear");
+  const categorical = [program.guideConfigs.legend?.series, program.guideConfigs.legend?.color]
+    .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 position = categorical?.position ?? config.position;
+  if (categorical?.layout === "legacy-bottom") {
+    throw new Error('Combined size legends require layout "edge".');
   }
-  return value;
+  const horizontal = categorical !== undefined && ["top", "bottom"].includes(position);
+  const geometry = horizontal ? {
+    position, align: categorical.align, direction: categorical.direction,
+    columns: categorical.columns, titlePosition: categorical.titlePosition,
+    offset: categorical.offset, itemGap: categorical.itemGap
+  } : { position };
+  const values = sampleContinuousValues(scale.domain, config.count);
+  const areas = mapLinearValues(values, scale.domain, scale.range, { clamp: scale.clamp ?? false });
+  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 };
 }
 
 export const rematerializeSizeLegend = action(
@@ -81,34 +129,19 @@ export const rematerializeSizeLegend = action(
       title,
       domain: scale.domain
     };
-    const plot = bounds(this);
-    const categorical = this.guideConfigs.legend?.series ??
-      this.guideConfigs.legend?.color;
-    const leftLayout = categorical?.position === "left"
-      ? resolveCategoricalLayout(this, categorical).size
-      : undefined;
-    const originX = leftLayout?.titleX ?? plot.x + plot.width + 30;
-    const seriesCount = categorical?.domain.length ?? 0;
-    const titleY = leftLayout?.titleY ?? plot.y + 56 + seriesCount * 34 + 22;
-    const values = sampleContinuousValues(scale.domain, currentConfig.count);
-    const areas = mapLinearValues(values, scale.domain, scale.range, {
-      clamp: scale.clamp ?? false
-    });
-    const itemY = leftLayout?.itemY ??
-      values.map((_, index) => titleY + 34 + index * 40);
-    const symbolX = leftLayout?.symbolX ?? values.map(() => originX + 16);
-    const labelX = leftLayout?.labelX ?? values.map(() => originX + 44);
+    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: values.length })
+      .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: areas.map(area => Math.sqrt(area / Math.PI))
+        value: radii
       })
       .editGraphics({
         target: "sizeLegendSymbols",
@@ -116,92 +149,103 @@ export const rematerializeSizeLegend = action(
         value: DEFAULT_COLORS.sizeSymbol
       })
       .editGraphics({ target: "sizeLegendSymbols", property: "opacity", value: 0.7 })
-      .editGraphics({ target: "sizeLegendLabels", property: "length", value: values.length })
+      .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: formatContinuousValues(values, scale.domain, "quantitative")
-      })
-      .editGraphics({ target: "sizeLegendTitle", property: "x", value: originX })
-      .editGraphics({ target: "sizeLegendTitle", property: "y", value: titleY })
+        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 });
-    next = styleContinuousText(
-      next,
-      "sizeLegendLabels",
-      currentConfig.inheritAppearance === true
-        ? categorical.labels
-        : {
-            color: DEFAULT_COLORS.text,
-            fontSize: 12,
-            fontFamily: DEFAULT_FONT_FAMILY,
-            fontWeight: "normal"
-          }
-    );
-    return styleContinuousText(
-      next,
-      "sizeLegendTitle",
-      currentConfig.inheritAppearance === true
-        ? categorical.titleStyle
-        : {
-            color: DEFAULT_COLORS.strongText,
-            fontSize: 13,
-            fontFamily: DEFAULT_FONT_FAMILY,
-            fontWeight: 600
-          }
-    );
+    return styleContinuousText(next, "sizeLegendTitle", titleStyle, { align: layout.title.align });
   }
 );
 
+
+export function resolveSizeLegendConfig(program, args = {}) {
+  validateKeys(args, [...SIZE_OPTIONS, "inheritAppearance"], "createSizeLegend");
+  if (args.title !== undefined) validateNonEmptyString(args.title, "Legend title");
+  const layer = resolveSizeLegendPoint(program, args.target);
+  const encoding = layer.encoding?.size;
+  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.");
+  }
+  validateGeneratedItemLimit(count, "Size legend count");
+  return {
+    target: layer.id,
+    scale: encoding.scale,
+    ...normalizeItemLegendLayout({ ...args, itemGap: args.itemGap ?? 40 }),
+    title: args.title ?? encoding.field,
+    inferredTitle: args.title === undefined,
+    domain: scale.domain,
+    count,
+    inheritAppearance: args.inheritAppearance === true,
+    labels: normalizeLegendTextOptions(args.labels, "createLegend.labels", SIZE_LEGEND_LABELS),
+    titleStyle: normalizeLegendTitleOptions(args.titleStyle, "createLegend.titleStyle", SIZE_LEGEND_TITLE_STYLE),
+    border: normalizeLegendBorder(args.border),
+    titleVisible: true
+  };
+}
+
+export function createSizeLegendFromConfig(program, config) {
+  resolveSizeLegendLayout(program, config);
+  const { count } = config;
+  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();
+}
+
 export const createSizeLegend = action(
   {
     op: "createSizeLegend",
     description: "Create a quantitative equal-area point-size legend."
   },
   function (args = {}) {
-    validateKeys(args, [...SIZE_OPTIONS, "inheritAppearance"], "createSizeLegend");
-    const layer = resolveSizeLegendPoint(this, args.target);
-    const encoding = layer.encoding?.size;
-    if (encoding?.scale === undefined) {
-      throw new Error(`Point mark "${layer.id}" requires a size encoding.`);
-    }
-    const scale = requireScale(this, 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.");
-    }
-    validateGeneratedItemLimit(count, "Size legend count");
-    return this
-      .editSemantic({ property: "guide.legend.size.scale", value: encoding.scale })
-      .editSemantic({ property: "guide.legend.size.title", value: encoding.field })
-      ._withLegendConfig("size", {
-        target: layer.id,
-        scale: encoding.scale,
-        title: encoding.field,
-        inferredTitle: true,
-        domain: scale.domain,
-        count,
-        inheritAppearance: args.inheritAppearance === true
-      })
-      .createGraphics({
-        id: "sizeLegendSymbols",
-        type: "circle",
-        length: count,
-        ...resolveLegendGraphicPlacement(this)
-      })
-      .createGraphics({
-        id: "sizeLegendLabels",
-        type: "text",
-        length: count,
-        ...resolveLegendGraphicPlacement(this)
-      })
-      .createGraphics({
-        id: "sizeLegendTitle",
-        type: "text",
-        ...resolveLegendGraphicPlacement(this)
-      })
-      .rematerializeSizeLegend();
+    const config = resolveSizeLegendConfig(this, args);
+    return createSizeLegendFromConfig(this, config);
   }
 );
 

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

@@ -1,23 +1,33 @@
 import { action } from "../../../core/action.js";
 import {
   validateGeneratedItemLimit,
+  validateNonEmptyString,
   validateKeys
 } from "../../../core/validation.js";
 import { mapContinuousScaleValues } from "../../../grammar/scales/index.js";
-import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { resolveLegendItemLayout } from "../../../layout/legendItems.js";
 import { resolveLegendGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 import { findLayer } from "../../../selectors/layers.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
 import {
+  assertLegendBoundsInsideCanvas,
+  editLegendBackground,
+  normalizeItemLegendLayout,
+  normalizeLegendBorder,
+  normalizeLegendTextOptions,
+  normalizeLegendTitleOptions,
+  resolveContinuousBounds,
+  resolveLegendBackgroundFromBounds,
   formatContinuousValues,
   sampleContinuousValues,
   selectLegendLayer,
   styleContinuousText
 } from "./continuous/common.js";
 
-const OPTIONS = Object.freeze(["target", "count"]);
+const OPTIONS = Object.freeze(["target", "count", "position", "layout", "align",
+  "direction", "columns", "titlePosition", "offset", "itemGap", "title", "labels", "titleStyle", "border"]);
 
 export const STROKE_WIDTH_LEGEND_LABELS = Object.freeze({
   offset: 12,
@@ -63,7 +73,24 @@ function requireScale(program, id) {
   return scale;
 }
 
-export const rematerializeStrokeWidthLegend = action(
+export function resolveStrokeWidthLegendLayout(program, config) {
+  const scale = requireScale(program, config.scale);
+  const { plot, canvas } = resolveContinuousBounds(program);
+  const values = sampleContinuousValues(scale.domain, config.count);
+  const widths = mapContinuousScaleValues(values, scale);
+  const labels = formatContinuousValues(
+    values,
+    scale.domain,
+    "quantitative",
+    config.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 };
+}
+
+export const rematerializeStrokeWidthLegend = /* @__PURE__ */ action(
   {
     op: "rematerializeStrokeWidthLegend",
     description: "Rematerialize a quantitative stroke-width legend."
@@ -86,16 +113,9 @@ export const rematerializeStrokeWidthLegend = action(
       throw new Error("Stroke-width legend target requires a strokeWidth encoding.");
     }
     const scale = requireScale(this, encoding.scale);
-    const plot = resolveGraphicBounds(this);
-    if (plot === undefined) {
-      throw new Error("Stroke-width legend requires resolved plot bounds.");
-    }
-    const values = sampleContinuousValues(scale.domain, config.count);
-    const widths = mapContinuousScaleValues(values, scale);
-    const originX = plot.x + plot.width + 30;
-    const titleY = plot.y + 28;
-    const y = values.map((_, index) => titleY + 34 + index * 32);
     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 })
@@ -105,83 +125,105 @@ export const rematerializeStrokeWidthLegend = action(
         title,
         domain: scale.domain
       })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "length", value: values.length })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "x1", value: values.map(() => originX) })
-      .editGraphics({ target: "strokeWidthLegendSymbols", property: "x2", value: values.map(() => originX + 32) })
+      .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: values.length })
+      .editGraphics({ target: "strokeWidthLegendLabels", property: "length", value: widths.length })
       .editGraphics({
         target: "strokeWidthLegendLabels",
         property: "x",
-        value: values.map(() => originX + 32 + config.labels.offset)
+        value: layout.labelX
       })
       .editGraphics({ target: "strokeWidthLegendLabels", property: "y", value: y })
       .editGraphics({
         target: "strokeWidthLegendLabels",
         property: "text",
-        value: formatContinuousValues(values, scale.domain, "quantitative")
+        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: originX })
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "y", value: titleY })
+      .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);
+    return styleContinuousText(next, "strokeWidthLegendTitle", config.titleStyle, { align: layout.title.align });
   }
 );
 
-export const createStrokeWidthLegend = action(
+
+export function resolveStrokeWidthLegendConfig(program, args = {}) {
+  validateKeys(args, OPTIONS, "createStrokeWidthLegend");
+  if (args.title !== undefined) validateNonEmptyString(args.title, "Legend title");
+  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");
+  return {
+    target: layer.id,
+    scale: encoding.scale,
+    ...normalizeItemLegendLayout({ ...args, itemGap: args.itemGap ?? 32 }),
+    title: args.title ?? encoding.field,
+    inferredTitle: args.title === undefined,
+    count,
+    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),
+    titleVisible: true
+  };
+}
+
+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();
+}
+
+export const createStrokeWidthLegend = /* @__PURE__ */ action(
   {
     op: "createStrokeWidthLegend",
     description: "Create a quantitative stroke-width legend."
   },
   function (args = {}) {
-    validateKeys(args, OPTIONS, "createStrokeWidthLegend");
-    const layer = resolveLayer(this, args.target);
-    const encoding = layer.encoding.strokeWidth;
-    requireScale(this, 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");
-    return this
-      .editSemantic({ property: "guide.legend.strokeWidth.scale", value: encoding.scale })
-      .editSemantic({ property: "guide.legend.strokeWidth.title", value: encoding.field })
-      ._withLegendConfig("strokeWidth", {
-        target: layer.id,
-        scale: encoding.scale,
-        title: encoding.field,
-        inferredTitle: true,
-        count,
-        labels: { ...STROKE_WIDTH_LEGEND_LABELS },
-        titleStyle: { ...STROKE_WIDTH_LEGEND_TITLE_STYLE },
-        titleVisible: true
-      })
-      .createGraphics({
-        id: "strokeWidthLegendSymbols",
-        type: "line",
-        length: count,
-        ...resolveLegendGraphicPlacement(this)
-      })
-      .createGraphics({
-        id: "strokeWidthLegendLabels",
-        type: "text",
-        length: count,
-        ...resolveLegendGraphicPlacement(this)
-      })
-      .createGraphics({
-        id: "strokeWidthLegendTitle",
-        type: "text",
-        ...resolveLegendGraphicPlacement(this)
-      })
-      .rematerializeStrokeWidthLegend();
+    const config = resolveStrokeWidthLegendConfig(this, args);
+    return createStrokeWidthLegendFromConfig(this, config);
   }
 );
 

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

@@ -1,4 +1,16 @@
 import { validateUserId } from "../../../core/identifiers.js";
+import { LEGEND_CHANNELS } from "../../../core/vocabulary.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 ?? {})

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

@@ -0,0 +1,43 @@
+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";
+
+const family = type => type === "sequential" ? "gradient"
+  : isDiscretizedColorScaleType(type) ? "interval" : undefined;
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+export function planColorLegendTransition(program, scale, nextType) {
+  const from = family(scale.type), to = family(nextType);
+  if (from === undefined || to === undefined || from === to) return undefined;
+  const stored = program.guideConfigs.legend?.[from];
+  if (stored?.scale !== scale.id) return undefined;
+  const side = ["left", "right"].includes(stored.position);
+  const defaults = from === "gradient" ? normalizeContinuousLegend({ position: stored.position }, "gradient")
+    : normalizeIntervalLegend({ position: stored.position });
+  const custom = from === "gradient"
+    ? stored.count !== defaults.count || !same(stored.gradient, DEFAULT_GRADIENT_SIZE) || stored.itemGap !== defaults.itemGap
+    : !same(stored.symbol, defaults.symbol) || stored.itemGap !== defaults.itemGap ||
+      stored.direction !== defaults.direction || (stored.columns !== undefined && !(side && stored.columns === 1));
+  if (custom) {
+    throw new Error("Color legend transition cannot discard custom family settings; remove and recreate the legend explicitly.");
+  }
+  const args = {
+    target: stored.target, channels: ["color"], 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 (to === "interval") normalizeIntervalLegend(args);
+    else normalizeContinuousLegend(args, "gradient");
+  } catch (error) {
+    throw new Error(`Color legend transition has incompatible layout or style: ${error.message}`);
+  }
+  return { args, titleVisible: stored.titleVisible !== false };
+}
+
+export function applyColorLegendTransition(program, plan) {
+  const next = program.createLegend(plan.args);
+  return plan.titleVisible ? next : next.editLegend({ target: plan.args.target, title: false });
+}