ggaction 0.0.11 → 0.0.13

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

@@ -1,3 +1,4 @@
+import { editLegendBackground, resolveLegendBackgroundFromBounds } from "./continuous/common.js";
 import { action } from "../../../core/action.js";
 import { noOptions } from "../../../core/validation.js";
 import {
@@ -8,6 +9,9 @@ import { finiteMidpoint } from "../../../grammar/numeric.js";
 import { resolveGraphicBounds } from "../../../layout/canvas.js";
 import {
   resolveHorizontalLegendLane,
+  resolveHorizontalLegendGroup,
+  resolveSingleHorizontalLegendPlacement,
+  isHorizontalEdgeLegend,
   resolveSideLegendLane
 } from "../../../layout/legendLane.js";
 import { findCanvasGraphic } from
@@ -33,16 +37,13 @@ function categoricalFor(program, target) {
 
 function legendPosition(program, kind, config) {
   if (kind === "size") {
-    return categoricalFor(program, config.target)?.position ?? "right";
+    return categoricalFor(program, config.target)?.position ?? config.position;
   }
-  if (kind === "strokeWidth" || kind === "interval") return "right";
   return config.position;
 }
 
-function requestedOffset(kind, config) {
-  return ["size", "strokeWidth"].includes(kind)
-    ? 30
-    : config.offset;
+function requestedOffset(config) {
+  return config.offset;
 }
 
 function existingIds(program, kind) {
@@ -117,7 +118,8 @@ function blockDescriptor(program, kind, config) {
     id: kind,
     kind,
     target: config.target,
-    offset: requestedOffset(kind, config),
+    border: borderFor(kind, config),
+    offset: requestedOffset(config),
     bounds,
     title,
     symbol: {
@@ -130,19 +132,17 @@ function blockDescriptor(program, kind, config) {
       x: textAnchor(program, components.labelId),
       width: labels.right - labels.left
     },
-    occupiedBounds: components.backgroundId === undefined
-      ? bounds
-      : resolveConcreteGraphicBounds(
-          program.graphicSpec,
-          components.backgroundId
-        ),
+    occupiedBounds: unionConcreteGraphicBounds(program.graphicSpec, [
+      ...foregroundIds,
+      ...(components.backgroundId === undefined ? [] : [components.backgroundId])
+    ]),
     ...components,
     foregroundIds
   };
 }
 
 function borderFor(kind, config) {
-  return ["series", "color", "gradient", "opacity"].includes(kind)
+  return ["series", "color", "gradient", "opacity", "interval", "strokeWidth", "size"].includes(kind)
     ? config.border
     : false;
 }
@@ -159,7 +159,8 @@ function groupBlocks(blocks, configs) {
     ) {
       groups.push({
         id: `${block.kind}+size`,
-        blocks: [block, next],
+        blocks: [block, next.backgroundId === undefined ? next : { ...next,
+          bounds: next.occupiedBounds, inset: next.border.padding + next.border.lineWidth / 2 }],
         border: borderFor(block.kind, config),
         backgroundId: block.backgroundId
       });
@@ -193,13 +194,15 @@ export function hasMultiSideLegendLane(program) {
   return ["right", "left"].some(side => edgeKinds(program, side).length > 1);
 }
 
-export function hasMultiHorizontalLegendLane(program) {
-  return ["top", "bottom"].some(edge => edgeKinds(program, edge).length > 1);
+export function hasHorizontalLegendLane(program) {
+  return ["top", "bottom"].some(edge => edgeKinds(program, edge).some(
+    ([, config]) => isHorizontalEdgeLegend({ ...config, position: edge })
+  ));
 }
 
-export function hasMultiLegendLane(program) {
+export function hasLegendLane(program) {
   return hasMultiSideLegendLane(program) ||
-    hasMultiHorizontalLegendLane(program);
+    hasHorizontalLegendLane(program);
 }
 
 function translateCommands(commands, dx, dy) {
@@ -269,35 +272,20 @@ function translateGraphic(program, id, dx, dy) {
   return next;
 }
 
-function yAxisBounds(program) {
-  const ids = ["yAxisLine", "yAxisTicks", "yAxisLabels", "yAxisTitle"]
-    .filter(id => program.graphicSpec.objects[id] !== undefined);
-  return ids.length === 0
-    ? undefined
-    : unionConcreteGraphicBounds(program.graphicSpec, ids);
-}
-
-function horizontalCollisionBounds(program, edge) {
-  const ids = edge === "top"
-    ? ["chartTitle", "chartSubtitle"]
-    : ["xAxisLine", "xAxisTicks", "xAxisLabels", "xAxisTitle"];
-  return ids
-    .filter(id => program.graphicSpec.objects[id] !== undefined)
-    .map(id => resolveConcreteGraphicBounds(program.graphicSpec, id))
-    .filter(bounds => bounds !== undefined);
-}
-
 function horizontalGroups(program, groups) {
   return groups.map(group => {
     const representative = group.blocks[0];
     const config = program.guideConfigs.legend?.[representative.kind];
-    const titleId = representative.titleId;
+    const atomic = group.blocks.length > 1;
+    const titleId = atomic ? undefined : representative.titleId;
     const contentIds = group.blocks.flatMap(block => block.foregroundIds)
       .filter(id => id !== titleId);
+    if (atomic) contentIds.push(...group.blocks.slice(1).flatMap(block =>
+      block.backgroundId === undefined ? [] : [block.backgroundId]));
     const content = unionConcreteGraphicBounds(program.graphicSpec, contentIds);
     const foreground = unionConcreteGraphicBounds(
       program.graphicSpec,
-      group.blocks.flatMap(block => block.foregroundIds)
+      [...contentIds, ...(titleId === undefined ? [] : [titleId])]
     );
     if (content === undefined || foreground === undefined) {
       throw new Error(`Legend lane could not measure ${group.id} content.`);
@@ -308,11 +296,12 @@ function horizontalGroups(program, groups) {
       : border.padding + border.lineWidth / 2;
     return {
       id: group.id,
+      atomic,
       titleId,
       contentIds,
-      title: representative.title,
+      title: atomic ? undefined : representative.title,
       inline: config?.titlePosition === "left",
-      element: representative.symbol.bounds,
+      element: atomic ? foreground : representative.symbol.bounds,
       content,
       horizontal: { left: foreground.left, right: foreground.right,
         top: foreground.top, bottom: foreground.bottom },
@@ -323,6 +312,33 @@ function horizontalGroups(program, groups) {
   });
 }
 
+function applyHorizontalPlan(program, groups, plan) {
+  let next = program;
+  const byId = new Map(groups.map(group => [group.id, group]));
+  for (const placement of plan.placements) {
+    const group = byId.get(placement.id);
+    if (group.titleId !== undefined) {
+      next = translateGraphic(next, group.titleId, placement.dx, placement.titleDy);
+    }
+    for (const id of group.contentIds) {
+      next = translateGraphic(next, id, placement.dx, placement.contentDy);
+    }
+    if (placement.background !== undefined) {
+      for (const property of ["x", "y", "width", "height"]) {
+        next = next.editGraphics({ target: placement.background.id, property,
+          value: placement.background[property] });
+      }
+    }
+  }
+  if (plan.background !== undefined) {
+    for (const property of ["x", "y", "width", "height"]) {
+      next = next.editGraphics({ target: plan.background.id, property,
+        value: plan.background[property] });
+    }
+  }
+  return next;
+}
+
 export const rematerializeSideLegendLane = action(
   {
     op: "rematerializeSideLegendLane",
@@ -346,8 +362,7 @@ export const rematerializeSideLegendLane = action(
         side,
         plot,
         canvas,
-        groups: groupBlocks(blocks, configs),
-        axisBounds: yAxisBounds(this)
+        groups: groupBlocks(blocks, configs)
       });
       return [{ plan, blocks }];
     });
@@ -387,6 +402,12 @@ export const rematerializeSideLegendLane = action(
           value: "left"
         });
       }
+      for (const block of blocks) {
+        if (block.backgroundId === undefined || plan.backgrounds.some(item => item.id === block.backgroundId)) continue;
+        const bounds = unionConcreteGraphicBounds(next.graphicSpec, block.foregroundIds);
+        const background = resolveLegendBackgroundFromBounds([bounds], block.border, canvas, "Legend");
+        next = editLegendBackground(next, block.backgroundId, background, block.border);
+      }
       for (const background of plan.backgrounds) {
         for (const property of ["x", "y", "width", "height"]) {
           next = next.editGraphics({
@@ -414,55 +435,46 @@ export const rematerializeHorizontalLegendLane = action(
       throw new Error("Legend lane requires resolved Canvas and plot bounds.");
     }
     const configs = this.guideConfigs.legend ?? {};
-    const plans = ["top", "bottom"].flatMap(edge => {
-      const entries = edgeKinds(this, edge);
-      if (entries.length < 2) return [];
-      const blocks = entries.map(([kind, config]) =>
-        blockDescriptor(this, kind, config)
+    let next = this;
+    for (const edge of ["top", "bottom"]) {
+      const entries = edgeKinds(next, edge).filter(
+        ([, config]) => isHorizontalEdgeLegend({ ...config, position: edge })
       );
-      const groups = groupBlocks(blocks, configs);
-      if (groups.length < 2) return [];
-      const horizontal = horizontalGroups(this, groups);
+      if (entries.length === 0) continue;
+      if (entries.length === 1) {
+        const [kind, config] = entries[0];
+        const ids = existingIds(next, kind);
+        const bounds = unionConcreteGraphicBounds(next.graphicSpec, ids);
+        const { dx, dy } = resolveSingleHorizontalLegendPlacement({
+          plot, canvas, config, bounds
+        });
+        for (const id of ids) next = translateGraphic(next, id, dx, dy);
+        continue;
+      }
+      let groups = groupBlocks(entries.map(([kind, config]) =>
+        blockDescriptor(next, kind, config)), configs);
+      for (const group of groups.filter(group => group.blocks.length > 1)) {
+        const config = configs[group.blocks[0].kind];
+        const children = horizontalGroups(next, group.blocks.map((block, index) => ({
+          id: block.id, blocks: [block], border: index === 0 ? false : block.border,
+          backgroundId: index === 0 ? undefined : block.backgroundId
+        }))).map(child => ({ ...child, element: child.content }));
+        const plan = resolveHorizontalLegendGroup({ edge, plot, canvas, groups: children,
+          align: config.align, offset: config.offset, border: group.border,
+          backgroundId: group.backgroundId });
+        next = applyHorizontalPlan(next, children, plan);
+      }
+      if (groups.length < 2) continue;
+      groups = groupBlocks(entries.map(([kind, config]) =>
+        blockDescriptor(next, kind, config)), configs);
+      const horizontal = horizontalGroups(next, groups);
       const plan = resolveHorizontalLegendLane({
         edge,
         plot,
         canvas,
-        groups: horizontal,
-        collisionBounds: horizontalCollisionBounds(this, edge)
+        groups: horizontal
       });
-      return [{ plan, groups: horizontal }];
-    });
-    let next = this;
-    for (const { plan, groups } of plans) {
-      const byId = new Map(groups.map(group => [group.id, group]));
-      for (const placement of plan.placements) {
-        const group = byId.get(placement.id);
-        if (group.titleId !== undefined) {
-          next = translateGraphic(
-            next,
-            group.titleId,
-            placement.dx,
-            placement.titleDy
-          );
-        }
-        for (const id of group.contentIds) {
-          next = translateGraphic(
-            next,
-            id,
-            placement.dx,
-            placement.contentDy
-          );
-        }
-        if (placement.background !== undefined) {
-          for (const property of ["x", "y", "width", "height"]) {
-            next = next.editGraphics({
-              target: placement.background.id,
-              property,
-              value: placement.background[property]
-            });
-          }
-        }
-      }
+      next = applyHorizontalPlan(next, horizontal, plan);
     }
     return next;
   }

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

@@ -0,0 +1,132 @@
+import {
+  legendGraphicIds, legendResourcePolicy, legendResourcePolicies
+} from "../../../materialization/guides/resources.js";
+import { findLayer } from "../../../selectors/layers.js";
+import { resolveDefinition } from "./categorical/resolve.js";
+import { normalizeRecipe, resolveLegendSymbol } from "./categorical/recipes.js";
+import { resolveLayout, symbolGraphic } from "./categorical/layout.js";
+import { resolveLegendGraphicPlacement } from "../../../materialization/graphicHierarchy.js";
+
+export function removeLegendKinds(program, kinds) {
+  const removed = new Set(kinds);
+  const retainedSemanticKinds = new Set(
+    Object.entries(program.guideConfigs.legend ?? {})
+      .filter(([kind]) => !removed.has(kind))
+      .map(([kind]) => legendResourcePolicy(kind).semanticKind)
+  );
+  const semanticKinds = new Set(
+    kinds.map(kind => legendResourcePolicy(kind).semanticKind)
+  );
+  let next = program;
+  for (const kind of semanticKinds) {
+    if (
+      !retainedSemanticKinds.has(kind) &&
+      next.semanticSpec.guides.legend?.[kind] !== undefined
+    ) {
+      next = next.editSemantic({
+        property: `guide.legend.${kind}`,
+        remove: true
+      });
+    }
+  }
+  for (const id of new Set(kinds.flatMap(legendGraphicIds))) {
+    if (next.graphicSpec.objects[id] !== undefined) {
+      next = next.editGraphics({ target: id, remove: true });
+    }
+  }
+  for (const kind of kinds) {
+    next = next._withoutMaterializationConfig(["guides", "legend", kind]);
+  }
+  return next;
+}
+
+export function resolveCategoricalLegendRevision(program, kind, previous, channels, {
+  order = program.semanticSpec.guides.legend?.[kind]?.order, validateLayout = true
+} = {}) {
+  const layer = findLayer(program, previous.target);
+  const definition = resolveDefinition(program, layer, channels,
+    previous.inferredTitle ? undefined : previous.title, order);
+  const config = {
+    ...previous,
+    ...definition,
+    symbol: normalizeRecipe(resolveLegendSymbol(program, layer, channels,
+      previous.inferredSymbol ? undefined : previous.symbol), definition.kind)
+  };
+  if (validateLayout) resolveLayout(program, config);
+  return { kind, config, order };
+}
+
+export function createCategoricalLegendFromConfig(program, config, order) {
+  const { kind } = config;
+  let next = program;
+  if (kind === "series") {
+    next = next
+      .editSemantic({
+        property: "guide.legend.series.channels",
+        value: config.channels
+      })
+      .editSemantic({
+        property: "guide.legend.series.scales",
+        value: config.scales
+      })
+      .editSemantic({
+        property: "guide.legend.series.title",
+        value: config.title
+      });
+  } else {
+    next = next
+      .editSemantic({
+        property: "guide.legend.color.scale",
+        value: config.scales[0]
+      })
+      .editSemantic({
+        property: "guide.legend.color.title",
+        value: config.title
+      });
+  }
+  if (order !== undefined && order !== "scale") {
+    next = next.editSemantic({
+      property: `guide.legend.${kind}.order`,
+      value: order
+    });
+  }
+  next = next._withLegendConfig(kind, config);
+  if (config.border !== false) next = next.createLegendBackground();
+  next = next.createLegendSymbols().createLegendLabels();
+  return config.titleVisible === false ? next : next.createLegendTitle();
+}
+
+// Categorical content precedes its sampled companions in both creation and revision.
+export function resolveCategoricalLegendPlacement(program) {
+  const companions = new Set(legendResourcePolicies()
+    .filter(policy => policy.family !== "categorical" && program.guideConfigs.legend?.[policy.kind] !== undefined)
+    .flatMap(policy => legendGraphicIds(policy.kind)));
+  const before = program.graphicSpec.objects.canvas?.children?.find(id => companions.has(id));
+  return resolveLegendGraphicPlacement(program, before === undefined ? {} : { before });
+}
+
+export function categoricalSymbolIds(config) {
+  return new Set(config.symbol.layers.map(layer => symbolGraphic(config, layer.type)));
+}
+
+export function reconcileCategoricalSymbols(program, previous, config) {
+  const oldSymbols = categoricalSymbolIds(previous);
+  const newSymbols = categoricalSymbolIds(config);
+  const sameOrder = oldSymbols.size === newSymbols.size &&
+    [...oldSymbols].every((id, index) => id === [...newSymbols][index]);
+  let next = program;
+  if (!sameOrder) {
+    for (const id of oldSymbols) {
+      if (next.graphicSpec.objects[id] !== undefined) {
+        next = next.editGraphics({ target: id, remove: true });
+      }
+    }
+  }
+  for (const layer of config.symbol.layers) {
+    if (next.graphicSpec.objects[symbolGraphic(config, layer.type)] === undefined) {
+      const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[layer.type];
+      next = next[`createLegendSymbol${suffix}`]();
+    }
+  }
+  return next;
+}

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

@@ -1,9 +1,13 @@
 import { action } from "../../../core/action.js";
 import { validateKeys } from "../../../core/validation.js";
-import { legendGraphicIds, legendResourcePolicy } from
-  "../../../materialization/guides/resources.js";
-import { LEGEND_CHANNELS } from "../../../core/vocabulary.js";
-import { resolveLegendTarget } from "./target.js";
+import {
+  removeLegendKinds,
+  resolveCategoricalLegendRevision,
+  createCategoricalLegendFromConfig
+} from "./lifecycle.js";
+import { resolveLegendTarget, validateLegendChannels } from "./target.js";
+
+export { removeLegendKinds } from "./lifecycle.js";
 
 const OPTIONS = Object.freeze(["target", "channels"]);
 
@@ -18,85 +22,33 @@ function legendKindChannels(kind, config) {
   }[kind];
 }
 
-function validateRequestedChannels(channels) {
-  if (!Array.isArray(channels)) {
-    throw new TypeError("removeLegend channels must be an array.");
-  }
-  if (channels.length === 0) {
-    throw new Error("removeLegend channels must select at least one channel.");
-  }
-  const seen = new Set();
-  for (const channel of channels) {
-    if (!LEGEND_CHANNELS.includes(channel)) {
-      throw new Error(`Unsupported legend channel "${channel}".`);
-    }
-    if (seen.has(channel)) {
-      throw new Error(`removeLegend channels contains duplicate "${channel}".`);
-    }
-    seen.add(channel);
-  }
-}
-
-function resolveRequestedKinds(program, target, channels) {
-  validateRequestedChannels(channels);
+function resolveRequestedRemoval(program, target, channels) {
+  validateLegendChannels(channels, "removeLegend");
   const requested = new Set(channels);
   const matched = new Set();
   const kinds = [];
+  let partial;
   for (const [kind, config] of Object.entries(program.guideConfigs.legend ?? {})) {
     if (config?.target !== target) continue;
     const owned = legendKindChannels(kind, config);
     const overlap = owned.filter(channel => requested.has(channel));
-    if (overlap.length > 0 && overlap.length !== owned.length) {
-      throw new Error(
-        `Legend channels ${owned.map(channel => `"${channel}"`).join(", ")} ` +
-        "belong to one combined block and must be removed together."
-      );
-    }
-    if (overlap.length === owned.length) {
-      kinds.push(kind);
-      for (const channel of owned) matched.add(channel);
+    if (overlap.length === 0) continue;
+    kinds.push(kind);
+    for (const channel of overlap) matched.add(channel);
+    if (overlap.length !== owned.length) {
+      partial = { kind, config, channels: owned.filter(channel => !requested.has(channel)) };
     }
   }
   const missing = channels.filter(channel => !matched.has(channel));
   if (missing.length > 0) {
-    throw new Error(
-      `Legend target "${target}" has no complete block for channel "${missing[0]}".`
-    );
-  }
-  return kinds;
-}
-
-export function removeLegendKinds(program, kinds) {
-  const removed = new Set(kinds);
-  const retainedSemanticKinds = new Set(
-    Object.entries(program.guideConfigs.legend ?? {})
-      .filter(([kind]) => !removed.has(kind))
-      .map(([kind]) => legendResourcePolicy(kind).semanticKind)
-  );
-  const semanticKinds = new Set(
-    kinds.map(kind => legendResourcePolicy(kind).semanticKind)
-  );
-  let next = program;
-  for (const kind of semanticKinds) {
-    if (
-      !retainedSemanticKinds.has(kind) &&
-      next.semanticSpec.guides.legend?.[kind] !== undefined
-    ) {
-      next = next.editSemantic({
-        property: `guide.legend.${kind}`,
-        remove: true
-      });
-    }
-  }
-  for (const id of new Set(kinds.flatMap(legendGraphicIds))) {
-    if (next.graphicSpec.objects[id] !== undefined) {
-      next = next.editGraphics({ target: id, remove: true });
-    }
+    throw new Error(`Legend target "${target}" has no complete block for channel "${missing[0]}".`);
   }
-  for (const kind of kinds) {
-    next = next._withoutMaterializationConfig(["guides", "legend", kind]);
-  }
-  return next;
+  // Remove departing sibling configs from the immutable layout preflight view.
+  const view = kinds.reduce((next, kind) =>
+    next._withoutMaterializationConfig(["guides", "legend", kind]), program);
+  const revision = partial === undefined ? undefined
+    : resolveCategoricalLegendRevision(view, partial.kind, partial.config, partial.channels);
+  return { kinds, revision };
 }
 
 export function removeOwnedColorLegends(program, target) {
@@ -108,17 +60,20 @@ export function removeOwnedColorLegends(program, target) {
 }
 
 export const removeLegend = action(
-  { op: "removeLegend", description: "Remove every legend block owned by one mark." },
+  { op: "removeLegend", description: "Remove selected legend content or every block owned by one mark." },
   function (args = {}) {
     validateKeys(args, OPTIONS, "removeLegend");
     const target = resolveLegendTarget(this, args.target, "removeLegend");
     const targetKinds = Object.entries(this.guideConfigs.legend ?? {})
       .filter(([, config]) => config?.target === target)
       .map(([kind]) => kind);
-    const kinds = args.channels === undefined
-      ? targetKinds
-      : resolveRequestedKinds(this, target, args.channels);
+    const { kinds, revision } = args.channels === undefined
+      ? { kinds: targetKinds }
+      : resolveRequestedRemoval(this, target, args.channels);
     let next = removeLegendKinds(this, kinds);
+    if (revision !== undefined) {
+      next = createCategoricalLegendFromConfig(next, revision.config, revision.order);
+    }
     const retainedKinds = Object.keys(next.guideConfigs.legend ?? {});
     if (args.channels === undefined) {
       return retainedKinds.length === 0
@@ -128,7 +83,7 @@ export const removeLegend = action(
     const remainingTargetKinds = targetKinds.filter(kind => !kinds.includes(kind));
     const removedCategorical = kinds.some(kind => ["series", "color"].includes(kind));
     if (
-      removedCategorical &&
+      removedCategorical && revision === undefined &&
       remainingTargetKinds.includes("size") &&
       next.guideConfigs.legend.size.inheritAppearance === true
     ) {