ggaction 0.0.2 → 0.0.3

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

@@ -8,19 +8,19 @@ import {
   createLegendBackground,
   createLegendLabels,
   createLegendTitle,
-  editLegendBackground,
-  editLegendLabels,
-  editLegendTitle
+  rematerializeLegendBackground,
+  rematerializeLegendLabels,
+  rematerializeLegendTitle
 } from "./components.js";
 import {
   createLegendSymbolLines,
   createLegendSymbolPoints,
   createLegendSymbolSwatches,
   createLegendSymbols,
-  editLegendSymbolLines,
-  editLegendSymbolPoints,
-  editLegendSymbolSwatches,
-  editLegendSymbols,
+  rematerializeLegendSymbolLines,
+  rematerializeLegendSymbolPoints,
+  rematerializeLegendSymbolSwatches,
+  rematerializeLegendSymbols,
   rematerializeLegendHighlights
 } from "./symbols.js";
 import { editLegend } from "../edit.js";
@@ -31,19 +31,19 @@ export function registerCategoricalLegendActions(ProgramClass) {
   ProgramClass.prototype.createCategoricalLegend = createCategoricalLegend;
   ProgramClass.prototype.removeCategoricalLegend = removeCategoricalLegend;
   ProgramClass.prototype.createLegendBackground = createLegendBackground;
-  ProgramClass.prototype.editLegendBackground = editLegendBackground;
+  ProgramClass.prototype.rematerializeLegendBackground = rematerializeLegendBackground;
   ProgramClass.prototype.createLegendSymbols = createLegendSymbols;
-  ProgramClass.prototype.editLegendSymbols = editLegendSymbols;
+  ProgramClass.prototype.rematerializeLegendSymbols = rematerializeLegendSymbols;
   ProgramClass.prototype.rematerializeLegendHighlights = rematerializeLegendHighlights;
   ProgramClass.prototype.createLegendSymbolLines = createLegendSymbolLines;
-  ProgramClass.prototype.editLegendSymbolLines = editLegendSymbolLines;
+  ProgramClass.prototype.rematerializeLegendSymbolLines = rematerializeLegendSymbolLines;
   ProgramClass.prototype.createLegendSymbolPoints = createLegendSymbolPoints;
-  ProgramClass.prototype.editLegendSymbolPoints = editLegendSymbolPoints;
+  ProgramClass.prototype.rematerializeLegendSymbolPoints = rematerializeLegendSymbolPoints;
   ProgramClass.prototype.createLegendSymbolSwatches = createLegendSymbolSwatches;
-  ProgramClass.prototype.editLegendSymbolSwatches = editLegendSymbolSwatches;
+  ProgramClass.prototype.rematerializeLegendSymbolSwatches = rematerializeLegendSymbolSwatches;
   ProgramClass.prototype.createLegendLabels = createLegendLabels;
-  ProgramClass.prototype.editLegendLabels = editLegendLabels;
+  ProgramClass.prototype.rematerializeLegendLabels = rematerializeLegendLabels;
   ProgramClass.prototype.createLegendTitle = createLegendTitle;
-  ProgramClass.prototype.editLegendTitle = editLegendTitle;
+  ProgramClass.prototype.rematerializeLegendTitle = rematerializeLegendTitle;
   ProgramClass.prototype.rematerializeLegend = rematerializeLegend;
 }

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

@@ -10,6 +10,8 @@ import {
   measureLegendTextWidth,
   resolveLegendGrid
 } from "../../../../layout/legend.js";
