ggaction 0.0.2 → 0.0.4

package/src/actions/guides/axes/axes.js

@@ -1,10 +1,13 @@
 import { action } from "../../../core/action.js";
 import { isPlainObject } from "../../../core/immutable.js";
 import { validateUserId } from "../../../core/identifiers.js";
-import { validateKeys } from "../../../core/validation.js";
+import { validateKeys, validateOptionObject } from "../../../core/validation.js";
 import { findCoordinate } from "../../../selectors/coordinates.js";
+import { resolvePolarGuideResources } from "../polar/resolve.js";
 
-const TOP_OPTIONS = Object.freeze(["coordinate", "x", "y"]);
+const TOP_OPTIONS = Object.freeze([
+  "coordinate", "x", "y", "theta", "radius"
+]);
 const COORDINATE_OPTIONS = Object.freeze(["id", "type"]);
 const COORDINATE_API_TYPES = new Set(["auto", "cartesian", "polar"]);
 
@@ -15,13 +18,11 @@ function validateAxisOption(value, channel) {
 }
 
 function validateArgs(args) {
-  if (!isPlainObject(args)) {
-    throw new TypeError("createAxes options must be a plain object.");
-  }
-
-  validateKeys(args, TOP_OPTIONS, "createAxes");
+  validateOptionObject(args, TOP_OPTIONS, "createAxes");
   validateAxisOption(args.x, "x");
   validateAxisOption(args.y, "y");
+  validateAxisOption(args.theta, "theta");
+  validateAxisOption(args.radius, "radius");
 
   const coordinate = args.coordinate ?? {};
   if (!isPlainObject(coordinate)) {
@@ -60,14 +61,10 @@ function inspectChannels(layers) {
     );
   }
 
-  return { cartesianLayers, hasPolar: polarLayers.length > 0 };
+  return { cartesianLayers, polarLayers };
 }
 
