ggaction 0.0.1

package/src/actions/encodings/position/policies/rule.js

@@ -0,0 +1,17 @@
+import { emptyPositionPolicy } from "./common.js";
+
+export function resolveRulePositionPolicy({ args, fieldType }) {
+  if (!["quantitative", "temporal", "ordinal", "nominal"].includes(fieldType)) {
+    throw new Error("Rule position encoding requires a supported field type.");
+  }
+  if (args.aggregate !== undefined) {
+    throw new Error("Rule position encoding does not support aggregate.");
+  }
+  if (args.bin !== undefined) {
+    throw new Error("Rule position encoding does not support bin.");
+  }
+  if (args.stack !== undefined) {
+    throw new Error("Rule position encoding does not support stack.");
+  }
+  return emptyPositionPolicy();
+}

package/src/actions/encodings/position/resolve.js

@@ -0,0 +1,170 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import { getPositionCoordinateDefaults } from "../../../grammar/coordinates.js";
+import {
+  readNominalField,
+  readQuantitativeField,
+  readScaleField,
+  readTemporalField,
+  validateFieldType,
+  validatePositionChannel
+} from "../../../grammar/scales.js";
+import { resolvePositionScaleDefinition } from "../../scales/definitions.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
+import {
+  resolveReassignmentScaleOptions,
+  resolveTarget,
+  validateOptions
+} from "../shared.js";
+import {
+  isAggregate,
+  validateAggregateFieldType,
+  validateAggregateFieldValues,
+} from "../../../grammar/aggregate.js";
+import { normalizeRuleDatum } from "../../../grammar/rules.js";
+import { resolveMarkPositionPolicy } from "./policies/index.js";
+
+const POSITION_ENCODING_OPTIONS = Object.freeze([
+  "field", "datum", "target", "fieldType", "scale", "coordinate",
+  "aggregate", "bin", "stack"
+]);
+
+function resolveCoordinate(program, channel, layer, requestedId) {
+  const defaults = getPositionCoordinateDefaults(channel);
+  const existingId = layer.coordinate;
+  if (requestedId !== undefined) validateUserId(requestedId, "Coordinate id");
+  if (existingId !== undefined && requestedId !== undefined && existingId !== requestedId) {
+    throw new Error(`Layer "${layer.id}" already uses coordinate "${existingId}".`);
+  }
+  const id = existingId ?? requestedId ?? defaults.id;
+  const coordinate = findCoordinate(program, id);
+  if (coordinate !== undefined && coordinate.type !== defaults.type) {
+    throw new Error(
+      `${channel} encoding requires a ${defaults.type} coordinate, but "${id}" is ${coordinate.type}.`
+    );
+  }
+  return { id, type: defaults.type };
+}
+
+export function resolvePositionEncoding(program, channel, args, operation) {
+  validateOptions(args, POSITION_ENCODING_OPTIONS, operation);
+  validatePositionChannel(channel);
+  const { id: target, dataset, layer } = resolveTarget(
+    program,
+    args.target,
+    ["point", "line", "bar", "area", "rule"]
+  );
+  const hasField = Object.hasOwn(args, "field");
+  const hasDatum = Object.hasOwn(args, "datum");
+  if (layer.mark.type === "rule") {
+    if (hasField === hasDatum) {
+      throw new Error(`${operation} requires exactly one of field or datum for a rule mark.`);
+    }
+    if (args.fieldType === undefined) {
+      throw new Error(`${operation} requires fieldType for a rule mark.`);
+    }
+  } else if (hasDatum) {
+    throw new Error(`${operation} does not support datum for a ${layer.mark.type} mark.`);
+  }
+  const previous = layer.encoding?.[channel];
+  const requestedFieldType =
+    args.fieldType ?? previous?.fieldType ?? "quantitative";
+  const fieldType = requestedFieldType === "nominal"
+    ? "nominal"
+    : validateFieldType(requestedFieldType);
+  const xEncoding = layer.encoding?.x;
+  const field = layer.mark.type === "bar" && channel === "y" &&
+    xEncoding?.bin !== undefined && args.field === undefined
+    ? xEncoding.field
+    : args.field;
+  const datum = args.datum;
+  const effectiveArgs = { ...args };
+  for (const property of ["aggregate", "bin", "stack"]) {
+    if (!Object.hasOwn(effectiveArgs, property) && previous !== undefined &&
+      Object.hasOwn(previous, property)) {
+      effectiveArgs[property] = previous[property];
+    }
+  }
+  const policy = resolveMarkPositionPolicy({
+    program,
+    layer,
+    dataset,
+    channel,
+    args: effectiveArgs,
+    fieldType,
+    field
+  });
+  const usesField = layer.mark.type !== "rule" || hasField;
+  if (usesField && (typeof field !== "string" || field.length === 0)) {
+    throw new TypeError(`${operation} field must be a non-empty string.`);
+  }
+
+  const aggregateOutput = isAggregate(policy.aggregate);
+  const requestedScale = resolveReassignmentScaleOptions(
+    previous,
+    Object.hasOwn(args, "scale") ? args.scale : {}
+  );
+  const scale = resolvePositionScaleDefinition(
+    program,
+    channel,
+    aggregateOutput ? "quantitative" : fieldType,
+    requestedScale,
+    layer.mark.type === "bar"
+      ? program.markConfigs[target]?.boxPlot !== undefined && fieldType === "quantitative"
+        ? { nice: true, zero: false }
+        : fieldType === "quantitative"
+        ? policy.bin !== undefined || policy.stack === null
+          ? { nice: true, zero: false }
+          : { nice: true, zero: true }
+        : fieldType === "temporal"
+          ? { nice: true }
+          : { discreteType: "band" }
+      : ["ordinal", "nominal"].includes(fieldType)
+        ? { discreteType: "point" }
+        : {}
+  );
+  if (Object.hasOwn(scale, "unknown") && layer.mark.type !== "point") {
+    throw new Error(
+      "Position scale unknown currently requires a row-owned point mark."
+    );
+  }
+  if (layer.mark.type === "rule" && hasDatum) {
+    normalizeRuleDatum(datum, fieldType, channel);
+  } else if (aggregateOutput) {
+    validateAggregateFieldType(policy.aggregate, fieldType);
+    validateAggregateFieldValues(dataset.values, field, fieldType);
+  } else if (program.markConfigs[target]?.boxPlot !== undefined) {
+    for (const [index, row] of dataset.values.entries()) {
+      const value = row[field];
+      if (value === undefined || value === null || value === "") continue;
+      if (fieldType === "quantitative" && !Number.isFinite(value)) {
+        throw new TypeError(`Field "${field}" must contain a finite number at row ${index}.`);
+      }
+    }
+  } else if (Object.hasOwn(scale, "unknown")) {
+    readScaleField(dataset.values, field, fieldType, { allowUnknown: true });
+  } else if (fieldType === "temporal") readTemporalField(dataset.values, field);
+  else if (["ordinal", "nominal"].includes(fieldType)) {
+    readNominalField(dataset.values, field);
+  } else readQuantitativeField(dataset.values, field);
+
+  if (
+    layer.mark.type === "bar" &&
+    ["ordinal", "nominal"].includes(fieldType) &&
+    scale.type === "point"
+  ) {
+    throw new Error("Categorical bar positions require a band scale.");
+  }
+  return {
+    target,
+    layer,
+    previous,
+    requestedScale,
+    field,
+    datum,
+    hasField: usesField,
+    fieldType,
+    scale,
+    coordinate: resolveCoordinate(program, channel, layer, args.coordinate),
+    ...policy
+  };
+}