+import { findCanvasGraphic } from
+  "../../../../materialization/graphicHierarchy.js";
 
 export function activeConfig(program) {
   const entries = ["series", "color"]
@@ -366,7 +368,7 @@ function resolveCompactBottomLayout(bounds, canvas, config, width, count) {
 
 export function resolveLayout(program, config) {
   const bounds = resolveGraphicBounds(program);
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
   if (
     bounds === undefined ||
     ![bounds.x, bounds.y, bounds.width, bounds.height].every(Number.isFinite) ||

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

@@ -1,4 +1,4 @@
-import { isPlainObject } from "../../../../core/immutable.js";
+import { validateOptionObject } from "../../../../core/validation.js";
 import { CATEGORICAL_LEGEND_CHANNELS } from "../../../../core/vocabulary.js";
 import { normalizeRecipe } from "./recipes.js";
 import {
@@ -86,10 +86,7 @@ function normalizeBorder(border) {
 }
 
 export function normalizeOptions(args, kind) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("createLegend options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "createLegend");
+  validateOptionObject(args, OPTIONS, "createLegend");
   if (Object.hasOwn(args, "labels")) {
     validateObject(args.labels, TEXT_OPTIONS, "createLegend.labels");
   }

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

@@ -11,7 +11,7 @@ function isCategoricalTarget(layer) {
       channel => layer.encoding?.[channel]?.scale !== undefined
     );
   }
-  return ["bar", "area"].includes(layer?.mark?.type) &&
+  return ["bar", "area", "arc", "rect"].includes(layer?.mark?.type) &&
     layer.encoding?.color?.scale !== undefined;
 }
 
@@ -39,7 +39,7 @@ export function resolveTarget(program, requested) {
 export const sameValues = sameOrderedValues;
 
 export function resolveLegendKind(layer, requestedChannels) {
-  if (["bar", "area"].includes(layer.mark.type)) return "color";
+  if (["bar", "area", "arc", "rect"].includes(layer.mark.type)) return "color";
   if (
     layer.mark.type === "point" &&
     sameValues(requestedChannels, ["color"])

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

@@ -53,7 +53,7 @@ function legendLayerStyle(layer, style) {
 
 function makeEditSymbol(type) {
   const suffix = { line: "Lines", point: "Points", swatch: "Swatches" }[type];
-  const op = `editLegendSymbol${suffix}`;
+  const op = `rematerializeLegendSymbol${suffix}`;
   return action(
     { op, description: `Rematerialize categorical legend ${type} symbols.` },
     function (args = {}) {
@@ -180,20 +180,20 @@ function makeCreateSymbol(type, edit) {
   );
 }
 
-export const editLegendSymbolLines = makeEditSymbol("line");
-export const editLegendSymbolPoints = makeEditSymbol("point");
-export const editLegendSymbolSwatches = makeEditSymbol("swatch");
+export const rematerializeLegendSymbolLines = makeEditSymbol("line");
+export const rematerializeLegendSymbolPoints = makeEditSymbol("point");
+export const rematerializeLegendSymbolSwatches = makeEditSymbol("swatch");
 export const createLegendSymbolLines = makeCreateSymbol(
   "line",
-  "editLegendSymbolLines"
+  "rematerializeLegendSymbolLines"
 );
 export const createLegendSymbolPoints = makeCreateSymbol(
   "point",
-  "editLegendSymbolPoints"
+  "rematerializeLegendSymbolPoints"
 );
 export const createLegendSymbolSwatches = makeCreateSymbol(
   "swatch",
-  "editLegendSymbolSwatches"
+  "rematerializeLegendSymbolSwatches"
 );
 
 export const createLegendSymbols = action(
@@ -214,17 +214,17 @@ export const createLegendSymbols = action(
   }
 );
 
-export const editLegendSymbols = action(
-  { op: "editLegendSymbols", description: "Rematerialize layered legend symbols." },
+export const rematerializeLegendSymbols = action(
+  { op: "rematerializeLegendSymbols", description: "Rematerialize layered legend symbols." },
   function (args = {}) {
-    noOptions(args, "editLegendSymbols");
+    noOptions(args, "rematerializeLegendSymbols");
     const { config } = activeConfig(this);
     let next = this;
     for (const layer of config.symbol.layers) {
       const operation = {
-        line: "editLegendSymbolLines",
-        point: "editLegendSymbolPoints",
-        swatch: "editLegendSymbolSwatches"
+        line: "rematerializeLegendSymbolLines",
+        point: "rematerializeLegendSymbolPoints",
+        swatch: "rematerializeLegendSymbolSwatches"
       }[layer.type];
       next = next[operation]();
     }
@@ -252,7 +252,7 @@ export const rematerializeLegendHighlights = action(
     })).filter(entry => entry.states !== undefined);
     if (highlights.length === 0) return this;
 
-    let next = this.editLegendSymbols();
+    let next = this.rematerializeLegendSymbols();
     for (const { highlight, states } of highlights) {
       for (const layer of config.symbol.layers) {
         const id = symbolGraphic(config, layer.type);

package/src/actions/guides/legends/continuous/common.js

@@ -1,6 +1,7 @@
 import { isPlainObject } from "../../../../core/immutable.js";
 import {
   validateKeys,
+  validateOptionObject,
   validateNonEmptyString,
   validateNonNegativeFinite,
   validatePositiveFinite
@@ -10,6 +11,8 @@ import { resolveGraphicBounds } from "../../../../layout/canvas.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../../theme/defaults.js";
 import { findLayer } from "../../../../selectors/layers.js";
+import { findCanvasGraphic } from
+  "../../../../materialization/graphicHierarchy.js";
 
 const OPTIONS = Object.freeze([
   "target", "channels", "position", "align", "offset", "title", "count",
@@ -85,10 +88,7 @@ function normalizeBorder(value) {
 }
 
 export function normalizeContinuousLegend(args, kind) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("createLegend options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "createLegend");
+  validateOptionObject(args, OPTIONS, "createLegend");
   const position = args.position ?? "right";
   if (!POSITIONS.includes(position)) {
     throw new Error(`Unsupported legend position "${position}".`);
@@ -170,7 +170,7 @@ export function resolveContinuousPoint(program, requested, channel) {
 
 export function resolveContinuousColorLayer(program, requested) {
   const candidates = program.semanticSpec.layers.filter(layer =>
-    ["point", "bar"].includes(layer.mark?.type) &&
+    ["point", "bar", "rect"].includes(layer.mark?.type) &&
     layer.encoding?.color?.scale !== undefined
   );
   const layer = requested === undefined
@@ -182,7 +182,7 @@ export function resolveContinuousColorLayer(program, requested) {
   if (layer === undefined) {
     throw new Error(
       requested === undefined
-        ? "color legend requires one eligible point or bar mark."
+        ? "color legend requires one eligible point, bar, or rect mark."
         : `Unknown color legend target "${requested}".`
     );
   }
@@ -199,7 +199,7 @@ export function requireResolvedLegendScale(program, id, type) {
 
 export function resolveContinuousBounds(program) {
   const plot = resolveGraphicBounds(program);
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
   if (
     plot === undefined ||
     ![plot.x, plot.y, plot.width, plot.height].every(Number.isFinite) ||

package/src/actions/guides/legends/continuous/interval.js

@@ -1,6 +1,9 @@
 import { action } from "../../../../core/action.js";
 import { isPlainObject } from "../../../../core/immutable.js";
-import { validateKeys } from "../../../../core/validation.js";
+import {
+  validateKeys,
+  validateOptionObject
+} from "../../../../core/validation.js";
 import { formatDiscretizedIntervals } from "../../../../grammar/scales.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../../theme/defaults.js";
@@ -38,10 +41,7 @@ function textOptions(value, label, defaults) {
 }
 
 export function normalizeIntervalLegend(args) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("createLegend options must be a plain object.");
-  }
-  validateKeys(args, OPTIONS, "createLegend");
+  validateOptionObject(args, OPTIONS, "createLegend");
   if (args.channels !== undefined && (
     !Array.isArray(args.channels) ||
     args.channels.length !== 1 ||

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

@@ -1,7 +1,6 @@
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
-import { isPlainObject } from "../../../core/immutable.js";
-import { validateKeys } from "../../../core/validation.js";
+import { validateOptionObject } from "../../../core/validation.js";
 import { normalizeOptions } from "./categorical/options.js";
 import { symbolGraphic } from "./categorical/layout.js";
 import {
@@ -276,10 +275,7 @@ function editCategorical(program, kind, previous, size, args) {
 export const editLegend = action(
   { op: "editLegend", description: "Edit one stable legend layout or appearance." },
   function (args = {}) {
-    if (!isPlainObject(args)) {
-      throw new TypeError("editLegend options must be a plain object.");
-    }
-    validateKeys(args, OPTIONS, "editLegend");
+    validateOptionObject(args, OPTIONS, "editLegend");
     const changes = Object.keys(args).filter(key => key !== "target");
     if (changes.length === 0) {
       throw new Error("editLegend requires at least one change.");

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

@@ -0,0 +1,63 @@
+import { action } from "../../../core/action.js";
+import { validateOptionObject } from "../../../core/validation.js";
+
+function makeFocusedLegendEdit({ name, options, map }) {
+  return action(
+    {
+      op: name,
+      description: `Edit one focused legend component through editLegend.`
+    },
+    function (args = {}) {
+      validateOptionObject(args, ["target", ...options], name);
+      if (!options.some(option => Object.hasOwn(args, option))) {
+        throw new Error(`${name} requires at least one component change.`);
+      }
+      return this.editLegend(map(args));
+    }
+  );
+}
+
+const editLegendLayout = makeFocusedLegendEdit({
+  name: "editLegendLayout",
+  options: [
+    "position", "align", "direction", "columns", "offset",
+    "titlePosition", "itemGap"
+  ],
+  map: args => args
+});
+
+const editLegendLabels = makeFocusedLegendEdit({
+  name: "editLegendLabels",
+  options: ["color", "fontSize", "fontFamily", "fontWeight"],
+  map: ({ target, ...labels }) => ({ target, labels })
+});
+
+const editLegendTitle = makeFocusedLegendEdit({
+  name: "editLegendTitle",
+  options: ["title", "color", "fontSize", "fontFamily", "fontWeight"],
+  map: ({ target, title, ...titleStyle }) => ({
+    target,
+    ...(title === undefined ? {} : { title }),
+    ...(Object.keys(titleStyle).length === 0 ? {} : { titleStyle })
+  })
+});
+
+const editLegendSymbols = makeFocusedLegendEdit({
+  name: "editLegendSymbols",
+  options: ["symbol", "count", "gradient"],
+  map: args => args
+});
+
+const editLegendBorder = makeFocusedLegendEdit({
+  name: "editLegendBorder",
+  options: ["border"],
+  map: args => args
+});
+
+export function registerFocusedLegendActions(ProgramClass) {
+  ProgramClass.prototype.editLegendLayout = editLegendLayout;
+  ProgramClass.prototype.editLegendLabels = editLegendLabels;
+  ProgramClass.prototype.editLegendTitle = editLegendTitle;
+  ProgramClass.prototype.editLegendSymbols = editLegendSymbols;
+  ProgramClass.prototype.editLegendBorder = editLegendBorder;
+}

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

@@ -1,9 +1,13 @@
 import { registerCategoricalLegendActions } from "./categorical/index.js";
 import { registerContinuousLegendActions } from "./continuous/index.js";
 import { registerSizeLegendActions } from "./size.js";
+import { registerFocusedLegendActions } from "./focused.js";
+import { removeLegend } from "./remove.js";
 
 export function registerLegendActions(ProgramClass) {
   registerCategoricalLegendActions(ProgramClass);
   registerContinuousLegendActions(ProgramClass);
   registerSizeLegendActions(ProgramClass);
+  registerFocusedLegendActions(ProgramClass);
+  ProgramClass.prototype.removeLegend = removeLegend;
 }

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

@@ -0,0 +1,64 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateKeys } from "../../../core/validation.js";
+import { legendGraphicIds } from
+  "../../../materialization/guides/resources.js";
+
+const OPTIONS = Object.freeze(["target"]);
+
+function resolveTarget(program, requested) {
+  const targets = [...new Set(Object.values(program.guideConfigs.legend ?? {})
+    .map(config => config?.target)
+    .filter(Boolean))];
+  if (requested !== undefined) {
+    const target = validateUserId(requested, "Legend target id");
+    if (!targets.includes(target)) {
+      throw new Error(`Unknown legend target "${target}".`);
+    }
+    return target;
+  }
+  if (targets.length === 0) throw new Error("removeLegend requires an existing legend.");
+  if (targets.length > 1) {
+    throw new Error("removeLegend requires target when the legend is ambiguous.");
+  }
+  return targets[0];
+}
+
+const SEMANTIC_KIND = Object.freeze({
+  series: "series",
+  color: "color",
+  size: "size",
+  gradient: "color",
+  interval: "color",
+  opacity: "opacity"
+});
+
+export const removeLegend = action(
+  { op: "removeLegend", description: "Remove every legend block owned by one mark." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "removeLegend");
+    const target = resolveTarget(this, args.target);
+    const kinds = Object.entries(this.guideConfigs.legend ?? {})
+      .filter(([, config]) => config?.target === target)
+      .map(([kind]) => kind);
+    const semanticKinds = new Set(kinds.map(kind => SEMANTIC_KIND[kind]));
+    let next = this;
+    for (const kind of semanticKinds) {
+      if (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;
+  }
+);

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

@@ -7,17 +7,18 @@ import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
 import { resolveLayout as resolveCategoricalLayout } from
   "./categorical/layout.js";
 import { findLayer } from "../../../selectors/layers.js";
-import { resolveLegendGraphicPlacement } from
+import { findCanvasGraphic, resolveLegendGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
 const SIZE_OPTIONS = Object.freeze(["target", "count"]);
 
-function resolvePoint(program, requested) {
-  const candidates = program.semanticSpec.layers.filter(layer =>
-    layer.mark?.type === "point" &&
-    layer.encoding?.color?.scale !== undefined &&
-    layer.encoding?.shape?.scale !== undefined
-  );
+export function isSizeLegendPoint(layer) {
+  return layer?.mark?.type === "point" &&
+    layer.encoding?.size?.scale !== undefined;
+}
+
+export function resolveSizeLegendPoint(program, requested) {
+  const candidates = program.semanticSpec.layers.filter(isSizeLegendPoint);
   const layer = requested === undefined
     ? candidates.length === 1 ? candidates[0] : undefined
     : (() => {
@@ -27,13 +28,10 @@ function resolvePoint(program, requested) {
   if (layer === undefined) {
     throw new Error(
       requested === undefined
-        ? "Point series legend requires one eligible point mark."
-        : `Unknown point series legend target "${requested}".`
+        ? "Size legend requires one eligible point mark or an explicit target."
+        : `Unknown size legend target "${requested}".`
     );
   }
-  if (layer.encoding.color.field !== layer.encoding.shape.field) {
-    throw new Error("Point color and shape legends require the same field.");
-  }
   return layer;
 }
 
@@ -47,7 +45,7 @@ function requireScale(program, id, type) {
 
 function bounds(program) {
   const value = resolveGraphicBounds(program);
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
   if (
     value === undefined ||
     ![value.x, value.y, value.width, value.height].every(Number.isFinite) ||
@@ -171,7 +169,7 @@ export const createSizeLegend = action(
   },
   function (args = {}) {
     validateKeys(args, [...SIZE_OPTIONS, "inheritAppearance"], "createSizeLegend");
-    const layer = resolvePoint(this, args.target);
+    const layer = resolveSizeLegendPoint(this, args.target);
     const encoding = layer.encoding?.size;
     if (encoding?.scale === undefined) {
       throw new Error(`Point mark "${layer.id}" requires a size encoding.`);