ggaction 0.0.2 → 0.0.3

package/src/actions/encodings/ranged.js

@@ -4,6 +4,7 @@ import { isPlainObject } from "../../core/immutable.js";
 import {
   readNominalField,
   readQuantitativeField,
+  readScaleField,
   readTemporalField,
   validateSemanticFieldType
 } from "../../grammar/scales.js";
@@ -85,16 +86,35 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
   }
   const fieldType = rule
     ? validateSemanticFieldType(args.fieldType)
-    : args.fieldType ?? "quantitative";
-  if (!rule && fieldType !== "quantitative") {
+    : layer.mark.type === "rect"
+      ? args.fieldType ?? primary.fieldType
+      : args.fieldType ?? "quantitative";
+  if (
+    !rule &&
+    layer.mark.type !== "rect" &&
+    fieldType !== "quantitative"
+  ) {
     throw new Error(`${operation} requires a quantitative field.`);
   }
+  if (
+    layer.mark.type === "rect" &&
+    !["quantitative", "temporal"].includes(fieldType)
+  ) {
+    throw new Error(`${operation} requires a quantitative or temporal rect field.`);
+  }
+  if (layer.mark.type === "rect" && fieldType !== primary.fieldType) {
+    throw new Error(
+      `${operation} fieldType must match the primary ${primaryChannel} fieldType.`
+    );
+  }
   if (rule && fieldType !== primary.fieldType) {
     throw new Error(
       `${operation} fieldType must match the primary ${primaryChannel} fieldType.`
     );
   }
-  if (hasField) validateSecondaryField(dataset, args.field, fieldType);
+  if (hasField && layer.mark.type === "rect") {
+    readScaleField(dataset.values, args.field, fieldType, { allowUnknown: true });
+  } else if (hasField) validateSecondaryField(dataset, args.field, fieldType);
   else normalizeRuleDatum(args.datum, fieldType, channel);
 
   const previous = layer.encoding?.[channel];
@@ -135,7 +155,9 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
   if (rule) return next.rematerializeRuleMark({ id: target });
   return layer.mark.type === "bar"
     ? next.rematerializeBarMark({ id: target })
-    : next.rematerializeAreaMark({ id: target });
+    : layer.mark.type === "rect"
+      ? next.rematerializeRectMark({ id: target })
+      : next.rematerializeAreaMark({ id: target });
 }
 
 const encodeX2 = action(
@@ -149,7 +171,7 @@ const encodeX2 = action(
       "x2",
       args,
       "encodeX2",
-      ["area", "rule", "bar"]
+      ["area", "rule", "bar", "rect"]
     );
   }
 );
@@ -165,7 +187,7 @@ const encodeY2 = action(
       "y2",
       args,
       "encodeY2",
-      ["area", "rule", "bar"]
+      ["area", "rule", "bar", "rect"]
     );
   }
 );

package/src/actions/encodings/shared.js

@@ -3,10 +3,14 @@ import { findDataset } from "../../selectors/datasets.js";
 import { resolveEligibleLayer } from "../../selectors/layers.js";
 import { hasMaterializedLegend } from "../../materialization/legends.js";
 import { findSemanticScale } from "../../selectors/scales.js";
