ggaction 0.0.12 → 0.0.13

package/src/actions/marks/text/actions.js

@@ -1,12 +1,17 @@
+import { TEXT_LABEL_LAYOUT_OPTIONS } from "./layout.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
   DEFAULT_TEXT_MARK,
+  isSourceOwnedText,
   normalizeTextMarkConfig
 } from "../../../grammar/text.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
 import {
   canMaterializeArc,
-  canMaterializeText
+  canMaterializeRect,
+  canMaterializeText,
+  isTextSource
 } from "../../../materialization/marks/index.js";
 import { resolveTextGraphicItems } from "../../../materialization/text.js";
 import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
@@ -18,6 +23,10 @@ import {
   resolveMarkId,
   validateMarkOptions
 } from "../shared.js";
+import {
+  resolveFacadeData,
+  resolveFacadeId
+} from "../../charts/shared.js";
 import { resolveMarkGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
 
@@ -25,10 +34,9 @@ const STYLE_OPTIONS = Object.freeze([
   "fill", "opacity", "fontSize", "fontFamily", "fontWeight",
   "align", "baseline", "rotation", "dx", "dy"
 ]);
-const CREATE_OPTIONS = Object.freeze(["id", "data", "text", ...STYLE_OPTIONS]);
+const CREATE_OPTIONS = Object.freeze(["id", "data", "source", "text", ...STYLE_OPTIONS]);
 const EDIT_OPTIONS = Object.freeze(["target", ...STYLE_OPTIONS]);
 const REMATERIALIZE_OPTIONS = Object.freeze(["id", "replayLayout"]);
-const SOURCE_TYPES = new Set(["point", "bar", "rule", "rect", "arc"]);
 
 function sourceMatchesData(program, layer, requestedData) {
   if (requestedData === undefined || layer?.data === requestedData) return true;
@@ -37,16 +45,27 @@ function sourceMatchesData(program, layer, requestedData) {
 
 function eligibleSource(program, layer, requestedData) {
   if (
-    !SOURCE_TYPES.has(layer?.mark?.type) ||
-    layer.data === undefined ||
+    !isTextSource(layer) ||
     !sourceMatchesData(program, layer, requestedData)
   ) return false;
   if (layer.mark.type === "arc") return canMaterializeArc(program, layer);
+  if (layer.mark.type === "rect" && (canMaterializeRect(program, layer) ||
+    program.markConfigs[layer.id]?.gradientPlot?.materialized === true)) return true;
   const encodings = resolveCompatibleEncodings(program, layer, "text");
   return encodings.x !== undefined && encodings.y !== undefined;
 }
 
 function resolveTextInheritance(program, args) {
+  if (Object.hasOwn(args, "source")) {
+    if (Object.hasOwn(args, "data")) {
+      throw new Error("createTextMark source and data are mutually exclusive.");
+    }
+    return textInheritance(program, resolveEligibleLayer(program, {
+      target: validateUserId(args.source, "Text source id"),
+      predicate: isTextSource,
+      label: "text source"
+    }));
+  }
   if (Object.hasOwn(args, "data")) return undefined;
   const requestedData = program.context.currentData;
   const candidates = program.semanticSpec.layers.filter(layer =>
@@ -60,10 +79,14 @@ function resolveTextInheritance(program, args) {
       : undefined;
   if (source === undefined && candidates.length > 1) {
     throw new Error(
-      "Text source inference is ambiguous; provide data and encode its position explicitly."
+      "Text source inference is ambiguous; provide source, or data and encode its position explicitly."
     );
   }
   if (source === undefined) return undefined;
+  return textInheritance(program, source);
+}
+
+function textInheritance(program, source) {
   return {
     source: source.id,
     data: source.data,
@@ -136,6 +159,199 @@ const createTextMark = action(
   }
 );
 
+const LABEL_OPTIONS = Object.freeze([
+  "id", "source", "field", "value", "content", "normalizeBy", "format", "layout",
+  ...STYLE_OPTIONS
+]);
+
+const ANNOTATION_OPTIONS = Object.freeze([
+  "id", "text", "format", "x", "y", "space", "source", "data", "coordinate", "layout",
+  ...STYLE_OPTIONS
+]);
+
+function annotationLayout(value) {
+  const layout = value === undefined || value === false ? undefined : value;
+  if (layout !== undefined && Object.hasOwn(layout ?? {}, "target")) {
+    throw new Error("createAnnotation layout target is owned by the created text layer.");
+  }
+  if (layout !== undefined) {
+    validateMarkOptions(layout, TEXT_LABEL_LAYOUT_OPTIONS, "createAnnotation layout");
+  }
+  return layout;
+}
+
+function resolveAnnotationBinding(program, args) {
+  const hasX = Object.hasOwn(args, "x");
+  const hasY = Object.hasOwn(args, "y");
+  if (!hasX && !hasY) {
+    if (["space", "data", "coordinate"].some(option => Object.hasOwn(args, option))) {
+      throw new Error("createAnnotation mark anchor accepts source but not space, data, or coordinate.");
+    }
+    return { mode: "mark" };
+  }
+  if (!hasX || !hasY) {
+    throw new Error("createAnnotation coordinate anchor requires both x and y.");
+  }
+  const space = args.space ?? "data";
+  if (space !== "data" && space !== "plot") {
+    throw new Error("createAnnotation space must be data or plot.");
+  }
+  if (space === "plot") {
+    if (Object.hasOwn(args, "source")) {
+      throw new Error("createAnnotation plot anchor does not accept source.");
+    }
+    if (![args.x, args.y].every(value => Number.isFinite(value) && value >= 0 && value <= 1)) {
+      throw new Error("createAnnotation plot coordinates must be finite numbers in [0, 1].");
+    }
+    return {
+      mode: "plot",
+      data: resolveFacadeData(program, args.data, "createAnnotation"),
+      coordinate: args.coordinate
+    };
+  }
+  if (Object.hasOwn(args, "data") || Object.hasOwn(args, "coordinate")) {
+    throw new Error("createAnnotation data anchor uses source data and coordinate.");
+  }
+  const source = resolveEligibleLayer(program, {
+    target: args.source === undefined
+      ? undefined
+      : validateUserId(args.source, "createAnnotation source"),
+    predicate: layer =>
+      !isSourceOwnedText(layer) &&
+      layer.data !== undefined &&
+      layer.encoding?.x?.scale !== undefined &&
+      layer.encoding?.y?.scale !== undefined &&
+      findCoordinate(program, layer.coordinate)?.type === "cartesian",
+    label: "createAnnotation Cartesian layer",
+    targetOption: "source"
+  });
+  return {
+    mode: "data",
+    data: source.data,
+    coordinate: source.coordinate,
+    x: source.encoding.x,
+    y: source.encoding.y
+  };
+}
+
+const createAnnotation = action(
+  {
+    op: "createAnnotation",
+    description: "Create text at a final mark, data, or plot anchor."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, ANNOTATION_OPTIONS, "createAnnotation");
+    if (!Object.hasOwn(args, "text")) {
+      throw new Error("createAnnotation requires text.");
+    }
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "annotation",
+      operation: "createAnnotation"
+    });
+    const binding = resolveAnnotationBinding(this, args);
+    const layout = annotationLayout(args.layout);
+    const style = Object.fromEntries(STYLE_OPTIONS
+      .filter(option => Object.hasOwn(args, option))
+      .map(option => [option, args[option]]));
+    const text = {
+      value: args.text,
+      ...(args.format === undefined ? {} : { format: args.format })
+    };
+    const apply = program => {
+      if (binding.mode === "mark") {
+        return program.createMarkLabels({
+          id,
+          ...(args.source === undefined ? {} : { source: args.source }),
+          ...style,
+          ...text,
+          ...(layout === undefined ? {} : { layout })
+        });
+      }
+      const xScale = binding.mode === "plot" ? `${id}-x` : binding.x.scale;
+      const yScale = binding.mode === "plot" ? `${id}-y` : binding.y.scale;
+      let next = binding.mode === "plot"
+        ? program
+          .createScale({ id: xScale, type: "linear", domain: [0, 1] })
+          .createScale({ id: yScale, type: "linear", domain: [0, 1] })
+        : program;
+      next = next
+        .createTextMark({ id, data: binding.data, ...style })
+        .encodeText({ target: id, ...text })
+        .encodeX({
+          target: id,
+          datum: args.x,
+          fieldType: binding.mode === "plot" ? "quantitative" : binding.x.fieldType,
+          scale: { id: xScale },
+          ...(binding.coordinate === undefined ? {} : { coordinate: binding.coordinate }),
+          ...(binding.mode === "data" && binding.x.temporalUnit !== undefined
+            ? { temporalUnit: binding.x.temporalUnit }
+            : {})
+        })
+        .encodeY({
+          target: id,
+          datum: args.y,
+          fieldType: binding.mode === "plot" ? "quantitative" : binding.y.fieldType,
+          scale: { id: yScale },
+          ...(binding.coordinate === undefined ? {} : { coordinate: binding.coordinate }),
+          ...(binding.mode === "data" && binding.y.temporalUnit !== undefined
+            ? { temporalUnit: binding.y.temporalUnit }
+            : {})
+        });
+      return layout === undefined
+        ? next
+        : next.layoutLabels({ ...layout, target: id });
+    };
+    // Validate the full lower action chain before committing any child effect.
+    apply(this);
+    return apply(this);
+  }
+);
+
+const createMarkLabels = action(
+  {
+    op: "createMarkLabels",
+    description: "Create final-item text labels attached to an existing mark."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, LABEL_OPTIONS, "createMarkLabels");
+    const inherited = resolveTextInheritance(this, args);
+    if (inherited === undefined) {
+      throw new Error("createMarkLabels requires an eligible source mark; provide source explicitly.");
+    }
+    const id = validateUserId(args.id === undefined ? `${inherited.source}-labels` : args.id, "Text mark id");
+    assertMarkAvailable(this, id);
+    const style = Object.fromEntries(STYLE_OPTIONS
+      .filter(option => Object.hasOwn(args, option))
+      .map(option => [option, args[option]]));
+    normalizeTextMarkConfig(style);
+    const encoding = Object.fromEntries(
+      ["field", "value", "content", "normalizeBy", "format"]
+        .filter(option => Object.hasOwn(args, option))
+        .map(option => [option, args[option]])
+    );
+    if (!["field", "value", "content"].some(option => Object.hasOwn(args, option))) {
+      encoding.content = "value";
+    }
+    const layout = args.layout === undefined || args.layout === false ? undefined : args.layout;
+    if (layout !== undefined && Object.hasOwn(layout ?? {}, "target")) {
+      throw new Error("createMarkLabels layout target is owned by the created label layer.");
+    }
+    const apply = program => {
+      const next = program.createTextMark({
+        id, source: inherited.source, align: "center", baseline: "middle", ...style
+      }).encodeText({ target: id, ...encoding });
+      return layout === undefined ? next : next.layoutLabels({ ...layout, target: id });
+    };
+    if (layout !== undefined) {
+      // Validate object shape before spreading it into the child action's options.
+      validateMarkOptions(layout, TEXT_LABEL_LAYOUT_OPTIONS, "createMarkLabels layout");
+    }
+    // Validate all child effects on a discarded immutable branch, as scale edits do.
+    apply(this);
+    return apply(this);
+  }
+);
+
 const rematerializeTextMark = action(
   {
     op: "rematerializeTextMark",
@@ -209,6 +425,8 @@ const editTextMark = action(
 export function registerTextMarkActions(ProgramClass) {
   Object.assign(ProgramClass.prototype, {
     createTextMark,
+    createMarkLabels,
+    createAnnotation,
     editTextMark,
     rematerializeTextMark
   });

package/src/actions/marks/text/layout.js

@@ -16,7 +16,7 @@ import { resolveTextGraphicEntries } from "../../../materialization/text.js";
 import { findLayer, resolveEligibleLayer } from "../../../selectors/layers.js";
 import { editMarkGraphic } from "../shared.js";
 
-const LAYOUT_OPTIONS = Object.freeze([
+export const TEXT_LABEL_LAYOUT_OPTIONS = Object.freeze([
   "target", "axis", "padding", "maxDisplacement", "bounds", "leader"
 ]);
 const REMOVE_OPTIONS = Object.freeze(["target"]);
@@ -252,7 +252,7 @@ const layoutLabels = action(
     description: "Assign deterministic collision-aware layout to a text mark."
   },
   function (args = {}) {
-    validateOptionObject(args, LAYOUT_OPTIONS, "layoutLabels");
+    validateOptionObject(args, TEXT_LABEL_LAYOUT_OPTIONS, "layoutLabels");
     const layer = requireCompleteText(this, args.target, "layoutLabels");
     const policy = normalizePolicy(args);
     const generatedId = leaderId(layer.id);

package/src/actions/primitives/createGraphics.js

@@ -129,7 +129,9 @@ const createGraphics = action(
       id, type: validatedType, parent, before, after
     });
 
-    const existing = this.graphicSpec.objects[id];
+    const existing = Object.hasOwn(this.graphicSpec.objects, id)
+      ? this.graphicSpec.objects[id]
+      : undefined;
     if (existing !== undefined) {
       if (
         sameDefinition(existing, { type: validatedType, length }) &&

package/src/actions/primitives/semantic.js

@@ -21,7 +21,7 @@ export function registerSemanticPrimitiveAction(ProgramClass) {
   const validateSemanticValue = createSemanticValueValidator({
     validateDatasetTransforms,
     validateParallel,
-    sourceMarkTypes: ["point", "bar", "rule", "rect", "arc"]
+    sourceMarkTypes: ["point", "bar", "line", "rule", "rect", "arc"]
   });
   ProgramClass.prototype.editSemantic =
     createSemanticPrimitiveAction(validateSemanticValue);

package/src/actions/primitives/semanticAction.js

@@ -1,3 +1,4 @@
+import { hasSemanticScaleReferences } from "../../selectors/scales.js";
 import { action } from "../../core/action.js";
 import {
   cloneAndFreeze,
@@ -75,7 +76,10 @@ function removeEntity(spec, parsed) {
   const collection = spec[parsed.collection];
   const index = collection.findIndex(item => item.id === parsed.id);
   if (index === -1) return spec;
-  if (parsed.kind === "layer" && parsed.path.length === 0) {
+  if (parsed.kind === "scale" && parsed.path.length === 0) {
+    if (hasSemanticScaleReferences(spec, parsed.id)) throw new Error(`Scale "${parsed.id}" is still referenced.`);
+  }
+  if (["layer", "scale"].includes(parsed.kind) && parsed.path.length === 0) {
     const nextCollection = collection.filter((_, itemIndex) => itemIndex !== index);
     return freezeOwned({
       ...spec,
@@ -118,6 +122,35 @@ function removeRootProperty(spec, root, path) {
     : spec;
 }
 
+// Materializers use this only for an immutable speculative branch while they
+// replay a multi-step recipe. The public semantic primitive deliberately keeps
+// materialized dataset values immutable after creation.
+export function withPreviewDatasetValues(program, {
+  id,
+  values,
+  target,
+  omitValues = false
+}) {
+  const semanticSpec = {
+    ...program.semanticSpec,
+    datasets: program.semanticSpec.datasets.map(dataset => {
+      if (dataset.id !== id) return dataset;
+      if (omitValues) {
+        const { values: unused, ...definition } = dataset;
+        void unused;
+        return definition;
+      }
+      return { ...dataset, values };
+    }),
+    layers: target === undefined
+      ? program.semanticSpec.layers
+      : program.semanticSpec.layers.map(layer =>
+          layer.id === target ? { ...layer, data: id } : layer
+        )
+  };
+  return program._clone({ semanticSpec });
+}
+
 export function createSemanticPrimitiveAction(validateSemanticValue) {
   return action(
     {
@@ -159,11 +192,15 @@ export function createSemanticPrimitiveAction(validateSemanticValue) {
           parsed.kind === "layer" &&
           parsed.path.length === 0 &&
           this.context.currentMark === parsed.id;
+        const removesScale = parsed.kind === "scale" && parsed.path.length === 0;
+        const resolvedScales = removesScale ? Object.fromEntries(Object.entries(this.resolvedScales).filter(([id]) => id !== parsed.id)) : this.resolvedScales;
         return this._clone({
           semanticSpec,
-          ...(clearsCurrentData || clearsCurrentMark
+          ...(removesScale ? { resolvedScales: freezeOwned(resolvedScales) } : {}),
+          ...(clearsCurrentData || clearsCurrentMark || (removesScale && this.context.currentScale === parsed.id)
             ? { context: freezeOwned({
                 ...this.context,
+                ...(removesScale && this.context.currentScale === parsed.id ? { currentScale: undefined } : {}),
                 ...(clearsCurrentData ? { currentData: undefined } : {}),
                 ...(clearsCurrentMark ? { currentMark: undefined } : {})
               }) }

package/src/actions/primitives/semanticValidation/guide.js

@@ -1,6 +1,8 @@
+import { normalizeLegendOrder } from "../../../grammar/categoryOrder.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import { CATEGORICAL_LEGEND_CHANNELS } from "../../../core/vocabulary.js";
 import { validateNonEmptySemanticString } from "./shared.js";
+import { validateParallelAxisTitles } from "../../../grammar/parallelAxisTitles.js";
 
 function validateLegend(property, value) {
   if (property === "title") {
@@ -24,6 +26,14 @@ function validateLegend(property, value) {
 
 export function validateGuideSemanticValue(_program, parsed, value) {
   const property = parsed.path.at(-1);
+  if (parsed.id === "axis.parallel" && property === "titles") {
+    validateParallelAxisTitles(value);
+    return;
+  }
+  if (["legend.series", "legend.color"].includes(parsed.id) && property === "order") {
+    normalizeLegendOrder(value);
+    return;
+  }
   if (parsed.id === "legend.series") {
     validateLegend(property, value);
     return;

package/src/actions/primitives/semanticValidation/layer.js

@@ -4,6 +4,7 @@ import {
   MARK_TYPES,
   STACK_MODES
 } from "../../../core/vocabulary.js";
+import { validateMarkLabelContent, validateMarkLabelNormalization } from "../../../grammar/markLabels.js";
 import { validateAggregate } from "../../../grammar/aggregate.js";
 import {
   normalizeHistogramBin,
@@ -11,6 +12,7 @@ import {
   validateHistogramBinStep
 } from "../../../grammar/histogram.js";
 import { validatePathOrderDirection } from "../../../grammar/pathOrder.js";
+import { normalizeGroupFields } from "../../../grammar/pathSeries.js";
 import { normalizeCategoryOrder } from "../../../grammar/categoryOrder.js";
 import { validateSemanticFieldType } from "../../../grammar/scales/index.js";
 import { findLayer } from "../../../selectors/layers.js";
@@ -40,7 +42,7 @@ export function validateLayerSemanticValue(
   parsed,
   value,
   {
-    sourceMarkTypes = ["point", "bar", "rule", "rect", "arc"],
+    sourceMarkTypes = ["point", "bar", "line", "rule", "rect", "arc"],
     validateParallel
   } = {}
 ) {
@@ -48,6 +50,17 @@ export function validateLayerSemanticValue(
   if (property === "mark.type" && !MARK_TYPES.includes(value)) {
     throw new Error(`Unknown mark type "${value}".`);
   }
+  if (property === "mark.missing" && !["error", "break"].includes(value)) {
+    throw new Error(`Unsupported area missing policy "${value}".`);
+  }
+  if (property === "layout.mode" && !COLOR_LAYOUTS.includes(value)) {
+    throw new Error(`Unsupported series layout "${value}".`);
+  }
+  if (property === "encoding.group.inferredFrom" && !["color", "offset"].includes(value)) {
+    throw new Error(`Unsupported group inference origin "${value}".`);
+  }
+  if (property === "encoding.text.content") validateMarkLabelContent(value);
+  if (property === "encoding.text.normalizeBy") validateMarkLabelNormalization(value);
   if (property === "source") {
     validateLayerSource(program, parsed, value, sourceMarkTypes);
   }
@@ -58,6 +71,10 @@ export function validateLayerSemanticValue(
     throw new Error("Path order field type must be quantitative.");
   }
   if (property.endsWith(".fieldType")) validateSemanticFieldType(value);
+  if (property === "encoding.group.fields") {
+    if (!Array.isArray(value)) throw new TypeError("Group fields must be an array.");
+    normalizeGroupFields(value);
+  }
   if (property === "encoding.pathOrder.order") validatePathOrderDirection(value);
   if (property.endsWith(".categoryOrder")) normalizeCategoryOrder(value);
   if (property.startsWith("encoding.parallel.")) {

package/src/actions/primitives/semanticValidation/scale.js

@@ -1,5 +1,7 @@
+import { validateRadialMapping } from "../../../grammar/scales/radial.js";
 import {
   validateContinuousColorInterpolation,
+  validateSequentialMidpoint,
   validateScalePropertyForType,
   validateSemanticScaleDomain,
   validateSemanticScaleRange,
@@ -16,10 +18,17 @@ function validateOwnedProperty(existing, property) {
 export function validateScaleSemanticValue(program, parsed, value) {
   const property = parsed.path.join(".");
   const existing = findSemanticScale(program, parsed.id);
+  if (property === "midpoint") {
+    if (value === "auto" || value === undefined) {
+      throw new TypeError("Semantic midpoint must be a finite number; remove the property to reset it.");
+    }
+    return validateSequentialMidpoint(value, existing?.type ?? "sequential");
+  }
+  if (property === "radialMapping") return validateRadialMapping(value);
   if (property === "type") {
     validateSemanticScaleType(value);
     for (const owned of [
-      "nice", "zero", "clamp", "base", "exponent", "constant",
+      "nice", "zero", "clamp", "base", "exponent", "constant", "midpoint",
       "paddingInner", "paddingOuter", "padding", "align"
     ]) {
       if (existing?.[owned] !== undefined) validateScalePropertyForType(value, owned);

package/src/actions/regression/create.js

@@ -10,7 +10,7 @@ import {
 
 const REGRESSION_OPTIONS = Object.freeze([
   "target", "x", "y", "groupBy", "method", "degree", "span",
-  "confidence", "interval", "band", "line"
+  "confidenceMethod", "level", "confidence", "interval", "band", "line"
 ]);
 
 export const createRegression = action(

package/src/actions/regression/edit.js

@@ -18,7 +18,7 @@ import { requireRegressionField } from "./resolve.js";
 
 const OPTIONS = Object.freeze([
   "target", "data", "x", "y", "groupBy", "method", "degree", "span",
-  "confidence", "interval", "band", "line"
+  "confidenceMethod", "level", "confidence", "interval", "band", "line"
 ]);
 const BAND_OPTIONS = Object.freeze([
   "color", "opacity", "stroke", "strokeWidth", "curve"
@@ -100,18 +100,31 @@ function validateLinePatch(value) {
 function resolveParameters(previous, args) {
   const method = args.method ?? previous.method;
   const raw = { method };
-  for (const key of ["degree", "span", "confidence", "interval"]) {
+  for (const key of [
+    "degree", "span", "confidenceMethod", "level", "confidence", "interval"
+  ]) {
     if (Object.hasOwn(args, key)) raw[key] = args[key];
   }
+  const inheritsLevel = !Object.hasOwn(raw, "confidence");
   if (method === previous.method) {
-    for (const key of ["degree", "span", "confidence", "interval"]) {
-      if (!Object.hasOwn(raw, key) && Object.hasOwn(previous, key)) {
+    for (const key of [
+      "degree", "span", "confidenceMethod", "level", "interval"
+    ]) {
+      if (
+        !Object.hasOwn(raw, key) &&
+        (key !== "level" || inheritsLevel) &&
+        Object.hasOwn(previous, key)
+      ) {
         raw[key] = previous[key];
       }
     }
   } else if (method !== "loess" && previous.method !== "loess") {
-    for (const key of ["confidence", "interval"]) {
-      if (!Object.hasOwn(raw, key) && Object.hasOwn(previous, key)) {
+    for (const key of ["confidenceMethod", "level", "interval"]) {
+      if (
+        !Object.hasOwn(raw, key) &&
+        (key !== "level" || inheritsLevel) &&
+        Object.hasOwn(previous, key)
+      ) {
         raw[key] = previous[key];
       }
     }

package/src/actions/regression/resolve.js

@@ -41,7 +41,7 @@ export function findRegressionPoint(program, requested) {
 
 export function inferRegressionGroup(layer, args) {
   if (Object.hasOwn(args, "groupBy")) {
-    return args.groupBy === undefined
+    return args.groupBy === undefined || args.groupBy === false
       ? undefined
       : requireRegressionField(args.groupBy, "Regression groupBy");
   }