ggaction 0.0.4 → 0.0.6

package/src/actions/guides/applicability.js

@@ -7,9 +7,21 @@ import {
   POLAR_POSITION_CHANNELS
 } from "../../core/vocabulary.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findUpstreamTransform } from
+  "../../materialization/dataProvenance.js";
+
+function isHorizonLayer(program, layer) {
+  return findUpstreamTransform(
+    program,
+    findDataset(program, layer.data),
+    "horizon"
+  ) !== undefined;
+}
 
 function hasEncoding(program, channel, { scaled = false, grid = false } = {}) {
   return program.semanticSpec.layers.some(layer => {
+    if (isHorizonLayer(program, layer) && channel !== "x") return false;
     const encoding = layer.encoding?.[channel];
     if (!scaled && !grid) return encoding !== undefined;
     if (encoding?.scale === undefined) return false;
@@ -33,22 +45,24 @@ function positionalApplicability(program, channels) {
 
 export function hasInferableLegend(program) {
   return program.semanticSpec.layers.some(layer =>
-    (layer.mark?.type === "point" &&
-      layer.encoding?.opacity?.scale !== undefined) ||
-    (layer.mark?.type === "point" &&
-      layer.encoding?.size?.scale !== undefined) ||
-    (layer.mark?.type === "point" &&
-      layer.encoding?.color?.scale !== undefined &&
-      (layer.encoding?.shape?.scale !== undefined ||
-        ["sequential", "quantize", "quantile", "threshold"].includes(
-          findSemanticScale(program, layer.encoding.color.scale)?.type
-        ))) ||
-    (layer.mark?.type === "line" &&
-      ["color", "strokeDash"].some(
-        channel => layer.encoding?.[channel]?.scale !== undefined
-      )) ||
-    (["bar", "area", "arc", "rect"].includes(layer.mark?.type) &&
-      layer.encoding?.color?.scale !== undefined)
+    !isHorizonLayer(program, layer) && (
+      (layer.mark?.type === "point" &&
+        layer.encoding?.opacity?.scale !== undefined) ||
+      (layer.mark?.type === "point" &&
+        layer.encoding?.size?.scale !== undefined) ||
+      (layer.mark?.type === "point" &&
+        layer.encoding?.color?.scale !== undefined &&
+        (layer.encoding?.shape?.scale !== undefined ||
+          ["sequential", "quantize", "quantile", "threshold"].includes(
+            findSemanticScale(program, layer.encoding.color.scale)?.type
+          ))) ||
+      (layer.mark?.type === "line" &&
+        ["color", "strokeDash"].some(
+          channel => layer.encoding?.[channel]?.scale !== undefined
+        )) ||
+      (["bar", "area", "arc", "rect"].includes(layer.mark?.type) &&
+        layer.encoding?.color?.scale !== undefined)
+    )
   );
 }
 
@@ -58,12 +72,22 @@ export function resolveGuideApplicability(program) {
     CARTESIAN_POSITION_CHANNELS
   );
   const polar = positionalApplicability(program, POLAR_POSITION_CHANNELS);
+  const parallel = program.semanticSpec.layers.some(layer =>
+    layer.encoding?.parallel?.dimensions?.length >= 2
+  );
   return Object.freeze({
     axes: Object.freeze({
       cartesian: CARTESIAN_POSITION_CHANNELS.some(
         channel => cartesian[channel].axis
       ),
-      polar: POLAR_POSITION_CHANNELS.some(channel => polar[channel].axis)
+      polar: POLAR_POSITION_CHANNELS.some(channel => polar[channel].axis),
+      parallel,
+      directions: Object.freeze({
+        x: cartesian.x.axis,
+        y: cartesian.y.axis,
+        theta: polar.theta.axis,
+        radius: polar.radius.axis
+      })
     }),
     grid: Object.freeze({
       cartesian: CARTESIAN_POSITION_CHANNELS.some(
@@ -90,6 +114,9 @@ export function resolveAutomaticGridOptions(program) {
       ...(directions.radial ? { radial: {} } : {})
     });
   }
+  if (directions.vertical && !directions.horizontal) {
+    return Object.freeze({ horizontal: false, vertical: {} });
+  }
 
   const barOrientations = program.semanticSpec.layers
     .map(resolveBarOrientation)

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

@@ -9,7 +9,9 @@ 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"]);
+const COORDINATE_API_TYPES = new Set([
+  "auto", "cartesian", "polar", "parallel"
+]);
 
 function validateAxisOption(value, channel) {
   if (value !== undefined && value !== false && !isPlainObject(value)) {
@@ -47,6 +49,9 @@ function inspectChannels(layers) {
     layer =>
       layer.encoding?.theta !== undefined || layer.encoding?.radius !== undefined
   );
+  const parallelLayers = layers.filter(
+    layer => layer.encoding?.parallel !== undefined
+  );
   const hasMixedLayer = layers.some(layer => {
     const hasCartesian =
       layer.encoding?.x !== undefined || layer.encoding?.y !== undefined;
@@ -61,7 +66,7 @@ function inspectChannels(layers) {
     );
   }
 
-  return { cartesianLayers, polarLayers };
+  return { cartesianLayers, polarLayers, parallelLayers };
 }
 
 function resolveCoordinate(program, descriptor, cartesianLayers) {
@@ -185,7 +190,7 @@ const createAxes = action(
   },
   function (args = {}) {
     const coordinateDescriptor = validateArgs(args);
-    const { cartesianLayers, polarLayers } = inspectChannels(
+    const { cartesianLayers, polarLayers, parallelLayers } = inspectChannels(
       this.semanticSpec.layers
     );
     const requestedCoordinateType = coordinateDescriptor.id === undefined
@@ -194,6 +199,35 @@ const createAxes = action(
     const explicitlyPolar = coordinateDescriptor.type === "polar" ||
       requestedCoordinateType === "polar" ||
       args.theta !== undefined || args.radius !== undefined;
+    const explicitlyParallel = coordinateDescriptor.type === "parallel" ||
+      requestedCoordinateType === "parallel";
+    if (parallelLayers.length > 0 && (
+      (cartesianLayers.length === 0 && polarLayers.length === 0) ||
+      explicitlyParallel
+    )) {
+      if (
+        args.x !== undefined || args.y !== undefined ||
+        args.theta !== undefined || args.radius !== undefined
+      ) {
+        throw new Error(
+          "createAxes channel options are not supported for Parallel axes."
+        );
+      }
+      const candidates = coordinateDescriptor.id === undefined
+        ? parallelLayers
+        : parallelLayers.filter(layer =>
+            layer.coordinate === coordinateDescriptor.id
+          );
+      if (candidates.length !== 1) {
+        throw new Error(
+          "createAxes requires coordinate.id when one Parallel layer cannot be inferred."
+        );
+      }
+      return this.createParallelAxes({
+        target: candidates[0].id,
+        coordinate: candidates[0].coordinate
+      });
+    }
     if (polarLayers.length > 0 &&
         (cartesianLayers.length === 0 || explicitlyPolar)) {
       if (coordinateDescriptor.type === "cartesian") {

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

@@ -18,11 +18,19 @@ const TITLE_OPTIONS = Object.freeze([
   "text", "at", "offset", "rotation", "color", "fontSize",
   "fontFamily", "fontWeight"
 ]);
+const COMPONENTS = Object.freeze({
+  line: Object.freeze({ suffix: "Line", config: "line" }),
+  ticks: Object.freeze({ suffix: "Ticks", config: "ticks" }),
+  labels: Object.freeze({ suffix: "Labels", config: "labels" }),
+  title: Object.freeze({ suffix: "Title", config: "title" })
+});
 
-function validateNested(args, key, options, operation) {
+function validateNested(args, key, options, operation, { allowFalse = false } = {}) {
   if (!Object.hasOwn(args, key)) return;
+  if (allowFalse && args[key] === false) return;
   if (!isPlainObject(args[key])) {
-    throw new TypeError(`${operation}.${key} must be a plain object.`);
+    const accepted = allowFalse ? "false or a plain object" : "a plain object";
+    throw new TypeError(`${operation}.${key} must be ${accepted}.`);
   }
   validateKeys(args[key], options, `${operation}.${key}`);
 }
@@ -33,11 +41,12 @@ function validateArgs(args, operation) {
     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);
+  const removable = { allowFalse: true };
+  validateNested(args, "line", LINE_OPTIONS, operation, removable);
+  validateNested(args, "ticks", TICK_OPTIONS, operation, removable);
+  validateNested(args, "labels", LABEL_OPTIONS, operation, removable);
+  validateNested(args, "ticksAndLabels", GROUP_OPTIONS, operation, removable);
+  validateNested(args, "title", TITLE_OPTIONS, operation, removable);
   if (args.ticksAndLabels !== undefined && (
     args.ticks !== undefined || args.labels !== undefined
   )) {
@@ -45,10 +54,10 @@ function validateArgs(args, operation) {
       `${operation} cannot combine ticksAndLabels with ticks or labels.`
     );
   }
-  if (args.ticksAndLabels?.ticks !== undefined) {
+  if (args.ticksAndLabels !== false && args.ticksAndLabels?.ticks !== undefined) {
     validateNested(args.ticksAndLabels, "ticks", ["length", "color", "lineWidth"], `${operation}.ticksAndLabels`);
   }
-  if (args.ticksAndLabels?.labels !== undefined) {
+  if (args.ticksAndLabels !== false && args.ticksAndLabels?.labels !== undefined) {
     validateNested(args.ticksAndLabels, "labels", [
       "offset", "format", "color", "fontSize", "fontFamily", "fontWeight"
     ], `${operation}.ticksAndLabels`);
@@ -63,10 +72,114 @@ function names(channel) {
     ticks: `edit${prefix}AxisTicks`,
     labels: `edit${prefix}AxisLabels`,
     group: `edit${prefix}AxisTicksAndLabels`,
-    title: `edit${prefix}AxisTitle`
+    title: `edit${prefix}AxisTitle`,
+    remove: `remove${prefix}Axis`
   };
 }
 
+function graphicId(channel, component) {
+  return `${channel}Axis${COMPONENTS[component].suffix}`;
+}
+
+function hasComponent(program, channel, component) {
+  return program.graphicSpec.objects[graphicId(channel, component)] !== undefined ||
+    program.guideConfigs.axis?.[channel]?.[COMPONENTS[component].config] !== undefined ||
+    (component === "title" &&
+      program.semanticSpec.guides.axis?.[channel]?.title !== undefined);
+}
+
+function assertRemovable(program, channel, component, operation) {
+  if (!hasComponent(program, channel, component)) {
+    throw new Error(
+      `${operation}.${component} requires an existing ${channel}-axis ${component}.`
+    );
+  }
+}
+
+function removeComponent(program, channel, component) {
+  const id = graphicId(channel, component);
+  let next = program;
+
+  if (
+    component === "title" &&
+    next.semanticSpec.guides.axis?.[channel]?.title !== undefined
+  ) {
+    next = next.editSemantic({
+      property: `guide.axis.${channel}.title`,
+      remove: true
+    });
+  }
+  if (next.graphicSpec.objects[id] !== undefined) {
+    next = next.editGraphics({ target: id, remove: true });
+  }
+  return next._withoutMaterializationConfig([
+    "guides", "axis", channel, COMPONENTS[component].config
+  ]);
+}
+
+function buildPlan(program, channel, args, operation) {
+  const shared = Object.hasOwn(args, "position")
+    ? { position: args.position }
+    : {};
+  const plan = [];
+  const addLeaf = (component, edit) => {
+    const value = args[component];
+    if (value === false) {
+      assertRemovable(program, channel, component, operation.operation);
+      plan.push({ kind: "remove", component });
+    } else if (value !== undefined) {
+      plan.push({ kind: "edit", operation: edit, args: { ...shared, ...value } });
+    } else if (args.position !== undefined && hasComponent(program, channel, component)) {
+      plan.push({ kind: "edit", operation: edit, args: shared });
+    }
+  };
+
+  addLeaf("line", operation.line);
+  if (args.ticksAndLabels === false) {
+    assertRemovable(program, channel, "ticks", operation.operation);
+    assertRemovable(program, channel, "labels", operation.operation);
+    plan.push(
+      { kind: "remove", component: "ticks" },
+      { kind: "remove", component: "labels" }
+    );
+  } else if (args.ticksAndLabels !== undefined) {
+    plan.push({
+      kind: "edit",
+      operation: operation.group,
+      args: { ...shared, ...args.ticksAndLabels }
+    });
+  } else {
+    addLeaf("ticks", operation.ticks);
+    addLeaf("labels", operation.labels);
+  }
+  addLeaf("title", operation.title);
+
+  if (plan.length === 0) {
+    throw new Error(`${operation.operation} requires an existing ${channel}-axis component.`);
+  }
+  return plan;
+}
+
+function applyPlan(program, channel, plan, operation) {
+  let next = program;
+  for (const step of plan) {
+    next = step.kind === "remove"
+      ? removeComponent(next, channel, step.component)
+      : next[step.operation](step.args);
+  }
+
+  const hasRetainedGraphic = Object.keys(COMPONENTS).some(
+    component => next.graphicSpec.objects[graphicId(channel, component)] !== undefined
+  );
+  if (!hasRetainedGraphic && (
+    next.semanticSpec.guides.axis?.[channel] !== undefined ||
+    next.guideConfigs.axis?.[channel] !== undefined
+  )) {
+    next = next[operation.remove]();
+  }
+  return next;
+}
+
 function makeEditAxis(channel) {
   const operation = names(channel);
   return action(
@@ -76,43 +189,12 @@ function makeEditAxis(channel) {
     },
     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 plan = buildPlan(this, channel, args, operation);
+
+      // Run the complete proposal against an immutable speculative branch so a
+      // later leaf failure cannot begin the returned action trace or state.
+      applyPlan(this, channel, plan, operation);
+      return applyPlan(this, channel, plan, operation);
     }
   );
 }

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

@@ -12,6 +12,7 @@ import {
   removeXAxis,
   removeYAxis
 } from "./remove.js";
+import { registerParallelAxisActions } from "./parallel.js";
 
 export function registerGuideAxisActions(ProgramClass) {
   registerAxisLineActions(ProgramClass);
@@ -22,6 +23,7 @@ export function registerGuideAxisActions(ProgramClass) {
   registerAxisActions(ProgramClass);
   registerAxisCollectionActions(ProgramClass);
   registerCompleteAxisEditActions(ProgramClass);
+  registerParallelAxisActions(ProgramClass);
   ProgramClass.prototype.removeXAxis = removeXAxis;
   ProgramClass.prototype.removeYAxis = removeYAxis;
   ProgramClass.prototype.removeThetaAxis = removeThetaAxis;

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

@@ -27,6 +27,7 @@ import {
 } from "./policy.js";
 import { findCanvasGraphic, resolvePlotGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
+import { resolveTextBounds } from "../../../core/textMetrics.js";
 
 const OPTIONS = Object.freeze([
   "scale", "position", "count", "values", "offset", "format", "color",
@@ -122,14 +123,18 @@ function resolve(program, channel, config) {
     })
   };
   const canvas = findCanvasGraphic(program)?.properties;
-  const maximumTextWidth = Math.max(
-    0,
-    ...text.map(value => [...value].length * config.fontSize * 0.6)
-  );
+  const labelBounds = text.map((value, index) => resolveTextBounds({
+    x: Array.isArray(resolved.x) ? resolved.x[index] : resolved.x,
+    y: Array.isArray(resolved.y) ? resolved.y[index] : resolved.y,
+    text: value,
+    fontSize: config.fontSize,
+    textAlign: resolved.textAlign,
+    textBaseline: resolved.textBaseline
+  }));
   const fits = config.position === "top"
-    ? resolved.y - config.fontSize >= 0
+    ? labelBounds.every(item => item.top >= 0)
     : config.position === "right"
-      ? resolved.x + maximumTextWidth <= canvas?.width
+      ? labelBounds.every(item => item.right <= canvas?.width)
       : true;
   if (!canvas || !fits) {
     throw new Error(`The ${channel}-axis labels do not fit the Canvas margin.`);

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

@@ -0,0 +1,86 @@
+import { validateUserId } from "../../../../core/identifiers.js";
+import {
+  isTransformedScaleType,
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues,
+  transformedTicks
+} from "../../../../grammar/scales/index.js";
+import { niceTicks } from "../../../../grammar/ticks.js";
+import { resolveGraphicBounds } from "../../../../layout/canvas.js";
+import { findCoordinate } from "../../../../selectors/coordinates.js";
+import { findLayer } from "../../../../selectors/layers.js";
+
+export function requireParallelAxisLayer(program, target) {
+  const layer = findLayer(program, target);
+  const coordinate = layer === undefined
+    ? undefined
+    : findCoordinate(program, layer.coordinate);
+  if (
+    layer?.mark?.type !== "line" ||
+    coordinate?.type !== "parallel" ||
+    layer.encoding?.parallel?.dimensions?.length < 2
+  ) {
+    throw new Error(`Parallel axes require an encoded Parallel line "${target}".`);
+  }
+  return { coordinate, dimensions: layer.encoding.parallel.dimensions, layer };
+}
+
+export function resolveParallelAxisTarget(program, requested) {
+  if (requested !== undefined) {
+    const target = validateUserId(requested, "Parallel axes target");
+    requireParallelAxisLayer(program, target);
+    return target;
+  }
+  const candidates = program.semanticSpec.layers.filter(layer => {
+    const coordinate = findCoordinate(program, layer.coordinate);
+    return layer.encoding?.parallel !== undefined && coordinate?.type === "parallel";
+  });
+  if (candidates.length !== 1) {
+    throw new Error(
+      "Parallel axes require target when one Parallel layer cannot be inferred."
+    );
+  }
+  return candidates[0].id;
+}
+
+function ticksForScale(scale) {
+  if (["ordinal", "band", "point"].includes(scale.type)) return scale.domain;
+  if (isTransformedScaleType(scale.type)) {
+    return transformedTicks(scale.type, scale.domain, 5, {
+      ...(scale.base === undefined ? {} : { base: scale.base }),
+      ...(scale.exponent === undefined ? {} : { exponent: scale.exponent }),
+      ...(scale.constant === undefined ? {} : { constant: scale.constant })
+    });
+  }
+  return niceTicks(scale.domain, 5);
+}
+
+function formatValue(value) {
+  if (Number.isFinite(value) && Math.abs(value) >= 1000 && value % 1000 === 0) {
+    return `${value / 1000}k`;
+  }
+  return String(value);
+}
+
+export function resolveParallelAxisValues(program, dimensions) {
+  const bounds = resolveGraphicBounds(program);
+  const step = bounds.width / (dimensions.length - 1);
+  const axes = dimensions.map((dimension, index) => {
+    const scale = program.resolvedScales[dimension.scale];
+    if (scale === undefined) {
+      throw new Error(`Parallel axis requires resolved scale "${dimension.scale}".`);
+    }
+    const values = ticksForScale(scale);
+    const y = ["ordinal", "band", "point"].includes(scale.type)
+      ? mapOrdinalPositionValues(values, scale)
+      : mapContinuousScaleValues(values, scale);
+    return {
+      ...dimension,
+      x: bounds.x + step * index,
+      values,
+      y,
+      labels: values.map(formatValue)
+    };
+  });
+  return { axes, bounds };
+}