-import { validateKeys } from "../../core/validation.js";
+import { validateOptionObject } from "../../core/validation.js";
+import {
+  getMarkGraphicTypes,
+  getPositionChannelDefinition
+} from "../../core/vocabulary.js";
 
 export function validateOptions(args, supported, operation) {
-  validateKeys(args, supported, operation);
+  validateOptionObject(args, supported, operation);
 }
 
 export function validateLineSeriesCompatibility(layer, channel, field) {
@@ -65,10 +69,12 @@ export function rebindPositionGuides(
   nextScale,
   target
 ) {
+  const definition = getPositionChannelDefinition(channel);
+  if (definition?.guideChannel === undefined) return program;
   if (previousScale === undefined || previousScale === nextScale) return program;
 
-  const axis = program.semanticSpec.guides.axis?.[channel];
-  const direction = channel === "x" ? "vertical" : "horizontal";
+  const axis = program.semanticSpec.guides.axis?.[definition.guideChannel];
+  const direction = definition.gridDirection;
   const grid = program.semanticSpec.guides.grid?.[direction];
   const ownsAxis = axis?.scale === previousScale;
   const ownsGrid = grid?.scale === previousScale;
@@ -86,13 +92,13 @@ export function rebindPositionGuides(
   let next = program;
   if (ownsAxis) {
     next = next.editSemantic({
-      property: `guide.axis.${channel}.scale`,
+      property: `guide.axis.${definition.guideChannel}.scale`,
       value: nextScale
     });
-    for (const component of ["ticks", "labels", "title"]) {
-      const config = next.guideConfigs.axis?.[channel]?.[component];
+    for (const component of ["line", "ticks", "labels", "title"]) {
+      const config = next.guideConfigs.axis?.[definition.guideChannel]?.[component];
       if (config?.scale === previousScale) {
-        next = next._withGuideConfig(channel, component, {
+        next = next._withGuideConfig(definition.guideChannel, component, {
           ...config,
           scale: nextScale
         });
@@ -141,22 +147,12 @@ export function resolveTarget(
     throw new Error(`Mark "${id}" requires an existing dataset.`);
   }
 
-  const expectedGraphic = {
-    point: ["circle", "rect", "collection"],
-    line: "path",
-    bar: "rect",
-    area: "path",
-    rule: "line"
-  }[layer.mark.type];
+  const expectedGraphic = getMarkGraphicTypes(layer.mark.type);
 
   const graphicType = program.graphicSpec.objects[id]?.type;
-  const matches = Array.isArray(expectedGraphic)
-    ? expectedGraphic.includes(graphicType)
-    : graphicType === expectedGraphic;
+  const matches = expectedGraphic?.includes(graphicType) === true;
   if (!matches) {
-    const label = Array.isArray(expectedGraphic)
-      ? expectedGraphic.join(" or ")
-      : expectedGraphic;
+    const label = expectedGraphic?.join(" or ") ?? "supported";
     throw new Error(`Mark "${id}" requires ${label} graphics.`);
   }
 

package/src/actions/encodings/text.js

@@ -0,0 +1,73 @@
+import { action } from "../../core/action.js";
+import { formatTextValue, validateTextFormat } from "../../grammar/text.js";
+import { canMaterializeText } from "../../materialization/marks.js";
+import { findLayer } from "../../selectors/layers.js";
+import { resolveTarget, validateOptions } from "./shared.js";
+
+const OPTIONS = Object.freeze(["target", "field", "value", "format"]);
+
+function validateTextField(rows, field, format) {
+  if (typeof field !== "string" || field.length === 0) {
+    throw new TypeError("encodeText field must be a non-empty string.");
+  }
+  let found = false;
+  for (const row of rows) {
+    if (!Object.hasOwn(row, field)) continue;
+    found = true;
+    formatTextValue(row[field], format);
+  }
+  if (!found) throw new Error(`Unknown text field "${field}".`);
+}
+
+export const encodeText = action(
+  {
+    op: "encodeText",
+    description: "Assign field-driven or constant text content."
+  },
+  function (args = {}) {
+    validateOptions(args, OPTIONS, "encodeText");
+    const hasField = Object.hasOwn(args, "field");
+    const hasValue = Object.hasOwn(args, "value");
+    if (hasField === hasValue) {
+      throw new Error("encodeText requires exactly one of field or value.");
+    }
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["text"],
+      "text mark"
+    );
+    const previous = layer.encoding?.text;
+    const format = validateTextFormat(args.format ?? previous?.format ?? "auto");
+    if (hasField) validateTextField(dataset.values, args.field, format);
+    else if (formatTextValue(args.value, format) === undefined) {
+      throw new Error("encodeText value must produce non-empty text.");
+    }
+
+    let next = this;
+    const alternate = hasField ? "datum" : "field";
+    if (Object.hasOwn(previous ?? {}, alternate)) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.text.${alternate}`,
+        remove: true
+      });
+    }
+    next = next
+      .editSemantic({
+        property: `layer[${target}].encoding.text.${hasField ? "field" : "datum"}`,
+        value: hasField ? args.field : args.value
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.text.format`,
+        value: format
+      });
+    const updated = findLayer(next, target);
+    return canMaterializeText(next, updated)
+      ? next.rematerializeTextMark({ id: target })
+      : next;
+  }
+);
+
+export function registerTextEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeText = encodeText;
+}

package/src/actions/errorBands/create.js

@@ -2,13 +2,10 @@ import { action } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import {
   validateKeys,
-  validateNonEmptyString,
-  validateNonNegativeFinite,
-  validateUnitInterval
 } from "../../core/validation.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
 import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
-import { normalizeStrokeDashPattern } from "../../grammar/scales.js";
+import { resolveBoundaryAppearance } from "./options.js";
 import { resolveErrorBand } from "./resolve.js";
 
 const OPTIONS = Object.freeze([
@@ -24,35 +21,21 @@ const OPTIONS = Object.freeze([
   "curve",
   "boundaries"
 ]);
-const BOUNDARY_OPTIONS = Object.freeze([
-  "stroke", "strokeWidth", "strokeDash", "opacity", "curve"
-]);
-
 function resolveBoundaries(value, areaCurve) {
   if (value === undefined || value === false) return undefined;
   if (!isPlainObject(value)) {
     throw new TypeError("createErrorBand boundaries must be false or a plain object.");
   }
-  validateKeys(value, BOUNDARY_OPTIONS, "createErrorBand boundaries");
-  const stroke = value.stroke ?? DEFAULT_COLORS.mark;
-  const strokeWidth = value.strokeWidth ?? 1;
-  const strokeDash = value.strokeDash ?? "solid";
-  const opacity = value.opacity ?? 1;
-  const curve = validateCurveInterpolation(value.curve ?? areaCurve);
-  validateNonEmptyString(stroke, "Error-band boundary stroke");
-  validateNonNegativeFinite(
-    strokeWidth,
-    "Error-band boundary strokeWidth"
-  );
-  const resolvedStrokeDash = normalizeStrokeDashPattern(strokeDash);
-  validateUnitInterval(opacity, "Error-band boundary opacity");
-  return {
-    stroke,
-    strokeWidth,
-    strokeDash: resolvedStrokeDash,
-    opacity,
-    curve
-  };
+  return resolveBoundaryAppearance(value, {
+    defaults: {
+      stroke: DEFAULT_COLORS.mark,
+      strokeWidth: 1,
+      strokeDash: "solid",
+      opacity: 1,
+      curve: areaCurve
+    },
+    operation: "createErrorBand boundaries"
+  });
 }
 
 function positionArgs(resolved) {
@@ -153,7 +136,32 @@ export const createErrorBand = action(
           id: `${resolved.id}UpperBoundary`,
           bound: resolved.fields.upper
         });
+      for (const [id, bound] of [
+        [`${resolved.id}LowerBoundary`, "lower"],
+        [`${resolved.id}UpperBoundary`, "upper"]
+      ]) {
+        next = next._withMarkConfig(id, {
+          ...next.markConfigs[id],
+          ...boundaries,
+          errorBandBoundary: { owner: resolved.id, bound }
+        });
+      }
     }
-    return next;
+    return next._withMarkConfig(resolved.id, {
+      ...next.markConfigs[resolved.id],
+      errorBand: {
+        data: resolved.dataId,
+        orientation: resolved.orientation,
+        position: resolved.position,
+        coordinate: resolved.coordinate,
+        intervalScale: resolved.interval.scale.id ?? resolved.interval.channel,
+        positionScale: resolved.position.scale.id ?? resolved.position.channel,
+        groupBy: resolved.groupField,
+        lowerField: resolved.fields.lower,
+        upperField: resolved.fields.upper,
+        lowerBoundaryId: `${resolved.id}LowerBoundary`,
+        upperBoundaryId: `${resolved.id}UpperBoundary`
+      }
+    });
   }
 );

package/src/actions/errorBands/edit.js

@@ -0,0 +1,206 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import {
+  validateOptionObject,
+  validateNonEmptyString,
+  validateUnitInterval
+} from "../../core/validation.js";
+import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
+import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import {
+  ERROR_BAND_BOUNDARY_OPTIONS,
+  resolveBoundaryAppearance
+} from "./options.js";
+
+const EDIT_OPTIONS = Object.freeze(["target", "fill", "opacity", "curve"]);
+const BOUNDARY_EDIT_OPTIONS = Object.freeze([
+  "target", "boundary", ...ERROR_BAND_BOUNDARY_OPTIONS
+]);
+const REMATERIALIZE_OPTIONS = Object.freeze([
+  "id", ...ERROR_BAND_BOUNDARY_OPTIONS
+]);
+
+function resolveOwner(program, requested) {
+  const target = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Error-band id");
+  return resolveEligibleLayer(program, {
+    target,
+    label: "error band",
+    predicate: layer =>
+      layer.mark?.type === "area" &&
+      program.markConfigs[layer.id]?.errorBand !== undefined
+  });
+}
+
+function currentBoundaryAppearance(program, id) {
+  const config = program.markConfigs[id];
+  if (findLayer(program, id)?.mark?.type !== "line" || config === undefined) {
+    throw new Error(`Unknown error-band boundary "${id}".`);
+  }
+  return {
+    stroke: config.stroke,
+    strokeWidth: config.strokeWidth,
+    strokeDash: config.strokeDash,
+    opacity: config.opacity,
+    curve: config.curve ?? "linear"
+  };
+}
+
+function defaultBoundaryAppearance(program, owner) {
+  return {
+    stroke: DEFAULT_COLORS.mark,
+    strokeWidth: 1,
+    strokeDash: "solid",
+    opacity: 1,
+    curve: program.markConfigs[owner]?.curve ?? "linear"
+  };
+}
+
+function createBoundary(program, owner, id, bound, appearance) {
+  const config = program.markConfigs[owner].errorBand;
+  const next = program.createErrorBandBoundary({
+    id,
+    data: config.data,
+    orientation: config.orientation,
+    bound,
+    position: config.position,
+    coordinate: config.coordinate,
+    intervalScale: config.intervalScale,
+    positionScale: config.positionScale,
+    groupBy: config.groupBy,
+    ...appearance
+  });
+  return next._withMarkConfig(id, {
+    ...next.markConfigs[id],
+    ...appearance,
+    errorBandBoundary: {
+      owner,
+      bound: id === config.lowerBoundaryId ? "lower" : "upper"
+    }
+  });
+}
+
+export const rematerializeErrorBandBoundary = action(
+  {
+    op: "rematerializeErrorBandBoundary",
+    description: "Rematerialize one owned error-band boundary."
+  },
+  function (args = {}) {
+    validateOptionObject(
+      args,
+      REMATERIALIZE_OPTIONS,
+      "rematerializeErrorBandBoundary"
+    );
+    const id = validateUserId(args.id, "Error-band boundary id");
+    currentBoundaryAppearance(this, id);
+    const graphic = this.graphicSpec.objects[id];
+    const next = this
+      ._withMarkConfig(id, {
+        ...this.markConfigs[id],
+        stroke: args.stroke,
+        strokeWidth: args.strokeWidth,
+        strokeDash: args.strokeDash,
+        opacity: args.opacity,
+        curve: args.curve
+      })
+      .editGraphics({
+        target: id,
+        property: "strokeDash",
+        value: graphic.items.map(() => args.strokeDash)
+      });
+    return next.rematerializeLineMark({ id });
+  }
+);
+
+export const editErrorBand = action(
+  {
+    op: "editErrorBand",
+    description: "Edit one error-band body appearance."
+  },
+  function (args = {}) {
+    validateOptionObject(args, EDIT_OPTIONS, "editErrorBand");
+    if (!["fill", "opacity", "curve"].some(key => Object.hasOwn(args, key))) {
+      throw new Error("editErrorBand requires fill, opacity, or curve.");
+    }
+    const owner = resolveOwner(this, args.target);
+    const config = { ...this.markConfigs[owner.id] };
+    const errorBand = { ...config.errorBand };
+    if (Object.hasOwn(args, "fill")) {
+      errorBand.fill = validateNonEmptyString(args.fill, "Error-band fill");
+    }
+    if (Object.hasOwn(args, "opacity")) {
+      config.opacity = validateUnitInterval(args.opacity, "Error-band opacity");
+    }
+    if (Object.hasOwn(args, "curve")) {
+      config.curve = validateCurveInterpolation(args.curve);
+    }
+    return this
+      ._withMarkConfig(owner.id, { ...config, errorBand })
+      .rematerializeAreaMark({ id: owner.id });
+  }
+);
+
+export const editErrorBandBoundary = action(
+  {
+    op: "editErrorBandBoundary",
+    description: "Edit one or both owned error-band boundaries."
+  },
+  function (args = {}) {
+    validateOptionObject(
+      args,
+      BOUNDARY_EDIT_OPTIONS,
+      "editErrorBandBoundary"
+    );
+    if (!ERROR_BAND_BOUNDARY_OPTIONS.some(key => Object.hasOwn(args, key))) {
+      throw new Error("editErrorBandBoundary requires an appearance change.");
+    }
+    const boundary = args.boundary ?? "both";
+    if (!["both", "lower", "upper"].includes(boundary)) {
+      throw new Error(`Unsupported error-band boundary "${boundary}".`);
+    }
+    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 ids = boundary === "both"
+      ? [config.lowerBoundaryId, config.upperBoundaryId]
+      : [boundary === "lower" ? config.lowerBoundaryId : config.upperBoundaryId];
+    const plans = ids.map(id => {
+      const existing = findLayer(this, id) !== undefined;
+      return {
+        id,
+        existing,
+        bound: id === config.lowerBoundaryId
+          ? config.lowerField
+          : config.upperField,
+        appearance: resolveBoundaryAppearance(patch, {
+          defaults: existing
+            ? currentBoundaryAppearance(this, id)
+            : defaultBoundaryAppearance(this, owner.id),
+          operation: "editErrorBandBoundary"
+        })
+      };
+    });
+    let next = this;
+    for (const plan of plans) {
+      next = plan.existing
+        ? next.rematerializeErrorBandBoundary({
+            id: plan.id,
+            ...plan.appearance
+          })
+        : createBoundary(
+            next,
+            owner.id,
+            plan.id,
+            plan.bound,
+            plan.appearance
+          );
+    }
+    return next;
+  }
+);

package/src/actions/errorBands/index.js

@@ -1,7 +1,16 @@
 import { createErrorBand } from "./create.js";
 import { createErrorBandBoundary } from "./components.js";
+import {
+  editErrorBand,
+  editErrorBandBoundary,
+  rematerializeErrorBandBoundary
+} from "./edit.js";
 
 export function registerErrorBandActions(ProgramClass) {
   ProgramClass.prototype.createErrorBand = createErrorBand;
   ProgramClass.prototype.createErrorBandBoundary = createErrorBandBoundary;
+  ProgramClass.prototype.editErrorBand = editErrorBand;
+  ProgramClass.prototype.editErrorBandBoundary = editErrorBandBoundary;
+  ProgramClass.prototype.rematerializeErrorBandBoundary =
+    rematerializeErrorBandBoundary;
 }

package/src/actions/errorBands/options.js

@@ -0,0 +1,39 @@
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../core/validation.js";
+import { validateCurveInterpolation } from "../../grammar/curveCommands.js";
+import { normalizeStrokeDashPattern } from "../../grammar/scales.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
+  };
+}