ggaction 0.0.21 → 0.0.22

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

@@ -1,515 +1 @@
-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";
-import { action } from "../../../../core/action.js";
-import { validateOptionObject } from "../../../../core/validation.js";
-import { noOptions, resolveLayout, activeConfig } from "./layout.js";
-import { normalizeOptions } from "./options.js";
-import { normalizeRecipe, resolveLegendSymbol } from "./recipes.js";
-import { validateLegendChannels } from "../target.js";
-import { createCategoricalLegendFromConfig, reconcileCategoricalSymbols } from "../lifecycle.js";
-import { findLayer } from "../../../../selectors/layers.js";
-import { findSemanticScale } from "../../../../selectors/scales.js";
-import { isSizeLegendPoint, resolveSizeLegendConfig } from "../size.js";
-import { isStrokeWidthLegendLayer } from "../strokeWidth.js";
-import { isOpacityLegendLayer } from "../../../../materialization/legends.js";
-import { legendResourcePolicies } from
-  "../../../../materialization/guides/resources.js";
-import {
-  hasHorizontalLegendLane,
-  hasLegendLane
-} from "../lane.js";
-import {
-  resolveCurrentDefinition,
-  resolveDefinition,
-  resolveTarget,
-  sameValues
-} from "./resolve.js";
-import { readLegendSampling } from "../sampling.js";
-import {
-  reconcileLegendBlockTitleGraphic,
-  resolveEffectiveLegendBlockConfig
-} from "../blocks.js";
-
-function finishLegend(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) {
-  if (target === undefined) {
-    return candidates.length === 1 ? candidates[0] : undefined;
-  }
-  const layer = findLayer(program, target);
-  return candidates.includes(layer) ? layer : undefined;
-}
-
-function resolveStandaloneLegendStep(args, kind) {
-  if (Object.hasOwn(args, "inheritAppearance")) throw new Error("createLegend does not accept inheritAppearance.");
-  const { channels: _channels, ...options } = args;
-  return { op: kind === "size" ? "createSizeLegend" : "createStrokeWidthLegend", args: options };
-}
-
-export const rematerializeLegend = /* @__PURE__ */ action(
-  { op: "rematerializeLegend", description: "Rematerialize every existing legend component." },
-  withGuideLayoutValidation(function (args = {}) {
-    noOptions(args, "rematerializeLegend");
-    const oldClipContext=this.context.deferLegendClip;
-    let next = resetLegendClipGraphics(this)._withContext({deferLegendClip:true});
-    const categoricalKinds = ["series", "color", "stroke"].filter(
-      kind => this.guideConfigs.legend?.[kind] !== undefined
-    );
-    for (const kind of categoricalKinds) {
-      const stored = next.guideConfigs.legend[kind];
-      const definition = resolveCurrentDefinition(next, stored);
-      const symbol = stored.inferredSymbol
-        ? normalizeRecipe(
-            resolveLegendSymbol(
-              next,
-              findLayer(next, stored.target),
-              definition.channels,
-              undefined,
-              kind
-            ),
-            kind,
-            { internal: true }
-          )
-        : stored.symbol;
-      const symbolChanged = !sameGuideValue(symbol, stored.symbol);
-      const changed = symbolChanged ||
-        !sameValues(stored.channels, definition.channels) ||
-        !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, {
-            ...stored,
-            symbol,
-            channels: definition.channels,
-            scales: definition.scales,
-            field: definition.field,
-            ...(definition.combine === undefined ? {} : {combine: definition.combine, sizeAreas: definition.sizeAreas}),
-            title: definition.title,
-            domain: definition.domain
-          })
-        : next;
-      const config = resolveEffectiveLegendBlockConfig(
-        next,
-        kind,
-        next.guideConfigs.legend[kind]
-      );
-      next = reconcileLegendBlockTitleGraphic(next, kind,
-        config.titleVisible !== false);
-      if (kind === "series") {
-        if (!sameValues(
-          next.semanticSpec.guides.legend.series.scales,
-          definition.scales
-        )) {
-          next = next.editSemantic({
-            property: "guide.legend.series.scales",
-            value: definition.scales
-          });
-        }
-        if (next.semanticSpec.guides.legend.series.title !== definition.title) {
-          next = next.editSemantic({
-            property: "guide.legend.series.title",
-            value: definition.title
-          });
-        }
-      } else {
-        if (next.semanticSpec.guides.legend[kind].scale !== definition.scales[0]) {
-          next = next.editSemantic({
-            property: `guide.legend.${kind}.scale`,
-            value: definition.scales[0]
-          });
-        }
-        if (next.semanticSpec.guides.legend[kind].title !== definition.title) {
-          next = next.editSemantic({
-            property: `guide.legend.${kind}.title`,
-            value: definition.title
-          });
-        }
-      }
-      if (symbolChanged) {
-        resolveLayout(next, config);
-        next = reconcileCategoricalSymbols(next, stored, config);
-      }
-      if (config.border !== false) {
-        next = next.rematerializeLegendBackground({ kind });
-      }
-      next = next
-        .rematerializeLegendSymbols({ kind })
-        .rematerializeLegendLabels({ kind });
-      if (config.titleVisible !== false) {
-        next = next.rematerializeLegendTitle({ kind });
-      }
-      const hasHighlight = Object.values(
-        next.materializationConfigs.highlights ?? {}
-      ).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 &&
-        this.guideConfigs.legend?.[policy.kind] !== undefined
-      ) {
-        const config = resolveEffectiveLegendBlockConfig(
-          next,
-          policy.kind,
-          next.guideConfigs.legend[policy.kind]
-        );
-        next = reconcileLegendBlockTitleGraphic(next, policy.kind,
-          config.titleVisible !== false);
-        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();
-    }
-    return next;
-  })
-);
-
-export function resolveCategoricalLegendConfig(program, args = {}) {
-  const layer = resolveTarget(program, args.target);
-  const definition = resolveDefinition(
-    program,
-    layer,
-    args.channels,
-    args.title === false ? undefined : args.title,
-    args.order === undefined ? undefined : normalizeLegendOrder(args.order)
-  );
-  const inferredSymbol = args.symbol === undefined || args.symbol === "auto";
-  const options = normalizeOptions({ ...args,
-    symbol: resolveLegendSymbol(
-      program,
-      layer,
-      definition.channels,
-      args.symbol,
-      definition.kind
-    )
-  }, definition.kind, { internalSymbol: inferredSymbol });
-  const config = {
-    target: layer.id,
-    ...definition,
-    ...normalizeInitialLegendTitle(args.title, definition.title),
-    inferredTitle: args.title === false || !Object.hasOwn(args, "title"),
-    inferredSymbol,
-    position: options.position,
-    align: options.align,
-    direction: options.direction,
-    columns: options.columns,
-    offset: options.offset,
-    titlePosition: options.titlePosition,
-    symbol: options.symbol,
-    labels: options.labels,
-    titleStyle: options.titleStyle,
-    itemGap: options.itemGap,
-    layout: options.layout,
-    ...(options.clipHeight === undefined ? {} : {clipHeight:options.clipHeight}),
-    ...(options.overflow === undefined ? {} : { overflow: options.overflow }),
-    border: options.border
-  };
-  return config;
-}
-
-export const createCategoricalLegend = /* @__PURE__ */ action(
-  { op: "createCategoricalLegend", description: "Create one categorical legend block." },
-  withGuideLayoutValidation(function (args = {}) {
-    const config = resolveCategoricalLegendConfig(this, args);
-    if (this.semanticSpec.guides.legend?.[config.kind] !== undefined) {
-      throw new Error(
-        `createCategoricalLegend requires a missing legend for ${config.kind}.`
-      );
-    }
-    resolveLayout(this, config);
-    return createCategoricalLegendFromConfig(this, config,
-      args.order === undefined ? undefined : normalizeLegendOrder(args.order));
-  })
-);
-
-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;
-  if (channels !== undefined) validateLegendChannels(channels, "createLegend");
-  const standalone = [
-    ["size", isSizeLegendPoint, ["color", "stroke", "shape", "strokeDash", "opacity"]],
-    ["strokeWidth", isStrokeWidthLegendLayer, args.target === undefined
-      ? ["color", "stroke", "shape", "strokeDash", "size", "opacity"]
-      : ["color", "stroke", "shape", "strokeDash", "opacity"]],
-    ["opacity", isOpacityLegendLayer,
-      ["color", "stroke", "shape", "strokeDash", "size"]]
-  ];
-  for (const [kind, eligible, otherChannels] of standalone) {
-    const explicit = channels?.length === 1 && channels[0] === kind;
-    const inferred = channels === undefined && candidates.filter(eligible).length === 1 &&
-      !candidates.some(layer => otherChannels.some(channel => layer.encoding?.[channel]?.scale !== undefined));
-    if (explicit || inferred) {
-      const step = kind === "opacity" ? { op: "createOpacityLegend", args }
-        : resolveStandaloneLegendStep(args, kind);
-      return { steps: [step], finish: "auto" };
-    }
-  }
-  const continuousColorCandidates = candidates.filter(layer => {
-    const encoding = ["point", "bar", "rect", "text", "area"].includes(layer.mark?.type)
-      ? layer.encoding?.color
-      : undefined;
-    const scale = findSemanticScale(program, encoding?.scale);
-    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)
-  ) {
-    return { steps: [{ op: "createGradientLegend", args }], finish: "auto" };
-  }
-  const intervalColorCandidates = candidates.filter(layer => {
-    const encoding = ["point", "bar", "rect", "text", "area"].includes(layer.mark?.type) ? layer.encoding?.color : undefined;
-    const scale = findSemanticScale(program, encoding?.scale);
-    return ["quantize", "quantile", "threshold"].includes(scale?.type);
-  });
-  if (
-    (channels?.length === 1 && channels[0] === "color" &&
-      intervalColorCandidates.length > 0) ||
-    (channels === undefined && intervalColorCandidates.length > 0)
-  ) {
-    return { steps: [{ op: "createIntervalLegend", args }], finish: "auto" };
-  }
-  const continuousStrokeCandidates = candidates.filter(layer => {
-    const scale = findSemanticScale(program, layer.encoding?.stroke?.scale);
-    return isContinuousColorScaleType(scale?.type);
-  });
-  const continuousStroke = requestedCandidate(
-    program,
-    args.target,
-    continuousStrokeCandidates
-  );
-  if (
-    (channels?.length === 1 && channels[0] === "stroke" && continuousStroke) ||
-    (channels === undefined && continuousStroke &&
-      !["color", "shape", "strokeDash", "size", "opacity", "strokeWidth"].some(
-        channel => continuousStroke.encoding?.[channel]?.scale !== undefined
-      ))
-  ) {
-    return {
-      steps: [{ op: "createStrokeGradientLegend", args: {
-        ...args,
-        channels: ["stroke"]
-      } }],
-      finish: "auto"
-    };
-  }
-  const intervalStrokeCandidates = candidates.filter(layer => {
-    const scale = findSemanticScale(program, layer.encoding?.stroke?.scale);
-    return ["quantize", "quantile", "threshold"].includes(scale?.type);
-  });
-  if (
-    (channels?.length === 1 && channels[0] === "stroke" &&
-      intervalStrokeCandidates.length > 0) ||
-    (channels === undefined && intervalStrokeCandidates.length === 1)
-  ) {
-    return {
-      steps: [{ op: "createStrokeIntervalLegend", args: {
-        ...args,
-        channels: ["stroke"]
-      } }],
-      finish: "auto"
-    };
-  }
-  const wantsShape = channels?.includes("shape") === true;
-  const wantsSize = channels?.includes("size") === true;
-  const pointCandidates = candidates.filter(layer =>
-    layer.mark?.type === "point" &&
-    (channels === undefined
-      ? ["color", "shape"].some(channel => layer.encoding?.[channel]?.scale !== undefined)
-      : (wantsShape || wantsSize) && channels.every(channel =>
-        ["color", "stroke", "shape", "size"].includes(channel) && layer.encoding?.[channel]?.scale !== undefined))
-  );
-  const requestedPoint = requestedCandidate(program, args.target, pointCandidates);
-  const inferredSize = channels === undefined && pointCandidates.some(isSizeLegendPoint);
-  if ((wantsSize || inferredSize) && requestedPoint === undefined) {
-    throw new Error("Combined size legend requires one eligible point mark or an explicit target.");
-  }
-  if (requestedPoint !== undefined) {
-    if (Object.hasOwn(args, "values")) {
-      throw new Error(
-        "Combined and categorical legends require a channel block selector for exact values."
-      );
-    }
-    const { count, ...categoricalArgs } = args;
-    const combined = requestedPoint.encoding?.size?.scale !== undefined &&
-      (channels === undefined || wantsSize);
-    if (count !== undefined && !combined) {
-      throw new Error("Legend count requires a selected size legend.");
-    }
-    if (combined && categoricalArgs.layout === "legacy-bottom") {
-      throw new Error('Combined size legends require layout "edge".');
-    }
-    const inferredChannels = ["color", "stroke", "shape"].filter(
-      channel => requestedPoint.encoding?.[channel]?.scale !== undefined
-    );
-    const { format: sizeFormat, ...categoricalLabels } = categoricalArgs.labels ?? {};
-    if (!combined && sizeFormat !== undefined && sizeFormat !== "auto") {
-      throw new Error("Categorical legend labels do not accept format.");
-    }
-    const steps = [{ op: "createCategoricalLegend", args: {
-      ...categoricalArgs,
-      ...(categoricalArgs.labels === undefined ? {} : { labels: categoricalLabels }),
-      target: requestedPoint.id,
-      channels: channels?.filter(channel => channel !== "size") ?? inferredChannels
-    } }];
-    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 })
-      } }),
-      inheritAppearance: true
-    } });
-    // Validate both content owners before any component action starts.
-    resolveCategoricalLegendConfig(program, steps[0].args);
-    if (combined) {
-      const size = resolveSizeLegendConfig(program, steps[1].args);
-      const existing = program.guideConfigs.legend?.size;
-      if (existing !== undefined && existing.target !== size.target) {
-        throw new Error("Combined point series legend requires the active size legend to share its target.");
-      }
-      if (existing !== undefined && count !== undefined &&
-        readLegendSampling(existing).count !== count) {
-        throw new Error("Existing size legend count must be edited before recreating the categorical block.");
-      }
-    }
-    return { steps, combined, finish: combined ? "always" : "auto" };
-  }
-  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 = 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 = step.op === "createColorSizeLegend" ? createColorSizeLegendFromConfig(next,resolveColorSizeConfig(next,step.args)) : next[step.op](step.args);
-    }
-  }
-  return plan.finish === "always" ? next.rematerializeLegend()
-    : plan.finish === "auto" ? finishLegend(next) : next;
-}
-
-export const createLegend = /* @__PURE__ */ action(
-  { op: "createLegend", description: "Create an inferred legend for selected channels." },
-  withGuideLayoutValidation(function (args = {}) {
-    return recordLegendOffsetIntent(this, applyLegendCreationPlan(this, resolveLegendCreationPlan(this, args)), args, { creation: true });
-  })
-);
-
-export const removeCategoricalLegend = /* @__PURE__ */ action(
-  {
-    op: "removeCategoricalLegend",
-    description: "Remove the active categorical legend and its concrete components."
-  },
-  withGuideLayoutValidation(function (args = {}) {
-    noOptions(args, "removeCategoricalLegend");
-    const entries = ["series", "color", "stroke"]
-      .filter(kind => this.guideConfigs.legend?.[kind] !== undefined);
-    if (entries.length === 0) return this;
-    if (entries.length !== 1) {
-      throw new Error("removeCategoricalLegend requires one active categorical legend.");
-    }
-    const kind = entries[0];
-    const prefix = `${kind}Legend`;
-    const targets = Object.keys(this.graphicSpec.objects)
-      .filter(id => id.startsWith(prefix));
-    let next = this.editSemantic({
-      property: `guide.legend.${kind}`,
-      remove: true
-    });
-    for (const target of targets) {
-      next = next.editGraphics({ target, remove: true });
-    }
-    return next._withoutMaterializationConfig(["guides", "legend", kind]);
-  })
-);
+import{resolveColorSizeConfig as B,createColorSizeLegendFromConfig as se,materializeColorSizeLegend as de}from"../colorSize.js";import{resetLegendClipGraphics as re,applyLegendClipGraphics as le,restoreLegendClipContext as ce}from"../../../../materialization/legendClip.js";import{validateLegendCombine as ae,resolveSizeShapeCreation as fe}from"../combine.js";import{recordLegendOffsetIntent as ue}from"../group.js";import{prepareLegendGroup as F,creationLegendTarget as N,validateLegendGroupOptions as ge}from"../group.js";import{PLOT_LEGEND_POSITIONS as pe}from"../../../../layout/legend.js";import{normalizeInitialLegendTitle as he}from"../continuous/common.js";import{isContinuousColorScaleType as K}from"../../../../grammar/scales/types.js";import{withGuideLayoutValidation as M}from"../../../../materialization/guides/layout.js";import{sameGuideValue as Y}from"../../reuse.js";import{normalizeLegendOrder as J}from"../../../../grammar/categoryOrder.js";import{action as W}from"../../../../core/action.js";import{validateOptionObject as me}from"../../../../core/validation.js";import{noOptions as Q,resolveLayout as A}from"./layout.js";import{normalizeOptions as Le}from"./options.js";import{normalizeRecipe as Ce,resolveLegendSymbol as U}from"./recipes.js";import{validateLegendChannels as be}from"../target.js";import{createCategoricalLegendFromConfig as ze,reconcileCategoricalSymbols as ye}from"../lifecycle.js";import{findLayer as X}from"../../../../selectors/layers.js";import{findSemanticScale as G}from"../../../../selectors/scales.js";import{isSizeLegendPoint as D,resolveSizeLegendConfig as Z}from"../size.js";import{isStrokeWidthLegendLayer as ke}from"../strokeWidth.js";import{isOpacityLegendLayer as ee}from"../../../../materialization/legends.js";import{legendResourcePolicies as Se}from"../../../../materialization/guides/resources.js";import{hasHorizontalLegendLane as ve,hasLegendLane as we}from"../lane.js";import{resolveCurrentDefinition as Oe,resolveDefinition as xe,resolveTarget as Ge,sameValues as j}from"./resolve.js";import{readLegendSampling as Pe}from"../sampling.js";import{reconcileLegendBlockTitleGraphic as ne,resolveEffectiveLegendBlockConfig as T}from"../blocks.js";function Ee(i){return Object.values(i.guideConfigs.legend??{}).some(e=>e.clipHeight!==void 0)||we(i)||Object.keys(i.guideConfigs.legendGroups??{}).length>0?i.rematerializeLegend():i}function $(i,e,n){if(e===void 0)return n.length===1?n[0]:void 0;const a=X(i,e);return n.includes(a)?a:void 0}function ie(i,e){if(Object.hasOwn(i,"inheritAppearance"))throw new Error("createLegend does not accept inheritAppearance.");const{channels:n,...a}=i;return{op:e==="size"?"createSizeLegend":"createStrokeWidthLegend",args:a}}const fn=W({op:"rematerializeLegend",description:"Rematerialize every existing legend component."},M(function(i={}){Q(i,"rematerializeLegend");const e=this.context.deferLegendClip;let n=re(this)._withContext({deferLegendClip:!0});const a=["series","color","stroke"].filter(t=>this.guideConfigs.legend?.[t]!==void 0);for(const t of a){const d=n.guideConfigs.legend[t],{defaultLabelMap:s,...L}=d,l=Oe(n,d),S=d.inferredSymbol?Ce(U(n,X(n,d.target),l.channels,void 0,t),t,{internal:!0}):d.symbol,b=!Y(S,d.symbol);n=b||!Y(s,l.defaultLabelMap)||!j(d.channels,l.channels)||!j(d.domain,l.domain)||!j(d.scales,l.scales)||d.field!==l.field||!j(d.sizeAreas??[],l.sizeAreas??[])||d.title!==l.title?n._withLegendConfig(t,{...L,symbol:S,channels:l.channels,scales:l.scales,field:l.field,...l.defaultLabelMap===void 0?{}:{defaultLabelMap:l.defaultLabelMap},...l.combine===void 0?{}:{combine:l.combine,sizeAreas:l.sizeAreas},title:l.title,domain:l.domain}):n;const g=T(n,t,n.guideConfigs.legend[t]);n=ne(n,t,g.titleVisible!==!1),t==="series"?(j(n.semanticSpec.guides.legend.series.scales,l.scales)||(n=n.editSemantic({property:"guide.legend.series.scales",value:l.scales})),n.semanticSpec.guides.legend.series.title!==l.title&&(n=n.editSemantic({property:"guide.legend.series.title",value:l.title}))):(n.semanticSpec.guides.legend[t].scale!==l.scales[0]&&(n=n.editSemantic({property:`guide.legend.${t}.scale`,value:l.scales[0]})),n.semanticSpec.guides.legend[t].title!==l.title&&(n=n.editSemantic({property:`guide.legend.${t}.title`,value:l.title}))),b&&(A(n,g),n=ye(n,d,g)),g.border!==!1&&(n=n.rematerializeLegendBackground({kind:t})),n=n.rematerializeLegendSymbols({kind:t}).rematerializeLegendLabels({kind:t}),g.titleVisible!==!1&&(n=n.rematerializeLegendTitle({kind:t})),Object.values(n.materializationConfigs.highlights??{}).some(E=>E.target===g.target)&&(n=n.rematerializeLegendHighlights({kind:t}))}n.guideConfigs.legend?.colorSize!==void 0&&(n=de(n,n.guideConfigs.legend.colorSize));for(const t of Se())if(t.rematerializeOp!==void 0&&this.guideConfigs.legend?.[t.kind]!==void 0){const d=T(n,t.kind,n.guideConfigs.legend[t.kind]);n=ne(n,t.kind,d.titleVisible!==!1),n=n[t.rematerializeOp]()}const r=Object.fromEntries(a.filter(t=>n.guideConfigs.legend[t].clipHeight!==void 0).map(t=>[t,A(n,T(n,t,n.guideConfigs.legend[t])).itemY]));return n=le(n,{force:!0,anchors:r}),n=ce(n,e),ve(n)&&(n=n.rematerializeHorizontalLegendLane()),n}));function I(i,e={}){const n=Ge(i,e.target),a=xe(i,n,e.channels,e.title===!1?void 0:e.title,e.order===void 0?void 0:J(e.order)),r=e.symbol===void 0||e.symbol==="auto",t=Le({...e,symbol:U(i,n,a.channels,e.symbol,a.kind)},a.kind,{internalSymbol:r});return{target:n.id,...a,...he(e.title,a.title),inferredTitle:e.title===!1||!Object.hasOwn(e,"title"),inferredSymbol:r,position:t.position,align:t.align,direction:t.direction,columns:t.columns,offset:t.offset,titlePosition:t.titlePosition,symbol:t.symbol,labels:t.labels,titleStyle:t.titleStyle,itemGap:t.itemGap,...t.rowPadding===void 0?{}:{rowPadding:t.rowPadding},...t.titlePadding===void 0?{}:{titlePadding:t.titlePadding},layout:t.layout,...t.clipHeight===void 0?{}:{clipHeight:t.clipHeight},...t.overflow===void 0?{}:{overflow:t.overflow},border:t.border}}const un=W({op:"createCategoricalLegend",description:"Create one categorical legend block."},M(function(i={}){const e=I(this,i);if(this.semanticSpec.guides.legend?.[e.kind]!==void 0)throw new Error(`createCategoricalLegend requires a missing legend for ${e.kind}.`);return A(this,e),ze(this,e,i.order===void 0?void 0:J(i.order))}));function P(i,e={},n=i.semanticSpec.layers,a){if(Object.hasOwn(e,"combine")){if(ae(e.combine),e.combine==="color-size"){const u=B(i,e),O=F(i,{...e,blockLayout:e.blockLayout??(["left","right"].includes(e.position??"right")?"column":"row")},u.target,{creation:!0,nativeOffset:30});return{steps:[{op:"createColorSizeLegend",args:e}],finish:"always",legendGroup:{target:u.target,config:O.program.guideConfigs.legendGroups[u.target]}}}if(e.combine==="size-shape")return fe(i,e,n,P,a);const{combine:o,...c}=e;return P(i,c,n)}me(e,void 0,"createLegend");const r=e.target===void 0?n:n.filter(o=>o.id===e.target),t=r.length===1&&["area","rect","bar","arc","text","rule","tick"].includes(r[0].mark?.type),d=t?["color","stroke"].filter(o=>r[0].encoding?.[o]?.scale!==void 0):[],s=e.channels!==void 0?e.channels:d.length>0?d:void 0;if(e.channels===void 0&&s?.length>0)return P(i,{...e,channels:s},n);s!==void 0&&be(s,"createLegend");const L=r.length===1&&r[0].mark?.type==="point",l=o=>["color","stroke"].includes(o)&&!["ordinal","band","point"].includes(G(i,r[0]?.encoding?.[o]?.scale)?.type),S=L&&((s??[]).some(l)||new Set((s??[]).filter(o=>!["size","opacity","strokeWidth"].includes(o)).map(o=>r[0].encoding?.[o]?.field)).size>1);if(s?.length>1&&(S||s.some(o=>["opacity","strokeWidth"].includes(o))||t)){const{representation:o,values:c,count:u,symbol:O,gradient:m,overflow:z,...y}=e,p=s.filter(f=>["opacity","strokeWidth"].includes(f)),x=s.filter(f=>!p.includes(f)),q=new Map;for(const f of x.filter(h=>h!=="size")){const h=l(f)?`channel:${f}`:`field:${r[0]?.encoding?.[f]?.field}`;q.has(h)||q.set(h,[]),q.get(h).push(f)}const H=[...q.values()];if(x.includes("size")){const f=H.find(h=>!h.some(l));f?f.push("size"):H.push(["size"])}return{steps:(L?[...H,...p.map(f=>[f])]:s.map(f=>[f])).flatMap(f=>P(i,f.includes("color")&&(o!==void 0||m!==void 0)?{...e,channels:f}:{...y,channels:f,...f.some(l)&&m!==void 0?{gradient:m}:{},...f.some(h=>!["size","opacity","strokeWidth"].includes(h)&&["ordinal","band","point"].includes(G(i,r[0]?.encoding?.[h]?.scale)?.type))&&z!==void 0?{overflow:z}:{},...f.some(h=>["size","opacity","strokeWidth"].includes(h))&&u!==void 0?{count:u}:{}},n).steps),finish:"always"}}if(s===void 0&&r.length===1&&D(r[0])&&ee(r[0])&&!["color","stroke","shape","strokeDash","strokeWidth"].some(o=>r[0].encoding?.[o]?.scale!==void 0)){const o=r[0].id;return{steps:[ie({...e,target:o},"size"),{op:"createOpacityLegend",args:{...e,target:o}}],finish:"auto"}}const b=[["size",D,["color","stroke","shape","strokeDash","opacity"]],["strokeWidth",ke,e.target===void 0?["color","stroke","shape","strokeDash","size","opacity"]:["color","stroke","shape","strokeDash","opacity"]],["opacity",ee,["color","stroke","shape","strokeDash","size"]]];for(const[o,c,u]of b){const O=s?.length===1&&s[0]===o,m=s===void 0&&r.filter(c).length===1&&!r.some(z=>u.some(y=>z.encoding?.[y]?.scale!==void 0));if(O||m)return{steps:[o==="opacity"?{op:"createOpacityLegend",args:e}:ie(e,o)],finish:"auto"}}const v=r.filter(o=>{const c=["point","line","bar","rect","text","area","arc","tick"].includes(o.mark?.type)?o.encoding?.color:void 0,u=G(i,c?.scale);return K(u?.type)}),g=$(i,e.target,v);if(e.representation!==void 0&&s!==void 0&&s.length>1){if(!g||!s.includes("color"))throw new Error("Legend representation requires selected continuous color.");const{representation:o,values:c,count:u,symbol:O,gradient:m,...z}=e;return{steps:s.flatMap(p=>P(i,p==="color"?{...e,channels:[p]}:{...z,channels:[p]},n).steps),finish:"always"}}if(s?.length===1&&s[0]==="color"&&g||s===void 0&&g)return{steps:[{op:"createGradientLegend",args:e}],finish:"auto"};const C=r.filter(o=>{const c=["point","line","bar","rect","text","area","arc","tick"].includes(o.mark?.type)?o.encoding?.color:void 0,u=G(i,c?.scale);return["quantize","quantile","threshold"].includes(u?.type)});if(s?.length===1&&s[0]==="color"&&C.length>0||s===void 0&&C.length>0)return{steps:[{op:"createIntervalLegend",args:e}],finish:"auto"};const E=r.filter(o=>{const c=G(i,o.encoding?.stroke?.scale);return K(c?.type)}),k=$(i,e.target,E);if(s?.length===1&&s[0]==="stroke"&&k||s===void 0&&k&&!["color","shape","strokeDash","size","opacity","strokeWidth"].some(o=>k.encoding?.[o]?.scale!==void 0))return{steps:[{op:"createStrokeGradientLegend",args:{...e,channels:["stroke"]}}],finish:"auto"};const V=r.filter(o=>{const c=G(i,o.encoding?.stroke?.scale);return["quantize","quantile","threshold"].includes(c?.type)});if(s?.length===1&&s[0]==="stroke"&&V.length>0||s===void 0&&V.length===1)return{steps:[{op:"createStrokeIntervalLegend",args:{...e,channels:["stroke"]}}],finish:"auto"};const te=s?.includes("shape")===!0,_=s?.includes("size")===!0,R=r.filter(o=>o.mark?.type==="point"&&(s===void 0?["color","shape"].some(c=>o.encoding?.[c]?.scale!==void 0):(te||_)&&s.every(c=>["color","stroke","shape","size"].includes(c)&&o.encoding?.[c]?.scale!==void 0))),w=$(i,e.target,R),oe=s===void 0&&R.some(D);if((_||oe)&&w===void 0)throw new Error("Combined size legend requires one eligible point mark or an explicit target.");if(w!==void 0){if(Object.hasOwn(e,"values"))throw new Error("Combined and categorical legends require a channel block selector for exact values.");const{count:o,...c}=e,u=w.encoding?.size?.scale!==void 0&&(s===void 0||_);if(o!==void 0&&!u)throw new Error("Legend count requires a selected size legend.");if(u&&c.layout==="legacy-bottom")throw new Error('Combined size legends require layout "edge".');const O=["color","stroke","shape"].filter(p=>w.encoding?.[p]?.scale!==void 0),{format:m,...z}=c.labels??{};if(!u&&m!==void 0&&m!=="auto")throw new Error("Categorical legend labels do not accept format.");const y=[{op:"createCategoricalLegend",args:{...c,...c.labels===void 0?{}:{labels:z},target:w.id,channels:s?.filter(p=>p!=="size")??O}}];if(u&&y.push({op:"createSizeLegend",args:{target:w.id,...o===void 0?{}:{count:o},...c.overflow!==void 0&&G(i,w.encoding.size.scale)?.type==="ordinal"?{overflow:c.overflow}:{},...c.labels===void 0?{}:{labels:{...c.labels.offset===void 0?{}:{offset:c.labels.offset},...m===void 0?{}:{format:m}}},inheritAppearance:!0}}),I(i,y[0].args),u){const p=Z(i,y[1].args),x=i.guideConfigs.legend?.size;if(x!==void 0&&x.target!==p.target)throw new Error("Combined point series legend requires the active size legend to share its target.");if(x!==void 0&&o!==void 0&&Pe(x).count!==o)throw new Error("Existing size legend count must be edited before recreating the categorical block.")}return{steps:y,combined:u,finish:u?"always":"auto"}}return{steps:[{op:"createCategoricalLegend",args:e}],finish:"auto"}}function je(i,e={},n=i.semanticSpec.layers,a){ge(e);const{blockLayout:r,at:t,...d}=e,s=i.guideConfigs.legendGroups??{};if(Object.keys(s).length>0&&d.position===void 0){const E=N(i,e),k=s[E]?.placement;k?.position!==void 0&&(d.position=k.position,d.align=e.align??k.align,d.offset=e.offset??k.offset)}d.position===void 0&&e.direction==="horizontal"&&(e.at!==void 0||Object.keys(s).length>0)&&(d.position="top");const L=P(i,d,n,a),l=Object.keys(i.guideConfigs.legendGroups??{}).length>0,S=pe.includes(e.position)&&(L.steps.length>1||L.steps[0]?.op!=="createCategoricalLegend"||Object.keys(i.guideConfigs.legend??{}).length>0);if(e.blockLayout===void 0&&e.at===void 0&&!l&&!S)return L;const b=N(i,e),v=L.steps[0],g=i.guideConfigs.legendGroups?.[b]!==void 0?30:v?.op==="createCategoricalLegend"?I(i,v.args).offset:v?.op==="createSizeLegend"?Z(i,v.args).offset:30,C=F(i,e,b,{creation:!0,corner:S,nativeOffset:g});return C.grouped?(C.options.position===void 0&&d.position!==void 0&&(C.options.position=d.position),{...P(C.program,C.options,n,a),legendGroup:{target:b,config:C.program.guideConfigs.legendGroups[b]}}):L}function qe(i,e){if(e.steps.length===0)return i;let n=e.legendGroup===void 0?i:i._withMaterializationConfig(["guides","legendGroups",e.legendGroup.target],e.legendGroup.config);for(const a of e.steps){const r=n.guideConfigs.legend?.size;e.combined&&r!==void 0&&a.op==="createCategoricalLegend"&&(n=n._withLegendConfig("size",{...r,inheritPosition:!0})),e.combined&&a.op==="createSizeLegend"&&r!==void 0||(n=a.op==="createColorSizeLegend"?se(n,B(n,a.args)):n[a.op](a.args))}return e.finish==="always"?n.rematerializeLegend():e.finish==="auto"?Ee(n):n}const gn=W({op:"createLegend",description:"Create an inferred legend for selected channels."},M(function(i={}){return ue(this,qe(this,je(this,i)),i,{creation:!0})})),pn=W({op:"removeCategoricalLegend",description:"Remove the active categorical legend and its concrete components."},M(function(i={}){Q(i,"removeCategoricalLegend");const e=["series","color","stroke"].filter(d=>this.guideConfigs.legend?.[d]!==void 0);if(e.length===0)return this;if(e.length!==1)throw new Error("removeCategoricalLegend requires one active categorical legend.");const n=e[0],a=`${n}Legend`,r=Object.keys(this.graphicSpec.objects).filter(d=>d.startsWith(a));let t=this.editSemantic({property:`guide.legend.${n}`,remove:!0});for(const d of r)t=t.editGraphics({target:d,remove:!0});return t._withoutMaterializationConfig(["guides","legend",n])}));export{qe as applyLegendCreationPlan,un as createCategoricalLegend,gn as createLegend,fn as rematerializeLegend,pn as removeCategoricalLegend,I as resolveCategoricalLegendConfig,je as resolveLegendCreationPlan};

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