package/src/actions/encodings/position.js

@@ -0,0 +1,176 @@
+import { action } from "../../core/action.js";
+import {
+  canMaterializeArea,
+  canMaterializeLine,
+} from "../../materialization/marks.js";
+import { resolveBarGrain } from "../../grammar/bars/policy.js";
+import { resolvePositionEncoding } from "./position/resolve.js";
+import { findLayer } from "../../selectors/layers.js";
+import {
+  applyEncodingScale,
+  rebindPositionGuides
+} from "./shared.js";
+
+function encodePosition(program, channel, args, operation) {
+  const {
+    target,
+    layer,
+    previous,
+    requestedScale,
+    field,
+    datum,
+    hasField,
+    fieldType,
+    scale,
+    coordinate,
+    bin,
+    aggregate,
+    stack
+  } = resolvePositionEncoding(program, channel, args, operation);
+
+  let next = program
+    .createCoordinate({
+      id: coordinate.id,
+      type: coordinate.type,
+      layers: [target]
+    });
+  if (previous !== undefined) {
+    const alternate = hasField ? "datum" : "field";
+    if (Object.hasOwn(previous, alternate)) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.${channel}.${alternate}`,
+        remove: true
+      });
+    }
+  }
+  next = next
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.${hasField ? "field" : "datum"}`,
+      value: hasField ? field : datum
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.fieldType`,
+      value: fieldType
+    });
+
+  if (layer.mark.type === "line" && channel === "y" && args.aggregate !== undefined) {
+    next = next.editSemantic({
+      property: `layer[${target}].encoding.y.aggregate`,
+      value: aggregate
+    });
+  }
+
+  if (layer.mark.type === "bar" && channel === "x" && bin !== undefined) {
+    const [mode] = Object.keys(bin);
+    const previousModes = Object.keys(layer.encoding?.x?.bin ?? {});
+    for (const previousMode of previousModes) {
+      if (previousMode === mode) continue;
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.x.bin.${previousMode}`,
+        remove: true
+      });
+    }
+    next = next.editSemantic({
+      property: `layer[${target}].encoding.x.bin.${mode}`,
+      value: bin[mode]
+    });
+  }
+
+  if (layer.mark.type === "bar") {
+    if (aggregate !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.${channel}.aggregate`,
+        value: aggregate
+      });
+    }
+    if (stack !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.${channel}.stack`,
+        value: stack
+      });
+    }
+  }
+
+  if (layer.mark.type === "area" && channel === "y" && stack !== undefined) {
+    next = next.editSemantic({
+      property: `layer[${target}].encoding.y.stack`,
+      value: stack
+    });
+  }
+
+  next = next.editSemantic({
+      property: `layer[${target}].encoding.${channel}.scale`,
+      value: scale.id
+    });
+  next = applyEncodingScale(next, scale, requestedScale, {
+    reassignment: previous?.scale === scale.id
+  });
+  next = rebindPositionGuides(
+    next,
+    channel,
+    previous?.scale,
+    scale.id,
+    target
+  );
+
+  if (layer.mark.type === "line") {
+    const updated = findLayer(next, target);
+    return canMaterializeLine(next, updated)
+      ? next.rematerializeLineMark({ id: target })
+      : next.rematerializeScale({ id: scale.id });
+  }
+
+  if (layer.mark.type === "rule") {
+    return next.rematerializeRuleMark({ id: target });
+  }
+
+  if (layer.mark.type === "bar") {
+    const updated = findLayer(next, target);
+    const pendingBox = next.markConfigs[target]?.boxPlot;
+    if (pendingBox !== undefined && !pendingBox.materialized) {
+      return updated.encoding?.x !== undefined && updated.encoding?.y !== undefined
+        ? next.materializeBoxPlot({ id: target })
+        : next;
+    }
+    const materialized = resolveBarGrain(updated) !== undefined
+      ? next.rematerializeBarMark({ id: target })
+      : next.rematerializeScale({ id: scale.id });
+    return materialized;
+  }
+
+  next = next.rematerializeScale({ id: scale.id });
+  if (layer.mark.type === "area") {
+    const updated = findLayer(next, target);
+    return canMaterializeArea(next, updated)
+      ? next.rematerializeAreaMark({ id: target })
+      : next;
+  }
+  return layer.mark.type === "point"
+    ? next.rematerializePointMark({ id: target })
+    : next;
+}
+
+const encodeX = action(
+  {
+    op: "encodeX",
+    description: "Encode a field as horizontal position."
+  },
+  function (args = {}) {
+    return encodePosition(this, "x", args, "encodeX");
+  }
+);
+
+const encodeY = action(
+  {
+    op: "encodeY",
+    description: "Encode a field as vertical position."
+  },
+  function (args = {}) {
+    return encodePosition(this, "y", args, "encodeY");
+  }
+);
+
+export function registerPositionEncodingActions(ProgramClass) {
+  ProgramClass.prototype.encodeX = encodeX;
+  ProgramClass.prototype.encodeY = encodeY;
+}

