ggaction 0.0.12 → 0.0.15

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

@@ -1,25 +1,57 @@
 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 {
+  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";
-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";
+import {
+  normalizeLegendSampling,
+  readLegendSampling,
+  resolveLegendSampleValues
+} from "./sampling.js";
+import { resolveEffectiveLegendBlockConfig } from "./blocks.js";
 
-const SIZE_OPTIONS = Object.freeze(["target", "count"]);
+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({
+  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" &&
@@ -38,25 +70,80 @@ 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;
 }
 
-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);
+  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 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".');
+  }
+  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: effective.blockGap ?? categorical.itemGap
+  } : { position };
+  const discrete = isDiscreteSizeScaleType(scale.type);
+  if (discrete && readLegendSampling(config).mode === "values") {
+    throw new Error("Discrete size legends do not support exact values.");
   }
-  return value;
+  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 = 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
+    }))
+  });
+  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(
@@ -73,7 +160,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,
@@ -81,127 +168,137 @@ 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 effective = layout.config;
+    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",
         property: "fill",
-        value: DEFAULT_COLORS.sizeSymbol
+        value: effective.blockSymbol?.fill ?? DEFAULT_COLORS.sizeSymbol
       })
-      .editGraphics({ target: "sizeLegendSymbols", property: "opacity", value: 0.7 })
-      .editGraphics({ target: "sizeLegendLabels", property: "length", value: values.length })
+      .editGraphics({ target: "sizeLegendSymbols", property: "opacity",
+        value: effective.blockSymbol?.opacity ?? 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: formatContinuousValues(values, scale.domain, "quantitative")
-      })
-      .editGraphics({ target: "sizeLegendTitle", property: "x", value: originX })
-      .editGraphics({ target: "sizeLegendTitle", property: "y", value: titleY })
-      .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
-          }
-    );
+        value: layout.text
+      });
+    next = editLegendBackground(next, "sizeLegendBackground", layout.background, currentConfig.border);
+    if (effective.blockSymbol?.stroke !== undefined) {
+      next = next.editGraphics({ target: "sizeLegendSymbols", property: "stroke",
+        value: effective.blockSymbol.stroke });
+    }
+    if (effective.blockSymbol?.strokeWidth !== undefined) {
+      next = next.editGraphics({ target: "sizeLegendSymbols", property: "strokeWidth",
+        value: effective.blockSymbol.strokeWidth });
+    }
+    next = styleContinuousText(next, "sizeLegendLabels", labels);
+    if (effective.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: effective.title });
+    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);
+  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.");
+  }
+  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,
+    ...normalizeItemLegendLayout({ ...args, itemGap: args.itemGap ?? 40 }),
+    title: args.title ?? encoding.field,
+    inferredTitle: args.title === undefined,
+    domain: scale.domain,
+    ...(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),
+    border: normalizeLegendBorder(args.border),
+    titleVisible: true
+  };
+}
+
+export function createSizeLegendFromConfig(program, 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();
+}
+
 export const createSizeLegend = action(
   {
     op: "createSizeLegend",
-    description: "Create a quantitative equal-area point-size legend."
+    description: "Create an 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,36 @@
 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";
+import {
+  normalizeLegendSampling,
+  resolveLegendSampleValues
+} from "./sampling.js";
+import { resolveEffectiveLegendBlockConfig } from "./blocks.js";
 
-const OPTIONS = Object.freeze(["target", "count"]);
+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({
   offset: 12,
@@ -63,7 +76,25 @@ function requireScale(program, id) {
   return scale;
 }
 
-export const rematerializeStrokeWidthLegend = action(
+export function resolveStrokeWidthLegendLayout(program, config) {
+  const effective = resolveEffectiveLegendBlockConfig(program, "strokeWidth", config);
+  const scale = requireScale(program, config.scale);
+  const { plot, canvas } = resolveContinuousBounds(program);
+  const values = resolveLegendSampleValues(effective, scale, "Stroke-width legend");
+  const widths = mapContinuousScaleValues(values, scale);
+  const labels = formatContinuousValues(
+    values,
+    scale.domain,
+    "quantitative",
+    effective.labels.format
+  );
+  const layout = resolveLegendItemLayout(plot, effective, labels, { width: 32, height: 0, strokeWidth: widths });
+  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(
   {
     op: "rematerializeStrokeWidthLegend",
     description: "Rematerialize a quantitative stroke-width legend."
@@ -86,102 +117,119 @@ 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 currentConfig = { ...config, scale: encoding.scale, title };
+    const layout = resolveStrokeWidthLegendLayout(this, currentConfig);
+    const effective = layout.config;
+    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,
+        ...currentConfig,
         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: "stroke",
+        value: effective.blockSymbol?.stroke ?? 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 = styleContinuousText(next, "strokeWidthLegendLabels", config.labels);
-    if (config.titleVisible === false) return next;
+    next = editLegendBackground(next, "strokeWidthLegendBackground", layout.background, config.border);
+    if (effective.blockSymbol?.opacity !== undefined) {
+      next = next.editGraphics({ target: "strokeWidthLegendSymbols", property: "opacity",
+        value: effective.blockSymbol.opacity });
+    }
+    next = styleContinuousText(next, "strokeWidthLegendLabels", effective.labels);
+    if (effective.titleVisible === false) return next;
     next = next
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "x", value: originX })
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "y", value: titleY })
-      .editGraphics({ target: "strokeWidthLegendTitle", property: "text", value: title });
-    return styleContinuousText(next, "strokeWidthLegendTitle", config.titleStyle);
+      .editGraphics({ target: "strokeWidthLegendTitle", property: "x", value: layout.title.x })
+      .editGraphics({ target: "strokeWidthLegendTitle", property: "y", value: layout.title.y })
+      .editGraphics({ target: "strokeWidthLegendTitle", property: "text", value: effective.title });
+    return styleContinuousText(next, "strokeWidthLegendTitle", effective.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 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,
+    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),
+    titleVisible: true
+  };
+}
+
+export function createStrokeWidthLegendFromConfig(program, config) {
+  const layout = resolveStrokeWidthLegendLayout(program, config);
+  const count = layout.widths.length;
+  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);
   }
 );