@@ -86,7 +86,7 @@ export function categoricalLegendLabels(config) {
   config = categoricalLegendView(config);
   const labels = config.domain.map(value => resolveDisplayLabel(
     value,
-    config.labelMap,
+    [...(config.labelMap ?? []), ...(config.defaultLabelMap ?? [])],
     formatVisibleText
   ));
   return config.hiddenCount > 0 ? [...labels, `…${config.hiddenCount} entries`] : labels;
@@ -174,8 +174,11 @@ export function resolveAppearance(program, config) {
     target.encoding.color === undefined &&
     !config.channels.includes("color") &&
     isLinearGradientPaint(program.markConfigs[target.id]?.fill);
+  const fixedLineStroke = target?.mark?.type === "line" &&
+    config.channels.includes("strokeDash")
+    ? program.markConfigs[target.id]?.stroke : undefined;
   const fallback = gradientFallback
-    ? program.markConfigs[target.id].fill : DEFAULT_COLORS.mark;
+    ? program.markConfigs[target.id].fill : fixedLineStroke ?? DEFAULT_COLORS.mark;
   let colors = config.domain.map(() => fallback);
   let strokes = config.domain.map(() => "white");
   let dashes = config.domain.map(() => []);

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

@@ -1,4 +1,5 @@
 import{normalizeLegendClipHeight}from"../../../../grammar/legendClip.js";
+import {normalizeLegendSpacing,validateLegendSpacing} from "../../../../grammar/legendSpacing.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";
@@ -34,6 +35,7 @@ const OPTIONS = Object.freeze([
   "labels",
   "titleStyle",
   "itemGap",
+  "rowPadding", "titlePadding",
   "border",
   "overflow"
 ]);
@@ -147,6 +149,7 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
     ? DEFAULT_VERTICAL_LEGEND_ITEM_GAP
     : position === "top" ? 24 : 20);
   const layout = args.layout === undefined ? "edge" : args.layout;
+  validateLegendSpacing(kind,{...args,layout});
   if (!["edge", "legacy-bottom"].includes(layout)) {
     throw new Error(`Unsupported legend layout "${layout}".`);
   }
@@ -198,6 +201,7 @@ export function normalizeOptions(args, kind, { internalSymbol = false } = {}) {
   const overflow = normalizeLegendOverflow(args.overflow);
   return {
     ...(args.clipHeight===undefined?{}:{clipHeight:normalizeLegendClipHeight(args.clipHeight)}),
+    ...normalizeLegendSpacing(args),
     ...(overflow === undefined ? {} : { overflow }),
     target: args.target,
     channels: args.channels,

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

@@ -11,6 +11,7 @@ import { CHANNELS } from "./options.js";
 import { nonEmptyString } from "./validation.js";
 import { findLayer } from "../../../../selectors/layers.js";
 import { findSemanticScale } from "../../../../selectors/scales.js";
+import { horizonLegendPresentation } from "../../../../grammar/horizon.js";
 
 function isCategoricalTarget(layer) {
   if (["line", "point"].includes(layer?.mark?.type)) {
@@ -76,8 +77,9 @@ function resolveOrdinalScales(program, scaleIds) {
     );
     return concrete;
   });
-  if (scales.slice(1).some(scale => !sameValues(scale.domain, scales[0].domain))) {
-    throw new Error("Combined legend scales must have identical ordered domains.");
+  if (scales.slice(1).some(scale => scale.domain.length !== scales[0].domain.length ||
+      scale.domain.some(value => !scales[0].domain.some(other => Object.is(value, other))))) {
+    throw new Error("Combined legend scales must contain the same domain values.");
   }
   return { scales, domain: scales[0].domain };
 }
@@ -119,6 +121,8 @@ export function resolveDefinition(program, layer, requestedChannels, requestedTi
   const scales = encodings.map(item => item.encoding.scale);
   const resolved = resolveOrdinalScales(program, scales);
   const field = [...fields][0];
+  const transform = requireDataset(program, layer.data).transform?.[0];
+  const horizon = field === transform?.as?.color ? horizonLegendPresentation(transform) : undefined;
   let linked;
   if (order?.channel !== undefined) {
     const position = layer.encoding?.[order.channel];
@@ -132,7 +136,8 @@ export function resolveDefinition(program, layer, requestedChannels, requestedTi
     channels,
     scales,
     field,
-    title: nonEmptyString(requestedTitle ?? field, "Legend title"),
+    title: nonEmptyString(requestedTitle ?? horizon?.title ?? field, "Legend title"),
+    ...(horizon === undefined ? {} : { defaultLabelMap: horizon.labelMap }),
     domain: resolveLegendOrderDomain(resolved.domain, order, linked,
       order?.values === undefined ? undefined : readNominalField(requireDataset(program, layer.data).values, field)),
     ...(sizeShape ? {combine:"size-shape",...resolveSizeShapeMapping({layer,

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

@@ -55,14 +55,14 @@ function makeEditSymbol(type) {
         ? "collection"
         : { line: "line", point: "circle", swatch: "rect" }[type];
       const actual = this.graphicSpec.objects[id]?.type;
-      const compatibleStyledSwatch = styledSwatch && ["rect", "collection"].includes(actual);
-      if (actual !== expected && !compatibleStyledSwatch) {
+      const compatibleSwatch = type === "swatch" && ["rect", "collection"].includes(actual);
+      if (actual !== expected && !compatibleSwatch) {
         throw new Error(`${op} requires existing ${type} symbols.`);
       }
       const layout = resolveLayout(this, config);
       const appearance = resolveAppearance(this, config);
       let next = this;
-      if (!dynamicPoint && !styledSwatch) {
+      if (!dynamicPoint && !styledSwatch && actual !== "collection") {
         next = next.editGraphics({
           target: id,
           property: "length",