package/src/actions/encodings/ranged.js

@@ -0,0 +1,276 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  readNominalField,
+  readQuantitativeField,
+  readTemporalField,
+  validateSemanticFieldType
+} from "../../grammar/scales.js";
+import { normalizeRuleDatum } from "../../grammar/rules.js";
+import {
+  canMaterializeArea,
+  canMaterializeLine
+} from "../../materialization/marks.js";
+import { findLayer } from "../../selectors/layers.js";
+import {
+  resolveTarget,
+  validateLineSeriesCompatibility,
+  validateOptions
+} from "./shared.js";
+
+const SECONDARY_OPTIONS = Object.freeze([
+  "field", "datum", "target", "fieldType", "scale", "coordinate"
+]);
+const RANGE_OPTIONS = Object.freeze([
+  "lower", "upper", "target", "fieldType", "coordinate", "scale"
+]);
+const GROUP_OPTIONS = Object.freeze(["field", "target", "fieldType"]);
+
+function validateSecondaryScale(args, primaryScale, axisLabel) {
+  if (args.scale === undefined) return;
+  if (!isPlainObject(args.scale)) {
+    throw new TypeError("Encoding scale must be a plain object.");
+  }
+  validateOptions(args.scale, ["id"], "scale");
+  if (args.scale.id !== undefined && args.scale.id !== primaryScale) {
+    throw new Error(`${axisLabel} primary and secondary endpoints must share one scale.`);
+  }
+}
+
+function validateSecondaryField(dataset, field, fieldType) {
+  if (["nominal", "ordinal"].includes(fieldType)) {
+    readNominalField(dataset.values, field);
+  } else if (fieldType === "temporal") {
+    readTemporalField(dataset.values, field);
+  } else {
+    readQuantitativeField(dataset.values, field);
+  }
+}
+
+function encodeSecondaryPosition(program, channel, args, operation, types) {
+  validateOptions(args, SECONDARY_OPTIONS, operation);
+  const { id: target, dataset, layer } = resolveTarget(
+    program,
+    args.target,
+    types,
+    types.length === 1 ? `${types[0]} mark` : "ranged mark"
+  );
+  const primaryChannel = channel === "x2" ? "x" : "y";
+  const primary = layer.encoding?.[primaryChannel];
+  if (primary?.scale === undefined) {
+    throw new Error(`${operation} requires an existing ${primaryChannel} encoding.`);
+  }
+  if (args.coordinate !== undefined) {
+    const coordinate = validateUserId(args.coordinate, "Coordinate id");
+    if (coordinate !== layer.coordinate) {
+      throw new Error(
+        `${operation} must use the primary ${primaryChannel} coordinate "${layer.coordinate}".`
+      );
+    }
+  }
+  validateSecondaryScale(args, primary.scale, primaryChannel);
+
+  const rule = layer.mark.type === "rule";
+  const hasField = Object.hasOwn(args, "field");
+  const hasDatum = Object.hasOwn(args, "datum");
+  if (rule && hasField === hasDatum) {
+    throw new Error(`${operation} requires exactly one of field or datum for a rule mark.`);
+  }
+  if (!rule && (!hasField || hasDatum)) {
+    throw new Error(`${operation} requires a field for a ranged mark.`);
+  }
+  if (rule && args.fieldType === undefined) {
+    throw new Error(`${operation} requires fieldType for a rule mark.`);
+  }
+  const fieldType = rule
+    ? validateSemanticFieldType(args.fieldType)
+    : args.fieldType ?? "quantitative";
+  if (!rule && fieldType !== "quantitative") {
+    throw new Error(`${operation} requires a quantitative field.`);
+  }
+  if (rule && fieldType !== primary.fieldType) {
+    throw new Error(
+      `${operation} fieldType must match the primary ${primaryChannel} fieldType.`
+    );
+  }
+  if (hasField) validateSecondaryField(dataset, args.field, fieldType);
+  else normalizeRuleDatum(args.datum, fieldType, channel);
+
+  const previous = layer.encoding?.[channel];
+  let next = program;
+  if (layer.mark.type === "bar") {
+    for (const property of ["aggregate", "stack", "bin"]) {
+      if (layer.encoding?.[primaryChannel]?.[property] !== undefined) {
+        next = next.editSemantic({
+          property: `layer[${target}].encoding.${primaryChannel}.${property}`,
+          remove: true
+        });
+      }
+    }
+  }
+  if (previous !== undefined) {
+    const alternate = hasField ? "datum" : "field";
+    if (Object.hasOwn(previous, alternate)) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.${channel}.${alternate}`,
+        remove: true
+      });
+    }
+  }
+  next = next
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.${hasField ? "field" : "datum"}`,
+      value: hasField ? args.field : args.datum
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.fieldType`,
+      value: fieldType
+    })
+    .editSemantic({
+      property: `layer[${target}].encoding.${channel}.scale`,
+      value: primary.scale
+    })
+    .rematerializeScale({ id: primary.scale });
+  if (rule) return next.rematerializeRuleMark({ id: target });
+  return layer.mark.type === "bar"
+    ? next.rematerializeBarMark({ id: target })
+    : next.rematerializeAreaMark({ id: target });
+}
+
+const encodeX2 = action(
+  {
+    op: "encodeX2",
+    description: "Encode a secondary horizontal endpoint."
+  },
+  function (args = {}) {
+    return encodeSecondaryPosition(
+      this,
+      "x2",
+      args,
+      "encodeX2",
+      ["area", "rule", "bar"]
+    );
+  }
+);
+
+const encodeY2 = action(
+  {
+    op: "encodeY2",
+    description: "Encode a secondary vertical endpoint."
+  },
+  function (args = {}) {
+    return encodeSecondaryPosition(
+      this,
+      "y2",
+      args,
+      "encodeY2",
+      ["area", "rule", "bar"]
+    );
+  }
+);
+
+const encodeYRange = action(
+  {
+    op: "encodeYRange",
+    description: "Atomically encode lower and upper area bounds."
+  },
+  function (args = {}) {
+    validateOptions(args, RANGE_OPTIONS, "encodeYRange");
+    const target = args.target;
+    const lower = this.encodeY({
+      field: args.lower,
+      ...(target === undefined ? {} : { target }),
+      fieldType: args.fieldType ?? "quantitative",
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      ...(args.scale === undefined ? {} : { scale: args.scale })
+    });
+    return lower.encodeY2({
+      field: args.upper,
+      ...(target === undefined ? {} : { target }),
+      fieldType: args.fieldType ?? "quantitative"
+    });
+  }
+);
+
+const encodeXRange = action(
+  {
+    op: "encodeXRange",
+    description: "Atomically encode lower and upper horizontal area bounds."
+  },
+  function (args = {}) {
+    validateOptions(args, RANGE_OPTIONS, "encodeXRange");
+    const target = args.target;
+    const lower = this.encodeX({
+      field: args.lower,
+      ...(target === undefined ? {} : { target }),
+      fieldType: args.fieldType ?? "quantitative",
+      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+      ...(args.scale === undefined ? {} : { scale: args.scale })
+    });
+    return lower.encodeX2({
+      field: args.upper,
+      ...(target === undefined ? {} : { target }),
+      fieldType: args.fieldType ?? "quantitative"
+    });
+  }
+);
+
+const encodeGroup = action(
+  {
+    op: "encodeGroup",
+    description: "Split path geometry by a nominal field without a scale."
+  },
+  function (args = {}) {
+    validateOptions(args, GROUP_OPTIONS, "encodeGroup");
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["line", "area"],
+      "path mark"
+    );
+    if ((args.fieldType ?? "nominal") !== "nominal") {
+      throw new Error("encodeGroup requires a nominal field.");
+    }
+    const densityTransform = dataset.transform?.length === 1 &&
+      dataset.transform[0].type === "density"
+      ? dataset.transform[0]
+      : undefined;
+    if (densityTransform !== undefined && densityTransform.groupBy !== args.field) {
+      throw new Error(
+        densityTransform.groupBy === undefined
+          ? `Ungrouped density area mark "${target}" cannot encode group.`
+          : `Density area mark "${target}" must group by "${densityTransform.groupBy}".`
+      );
+    }
+    readNominalField(dataset.values, args.field);
+    validateLineSeriesCompatibility(layer, "group", args.field);
+    const next = this
+      .editSemantic({
+        property: `layer[${target}].encoding.group.field`,
+        value: args.field
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.group.fieldType`,
+        value: "nominal"
+      });
+    if (layer.mark.type === "area") {
+      const updated = findLayer(next, target);
+      return canMaterializeArea(next, updated)
+        ? next.rematerializeAreaMark({ id: target })
+        : next;
+    }
+    const updated = findLayer(next, target);
+    return canMaterializeLine(next, updated)
+      ? next.rematerializeLineMark({ id: target })
+      : next;
+  }
+);
+
+export function registerRangedEncodingActions(ProgramClass) {
+  ProgramClass.prototype.encodeX2 = encodeX2;
+  ProgramClass.prototype.encodeY2 = encodeY2;
+  ProgramClass.prototype.encodeXRange = encodeXRange;
+  ProgramClass.prototype.encodeYRange = encodeYRange;
+  ProgramClass.prototype.encodeGroup = encodeGroup;
+}

