ggaction 0.0.17 → 0.0.19

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

@@ -1,3 +1,11 @@
+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";
+import { normalizeInitialLegendTitle } from "../continuous/common.js";
+import { isContinuousColorScaleType } from "../../../../grammar/scales/types.js";
 import { withGuideLayoutValidation } from "../../../../materialization/guides/layout.js";
 import { sameGuideValue } from "../../reuse.js";
 import { normalizeLegendOrder } from "../../../../grammar/categoryOrder.js";
@@ -17,8 +25,7 @@ import { legendResourcePolicies } from
   "../../../../materialization/guides/resources.js";
 import {
   hasHorizontalLegendLane,
-  hasLegendLane,
-  hasMultiSideLegendLane
+  hasLegendLane
 } from "../lane.js";
 import {
   resolveCurrentDefinition,
@@ -33,7 +40,8 @@ import {
 } from "../blocks.js";
 
 function finishLegend(program) {
-  return hasLegendLane(program) ? program.rematerializeLegend() : program;
+  return Object.values(program.guideConfigs.legend??{}).some(config=>config.clipHeight!==undefined)||hasLegendLane(program) || Object.keys(program.guideConfigs.legendGroups ?? {}).length > 0
+    ? program.rematerializeLegend() : program;
 }
 
 function requestedCandidate(program, target, candidates) {
@@ -54,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
     );
@@ -80,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, {
@@ -88,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
           })
@@ -147,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 &&
@@ -162,9 +174,10 @@ export const rematerializeLegend = /* @__PURE__ */ action(
         next = next[policy.rematerializeOp]();
       }
     }
-    if (hasMultiSideLegendLane(next)) {
-      next = next.rematerializeSideLegendLane();
-    }
+    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();
     }
@@ -178,7 +191,7 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
     program,
     layer,
     args.channels,
-    args.title,
+    args.title === false ? undefined : args.title,
     args.order === undefined ? undefined : normalizeLegendOrder(args.order)
   );
   const inferredSymbol = args.symbol === undefined || args.symbol === "auto";
@@ -194,7 +207,8 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
   const config = {
     target: layer.id,
     ...definition,
-    inferredTitle: !Object.hasOwn(args, "title"),
+    ...normalizeInitialLegendTitle(args.title, definition.title),
+    inferredTitle: args.title === false || !Object.hasOwn(args, "title"),
     inferredSymbol,
     position: options.position,
     align: options.align,
@@ -207,8 +221,9 @@ export function resolveCategoricalLegendConfig(program, args = {}) {
     titleStyle: options.titleStyle,
     itemGap: options.itemGap,
     layout: options.layout,
-    border: options.border,
-    titleVisible: true
+    ...(options.clipHeight === undefined ? {} : {clipHeight:options.clipHeight}),
+    ...(options.overflow === undefined ? {} : { overflow: options.overflow }),
+    border: options.border
   };
   return config;
 }
@@ -228,7 +243,18 @@ export const createCategoricalLegend = /* @__PURE__ */ action(
   })
 );
 
-export function resolveLegendCreationPlan(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;
@@ -252,15 +278,23 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
     }
   }
   const continuousColorCandidates = candidates.filter(layer => {
-    const encoding = ["point", "bar", "rect"].includes(layer.mark?.type)
+    const encoding = ["point", "bar", "rect", "text"].includes(layer.mark?.type)
       ? layer.encoding?.color
       : undefined;
     const scale = findSemanticScale(program, encoding?.scale);
-    return scale?.type === "sequential";
+    return isContinuousColorScaleType(scale?.type);
   });
   const continuousColor = requestedCandidate(
     program, args.target, continuousColorCandidates
   );
+  if (args.representation !== undefined && channels !== undefined && channels.length > 1) {
+    if (!continuousColor || !channels.includes("color")) throw new Error("Legend representation requires selected continuous color.");
+    const { representation, values, count, symbol, gradient, ...common } = args;
+    const steps = channels.flatMap(channel => resolveRawLegendCreationPlan(program,
+      channel === "color" ? { ...args, channels: [channel] }
+        : { ...common, channels: [channel] }, layers).steps);
+    return { steps, finish: "always" };
+  }
   if (
     (channels?.length === 1 && channels[0] === "color" && continuousColor) ||
     (channels === undefined && continuousColor)
@@ -268,7 +302,7 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
     return { steps: [{ op: "createGradientLegend", args }], finish: "auto" };
   }
   const intervalColorCandidates = candidates.filter(layer => {
-    const encoding = ["point", "bar", "rect"].includes(layer.mark?.type) ? layer.encoding?.color : undefined;
+    const encoding = ["point", "bar", "rect", "text"].includes(layer.mark?.type) ? layer.encoding?.color : undefined;
     const scale = findSemanticScale(program, encoding?.scale);
     return ["quantize", "quantile", "threshold"].includes(scale?.type);
   });