-function resolveCoordinate(program, descriptor, cartesianLayers, hasPolar) {
-  if (hasPolar && cartesianLayers.length === 0) {
-    throw new Error("createAxes does not yet support Polar axes.");
-  }
-
+function resolveCoordinate(program, descriptor, cartesianLayers) {
   if (cartesianLayers.length === 0) {
     throw new Error("createAxes requires an x or y encoding.");
   }
@@ -124,6 +121,24 @@ function resolveCoordinate(program, descriptor, cartesianLayers, hasPolar) {
   return { id, layers };
 }
 
+function resolvePolarAxisArgs(program, layers, channel, option, descriptor) {
+  const selected = option === false
+    ? false
+    : option !== undefined || hasChannel(layers, channel);
+  if (!selected) return undefined;
+  const args = option ?? {};
+  const kind = channel === "theta" ? "theta" : "radius";
+  const resource = resolvePolarGuideResources(program, kind, {
+    ...args,
+    ...(descriptor.id === undefined ? {} : { coordinate: descriptor.id })
+  }, "createAxes");
+  return {
+    ...args,
+    scale: resource.scale,
+    coordinate: resource.coordinate
+  };
+}
+
 function hasChannel(layers, channel) {
   return layers.some(layer => layer.encoding?.[channel] !== undefined);
 }
@@ -170,14 +185,53 @@ const createAxes = action(
   },
   function (args = {}) {
     const coordinateDescriptor = validateArgs(args);
-    const { cartesianLayers, hasPolar } = inspectChannels(
+    const { cartesianLayers, polarLayers } = inspectChannels(
       this.semanticSpec.layers
     );
+    const requestedCoordinateType = coordinateDescriptor.id === undefined
+      ? undefined
+      : findCoordinate(this, coordinateDescriptor.id)?.type;
+    const explicitlyPolar = coordinateDescriptor.type === "polar" ||
+      requestedCoordinateType === "polar" ||
+      args.theta !== undefined || args.radius !== undefined;
+    if (polarLayers.length > 0 &&
+        (cartesianLayers.length === 0 || explicitlyPolar)) {
+      if (coordinateDescriptor.type === "cartesian") {
+        throw new Error("createAxes coordinate type conflicts with Polar encodings.");
+      }
+      if (args.x !== undefined || args.y !== undefined) {
+        throw new Error("createAxes x/y options require Cartesian encodings.");
+      }
+      const theta = resolvePolarAxisArgs(
+        this,
+        polarLayers,
+        "theta",
+        args.theta,
+        coordinateDescriptor
+      );
+      const radius = resolvePolarAxisArgs(
+        this,
+        polarLayers,
+        "radius",
+        args.radius,
+        coordinateDescriptor
+      );
+      if (theta === undefined && radius === undefined) {
+        throw new Error("createAxes requires at least one selected axis.");
+      }
+      let polarProgram = this;
+      if (theta !== undefined) {
+        polarProgram = polarProgram.createThetaAxis(theta);
+      }
+      if (radius !== undefined) {
+        polarProgram = polarProgram.createRadialAxis(radius);
+      }
+      return polarProgram;
+    }
     const coordinate = resolveCoordinate(
       this,
       coordinateDescriptor,
-      cartesianLayers,
-      hasPolar
+      cartesianLayers
     );
     const x = resolveAxisArgs(coordinate.layers, "x", args.x);
     const y = resolveAxisArgs(coordinate.layers, "y", args.y);

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

@@ -0,0 +1,126 @@
+import { action } from "../../../core/action.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import { validateKeys, validateOptionObject } from "../../../core/validation.js";
+
+const OPTIONS = Object.freeze([
+  "position", "line", "ticks", "labels", "ticksAndLabels", "title"
+]);
+const LINE_OPTIONS = Object.freeze(["color", "lineWidth"]);
+const TICK_OPTIONS = Object.freeze([
+  "count", "values", "length", "color", "lineWidth"
+]);
+const LABEL_OPTIONS = Object.freeze([
+  "count", "values", "offset", "format", "color", "fontSize",
+  "fontFamily", "fontWeight"
+]);
+const GROUP_OPTIONS = Object.freeze(["count", "values", "ticks", "labels"]);
+const TITLE_OPTIONS = Object.freeze([
+  "text", "at", "offset", "rotation", "color", "fontSize",
+  "fontFamily", "fontWeight"
+]);
+
+function validateNested(args, key, options, operation) {
+  if (!Object.hasOwn(args, key)) return;
+  if (!isPlainObject(args[key])) {
+    throw new TypeError(`${operation}.${key} must be a plain object.`);
+  }
+  validateKeys(args[key], options, `${operation}.${key}`);
+}
+
+function validateArgs(args, operation) {
+  validateOptionObject(args, OPTIONS, operation, {
+    allowEmpty: false,
+    emptyMessage: `${operation} requires at least one axis change.`,
+    emptyError: Error
+  });
+  validateNested(args, "line", LINE_OPTIONS, operation);
+  validateNested(args, "ticks", TICK_OPTIONS, operation);
+  validateNested(args, "labels", LABEL_OPTIONS, operation);
+  validateNested(args, "ticksAndLabels", GROUP_OPTIONS, operation);
+  validateNested(args, "title", TITLE_OPTIONS, operation);
+  if (args.ticksAndLabels !== undefined && (
+    args.ticks !== undefined || args.labels !== undefined
+  )) {
+    throw new Error(
+      `${operation} cannot combine ticksAndLabels with ticks or labels.`
+    );
+  }
+  if (args.ticksAndLabels?.ticks !== undefined) {
+    validateNested(args.ticksAndLabels, "ticks", ["length", "color", "lineWidth"], `${operation}.ticksAndLabels`);
+  }
+  if (args.ticksAndLabels?.labels !== undefined) {
+    validateNested(args.ticksAndLabels, "labels", [
+      "offset", "format", "color", "fontSize", "fontFamily", "fontWeight"
+    ], `${operation}.ticksAndLabels`);
+  }
+}
+
+function names(channel) {
+  const prefix = channel === "x" ? "X" : "Y";
+  return {
+    operation: `edit${prefix}Axis`,
+    line: `edit${prefix}AxisLine`,
+    ticks: `edit${prefix}AxisTicks`,
+    labels: `edit${prefix}AxisLabels`,
+    group: `edit${prefix}AxisTicksAndLabels`,
+    title: `edit${prefix}AxisTitle`
+  };
+}
+
+function makeEditAxis(channel) {
+  const operation = names(channel);
+  return action(
+    {
+      op: operation.operation,
+      description: `Edit selected existing ${channel}-axis components.`
+    },
+    function (args = {}) {
+      validateArgs(args, operation.operation);
+      const shared = Object.hasOwn(args, "position")
+        ? { position: args.position }
+        : {};
+      const has = id => this.graphicSpec.objects[id] !== undefined;
+      let next = this;
+
+      if (args.line !== undefined || (args.position !== undefined && has(`${channel}AxisLine`))) {
+        next = next[operation.line]({ ...shared, ...(args.line ?? {}) });
+      }
+
+      if (args.ticksAndLabels !== undefined) {
+        next = next[operation.group]({
+          ...shared,
+          ...args.ticksAndLabels
+        });
+      } else if (args.ticks !== undefined || args.labels !== undefined) {
+        if (args.ticks !== undefined) {
+          next = next[operation.ticks]({ ...shared, ...args.ticks });
+        }
+        if (args.labels !== undefined) {
+          next = next[operation.labels]({ ...shared, ...args.labels });
+        }
+      } else if (args.position !== undefined) {
+        const hasTicks = has(`${channel}AxisTicks`);
+        const hasLabels = has(`${channel}AxisLabels`);
+        if (hasTicks && hasLabels) {
+          next = next[operation.group](shared);
+        } else {
+          if (hasTicks) next = next[operation.ticks](shared);
+          if (hasLabels) next = next[operation.labels](shared);
+        }
+      }
+
+      if (args.title !== undefined || (args.position !== undefined && has(`${channel}AxisTitle`))) {
+        next = next[operation.title]({ ...shared, ...(args.title ?? {}) });
+      }
+      return next;
+    }
+  );
+}
+
+const editXAxis = makeEditAxis("x");
+const editYAxis = makeEditAxis("y");
+
+export function registerCompleteAxisEditActions(ProgramClass) {
+  ProgramClass.prototype.editXAxis = editXAxis;
+  ProgramClass.prototype.editYAxis = editYAxis;
+}

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

@@ -5,6 +5,13 @@ import { registerAxisTickGroupActions } from "./tickGroups.js";
 import { registerAxisTickActions } from "./ticks.js";
 import { registerAxisTitleActions } from "./titles.js";
 import { registerAxisActions } from "./axis.js";
+import { registerCompleteAxisEditActions } from "./edit.js";
+import {
+  removeRadialAxis,
+  removeThetaAxis,
+  removeXAxis,
+  removeYAxis
+} from "./remove.js";
 
 export function registerGuideAxisActions(ProgramClass) {
   registerAxisLineActions(ProgramClass);
@@ -14,4 +21,9 @@ export function registerGuideAxisActions(ProgramClass) {
   registerAxisTitleActions(ProgramClass);
   registerAxisActions(ProgramClass);
   registerAxisCollectionActions(ProgramClass);
+  registerCompleteAxisEditActions(ProgramClass);
+  ProgramClass.prototype.removeXAxis = removeXAxis;
+  ProgramClass.prototype.removeYAxis = removeYAxis;
+  ProgramClass.prototype.removeThetaAxis = removeThetaAxis;
+  ProgramClass.prototype.removeRadialAxis = removeRadialAxis;
 }

package/src/actions/guides/axes/labels.js

@@ -2,6 +2,7 @@ import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   sameOrderedValues,
+  validateOptionObject,
   validateNonEmptyString,
   validateNonNegativeFinite,
   validatePositiveFinite
@@ -12,8 +13,8 @@ import {
   mapContinuousScaleValues,
   formatTransformedTick,
   mapOrdinalPositionValues
-} from "../../../grammar/scales.js";
-import { formatTimeTick } from "../../../grammar/ticks.js";
+} from "../../../grammar/scales/index.js";
+import { formatTimeTick, formatTimeTicks } from "../../../grammar/ticks.js";
 import { valuesFromTickConfig } from "../tickValues.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
@@ -24,7 +25,7 @@ import {
   validateAxisFormat,
   validateAxisPosition
 } from "./policy.js";
-import { resolvePlotGraphicPlacement } from
+import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
 const OPTIONS = Object.freeze([
@@ -41,11 +42,11 @@ const DEFAULTS = Object.freeze({
 });
 
 function validateOptions(args, operation, create) {
-  for (const key of Object.keys(args)) {
-    if (!OPTIONS.includes(key) || (!create && key === "scale")) {
-      throw new Error(`Unknown ${operation} option "${key}".`);
-    }
-  }
+  validateOptionObject(
+    args,
+    create ? OPTIONS : OPTIONS.filter(key => key !== "scale"),
+    operation
+  );
   if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) {
     throw new Error(`${operation} cannot use count and values together.`);
   }
@@ -97,16 +98,18 @@ function resolve(program, channel, config) {
   const positions = discrete
     ? mapOrdinalPositionValues(values, scale)
     : mapContinuousScaleValues(values, scale);
-  const text = values.map(value => formatAxisValue(
-    value,
-    scale.type,
-    config.format,
-    item => scale.type === "time"
-      ? formatTimeTick(item, scale.domain)
-      : isTransformedScaleType(scale.type)
-        ? formatTransformedTick(scale.type, item)
-        : String(item)
-  ));
+  const text = scale.type === "time" && config.format === "auto"
+    ? formatTimeTicks(values, scale.domain)
+    : values.map(value => formatAxisValue(
+        value,
+        scale.type,
+        config.format,
+        item => scale.type === "time"
+          ? formatTimeTick(item, scale.domain)
+          : isTransformedScaleType(scale.type)
+            ? formatTransformedTick(scale.type, item)
+            : String(item)
+      ));
   const resolved = {
     values,
     text,
@@ -118,7 +121,7 @@ function resolve(program, channel, config) {
       offset: config.offset
     })
   };
-  const canvas = program.graphicSpec.objects.canvas?.properties;
+  const canvas = findCanvasGraphic(program)?.properties;
   const maximumTextWidth = Math.max(
     0,
     ...text.map(value => [...value].length * config.fontSize * 0.6)

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

@@ -0,0 +1,60 @@
+import { action } from "../../../core/action.js";
+import { validateKeys } from "../../../core/validation.js";
+import { axisGraphicIds } from
+  "../../../materialization/guides/resources.js";
+
+const OPTIONS = Object.freeze(["coordinate", "scale"]);
+
+function makeRemoveAxis(channel) {
+  const prefix = channel === "x"
+    ? "X"
+    : channel === "y"
+      ? "Y"
+      : channel === "theta"
+        ? "Theta"
+        : "Radial";
+  const operation = `remove${prefix}Axis`;
+  const graphicIds = axisGraphicIds(channel);
+  return action(
+    {
+      op: operation,
+      description: `Remove the complete ${channel}-axis resource.`
+    },
+    function (args = {}) {
+      validateKeys(args, OPTIONS, operation);
+      const semantic = this.semanticSpec.guides.axis?.[channel];
+      const config = this.guideConfigs.axis?.[channel];
+      const hasGraphic = graphicIds.some(
+        id => this.graphicSpec.objects[id] !== undefined
+      );
+      if (semantic === undefined && config === undefined && !hasGraphic) {
+        throw new Error(`${operation} requires an existing ${channel}-axis.`);
+      }
+      if (args.scale !== undefined && semantic?.scale !== args.scale) {
+        throw new Error(`${operation} found no axis for scale "${args.scale}".`);
+      }
+      if (args.coordinate !== undefined && semantic?.coordinate !== args.coordinate) {
+        throw new Error(
+          `${operation} found no axis for coordinate "${args.coordinate}".`
+        );
+      }
+      let next = semantic === undefined
+        ? this
+        : this.editSemantic({
+            property: `guide.axis.${channel}`,
+            remove: true
+          });
+      for (const id of graphicIds) {
+        if (next.graphicSpec.objects[id] !== undefined) {
+          next = next.editGraphics({ target: id, remove: true });
+        }
+      }
+      return next._withoutMaterializationConfig(["guides", "axis", channel]);
+    }
+  );
+}
+
+export const removeXAxis = makeRemoveAxis("x");
+export const removeYAxis = makeRemoveAxis("y");
+export const removeThetaAxis = makeRemoveAxis("theta");
+export const removeRadialAxis = makeRemoveAxis("radius");

package/src/actions/guides/axes/tickGroups.js

@@ -1,6 +1,6 @@
 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";
 
 const CREATE_OPTIONS = Object.freeze([
   "scale",
@@ -38,7 +38,12 @@ function validateNested(value, supported, label) {
 }
 
 function validateArgs(args, operation, create) {
-  validateKeys(args, create ? CREATE_OPTIONS : EDIT_OPTIONS, operation);
+  validateOptionObject(
+    args,
+    create ? CREATE_OPTIONS : EDIT_OPTIONS,
+    operation,
+    { allowEmpty: create }
+  );
 
   if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) {
     throw new Error(`${operation} cannot use count and values together.`);
@@ -52,9 +57,6 @@ function validateArgs(args, operation, create) {
     validateNested(args.labels, LABEL_OPTIONS, `${operation}.labels`);
   }
 
-  if (!create && Object.keys(args).length === 0) {
-    throw new TypeError(`${operation} requires at least one option.`);
-  }
 }
 
 function select(source, keys) {

package/src/actions/guides/axes/ticks.js

@@ -2,14 +2,15 @@ import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   validateNonEmptyString,
-  validateNonNegativeFinite
+  validateNonNegativeFinite,
+  validateOptionObject
 } from "../../../core/validation.js";
 import { resolveGraphicBounds } from "../../../layout/canvas.js";
 import {
   isTransformedScaleType,
   mapContinuousScaleValues,
   mapOrdinalPositionValues
-} from "../../../grammar/scales.js";
+} from "../../../grammar/scales/index.js";
 import {
   DEFAULT_TICK_COUNT,
   inferHistogramBoundaries,
@@ -21,7 +22,7 @@ import {
   resolveAxisTickGeometry,
   validateAxisPosition
 } from "./policy.js";
-import { resolvePlotGraphicPlacement } from
+import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
 const OPTIONS = Object.freeze(["scale", "position", "count", "values", "length", "color", "lineWidth"]);
@@ -33,7 +34,11 @@ const DEFAULTS = Object.freeze({
 });
 
 function validateOptions(args, operation, create) {
-  for (const key of Object.keys(args)) if (!OPTIONS.includes(key) || (!create && key === "scale")) throw new Error(`Unknown ${operation} option "${key}".`);
+  validateOptionObject(
+    args,
+    create ? OPTIONS : OPTIONS.filter(key => key !== "scale"),
+    operation
+  );
   if (Object.hasOwn(args, "count") && Object.hasOwn(args, "values")) throw new Error(`${operation} cannot use count and values together.`);
 }
 
@@ -84,7 +89,7 @@ function geometry(program, channel, config) {
       length: config.length
     })
   };
-  const canvas = program.graphicSpec.objects.canvas?.properties;
+  const canvas = findCanvasGraphic(program)?.properties;
   const coordinates = channel === "x"
     ? [...resolved.x1, ...resolved.x2, resolved.y1, resolved.y2]
     : [resolved.x1, resolved.x2, ...resolved.y1, ...resolved.y2];

package/src/actions/guides/axes/titles.js

@@ -11,7 +11,7 @@ import {
   isTransformedScaleType,
   mapContinuousScaleValues,
   mapOrdinalPositionValues
-} from "../../../grammar/scales.js";
+} from "../../../grammar/scales/index.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from
   "../../../theme/defaults.js";
 import { findDataset } from "../../../selectors/datasets.js";
@@ -22,7 +22,7 @@ import {
   resolveAxisTitleGeometry,
   validateAxisPosition
 } from "./policy.js";
-import { resolvePlotGraphicPlacement } from
+import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
 const CREATE_OPTIONS = Object.freeze([
@@ -52,7 +52,7 @@ function validateConfig(channel, config) {
   if (typeof config.fontWeight !== "string" && !Number.isFinite(config.fontWeight)) throw new TypeError("Axis title fontWeight must be a string or number.");
 }
 
-function inferText(program, channel, scaleId) {
+export function inferAxisTitleText(program, channel, scaleId) {
   const titles = new Set();
   const primaryTitles = new Set();
   for (const layer of program.semanticSpec.layers) {
@@ -138,7 +138,7 @@ function resolveGeometry(program, channel, config) {
   const sine = Math.sin(config.rotation);
   const extentX = Math.abs(cosine) * width / 2 + Math.abs(sine) * height / 2;
   const extentY = Math.abs(sine) * width / 2 + Math.abs(cosine) * height / 2;
-  const canvas = program.graphicSpec.objects.canvas?.properties;
+  const canvas = findCanvasGraphic(program)?.properties;
   const newEdgeFits = config.position === "top"
     ? geometry.y - extentY >= 0
     : config.position === "right"
@@ -184,7 +184,7 @@ function makeEdit(channel) {
     const resolvedTitle = explicitText
       ? validateText(text)
       : config.inferredText === true
-        ? inferText(this, channel, config.scale)
+        ? inferAxisTitleText(this, channel, config.scale)
         : this.semanticSpec.guides.axis?.[channel]?.title;
     if (resolvedTitle !== this.semanticSpec.guides.axis?.[channel]?.title) {
       next = next.editSemantic({
@@ -218,7 +218,9 @@ function makeCreate(channel) {
     if (guideScale && guideScale !== scale) throw new Error(`${operation.create} conflicts with the existing axis scale.`);
     if (this.graphicSpec.objects[operation.graphic]) throw new Error(`${operation.create} requires a missing axis title.`);
     const inferredText = !Object.hasOwn(args, "text");
-    const text = validateText(args.text ?? inferText(this, channel, scale));
+    const text = validateText(
+      args.text ?? inferAxisTitleText(this, channel, scale)
+    );
     const position = args.position ?? defaultAxisPosition(channel);
     const inferredRotation = !Object.hasOwn(args, "rotation");
     const config = {