package/src/actions/encodings/ruleAppearance.js

@@ -0,0 +1,47 @@
+import { action } from "../../core/action.js";
+import {
+  validateRuleStroke,
+  validateRuleStrokeWidth
+} from "../../grammar/ruleAppearance.js";
+import { resolveTarget, validateOptions } from "./shared.js";
+
+const OPTIONS = Object.freeze(["target", "value"]);
+
+const encodeStroke = action(
+  {
+    op: "encodeStroke",
+    description: "Set a constant graphical stroke on a rule mark."
+  },
+  function (args = {}) {
+    validateOptions(args, OPTIONS, "encodeStroke");
+    const { id } = resolveTarget(this, args.target, ["rule"], "rule mark");
+    return this
+      ._withMarkConfig(id, {
+        ...this.markConfigs[id],
+        stroke: validateRuleStroke(args.value)
+      })
+      .rematerializeRuleMark({ id });
+  }
+);
+
+const encodeStrokeWidth = action(
+  {
+    op: "encodeStrokeWidth",
+    description: "Set a constant graphical stroke width on a rule mark."
+  },
+  function (args = {}) {
+    validateOptions(args, OPTIONS, "encodeStrokeWidth");
+    const { id } = resolveTarget(this, args.target, ["rule"], "rule mark");
+    return this
+      ._withMarkConfig(id, {
+        ...this.markConfigs[id],
+        strokeWidth: validateRuleStrokeWidth(args.value)
+      })
+      .rematerializeRuleMark({ id });
+  }
+);
+
+export function registerRuleAppearanceEncodingActions(ProgramClass) {
+  ProgramClass.prototype.encodeStroke = encodeStroke;
+  ProgramClass.prototype.encodeStrokeWidth = encodeStrokeWidth;
+}