@@ -281,7 +315,7 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
   }
   const continuousStrokeCandidates = candidates.filter(layer => {
     const scale = findSemanticScale(program, layer.encoding?.stroke?.scale);
-    return scale?.type === "sequential";
+    return isContinuousColorScaleType(scale?.type);
   });
   const continuousStroke = requestedCandidate(
     program,
@@ -365,6 +399,9 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
     if (combined) steps.push({ op: "createSizeLegend", args: {
       target: requestedPoint.id,
       ...(count === undefined ? {} : { count }),
+      ...(categoricalArgs.overflow !== undefined &&
+        findSemanticScale(program, requestedPoint.encoding.size.scale)?.type === "ordinal"
+        ? { overflow: categoricalArgs.overflow } : {}),
       ...(categoricalArgs.labels === undefined ? {} : { labels: {
         ...(categoricalArgs.labels.offset === undefined ? {} : { offset: categoricalArgs.labels.offset }),
         ...(sizeFormat === undefined ? {} : { format: sizeFormat })
@@ -389,14 +426,53 @@ export function resolveLegendCreationPlan(program, args = {}, layers = program.s
   return { steps: [{ op: "createCategoricalLegend", args }], finish: "auto" };
 }
 
+export function resolveLegendCreationPlan(program, args = {}, layers = program.semanticSpec.layers, internalChannels) {
+  validateLegendGroupOptions(args);
+  const { blockLayout: _layout, at: _at, ...raw } = args;
+  const groups = program.guideConfigs.legendGroups ?? {};
+  if (Object.keys(groups).length > 0 && raw.position === undefined) {
+    const target = creationLegendTarget(program, args);
+    const placement = groups[target]?.placement;
+    if (placement?.position !== undefined) {
+      raw.position = placement.position;
+      raw.align = args.align ?? placement.align;
+      raw.offset = args.offset ?? placement.offset;
+    }
+  }
+  if (raw.position === undefined && args.direction === "horizontal" &&
+      (args.at !== undefined || Object.keys(groups).length > 0)) raw.position = "top";
+  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" ||
+      Object.keys(program.guideConfigs.legend ?? {}).length > 0);
+  if (args.blockLayout === undefined && args.at === undefined && !inherited && !corner) return initial;
+  const target = creationLegendTarget(program, args);
+  const first = initial.steps[0];
+  const nativeOffset = program.guideConfigs.legendGroups?.[target] !== undefined ? 30 : first?.op === "createCategoricalLegend"
+    ? resolveCategoricalLegendConfig(program, first.args).offset
+    : first?.op === "createSizeLegend" ? resolveSizeLegendConfig(program, first.args).offset : 30;
+  const prepared = prepareLegendGroup(program, args, target, { creation: true, corner, nativeOffset });
+  if (!prepared.grouped) return initial;
+  if (prepared.options.position === undefined && raw.position !== undefined) {
+    prepared.options.position = raw.position;
+  }
+  return { ...resolveRawLegendCreationPlan(prepared.program, prepared.options, layers, internalChannels),
+    legendGroup: { target, config: prepared.program.guideConfigs.legendGroups[target] } };
+}
+
 export function applyLegendCreationPlan(program, plan) {
   if (plan.steps.length === 0) return program;
-  let next = program;
+  let next = plan.legendGroup === undefined ? program : program._withMaterializationConfig(
+    ["guides", "legendGroups", plan.legendGroup.target], plan.legendGroup.config);
   for (const step of plan.steps) {
     const existingSize = next.guideConfigs.legend?.size;
+    if (plan.combined && existingSize !== undefined && step.op === "createCategoricalLegend") {
+      next = next._withLegendConfig("size", { ...existingSize, inheritPosition: true });
+    }
     // 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()
@@ -406,7 +482,7 @@ export function applyLegendCreationPlan(program, plan) {
 export const createLegend = /* @__PURE__ */ action(
   { op: "createLegend", description: "Create an inferred legend for selected channels." },
   withGuideLayoutValidation(function (args = {}) {
-    return applyLegendCreationPlan(this, resolveLegendCreationPlan(this, args));
+    return recordLegendOffsetIntent(this, applyLegendCreationPlan(this, resolveLegendCreationPlan(this, args)), args, { creation: true });
   })
 );
 

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

@@ -1,4 +1,6 @@
+import { materializeLegendBorder } from "../../../../materialization/legendBorder.js";
 import { editGraphicProperties } from "../../../primitives/graphicProperties.js";
+import { materializeLegendTitleLines } from "../../../../materialization/legendText.js";
 import { action } from "../../../../core/action.js";
 import {
   activeConfig,
@@ -19,15 +21,17 @@ export const rematerializeLegendLabels = /* @__PURE__ */ action(
       throw new Error("rematerializeLegendLabels requires existing legend labels.");
     }
     const layout = resolveLayout(this, config);
+    const labels = categoricalLegendLabels(config);
+    const visible = labels.flatMap((text, index) => text === "" ? [] : [index]);
     return editGraphicProperties(editGraphicProperties(this, id, {
-      length: config.domain.length,
-      x: layout.labelX,
-      y: layout.itemY
+      length: visible.length,
+      x: visible.map(index => layout.labelX[index]),
+      y: visible.map(index => layout.itemY[index])
     })
       .editGraphics({
         target: id,
         property: "text",
-        value: categoricalLegendLabels(config)
+        value: visible.map(index => labels[index])
       }), id, {
       fill: config.labels.color,
       fontSize: config.labels.fontSize,
@@ -52,7 +56,7 @@ export const createLegendLabels = /* @__PURE__ */ action(
       .createGraphics({
         id,
         type: "text",
-        length: config.domain.length,
+        length: categoricalLegendLabels(config).length,
         ...resolveCategoricalLegendPlacement(this)
       })
       .rematerializeLegendLabels({ kind: config.kind });
@@ -69,7 +73,7 @@ export const rematerializeLegendTitle = /* @__PURE__ */ action(
       throw new Error("rematerializeLegendTitle requires an existing legend title.");
     }
     const layout = resolveLayout(this, config);
-    return editGraphicProperties(this, id, {
+    const next = editGraphicProperties(this, id, {
       x: layout.titleX,
       y: layout.titleY,
       text: config.title,
@@ -81,12 +85,13 @@ export const rematerializeLegendTitle = /* @__PURE__ */ action(
       .editGraphics({
         target: id,
         property: "textAlign",
-        value: ["top", "bottom"].includes(config.position) &&
+        value: config.titleStyle.align ?? (["top", "bottom"].includes(config.position) &&
           config.titlePosition === "top"
           ? "center"
-          : "left"
+          : "left")
       })
       .editGraphics({ target: id, property: "textBaseline", value: "middle" });
+    return materializeLegendTitleLines(next, id, config.title, config.titleStyle);
   }
 );
 
@@ -118,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
@@ -29,6 +30,7 @@ import {
 } from "./symbols.js";
 import { activeConfig, noOptions, symbolGraphic } from "./layout.js";
 import {
+  rematerializeLegendGroups,
   rematerializeHorizontalLegendLane,
   rematerializeSideLegendLane
 } from "../lane.js";
@@ -68,6 +70,11 @@ 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();
+      }
       const kinds = args.kind === undefined
         ? ["series", "color", "stroke"].filter(
             kind => this.guideConfigs.legend?.[kind] !== undefined
@@ -134,6 +141,7 @@ export function registerBasicCategoricalLegendActions(ProgramClass) {
   ProgramClass.prototype.createLegendTitle = createLegendTitle;
   ProgramClass.prototype.rematerializeLegendTitle = rematerializeLegendTitle;
   ProgramClass.prototype.rematerializeLegend = rematerializeLegend;
+  ProgramClass.prototype.rematerializeLegendGroups = rematerializeLegendGroups;
   ProgramClass.prototype.rematerializeSideLegendLane =
     rematerializeSideLegendLane;
   ProgramClass.prototype.rematerializeHorizontalLegendLane =

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

@@ -1,3 +1,9 @@
+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";
 import { validateOptionObject } from "../../../../core/validation.js";
 import { mapOrdinalValues } from "../../../../grammar/scales/index.js";
 import { DEFAULT_COLORS } from "../../../../theme/defaults.js";
@@ -57,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}`;
@@ -73,17 +71,25 @@ 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;
   }));
 }
 
+export function categoricalLegendView(config) {
+  if (config.hiddenCount !== undefined || !config.overflow || config.domain.length <= config.overflow.maxItems) return config;
+  return { ...config, domain: config.domain.slice(0, config.overflow.maxItems),
+    hiddenCount: config.domain.length - config.overflow.maxItems };
+}
+
 export function categoricalLegendLabels(config) {
-  return config.domain.map(value => resolveDisplayLabel(
+  config = categoricalLegendView(config);
+  const labels = config.domain.map(value => resolveDisplayLabel(
     value,
     config.labelMap,
     formatVisibleText
   ));
+  return config.hiddenCount > 0 ? [...labels, `…${config.hiddenCount} entries`] : labels;
 }
 
 function resolveSampleBounds(program, config, width) {
@@ -96,7 +102,7 @@ function resolveSampleBounds(program, config, width) {
           stroke: layer.stroke ?? (config.channels.includes("stroke")
             ? appearance.strokes[index]
             : appearance.colors[index]),
-          strokeWidth: layer.lineWidth, opacity: layer.opacity,
+          strokeWidth: layer.lineWidth, opacity: layer.opacity ?? appearance.opacity,
           ...requestedStrokeDetails(layer, "Legend line symbol") } };
       }
       if (layer.type === "swatch") {
@@ -106,24 +112,24 @@ function resolveSampleBounds(program, config, width) {
           stroke: config.channels.includes("stroke")
             ? appearance.strokes[index]
             : layer.stroke,
-          opacity: layer.opacity,
+          opacity: layer.opacity ?? appearance.opacity,
           ...requestedStrokeDetails(details, "Legend swatch symbol")
-        }, details.cornerRadius ?? 0);
+        }, details);
       }
       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],
-          stroke: layer.stroke, strokeWidth: layer.strokeWidth, opacity: layer.opacity,
+          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") });
       }
       return { type: "circle", properties: { x: width / 2, y: 0, radius: layer.size,
         stroke: config.channels.includes("stroke")
           ? appearance.strokes[index]
           : layer.stroke,
-        strokeWidth: layer.strokeWidth, opacity: layer.opacity,
+        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"]
@@ -142,11 +148,14 @@ 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,
     "Legend layout requires Canvas bounds, width, and height.");
   const width = symbolWidth(config);
@@ -160,7 +169,14 @@ export function resolveLayout(program, config) {
 }
 
 export function resolveAppearance(program, config) {
-  let colors = config.domain.map(() => DEFAULT_COLORS.mark);
+  const target = findLayer(program, config.target);
+  const gradientFallback = target?.mark?.type === "area" &&
+    target.encoding.color === undefined &&
+    !config.channels.includes("color") &&
+    isLinearGradientPaint(program.markConfigs[target.id]?.fill);
+  const fallback = gradientFallback
+    ? program.markConfigs[target.id].fill : DEFAULT_COLORS.mark;
+  let colors = config.domain.map(() => fallback);
   let strokes = config.domain.map(() => "white");
   let dashes = config.domain.map(() => []);
   let shapes = config.domain.map(() => "circle");
@@ -172,7 +188,8 @@ 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 } : {}) };
 }
 
 export function noOptions(args, operation) {
@@ -189,3 +206,11 @@ export function layerFor(config, type) {
   }
   return layer;
 }
+
+
+export function resolveSymbolLayout(program, config) {
+  const view = categoricalLegendView(config);
+  const layout = resolveLayout(program, view);
+  return { ...layout, symbolX: layout.symbolX.slice(0, view.domain.length),
+    itemY: layout.itemY.slice(0, view.domain.length) };
+}

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

@@ -1,3 +1,7 @@
+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";
 import { CATEGORICAL_LEGEND_CHANNELS } from "../../../../core/vocabulary.js";
 import { normalizeRecipe } from "./recipes.js";
@@ -9,11 +13,12 @@ import {
   validateKeys,
   validateObject
 } from "./validation.js";
-import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY, DEFAULT_VERTICAL_LEGEND_ITEM_GAP } from
   "../../../../theme/defaults.js";
 
 export const CHANNELS = CATEGORICAL_LEGEND_CHANNELS;
 const OPTIONS = Object.freeze([
+  "clipHeight",
   "target",
   "channels",
   "order",
@@ -29,7 +34,8 @@ const OPTIONS = Object.freeze([
   "labels",
   "titleStyle",
   "itemGap",
-  "border"
+  "border",
+  "overflow"
 ]);
 const TEXT_OPTIONS = Object.freeze([
   "offset",
@@ -39,17 +45,25 @@ const TEXT_OPTIONS = Object.freeze([
   "fontWeight",
   "format"
 ]);
-const TITLE_OPTIONS = Object.freeze([
-  "color",
-  "fontSize",
-  "fontFamily",
-  "fontWeight"
-]);
+
+export function normalizeLegendOverflow(value) {
+  if (value === undefined || value === false) return value;
+  validateObject(value, ["maxItems", "summary"], "Legend overflow");
+  if (!Number.isInteger(value.maxItems) || value.maxItems < 1) {
+    throw new RangeError("Legend overflow.maxItems must be a positive integer.");
+  }
+  if (value.summary !== undefined && value.summary !== "ellipsis-count") {
+    throw new Error("Legend overflow.summary must be ellipsis-count.");
+  }
+  return { maxItems: value.maxItems, summary: "ellipsis-count" };
+}
+
 const BORDER_OPTIONS = Object.freeze([
   "color",
   "lineWidth",
   "padding",
-  "background"
+  "background",
+  "strokeDash"
 ]);
 const COMMON_DEFAULTS = Object.freeze({
   labels: Object.freeze({
@@ -85,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 } = {}) {
@@ -99,7 +114,7 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
   if (Object.hasOwn(args, "titleStyle")) {
     validateObject(
       args.titleStyle,
-      TITLE_OPTIONS,
+      LEGEND_TITLE_STYLE_KEYS,
       "createLegend.titleStyle"
     );
   }
@@ -121,13 +136,15 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
   };
   const position = args.position ?? defaults.position;
   const align = args.align ?? defaults.align;
+  const inside = isPlotLegend({ position });
   const side = ["left", "right"].includes(position);
-  const direction = args.direction ?? (side ? "vertical" : "horizontal");
+  const direction = args.direction ?? (side || inside ? "vertical" : "horizontal");
   const columns = args.columns;
   const offset = args.offset ?? 8;
   const titlePosition = args.titlePosition ?? "top";
-  const itemGap = args.itemGap ?? (["right", "left"].includes(position)
-    ? 28
+  validateLegendTitleAlignment(titleStyle, titlePosition);
+  const itemGap = args.itemGap ?? (direction === "vertical"
+    ? DEFAULT_VERTICAL_LEGEND_ITEM_GAP
     : position === "top" ? 24 : 20);
   const layout = args.layout === undefined ? "edge" : args.layout;
   if (!["edge", "legacy-bottom"].includes(layout)) {
@@ -142,14 +159,14 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
     throw new Error('Legend columns, vertical direction, left title and custom offset require layout "edge".');
   }
 
-  if (!["right", "left", "bottom", "top"].includes(position)) {
+  if (!["right", "left", "bottom", "top", ...PLOT_LEGEND_POSITIONS].includes(position)) {
     throw new Error(`Unsupported legend position "${position}".`);
   }
   if (!["left", "center", "right"].includes(align)) {
     throw new Error(`Unsupported legend alignment "${align}".`);
   }
-  if (["right", "left"].includes(position) && align !== "center") {
-    throw new Error("Side legends currently require center alignment.");
+  if ((side || inside) && align !== "center") {
+    throw new Error(inside ? "In-plot legends require center alignment." : "Side legends currently require center alignment.");
   }
   if (!["horizontal", "vertical"].includes(direction)) {
     throw new Error(`Unsupported legend direction "${direction}".`);
@@ -157,11 +174,8 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
   if (side && direction !== "vertical") {
     throw new Error("Side legends require vertical direction.");
   }
-  if (side && columns !== undefined && columns !== 1) {
-    throw new Error("Side legends require one column.");
-  }
-  if (side && titlePosition !== "top") {
-    throw new Error("Side legends require a top title.");
+  if ((side || inside) && titlePosition !== "top") {
+    throw new Error(inside ? "In-plot legends require a top title." : "Side legends require a top title.");
   }
   if (columns !== undefined && (!Number.isInteger(columns) || columns <= 0)) {
     throw new RangeError("Legend columns must be a positive integer.");
@@ -181,7 +195,10 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
   validateFontWeight(titleStyle.fontWeight, "Legend title fontWeight");
   positive(itemGap, "Legend itemGap");
 
+  const overflow = normalizeLegendOverflow(args.overflow);
   return {
+    ...(args.clipHeight===undefined?{}:{clipHeight:normalizeLegendClipHeight(args.clipHeight)}),
+    ...(overflow === undefined ? {} : { overflow }),
     target: args.target,
     channels: args.channels,
     position,