ggaction 0.0.18 → 0.0.19

package/src/actions/guides/grids/resolve.js

@@ -1,4 +1,7 @@
+import { cartesianAxisOwners } from "../../../selectors/axes.js";
+import { axisGraphicIds } from "../../../materialization/guides/resources.js";
 import { isNominalValue } from "../../../grammar/scales/fields.js";
+import { patchGuideDash, validateGuideDash, normalizeGuideDashMap, resolveGuideDashes } from "../../../grammar/guideDash.js";
 import { isSourceOwnedText } from "../../../grammar/text.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
@@ -27,10 +30,10 @@ import {
 } from "../../../grammar/schemas/graphicTree.js";
 
 const GRID_OPTIONS = Object.freeze([
-  "scale", "coordinate", "count", "values", "color", "lineWidth", "strokeDash", "zIndex", "bandPosition", "alongOffset"
+  "scale", "coordinate", "count", "values", "color", "lineWidth", "strokeDash", "strokeDashMap", "zIndex", "bandPosition", "alongOffset"
 ]);
 const GRID_EDIT_OPTIONS = Object.freeze([
-  "count", "values", "color", "lineWidth", "strokeDash", "zIndex", "bandPosition", "alongOffset"
+  "count", "values", "color", "lineWidth", "strokeDash", "strokeDashMap", "zIndex", "bandPosition", "alongOffset"
 ]);
 const DEFAULT_STYLE = Object.freeze({
   color: DEFAULT_COLORS.grid,
@@ -49,19 +52,11 @@ export function gridNames(direction) {
 }
 
 function validateStrokeDash(value) {
-  if (
-    !Array.isArray(value) ||
-    value.length % 2 !== 0 ||
-    !value.every(item => Number.isFinite(item) && item >= 0)
-  ) {
-    throw new TypeError(
-      "Grid strokeDash must be an even-length array of non-negative finite numbers."
-    );
-  }
-  return value;
+  return validateGuideDash(value, "Grid strokeDash");
 }
 
 export function validateGridCreateArgs(args, operation) {
+  if (Object.hasOwn(args, "strokeDashMap")) normalizeGuideDashMap(args.strokeDashMap);
   validateOptionObject(args, GRID_OPTIONS, operation);
   if (Array.isArray(args.values)) {
     validateGeneratedItemLimit(args.values.length, "Grid value count");
@@ -95,6 +90,7 @@ export function validateGridCreateArgs(args, operation) {
 }
 
 export function validateGridEditArgs(args, operation) {
+  if (Object.hasOwn(args, "strokeDashMap")) normalizeGuideDashMap(args.strokeDashMap);
   validateOptionObject(args, GRID_EDIT_OPTIONS, operation, {
     allowEmpty: false
   });
@@ -138,39 +134,25 @@ export function resolveGridResources(program, direction, args) {
   let layers = program.semanticSpec.layers.filter(
     layer => !isSourceOwnedText(layer) && layer.encoding?.[channel]?.scale !== undefined
   );
-  if (layers.length === 0) throw new Error(`${direction} grid requires a ${channel} encoding.`);
-  const requestedCoordinate = args.coordinate === undefined
-    ? undefined
-    : validateUserId(args.coordinate, "Grid coordinate id");
-  const requestedScale = args.scale === undefined
-    ? undefined
-    : validateUserId(args.scale, "Grid scale id");
-  if (requestedCoordinate !== undefined) {
-    layers = layers.filter(layer => layer.coordinate === requestedCoordinate);
-  }
-  if (requestedScale !== undefined) {
-    layers = layers.filter(layer => layer.encoding[channel].scale === requestedScale);
-  }
-  if (layers.length === 0) throw new Error(`${direction} grid found no matching encoded layers.`);
-  const coordinateIds = [...new Set(layers.map(layer => layer.coordinate).filter(Boolean))];
-  if (layers.some(layer => layer.coordinate === undefined)) {
-    throw new Error(`${direction} grid requires a stored coordinate.`);
-  }
-  if (coordinateIds.length === 0) throw new Error(`Unknown grid coordinate "${requestedCoordinate}".`);
-  if (coordinateIds.length > 1) {
-    throw new Error(`${direction} grid found multiple coordinates; provide coordinate explicitly.`);
-  }
+  const requestedCoordinate = args.coordinate === undefined ? undefined : validateUserId(args.coordinate, "Grid coordinate id");
+  const requestedScale = args.scale === undefined ? undefined : validateUserId(args.scale, "Grid scale id");
+  const axes = cartesianAxisOwners(program).filter(owner => owner.channel === channel && owner.scale !== undefined && owner.coordinate !== undefined);
+  const bindings = [...layers.map(layer => ({ coordinate: layer.coordinate, scale: layer.encoding[channel].scale })),
+    ...axes.map(owner => ({ coordinate: owner.coordinate, scale: owner.scale }))]
+    .filter(binding => (requestedCoordinate === undefined || binding.coordinate === requestedCoordinate) &&
+      (requestedScale === undefined || binding.scale === requestedScale));
+  if (bindings.length === 0) throw new Error(layers.length === 0
+    ? `${direction} grid requires a ${channel} encoding or bound Cartesian axis.`
+    : `${direction} grid found no matching encoded layers.`);
+  if (bindings.some(binding => binding.coordinate === undefined)) throw new Error(`${direction} grid requires a stored coordinate.`);
+  const coordinateIds = [...new Set(bindings.map(binding => binding.coordinate))];
+  if (coordinateIds.length > 1) throw new Error(`${direction} grid found multiple coordinates; provide coordinate explicitly.`);
   const coordinate = requestedCoordinate ?? coordinateIds[0];
-  const definition = findCoordinate(program, coordinate);
-  if (definition?.type !== "cartesian") {
-    throw new Error(`${direction} grid requires a Cartesian coordinate.`);
-  }
-  const scaleIds = [...new Set(layers.map(layer => layer.encoding[channel].scale))];
-  if (scaleIds.length === 0) throw new Error(`Unknown grid scale "${requestedScale}".`);
-  if (scaleIds.length > 1) {
-    throw new Error(`${direction} grid found multiple ${channel} scales; provide scale explicitly.`);
-  }
+  if (findCoordinate(program, coordinate)?.type !== "cartesian") throw new Error(`${direction} grid requires a Cartesian coordinate.`);
+  const scaleIds = [...new Set(bindings.map(binding => binding.scale))];
+  if (scaleIds.length > 1) throw new Error(`${direction} grid found multiple ${channel} scales; provide scale explicitly.`);
   const scale = requestedScale ?? scaleIds[0];
+  layers = layers.filter(layer => layer.coordinate === coordinate && layer.encoding[channel].scale === scale);
   if (
     !["linear", "time", "band", "point"].includes(program.resolvedScales[scale]?.type) &&
     !isTransformedScaleType(program.resolvedScales[scale]?.type)
@@ -185,6 +167,11 @@ export function resolveGridResources(program, direction, args) {
     const leader = program.materializationConfigs.labelLayouts?.[layer.id]?.leaderId;
     return leader === undefined ? [layer.id] : [leader, layer.id];
   }));
+  if (related.size === 0) {
+    for (const owner of axes.filter(owner => owner.scale === scale && owner.coordinate === coordinate)) {
+      for (const id of axisGraphicIds(channel, owner.id)) if (program.graphicSpec.objects[id] !== undefined) related.add(id);
+    }
+  }
   let before;
   let after;
   walkGraphicDrawOrder(program.graphicSpec, ({ id }) => {
@@ -210,7 +197,7 @@ export function resolveGridConfig(program, direction, args, resources) {
     : Object.hasOwn(args, "count")
       ? { mode: "count", count: args.count }
       : inferGridTickConfig(program, resources.channel, resources.scale);
-  return {
+  return patchGuideDash({
     direction,
     ...(args.bandPosition === undefined ? {} : { bandPosition: args.bandPosition }),
     ...(args.zIndex === undefined ? {} : { zIndex: args.zIndex }),
@@ -222,7 +209,7 @@ export function resolveGridConfig(program, direction, args, resources) {
     color: args.color ?? DEFAULT_STYLE.color,
     lineWidth: args.lineWidth ?? DEFAULT_STYLE.lineWidth,
     strokeDash: args.strokeDash ?? DEFAULT_STYLE.strokeDash
-  };
+  }, args);
 }
 
 export function refreshGridConfig(program, config) {
@@ -257,7 +244,7 @@ export function editGridConfig(previous, args) {
   } else if (args.values === "auto") {
     config.inferredValues = true;
   }
-  return config;
+  return patchGuideDash(config, args);
 }
 
 export function resolveGridGeometry(program, config) {
@@ -281,11 +268,21 @@ export function resolveGridGeometry(program, config) {
     if (!values.every(value => scale.domain.includes(value))) throw new RangeError("Grid values must be inside the scale domain.");
     const centers = mapOrdinalPositionValues(values, scale);
     const direction = scale.range[1] >= scale.range[0] ? 1 : -1;
+    const owners = new Map();
+    if (config.bandPosition === "boundary") {
+      centers.forEach((center, index) => {
+        for (const edge of [center - direction * scale.bandwidth / 2, center + direction * scale.bandwidth / 2]) {
+          if (!owners.has(edge)) owners.set(edge, values[index]);
+        }
+      });
+    }
     const positions = config.bandPosition === "boundary"
-      ? [...new Set(centers.flatMap(center => [center - direction * scale.bandwidth / 2, center + direction * scale.bandwidth / 2]))].sort((a, b) => direction * (a - b))
-      : centers;
+      ? [...owners.keys()].sort((a, b) => direction * (a - b)) : centers;
     validateGeneratedItemLimit(positions.length, "Grid value count");
-    return resolveGridLineGeometry({ direction: config.direction, values: positions, positions: positions.map(value => value + (config.alongOffset ?? 0)), bounds });
+    return {
+      ...resolveGridLineGeometry({ direction: config.direction, values: positions, positions: positions.map(value => value + (config.alongOffset ?? 0)), bounds }),
+      strokeDash: resolveGuideDashes(config.bandPosition === "boundary" ? positions.map(value => owners.get(value)) : values, config)
+    };
   }
   const values = valuesFromTickConfig(program, config);
   validateGeneratedItemLimit(values.length, "Grid value count");
@@ -295,12 +292,12 @@ export function resolveGridGeometry(program, config) {
     throw new RangeError("Grid values must be inside the scale domain.");
   }
   const positions = mapContinuousScaleValues(values, scale);
-  return resolveGridLineGeometry({
+  return { ...resolveGridLineGeometry({
     direction: config.direction,
     values,
     positions: positions.map(value => value + (config.alongOffset ?? 0)),
     bounds
-  });
+  }), strokeDash: resolveGuideDashes(values, config) };
 }
 
 

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

@@ -1,3 +1,7 @@
+import { editFacetParentLegend } from "../../../materialization/facetGuides/edit.js";
+
+import {patchLegendClipHeight, validateLegendClip} from "../../../grammar/legendClip.js";
+import { LEGEND_POSITIONS } from "../../../core/vocabulary.js";
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
 import {
@@ -23,11 +27,11 @@ import {
   resolveLegendBlock
 } from "./target.js";
 import { validateFontWeight } from "./categorical/validation.js";
-import { normalizeDisplayLabelMap } from "../../../grammar/displayLabels.js";
+import { normalizeDisplayLabelMap, normalizeNumericDisplayLabelMap } from "../../../grammar/displayLabels.js";
 
 const OPTIONS = Object.freeze([
   "target", "channel", "title", "values", "count", "order", "gap", "text", "symbol",
-  "labelMap"
+  "labelMap", "position", "clipHeight"
 ]);
 const TEXT_OPTIONS = Object.freeze(["fontSize", "fontFamily", "fontWeight", "color"]);
 const SYMBOL_OPTIONS = Object.freeze(["size", "fill", "stroke", "strokeWidth", "opacity"]);
@@ -63,10 +67,12 @@ function categoricalSupports(config, property) {
 
 function validateSymbolSupport(descriptor, property) {
   const { channels, family, kind, config } = descriptor;
+  if(kind === "colorSize" && ["fill","size"].includes(property)) throw new Error("Color-size symbols cannot override mapped fill or size.");
   if (family === "gradient") {
     throw new Error(`editLegendBlock symbol.${property} is unsupported for gradient blocks.`);
   }
   if (family === "categorical") {
+    if (property === "size" && channels.includes("size")) throw new Error("Combined size-shape block cannot override mapped size.");
     if (property === "fill" && channels.includes("color")) {
       throw new Error("editLegendBlock symbol.fill conflicts with the color mapping.");
     }
@@ -125,13 +131,21 @@ function normalizeSymbolPatch(value, descriptor) {
   return { ...value };
 }
 
+function normalizeBlockLabelMap(descriptor, map) {
+  if (["size","colorSize"].includes(descriptor.kind) && descriptor.family === "sampled") {
+    return normalizeNumericDisplayLabelMap(map, "editLegendBlock labelMap");
+  }
+  if (descriptor.family !== "categorical") {
+    throw new Error("editLegendBlock labelMap requires a categorical or continuous size block.");
+  }
+  return normalizeDisplayLabelMap(map, "editLegendBlock labelMap");
+}
+
 export function validateLegendBlockOverride(descriptor, override) {
+  if (override.position !== undefined && !LEGEND_POSITIONS.includes(override.position)) throw new Error("Invalid local legend position.");
   if (override.symbol !== undefined) normalizeSymbolPatch(override.symbol, descriptor);
   if (override.labelMap !== undefined) {
-    if (descriptor.family !== "categorical") {
-      throw new Error("editLegendBlock labelMap requires a categorical block.");
-    }
-    normalizeDisplayLabelMap(override.labelMap, "editLegendBlock labelMap");
+    normalizeBlockLabelMap(descriptor, override.labelMap);
   }
   return override;
 }
@@ -176,6 +190,8 @@ export function patchLegendBlockOverride(config, key, patch) {
     entry = withoutEmptyNested(entry, "symbol", patch.symbol);
   }
   if (Object.hasOwn(patch, "labelMap")) entry.labelMap = patch.labelMap;
+  if (Object.hasOwn(patch, "position")) entry.position = patch.position;
+  if (patch.removePosition === true) delete entry.position;
   if (patch.removeLabelMap === true) delete entry.labelMap;
   const blockOverrides = { ...(config.blockOverrides ?? {}) };
   if (Object.keys(entry).length === 0) delete blockOverrides[key];
@@ -208,7 +224,7 @@ function applyCategoricalSymbol(symbol, patch) {
 }
 
 export function resolveEffectiveLegendBlockConfig(program, kind, config) {
-  const channels = kind === "series" || kind === "color" || kind === "stroke"
+  const channels = kind === "colorSize" ? ["color","size"] : kind === "series" || kind === "color" || kind === "stroke"
     ? config.channels
     : [{ size: "size", opacity: "opacity", strokeWidth: "strokeWidth",
       gradient: "color", interval: "color", strokeGradient: "stroke",
@@ -233,6 +249,7 @@ export function resolveEffectiveLegendBlockConfig(program, kind, config) {
       : {})
   };
   if (override.symbol === undefined) return effective;
+  if(kind === "colorSize") return {...effective,symbol:{...config.symbol,...override.symbol}};
   if (["series", "color", "stroke"].includes(kind)) {
     return {
       ...effective,
@@ -290,6 +307,7 @@ export function reconcileLegendBlockTitleGraphic(program, kind, visible) {
 }
 
 const SPECIALIZED_SYMBOLS = Object.freeze({
+  colorSize: Object.freeze({id:"colorSizeLegendSymbols",type:"circle"}),
   gradient: Object.freeze({ id: "colorGradientSymbols", type: "circle" }),
   size: Object.freeze({ id: "sizeLegendSymbols", type: "circle" }),
   opacity: Object.freeze({ id: "opacityLegendSymbols", type: "circle" }),
@@ -326,6 +344,13 @@ function recreateSymbolGraphics(program, descriptor) {
 
 function normalizeBlockPatch(args, descriptor) {
   const patch = {};
+  if (Object.hasOwn(args, "position")) {
+    if (args.position === "inherit") patch.removePosition = true;
+    else {
+      if (!LEGEND_POSITIONS.includes(args.position)) throw new Error("Legend block position requires an anchor or inherit.");
+      patch.position = args.position;
+    }
+  }
   if (Object.hasOwn(args, "title")) {
     if (typeof args.title !== "string") {
       throw new TypeError("editLegendBlock title must be a string.");
@@ -341,26 +366,21 @@ function normalizeBlockPatch(args, descriptor) {
     patch.symbol = normalizeSymbolPatch(args.symbol, descriptor);
   }
   if (Object.hasOwn(args, "labelMap")) {
-    if (descriptor.family !== "categorical") {
-      throw new Error("editLegendBlock labelMap requires a categorical block.");
-    }
+    // Validate eligibility even for a reset, without introducing an empty map owner.
+    const map = normalizeBlockLabelMap(descriptor, args.labelMap === "auto" ? [] : args.labelMap);
     if (args.labelMap === "auto") patch.removeLabelMap = true;
-    else {
-      patch.labelMap = normalizeDisplayLabelMap(
-        args.labelMap,
-        "editLegendBlock labelMap"
-      );
-    }
+    else patch.labelMap = map;
   }
   return patch;
 }
 
 export const editLegendBlock = /* @__PURE__ */ action(
   {
-    op: "editLegendBlock",
+    op: "editLegendBlock", scope: "any",
     description: "Edit one logical legend block selected by channel."
   },
   withGuideLayoutValidation(function (args = {}) {
+    if (this.compositionSpec !== undefined) return editFacetParentLegend(this, "editLegendBlock", args);
     validateOptionObject(args, OPTIONS, "editLegendBlock");
     if (!Object.hasOwn(args, "target") || typeof args.target !== "string") {
       throw new TypeError("editLegendBlock target must be an explicit legend target id.");
@@ -377,7 +397,9 @@ export const editLegendBlock = /* @__PURE__ */ action(
       throw new Error("editLegendBlock values and count require a sampled legend block.");
     }
     const patch = normalizeBlockPatch(args, descriptor);
-    let config = descriptor.config;
+    let config = Object.hasOwn(args, "clipHeight")
+      ? patchLegendClipHeight(descriptor.config, args.clipHeight) : descriptor.config;
+    validateLegendClip(descriptor.kind, config);
     const blockOverrides = patchLegendBlockOverride(config, descriptor.key, patch);
     if (blockOverrides === undefined) {
       const { blockOverrides: _removed, ...rest } = config;
@@ -423,6 +445,8 @@ export const editLegendBlock = /* @__PURE__ */ action(
     }
     next = reconcileLegendBlockTitleGraphic(next, descriptor.kind,
       effective.titleVisible !== false);
-    return next.rematerializeLegend();
+    return Object.hasOwn(args, "position")
+      ? next.editLegend({target: args.target, channel: args.channel, position: args.position})
+      : next.rematerializeLegend();
   })
 );

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

@@ -1,3 +1,6 @@
+import {resolveColorSizeConfig,createColorSizeLegendFromConfig,materializeColorSizeLegend} from "../colorSize.js";
+import {resetLegendClipGraphics,applyLegendClipGraphics,restoreLegendClipContext}from"../../../../materialization/legendClip.js";
+import {validateLegendCombine,resolveSizeShapeCreation} from "../combine.js";
 import { recordLegendOffsetIntent } from "../group.js";
 import { prepareLegendGroup, creationLegendTarget, validateLegendGroupOptions } from "../group.js";
 import { PLOT_LEGEND_POSITIONS } from "../../../../layout/legend.js";
@@ -37,7 +40,7 @@ import {
 } from "../blocks.js";
 
 function finishLegend(program) {
-  return hasLegendLane(program) || Object.keys(program.guideConfigs.legendGroups ?? {}).length > 0
+  return Object.values(program.guideConfigs.legend??{}).some(config=>config.clipHeight!==undefined)||hasLegendLane(program) || Object.keys(program.guideConfigs.legendGroups ?? {}).length > 0
     ? program.rematerializeLegend() : program;
 }
 
@@ -59,7 +62,8 @@ export const rematerializeLegend = /* @__PURE__ */ action(
   { op: "rematerializeLegend", description: "Rematerialize every existing legend component." },
   withGuideLayoutValidation(function (args = {}) {
     noOptions(args, "rematerializeLegend");
-    let next = this;
+    const oldClipContext=this.context.deferLegendClip;
+    let next = resetLegendClipGraphics(this)._withContext({deferLegendClip:true});
     const categoricalKinds = ["series", "color", "stroke"].filter(
       kind => this.guideConfigs.legend?.[kind] !== undefined
     );
@@ -85,6 +89,7 @@ export const rematerializeLegend = /* @__PURE__ */ action(
         !sameValues(stored.domain, definition.domain) ||
         !sameValues(stored.scales, definition.scales) ||
         stored.field !== definition.field ||
+        !sameValues(stored.sizeAreas ?? [], definition.sizeAreas ?? []) ||
         stored.title !== definition.title;
       next = changed
         ? next._withLegendConfig(kind, {
@@ -93,6 +98,7 @@ export const rematerializeLegend = /* @__PURE__ */ action(
             channels: definition.channels,
             scales: definition.scales,
             field: definition.field,
+            ...(definition.combine === undefined ? {} : {combine: definition.combine, sizeAreas: definition.sizeAreas}),
             title: definition.title,
             domain: definition.domain
           })
@@ -152,6 +158,7 @@ export const rematerializeLegend = /* @__PURE__ */ action(
       ).some(highlight => highlight.target === config.target);
       if (hasHighlight) next = next.rematerializeLegendHighlights({ kind });
     }
+    if(next.guideConfigs.legend?.colorSize !== undefined) next=materializeColorSizeLegend(next,next.guideConfigs.legend.colorSize);
     for (const policy of legendResourcePolicies()) {
       if (
         policy.rematerializeOp !== undefined &&
@@ -167,6 +174,10 @@ export const rematerializeLegend = /* @__PURE__ */ action(
         next = next[policy.rematerializeOp]();
       }
     }
+    const clipAnchors = Object.fromEntries(categoricalKinds.filter(kind => next.guideConfigs.legend[kind].clipHeight !== undefined)
+      .map(kind => [kind, resolveLayout(next, resolveEffectiveLegendBlockConfig(next, kind, next.guideConfigs.legend[kind])).itemY]));
+    next=applyLegendClipGraphics(next,{force:true,anchors:clipAnchors});
+    next=restoreLegendClipContext(next,oldClipContext);
     if (hasHorizontalLegendLane(next)) {
       next = next.rematerializeHorizontalLegendLane();
     }
@@ -210,6 +221,7 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
     titleStyle: options.titleStyle,
     itemGap: options.itemGap,
     layout: options.layout,
+    ...(options.clipHeight === undefined ? {} : {clipHeight:options.clipHeight}),
     ...(options.overflow === undefined ? {} : { overflow: options.overflow }),
     border: options.border
   };
@@ -231,7 +243,18 @@ export const createCategoricalLegend = /* @__PURE__ */ action(
   })
 );
 
-function resolveRawLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers) {
+function resolveRawLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers, internalChannels) {
+  if (Object.hasOwn(args, "combine")) {
+    validateLegendCombine(args.combine);
+    if (args.combine === "color-size") {
+      const config=resolveColorSizeConfig(program,args);
+      const prepared=prepareLegendGroup(program,{...args,blockLayout:args.blockLayout??(["left","right"].includes(args.position??"right")?"column":"row")},config.target,{creation:true,nativeOffset:30});
+      return {steps:[{op:"createColorSizeLegend",args}],finish:"always",legendGroup:{target:config.target,config:prepared.program.guideConfigs.legendGroups[config.target]}};
+    }
+    if (args.combine === "size-shape") return resolveSizeShapeCreation(program, args, layers, resolveRawLegendCreationPlan, internalChannels);
+    const {combine: _combine, ...separate} = args;
+    return resolveRawLegendCreationPlan(program, separate, layers);
+  }
   validateOptionObject(args, undefined, "createLegend");
   const candidates = args.target === undefined ? layers : layers.filter(layer => layer.id === args.target);
   const channels = args.channels;
@@ -403,7 +426,7 @@ function resolveRawLegendCreationPlan(program, args = {}, layers = program.seman
   return { steps: [{ op: "createCategoricalLegend", args }], finish: "auto" };
 }
 
-export function resolveLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers) {
+export function resolveLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers, internalChannels) {
   validateLegendGroupOptions(args);
   const { blockLayout: _layout, at: _at, ...raw } = args;
   const groups = program.guideConfigs.legendGroups ?? {};
@@ -418,7 +441,7 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
   }
   if (raw.position === undefined && args.direction === "horizontal" &&
       (args.at !== undefined || Object.keys(groups).length > 0)) raw.position = "top";
-  const initial = resolveRawLegendCreationPlan(program, raw, layers);
+  const initial = resolveRawLegendCreationPlan(program, raw, layers, internalChannels);
   const inherited = Object.keys(program.guideConfigs.legendGroups ?? {}).length > 0;
   const corner = PLOT_LEGEND_POSITIONS.includes(args.position) &&
     (initial.steps.length > 1 || initial.steps[0]?.op !== "createCategoricalLegend" ||
@@ -434,7 +457,7 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
   if (prepared.options.position === undefined && raw.position !== undefined) {
     prepared.options.position = raw.position;
   }
-  return { ...resolveRawLegendCreationPlan(prepared.program, prepared.options, layers),
+  return { ...resolveRawLegendCreationPlan(prepared.program, prepared.options, layers, internalChannels),
     legendGroup: { target, config: prepared.program.guideConfigs.legendGroups[target] } };
 }
 
@@ -449,7 +472,7 @@ export function applyLegendCreationPlan(program, plan) {
     }
     // The plan already validated that a retained size block is compatible.
     if (!(plan.combined && step.op === "createSizeLegend" && existingSize !== undefined)) {
-      next = next[step.op](step.args);
+      next = step.op === "createColorSizeLegend" ? createColorSizeLegendFromConfig(next,resolveColorSizeConfig(next,step.args)) : next[step.op](step.args);
     }
   }
   return plan.finish === "always" ? next.rematerializeLegend()

package/src/actions/guides/legends/categorical/components.js

@@ -1,3 +1,4 @@
+import { materializeLegendBorder } from "../../../../materialization/legendBorder.js";
 import { editGraphicProperties } from "../../../primitives/graphicProperties.js";
 import { materializeLegendTitleLines } from "../../../../materialization/legendText.js";
 import { action } from "../../../../core/action.js";
@@ -122,19 +123,11 @@ export const rematerializeLegendBackground = /* @__PURE__ */ action(
       throw new Error("rematerializeLegendBackground requires border configuration.");
     }
     const id = graphic(config, "Background");
-    if (this.graphicSpec.objects[id]?.type !== "rect") {
+    if (!["rect", "path"].includes(this.graphicSpec.objects[id]?.type)) {
       throw new Error("rematerializeLegendBackground requires an existing background.");
     }
     const layout = resolveLayout(this, config).background;
-    return editGraphicProperties(this, id, {
-      x: layout.x,
-      y: layout.y,
-      width: layout.width,
-      height: layout.height,
-      fill: config.border.background,
-      stroke: config.border.color,
-      strokeWidth: config.border.lineWidth
-    });
+    return materializeLegendBorder(this, id, layout, config.border);
   }
 );
 

package/src/actions/guides/legends/categorical/index.js

@@ -1,3 +1,4 @@
+import{hasLegendClipGraphics}from"../../../../materialization/legendClip.js";
 import { action } from "../../../../core/action.js";
 import { editLegend } from "../edit.js";
 import { resolveStoredSelection } from
@@ -69,6 +70,7 @@ function createLegendHighlightAction() {
     },
     function (args = {}) {
       noOptions(args, "rematerializeLegendHighlights");
+      if(hasLegendClipGraphics(this))return this.rematerializeLegend();
       if (this.context.deferGuideLayoutValidation !== true &&
           Object.values(this.guideConfigs.legend ?? {}).some(config => ["left", "right"].includes(config.position))) {
         return this.rematerializeLegend();

package/src/actions/guides/legends/categorical/layout.js

@@ -1,3 +1,6 @@
+import{validateLegendClip,clippedSampleBounds}from"../../../../grammar/legendClip.js";
+import {categoricalLegendSymbolId as symbolGraphic}from"../../../../grammar/legendBlocks.js";
+export {symbolGraphic};
 import { findLayer } from "../../../../selectors/layers.js";
 import { isLinearGradientPaint } from "../../../../grammar/paint.js";
 import { intrinsicLegendConfig } from "../../../../materialization/legendGroups.js";
@@ -60,14 +63,6 @@ function prefix(config) {
   return `${config.kind}Legend`;
 }
 
-export function symbolGraphic(config, type) {
-  const onlyDefault = config.symbol.layers.length === 1 &&
-    ((config.kind === "series" && type === "line") ||
-      (["color", "stroke"].includes(config.kind) && type === "swatch"));
-  if (onlyDefault) return `${prefix(config)}Symbols`;
-  const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[type];
-  return `${prefix(config)}Symbol${suffix}`;
-}
 
 export function graphic(config, component) {
   return `${prefix(config)}${component}`;
@@ -76,7 +71,7 @@ export function graphic(config, component) {
 export function symbolWidth(config) {
   return Math.max(...config.symbol.layers.map(layer => {
     if (layer.type === "line") return layer.length;
-    if (layer.type === "point") return layer.size * 2;
+    if (layer.type === "point") return config.combine === "size-shape" ? 2 * Math.sqrt(Math.max(...config.sizeAreas) / Math.PI) : layer.size * 2;
     return layer.width;
   }));
 }
@@ -123,7 +118,7 @@ function resolveSampleBounds(program, config, width) {
       }
       if (config.channels.includes("shape")) {
         return createPointShapeGraphic({ shape: appearance.shapes[index], x: width / 2, y: 0,
-          area: Math.PI * layer.size ** 2, fill: layer.fill ?? appearance.colors[index],
+          area: appearance.areas?.[index] ?? Math.PI * layer.size ** 2, fill: layer.fill ?? appearance.colors[index],
           stroke: layer.stroke, strokeWidth: layer.strokeWidth, opacity: layer.opacity ?? appearance.opacity,
           ...requestedStrokeDetails(layer, "Legend point symbol") });
       }
@@ -134,7 +129,7 @@ function resolveSampleBounds(program, config, width) {
         strokeWidth: layer.strokeWidth, opacity: layer.opacity ?? appearance.opacity,
         ...requestedStrokeDetails(layer, "Legend point symbol") } };
     });
-    return items.map((item, itemIndex) => {
+    return clippedSampleBounds(items.map((item, itemIndex) => {
       const bounds = resolveConcreteGraphicBounds({
         objects: { sample: item },
         order: ["sample"]
@@ -153,11 +148,12 @@ function resolveSampleBounds(program, config, width) {
           right: Math.max(result.right, bounds.right),
           top: Math.min(result.top, bounds.top),
           bottom: Math.max(result.bottom, bounds.bottom)
-        }, undefined);
+        }, undefined),config.clipHeight);
   });
 }
 
 export function resolveLayout(program, config) {
+  validateLegendClip(config.kind,config);
   config = intrinsicLegendConfig(program, config);
   config = categoricalLegendView(config);
   const { plot, canvas } = resolveContinuousBounds(program,
@@ -192,7 +188,7 @@ export function resolveAppearance(program, config) {
     if (config.channels[index] === "strokeDash") dashes = values;
     if (config.channels[index] === "shape") shapes = values;
   }
-  return { colors, strokes, dashes, shapes,
+  return { colors, strokes, dashes, shapes, ...(config.combine === "size-shape" ? {areas: config.sizeAreas} : {}),
     ...(gradientFallback ? { opacity: program.markConfigs[target.id].opacity } : {}) };
 }
 

package/src/actions/guides/legends/categorical/options.js

@@ -1,3 +1,5 @@
+import{normalizeLegendClipHeight}from"../../../../grammar/legendClip.js";
+import { normalizeLegendBorderDash } from "../../../../grammar/legendBorder.js";
 import { LEGEND_TITLE_STYLE_KEYS, validateLegendTitleAlignment } from "../../../../grammar/legendTitleStyle.js";
 import { PLOT_LEGEND_POSITIONS, isPlotLegend } from "../../../../layout/legend.js";
 import { validateOptionObject } from "../../../../core/validation.js";
@@ -16,6 +18,7 @@ import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY, DEFAULT_VERTICAL_LEGEND_ITEM_GAP }
 
 export const CHANNELS = CATEGORICAL_LEGEND_CHANNELS;
 const OPTIONS = Object.freeze([
+  "clipHeight",
   "target",
   "channels",
   "order",
@@ -59,7 +62,8 @@ const BORDER_OPTIONS = Object.freeze([
   "color",
   "lineWidth",
   "padding",
-  "background"
+  "background",
+  "strokeDash"
 ]);
 const COMMON_DEFAULTS = Object.freeze({
   labels: Object.freeze({
@@ -95,7 +99,8 @@ function normalizeBorder(border) {
   nonEmptyString(normalized.background, "Legend border background");
   nonNegative(normalized.lineWidth, "Legend border lineWidth");
   nonNegative(normalized.padding, "Legend border padding");
-  return normalized;
+  const dash = normalizeLegendBorderDash(normalized.strokeDash);
+  return { ...normalized, ...(dash === undefined ? {} : { strokeDash: dash }) };
 }
 
 export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
@@ -192,6 +197,7 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
 
   const overflow = normalizeLegendOverflow(args.overflow);
   return {
+    ...(args.clipHeight===undefined?{}:{clipHeight:normalizeLegendClipHeight(args.clipHeight)}),
     ...(overflow === undefined ? {} : { overflow }),
     target: args.target,
     channels: args.channels,