ggaction 0.0.10 → 0.0.12

package/src/actions/errorBands/edit.js

@@ -3,17 +3,44 @@ import { isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
 import {
   validateOptionObject,
+  validateKeys,
   validateNonEmptyString,
+  validateNonNegativeFinite,
   validateUnitInterval
 } from "../../core/validation.js";
 import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
-import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
+import { normalizeStrokeDashPattern } from "../../grammar/scales/index.js";
+import { findLayer } from "../../selectors/layers.js";
+import { removeOwnedMark } from "../marks/remove.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
-import { planIntervalEdit } from "../data/intervalEdit.js";
 import {
-  ERROR_BAND_BOUNDARY_OPTIONS,
-  resolveBoundaryAppearance
-} from "./options.js";
+  applyIntervalRevision,
+  ownOptions,
+  planIntervalEdit,
+  releaseIntervalRevision,
+  resolveIntervalOwner
+} from "../data/intervalEdit.js";
+
+export const ERROR_BAND_BOUNDARY_OPTIONS = Object.freeze([
+  "stroke", "strokeWidth", "strokeDash", "opacity", "curve"
+]);
+
+export function resolveBoundaryAppearance(value, { defaults, operation }) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${operation} must be a plain object.`);
+  }
+  validateKeys(value, ERROR_BAND_BOUNDARY_OPTIONS, operation);
+  const stroke = value.stroke ?? defaults.stroke;
+  const strokeWidth = value.strokeWidth ?? defaults.strokeWidth;
+  const strokeDash = value.strokeDash ?? defaults.strokeDash;
+  const opacity = value.opacity ?? defaults.opacity;
+  const curve = validateCurveInterpolation(value.curve ?? defaults.curve);
+  validateNonEmptyString(stroke, `${operation} stroke`);
+  validateNonNegativeFinite(strokeWidth, `${operation} strokeWidth`);
+  const resolvedStrokeDash = normalizeStrokeDashPattern(strokeDash);
+  validateUnitInterval(opacity, `${operation} opacity`);
+  return { stroke, strokeWidth, strokeDash: resolvedStrokeDash, opacity, curve };
+}
 
 const EDIT_OPTIONS = Object.freeze([
   "target", "fill", "opacity", "curve", "statistics", "boundaries"
@@ -25,16 +52,27 @@ const REMATERIALIZE_OPTIONS = Object.freeze([
   "id", ...ERROR_BAND_BOUNDARY_OPTIONS
 ]);
 
+export function errorBandBoundaries(config) {
+  return [
+    [
+      config.lowerBoundaryId,
+      config.fields?.lower ?? config.lowerField,
+      "lower"
+    ],
+    [
+      config.upperBoundaryId,
+      config.fields?.upper ?? config.upperField,
+      "upper"
+    ]
+  ];
+}
+
 function resolveOwner(program, requested) {
-  const target = requested === undefined
-    ? undefined
-    : validateUserId(requested, "Error-band id");
-  return resolveEligibleLayer(program, {
-    target,
+  return resolveIntervalOwner(program, requested, {
+    idLabel: "Error-band id",
     label: "error band",
-    predicate: layer =>
-      layer.mark?.type === "area" &&
-      program.markConfigs[layer.id]?.errorBand !== undefined
+    mark: "area",
+    config: "errorBand"
   });
 }
 
@@ -90,31 +128,7 @@ function createBoundary(program, owner, id, bound, appearance) {
 }
 
 function removeBoundary(program, id) {
-  if (findLayer(program, id) === undefined) return program;
-  const selectionIds = Object.entries(
-    program.materializationConfigs.selections ?? {}
-  ).filter(([, config]) => config.target === id).map(([selection]) => selection);
-  let next = program;
-  for (const [highlight, config] of Object.entries(
-    program.materializationConfigs.highlights ?? {}
-  )) {
-    if (config.target === id || selectionIds.includes(config.selection)) {
-      next = next._withoutMaterializationConfig(["highlights", highlight]);
-    }
-  }
-  for (const selection of selectionIds) {
-    next = next._withoutMaterializationConfig(["selections", selection]);
-  }
-  return next
-    .editSemantic({ property: `layer[${id}]`, remove: true })
-    .editGraphics({ target: id, remove: true })
-    ._withoutMaterializationConfig(["marks", id])
-    ._withContext({
-      ...(program.context.currentMark === id ? { currentMark: undefined } : {}),
-      ...(selectionIds.includes(program.context.currentSelection)
-        ? { currentSelection: undefined }
-        : {})
-    });
+  return removeOwnedMark(program, id);
 }
 
 export const rematerializeErrorBandBoundary = action(
@@ -178,7 +192,8 @@ export const editErrorBand = action(
           data: errorBand.data,
           consumers: [
             owner.id,
-            ...[errorBand.lowerBoundaryId, errorBand.upperBoundaryId]
+            ...errorBandBoundaries(errorBand)
+              .map(([id]) => id)
               .filter(id => findLayer(this, id) !== undefined)
           ],
           statistics: args.statistics,
@@ -195,58 +210,43 @@ export const editErrorBand = action(
       );
     }
 
-    const applyEdit = program => {
-      let next = program;
-      if (interval.changed) {
-        next = next.createIntervalData(interval.dataArgs);
-        for (const rebind of interval.revision.rebinds) {
-          next = next.rebindLayerData(rebind);
+    let next = applyIntervalRevision(this, interval);
+    if (interval.changed) errorBand.data = interval.revision.id;
+    next = next
+      ._withMarkConfig(owner.id, { ...config, errorBand })
+      .rematerializeAreaMark({ id: owner.id });
+    if (Object.hasOwn(args, "boundaries")) {
+      if (args.boundaries === false) {
+        next = removeBoundary(next, errorBand.lowerBoundaryId);
+        next = removeBoundary(next, errorBand.upperBoundaryId);
+      } else if (Object.keys(args.boundaries).length === 0) {
+        for (const [id, bound] of errorBandBoundaries(errorBand)) {
+          next = findLayer(next, id) === undefined
+            ? createBoundary(
+                next,
+                owner.id,
+                id,
+                bound,
+                defaultBoundaryAppearance(next, owner.id)
+              )
+            : interval.changed
+              ? next.rematerializeLineMark({ id })
+              : next;
         }
-        errorBand.data = interval.revision.id;
+      } else {
+        next = next.editErrorBandBoundary({
+          target: owner.id,
+          ...args.boundaries
+        });
       }
-      next = next
-        ._withMarkConfig(owner.id, { ...config, errorBand })
-        .rematerializeAreaMark({ id: owner.id });
-      if (Object.hasOwn(args, "boundaries")) {
-        if (args.boundaries === false) {
-          next = removeBoundary(next, errorBand.lowerBoundaryId);
-          next = removeBoundary(next, errorBand.upperBoundaryId);
-        } else if (Object.keys(args.boundaries).length === 0) {
-          for (const [id, bound] of [
-            [errorBand.lowerBoundaryId, errorBand.lowerField],
-            [errorBand.upperBoundaryId, errorBand.upperField]
-          ]) {
-            next = findLayer(next, id) === undefined
-              ? createBoundary(
-                  next,
-                  owner.id,
-                  id,
-                  bound,
-                  defaultBoundaryAppearance(next, owner.id)
-                )
-              : interval.changed
-                ? next.rematerializeLineMark({ id })
-                : next;
-          }
-        } else {
-          next = next.editErrorBandBoundary({
-            target: owner.id,
-            ...args.boundaries
-          });
-        }
-      } else if (interval.changed) {
-        for (const id of [errorBand.lowerBoundaryId, errorBand.upperBoundaryId]) {
-          if (findLayer(next, id) !== undefined) {
-            next = next.rematerializeLineMark({ id });
-          }
+    } else if (interval.changed) {
+      for (const [id] of errorBandBoundaries(errorBand)) {
+        if (findLayer(next, id) !== undefined) {
+          next = next.rematerializeLineMark({ id });
         }
       }
-      return interval.changed
-        ? next.releaseDerivedData(interval.revision.release)
-        : next;
-    };
-    if (interval.changed || Object.hasOwn(args, "boundaries")) applyEdit(this);
-    return applyEdit(this);
+    }
+    return releaseIntervalRevision(next, interval);
   }
 );
 
@@ -270,13 +270,9 @@ export const editErrorBandBoundary = action(
     }
     const owner = resolveOwner(this, args.target);
     const config = this.markConfigs[owner.id].errorBand;
-    const patch = Object.fromEntries(
-      ERROR_BAND_BOUNDARY_OPTIONS
-        .filter(key => Object.hasOwn(args, key))
-        .map(key => [key, args[key]])
-    );
+    const patch = ownOptions(args, ERROR_BAND_BOUNDARY_OPTIONS);
     const ids = boundary === "both"
-      ? [config.lowerBoundaryId, config.upperBoundaryId]
+      ? errorBandBoundaries(config).map(([id]) => id)
       : [boundary === "lower" ? config.lowerBoundaryId : config.upperBoundaryId];
     const plans = ids.map(id => {
       const existing = findLayer(this, id) !== undefined;

package/src/actions/errorBands/index.js

@@ -1,5 +1,4 @@
-import { createErrorBand } from "./create.js";
-import { createErrorBandBoundary } from "./components.js";
+import { createErrorBand, createErrorBandBoundary } from "./create.js";
 import {
   editErrorBand,
   editErrorBandBoundary,

package/src/actions/errorBars/create.js

@@ -1,9 +1,20 @@
 import { action } from "../../core/action.js";
-import { validateKeys } from "../../core/validation.js";
+import {
+  validateKeys,
+  validateOptionObject
+} from "../../core/validation.js";
 import { findLayer } from "../../selectors/layers.js";
+import { findDataset } from "../../selectors/datasets.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
-import { resolveErrorBarAppearance } from "./options.js";
-import { resolveErrorBar } from "./resolve.js";
+import {
+  readNominalField,
+  validateCategoricalFieldType
+} from "../../grammar/scales/index.js";
+import { normalizeOffsetPadding } from "../../grammar/bars/geometry.js";
+import { createResolvedIntervalData, ownOptions } from
+  "../data/intervalEdit.js";
+import { resolveIntervalComposite } from "../intervals/resolve.js";
+import { errorBarCaps, resolveErrorBarAppearance } from "./edit.js";
 
 const OPTIONS = Object.freeze([
   "id",
@@ -11,6 +22,8 @@ const OPTIONS = Object.freeze([
   "data",
   "x",
   "y",
+  "xOffset",
+  "yOffset",
   "groupBy",
   "coordinate",
   "caps",
@@ -21,13 +34,92 @@ const OPTIONS = Object.freeze([
   "opacity"
 ]);
 
-function resolveAppearance(args) {
-  const appearanceArgs = Object.fromEntries(
-    ["caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"]
-      .filter(key => Object.hasOwn(args, key))
-      .map(key => [key, args[key]])
+const OFFSET_OPTIONS = Object.freeze([
+  "field", "fieldType", "scale", "paddingInner", "paddingOuter"
+]);
+
+const ERROR_BAR_POLICY = Object.freeze({
+  operation: "createErrorBar",
+  resourceLabel: "error-bar",
+  defaultId: "errorBar",
+  ownerLabel: "Error-bar id",
+  positionTypes: Object.freeze([
+    "quantitative", "nominal", "ordinal", "temporal"
+  ]),
+  defaultPositionType: "nominal",
+  defaultIntervalChannel: "y",
+  scaleDefaults: () => ({}),
+  intervalScaleDefaults: Object.freeze({ nice: true, zero: false }),
+  allowExplicitGrouping: false,
+  ambiguousMessage:
+    "createErrorBar requires one quantitative interval axis and one compatible position axis; use interval options to disambiguate two quantitative channels."
+});
+
+function resolveErrorBar(program, args) {
+  const resolved = resolveIntervalComposite(program, args, ERROR_BAR_POLICY);
+  const offset = resolveErrorBarOffset(program, args, resolved);
+  const groupBy = resolved.interval.mode === "statistical" && offset !== undefined
+    ? [...new Set([...resolved.groupBy, offset.field])]
+    : resolved.groupBy;
+  return {
+    ...resolved,
+    groupBy,
+    offset,
+    lowerCapId: `${resolved.id}LowerCap`,
+    upperCapId: `${resolved.id}UpperCap`
+  };
+}
+
+function resolveErrorBarOffset(program, args, resolved) {
+  const channel = `${resolved.position.channel}Offset`;
+  const incompatible = channel === "xOffset" ? "yOffset" : "xOffset";
+  if (args[incompatible] !== undefined) {
+    throw new Error(
+      `createErrorBar ${incompatible} does not match the ${resolved.orientation} interval orientation.`
+    );
+  }
+  const explicit = args[channel] === undefined
+    ? undefined
+    : validateOptionObject(args[channel], OFFSET_OPTIONS, `createErrorBar ${channel}`);
+  const inferred = resolved.sourceLayer?.encoding?.[channel];
+  if (explicit === undefined && inferred === undefined) return undefined;
+  if (!["nominal", "ordinal"].includes(resolved.position.fieldType)) {
+    throw new Error(
+      `createErrorBar ${channel} requires a categorical ${resolved.position.channel} position.`
+    );
+  }
+  const field = explicit?.field ?? inferred?.field;
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError(`createErrorBar ${channel} field must be a non-empty string.`);
+  }
+  const fieldType = validateCategoricalFieldType(
+    explicit?.fieldType ?? inferred?.fieldType ?? "nominal"
+  );
+  const dataset = findDataset(program, resolved.source);
+  readNominalField(dataset.values, field);
+  const padding = normalizeOffsetPadding(
+    explicit ?? {},
+    resolved.sourceLayer === undefined
+      ? undefined
+      : program.markConfigs[resolved.sourceLayer.id]?.[channel],
+    channel
   );
-  return resolveErrorBarAppearance(appearanceArgs, {
+  return {
+    channel,
+    field,
+    fieldType,
+    scale: {
+      ...(inferred?.scale === undefined ? {} : { id: inferred.scale }),
+      ...(explicit?.scale ?? {})
+    },
+    ...padding
+  };
+}
+
+function resolveAppearance(args) {
+  return resolveErrorBarAppearance(ownOptions(args, [
+    "caps", "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"
+  ]), {
     defaults: {
       caps: true,
       capSize: 8,
@@ -40,6 +132,76 @@ function resolveAppearance(args) {
   });
 }
 
+export const createErrorBarCap = action(
+  {
+    op: "createErrorBarCap",
+    description: "Create one fixed-pixel error-bar cap."
+  },
+  function (args = {}) {
+    validateKeys(args, [
+      "id", "data", "orientation", "positionField", "positionFieldType",
+      "intervalField", "coordinate", "positionScale", "intervalScale",
+      "offsetChannel", "offsetField", "offsetFieldType", "offsetScale",
+      "offsetPaddingInner", "offsetPaddingOuter",
+      "capSize", "stroke", "strokeWidth", "strokeDash", "opacity"
+    ], "createErrorBarCap");
+    if (!["vertical", "horizontal"].includes(args.orientation)) {
+      throw new Error(`Unsupported error-bar orientation "${args.orientation}".`);
+    }
+    const vertical = args.orientation === "vertical";
+    const expectedOffset = vertical ? "xOffset" : "yOffset";
+    if (
+      args.offsetChannel !== undefined &&
+      args.offsetChannel !== expectedOffset
+    ) {
+      throw new Error(
+        `createErrorBarCap requires ${expectedOffset} for ${args.orientation} intervals.`
+      );
+    }
+    const positionAction = vertical ? "encodeX" : "encodeY";
+    const intervalAction = vertical ? "encodeY" : "encodeX";
+    let next = this
+      .createRuleMark({ id: args.id, data: args.data })
+      [positionAction]({
+        target: args.id,
+        field: args.positionField,
+        fieldType: args.positionFieldType,
+        coordinate: args.coordinate,
+        scale: { id: args.positionScale }
+      })
+      [intervalAction]({
+        target: args.id,
+        field: args.intervalField,
+        fieldType: "quantitative",
+        coordinate: args.coordinate,
+        scale: { id: args.intervalScale }
+      });
+    if (args.offsetChannel !== undefined) {
+      const offsetAction = args.offsetChannel === "xOffset"
+        ? "encodeXOffset"
+        : "encodeYOffset";
+      next = next[offsetAction]({
+        target: args.id,
+        field: args.offsetField,
+        fieldType: args.offsetFieldType,
+        scale: { id: args.offsetScale },
+        paddingInner: args.offsetPaddingInner,
+        paddingOuter: args.offsetPaddingOuter
+      });
+    }
+    return next
+      .encodeStroke({ target: args.id, value: args.stroke })
+      .encodeStrokeWidth({ target: args.id, value: args.strokeWidth })
+      .encodeStrokeDash({ target: args.id, value: args.strokeDash })
+      .encodeOpacity({ target: args.id, value: args.opacity })
+      .materializeRuleSpan({
+        id: args.id,
+        orientation: vertical ? "horizontal" : "vertical",
+        size: args.capSize
+      });
+  }
+);
+
 function positionArgs(resolved) {
   return {
     target: resolved.id,
@@ -50,6 +212,19 @@ function positionArgs(resolved) {
   };
 }
 
+function offsetArgs(resolved) {
+  return resolved.offset === undefined
+    ? undefined
+    : {
+        target: resolved.id,
+        field: resolved.offset.field,
+        fieldType: resolved.offset.fieldType,
+        scale: resolved.offset.scale,
+        paddingInner: resolved.offset.paddingInner,
+        paddingOuter: resolved.offset.paddingOuter
+      };
+}
+
 function intervalArgs(resolved, field) {
   return {
     target: resolved.id,
@@ -69,21 +244,7 @@ export const createErrorBar = action(
     validateKeys(args, OPTIONS, "createErrorBar");
     const resolved = resolveErrorBar(this, args);
     const appearance = resolveAppearance(args);
-    let next = this;
-
-    if (resolved.interval.mode === "statistical") {
-      next = next.createIntervalData({
-        id: resolved.dataId,
-        source: resolved.source,
-        field: resolved.interval.field,
-        groupBy: resolved.groupBy,
-        center: resolved.interval.center,
-        extent: resolved.interval.extent,
-        level: resolved.interval.level,
-        as: resolved.fields
-      });
-    }
-
+    let next = createResolvedIntervalData(this, resolved);
     next = next.createRuleMark({ id: resolved.id, data: resolved.dataId });
     const positionAction = resolved.position.channel === "x" ? "encodeX" : "encodeY";
     const intervalAction = resolved.interval.channel === "x" ? "encodeX" : "encodeY";
@@ -100,18 +261,21 @@ export const createErrorBar = action(
       target: resolved.id,
       field: resolved.fields.upper,
       fieldType: "quantitative"
-    })
-      .encodeStroke({ target: resolved.id, value: appearance.stroke })
+    });
+    if (resolved.offset !== undefined) {
+      const offsetAction = resolved.offset.channel === "xOffset"
+        ? "encodeXOffset"
+        : "encodeYOffset";
+      next = next[offsetAction](offsetArgs(resolved));
+    }
+    next = next.encodeStroke({ target: resolved.id, value: appearance.stroke })
       .encodeStrokeWidth({ target: resolved.id, value: appearance.strokeWidth })
       .encodeStrokeDash({ target: resolved.id, value: appearance.strokeDash })
       .encodeOpacity({ target: resolved.id, value: appearance.opacity });
 
     const intervalLayer = findLayer(next, resolved.id);
     if (appearance.caps) {
-      for (const [id, field] of [
-        [resolved.lowerCapId, resolved.fields.lower],
-        [resolved.upperCapId, resolved.fields.upper]
-      ]) {
+      for (const [id, field] of errorBarCaps(resolved)) {
         next = next.createErrorBarCap({
           id,
           data: resolved.dataId,
@@ -122,6 +286,16 @@ export const createErrorBar = action(
           coordinate: resolved.coordinate,
           positionScale: intervalLayer.encoding[resolved.position.channel].scale,
           intervalScale: intervalLayer.encoding[resolved.interval.channel].scale,
+          ...(resolved.offset === undefined
+            ? {}
+            : {
+                offsetChannel: resolved.offset.channel,
+                offsetField: resolved.offset.field,
+                offsetFieldType: resolved.offset.fieldType,
+                offsetScale: intervalLayer.encoding[resolved.offset.channel].scale,
+                offsetPaddingInner: resolved.offset.paddingInner,
+                offsetPaddingOuter: resolved.offset.paddingOuter
+              }),
           capSize: appearance.capSize,
           stroke: appearance.stroke,
           strokeWidth: appearance.strokeWidth,
@@ -142,6 +316,14 @@ export const createErrorBar = action(
         coordinate: resolved.coordinate,
         positionScale: intervalLayer.encoding[resolved.position.channel].scale,
         intervalScale: intervalLayer.encoding[resolved.interval.channel].scale,
+        ...(resolved.offset === undefined
+          ? {}
+          : {
+              offset: {
+                ...resolved.offset,
+                scale: intervalLayer.encoding[resolved.offset.channel].scale
+              }
+            }),
         lowerCapId: resolved.lowerCapId,
         upperCapId: resolved.upperCapId,
         ...appearance