ggaction 0.0.1

package/src/actions/encodings/density.js

@@ -0,0 +1,225 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  findDataset,
+  findLayer,
+  hasDataset,
+  resolveEligibleLayer
+} from "../../selectors/index.js";
+import { applyMaterializationPlan } from
+  "../../materialization/dependencies.js";
+import { planDensityRematerialization } from
+  "../../materialization/density.js";
+import { validateOptions } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "field", "target", "source", "groupBy", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "as", "densityChannel", "coordinate",
+  "valueScale", "densityScale"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "bandwidth", "extent", "steps", "kernel", "normalization"
+]);
+const EDITABLE = Object.freeze(EDIT_OPTIONS.filter(option => option !== "target"));
+
+function findArea(program, requested) {
+  const areas = program.semanticSpec.layers.filter(layer => layer.mark?.type === "area");
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Density target id");
+    const selected = findLayer(program, id);
+    if (selected === undefined || !areas.includes(selected)) {
+      throw new Error(`Unknown density area target "${id}".`);
+    }
+    return selected;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current !== undefined && areas.includes(current)) return current;
+  if (areas.length === 1) return areas[0];
+  if (areas.length === 0) {
+    throw new Error("encodeDensity requires an eligible area mark.");
+  }
+  throw new Error("encodeDensity target is ambiguous; provide target.");
+}
+
+function requireField(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError(`${label} must be a non-empty string.`);
+  }
+  return value;
+}
+
+function scaleOptions(value, defaults, label) {
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError(`${label} must be a plain object.`);
+  }
+  return { ...defaults, ...(value ?? {}) };
+}
+
+const encodeDensity = action(
+  {
+    op: "encodeDensity",
+    description: "Derive and encode a baseline-oriented kernel density area."
+  },
+  function (args = {}) {
+    validateOptions(args, OPTIONS, "encodeDensity");
+    const layer = findArea(this, args.target);
+    const field = requireField(args.field, "Density field");
+    const groupBy = args.groupBy === undefined
+      ? undefined
+      : requireField(args.groupBy, "Density groupBy");
+    const source = validateUserId(
+      args.source ?? layer.data,
+      "Density source dataset id"
+    );
+    if (!hasDataset(this, source)) {
+      throw new Error(`Unknown density source dataset "${source}".`);
+    }
+    if (["x", "y", "y2", "group"].some(channel =>
+      layer.encoding?.[channel] !== undefined
+    )) {
+      throw new Error(
+        `Density area target "${layer.id}" already has positional or group encodings.`
+      );
+    }
+    const densityChannel = args.densityChannel ?? "y";
+    if (!["x", "y"].includes(densityChannel)) {
+      throw new Error(`Unsupported densityChannel "${densityChannel}".`);
+    }
+    const output = args.as ?? [`${field}_value`, `${field}_density`];
+    if (!Array.isArray(output) || output.length !== 2) {
+      throw new TypeError("Density as must contain value and density field names.");
+    }
+    const derivedId = `${layer.id}DensityData`;
+    if (hasDataset(this, derivedId)) {
+      throw new Error(`Dataset "${derivedId}" already exists.`);
+    }
+    const valueScale = scaleOptions(
+      args.valueScale,
+      { nice: false, zero: false },
+      "Density valueScale"
+    );
+    const densityScale = scaleOptions(
+      args.densityScale,
+      { nice: true, zero: true },
+      "Density densityScale"
+    );
+    const xIsDensity = densityChannel === "x";
+    const xField = output[xIsDensity ? 1 : 0];
+    const yField = output[xIsDensity ? 0 : 1];
+    const xScale = xIsDensity ? densityScale : valueScale;
+    const yScale = xIsDensity ? valueScale : densityScale;
+
+    let next = this
+      .createDensityData({
+        id: derivedId,
+        source,
+        field,
+        ...(groupBy === undefined ? {} : { groupBy }),
+        ...(args.bandwidth === undefined ? {} : { bandwidth: args.bandwidth }),
+        ...(args.extent === undefined ? {} : { extent: args.extent }),
+        ...(args.steps === undefined ? {} : { steps: args.steps }),
+        ...(args.kernel === undefined ? {} : { kernel: args.kernel }),
+        ...(args.normalization === undefined
+          ? {}
+          : { normalization: args.normalization }),
+        ...(args.as === undefined ? {} : { as: args.as })
+      })
+      .editSemantic({
+        property: `layer[${layer.id}].data`,
+        value: derivedId
+      })
+      .encodeX({
+        target: layer.id,
+        field: xField,
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+        scale: xScale
+      })
+      .encodeY({
+        target: layer.id,
+        field: yField,
+        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+        scale: yScale
+      });
+    if (groupBy !== undefined) {
+      next = next.encodeGroup({ target: layer.id, field: groupBy });
+    }
+    return next.rematerializeAreaMark({ id: layer.id });
+  }
+);
+
+function findDensityArea(program, requested) {
+  const target = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Density target id");
+  return resolveEligibleLayer(program, {
+    target,
+    label: "density area",
+    predicate(layer) {
+      const dataset = findDataset(program, layer.data);
+      return layer.mark?.type === "area" &&
+        dataset?.transform?.length === 1 &&
+        dataset.transform[0].type === "density";
+    }
+  });
+}
+
+function nextDensityRevisionId(program, target) {
+  let revision = 1;
+  while (hasDataset(program, `${target}DensityDataRevision${revision}`)) {
+    revision += 1;
+  }
+  return `${target}DensityDataRevision${revision}`;
+}
+
+const editDensity = action(
+  {
+    op: "editDensity",
+    description: "Revise one density transform and rematerialize its consumers."
+  },
+  function (args = {}) {
+    validateOptions(args, EDIT_OPTIONS, "editDensity");
+    if (!EDITABLE.some(option => Object.hasOwn(args, option))) {
+      throw new Error("editDensity requires at least one density option.");
+    }
+    const layer = findDensityArea(this, args.target);
+    const previous = findDataset(this, layer.data);
+    const transform = previous.transform[0];
+    const revisionId = nextDensityRevisionId(this, layer.id);
+    const option = property => Object.hasOwn(args, property)
+      ? args[property]
+      : transform[property];
+
+    let next = this
+      .createDensityData({
+        id: revisionId,
+        source: previous.source,
+        field: transform.field,
+        ...(transform.groupBy === undefined
+          ? {}
+          : { groupBy: transform.groupBy }),
+        bandwidth: option("bandwidth"),
+        extent: option("extent"),
+        steps: option("steps"),
+        kernel: option("kernel") ?? "gaussian",
+        normalization: option("normalization") ?? "unit",
+        as: transform.as
+      })
+      .editSemantic({
+        property: `layer[${layer.id}].data`,
+        value: revisionId
+      })
+      .releaseDerivedData({ id: previous.id });
+
+    next = applyMaterializationPlan(
+      next,
+      planDensityRematerialization(next, layer.id)
+    );
+    return next;
+  }
+);
+
+export function registerDensityEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeDensity = encodeDensity;
+  ProgramClass.prototype.editDensity = editDensity;
+}

package/src/actions/encodings/histogram.js

@@ -0,0 +1,50 @@
+import { action } from "../../core/action.js";
+import { validateOptions } from "./shared.js";
+
+const HISTOGRAM_OPTIONS = Object.freeze([
+  "field", "target", "coordinate", "maxBins", "binStep", "binBoundaries",
+  "stack", "xScale", "yScale"
+]);
+
+const encodeHistogram = action(
+  {
+    op: "encodeHistogram",
+    description: "Encode a binned count histogram with a configurable layout stack."
+  },
+  function (args = {}) {
+    validateOptions(args, HISTOGRAM_OPTIONS, "encodeHistogram");
+    const binOptions = ["maxBins", "binStep", "binBoundaries"].filter(
+      key => Object.hasOwn(args, key)
+    );
+    if (binOptions.length > 1) {
+      throw new Error(
+        "encodeHistogram accepts only one of maxBins, binStep, or binBoundaries."
+      );
+    }
+    const bin = Object.hasOwn(args, "binStep")
+      ? { step: args.binStep }
+      : Object.hasOwn(args, "binBoundaries")
+        ? { boundaries: args.binBoundaries }
+        : { maxBins: args.maxBins ?? 10 };
+    const x = {
+      field: args.field,
+      bin
+    };
+    const y = {
+      stack: Object.hasOwn(args, "stack") ? args.stack : "zero"
+    };
+
+    for (const key of ["target", "coordinate"]) {
+      if (Object.hasOwn(args, key)) x[key] = args[key];
+    }
+    if (Object.hasOwn(args, "target")) y.target = args.target;
+    if (Object.hasOwn(args, "xScale")) x.scale = args.xScale;
+    if (Object.hasOwn(args, "yScale")) y.scale = args.yScale;
+
+    return this.encodeX(x).encodeY(y);
+  }
+);
+
+export function registerHistogramEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeHistogram = encodeHistogram;
+}

package/src/actions/encodings/index.js

@@ -0,0 +1,23 @@
+import { registerAppearanceEncodingAction } from "./appearance.js";
+import { registerBarWidthEncodingAction } from "./barWidth.js";
+import { registerColorEncodingAction } from "./color.js";
+import { registerDensityEncodingAction } from "./density.js";
+import { registerHistogramEncodingAction } from "./histogram.js";
+import { registerOffsetEncodingAction } from "./offset.js";
+import { registerPositionEncodingActions } from "./position.js";
+import { registerRangedEncodingActions } from "./ranged.js";
+import { registerStrokeDashEncodingActions } from "./strokeDash.js";
+import { registerRuleAppearanceEncodingActions } from "./ruleAppearance.js";
+
+export function registerEncodingActions(ProgramClass) {
+  registerPositionEncodingActions(ProgramClass);
+  registerRangedEncodingActions(ProgramClass);
+  registerOffsetEncodingAction(ProgramClass);
+  registerBarWidthEncodingAction(ProgramClass);
+  registerHistogramEncodingAction(ProgramClass);
+  registerDensityEncodingAction(ProgramClass);
+  registerColorEncodingAction(ProgramClass);
+  registerStrokeDashEncodingActions(ProgramClass);
+  registerAppearanceEncodingAction(ProgramClass);
+  registerRuleAppearanceEncodingActions(ProgramClass);
+}

package/src/actions/encodings/offset.js

@@ -0,0 +1,104 @@
+import { action } from "../../core/action.js";
+import {
+  readNominalField,
+  validateNominalFieldType
+} from "../../grammar/scales.js";
+import { resolveOffsetScaleDefinition } from "../scales/definitions.js";
+import {
+  applyEncodingScale,
+  resolveReassignmentScaleOptions,
+  resolveTarget,
+  validateOptions
+} from "./shared.js";
+import {
+  resolveBarColorLayout,
+  resolveBarGrain
+} from "../../grammar/bars/policy.js";
+import { normalizeOffsetPadding } from "../../grammar/bars/geometry.js";
+import { applyMaterializationPlan } from "../../materialization/dependencies.js";
+import { planEncodingRematerialization } from "../../materialization/encodings.js";
+
+const ENCODING_OPTIONS = Object.freeze([
+  "field", "target", "fieldType", "scale", "paddingInner", "paddingOuter"
+]);
+const encodeXOffset = action(
+  {
+    op: "encodeXOffset",
+    description: "Encode a nominal field within each ordinal x band."
+  },
+  function (args = {}) {
+    validateOptions(args, ENCODING_OPTIONS, "encodeXOffset");
+    const fieldType = validateNominalFieldType(args.fieldType ?? "nominal");
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["bar"],
+      "bar mark"
+    );
+
+    if (
+      resolveBarGrain(layer) === undefined ||
+      layer.encoding.x.scale === undefined
+    ) {
+      throw new Error(
+        "encodeXOffset requires a complete bar x/y encoding."
+      );
+    }
+    if (
+      layer.encoding?.color !== undefined &&
+      (resolveBarColorLayout(layer) !== "group" ||
+        layer.encoding.color.field !== args.field)
+    ) {
+      throw new Error(
+        "encodeXOffset field must match a grouped bar color field."
+      );
+    }
+
+    readNominalField(dataset.values, args.field);
+    const requestedScale = resolveReassignmentScaleOptions(
+      layer.encoding?.xOffset,
+      args.scale ?? {}
+    );
+    const scale = resolveOffsetScaleDefinition(this, requestedScale);
+    if (Object.hasOwn(scale, "unknown")) {
+      throw new Error("xOffset scale unknown is not supported for grouped bars.");
+    }
+    const padding = normalizeOffsetPadding(
+      args,
+      this.markConfigs[target]?.xOffset
+    );
+
+    let next = this
+      .editSemantic({
+        property: `layer[${target}].encoding.xOffset.field`,
+        value: args.field
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.xOffset.fieldType`,
+        value: fieldType
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.xOffset.scale`,
+        value: scale.id
+      })
+      ._withMarkConfig(target, {
+        ...this.markConfigs[target],
+        xOffset: padding
+      });
+    next = applyEncodingScale(next, scale, requestedScale, {
+      reassignment: layer.encoding?.xOffset?.scale === scale.id
+    });
+    return applyMaterializationPlan(
+      next,
+      planEncodingRematerialization(next, {
+        target,
+        channel: "xOffset",
+        scale: scale.id
+      })
+    );
+  }
+);
+
+export function registerOffsetEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeXOffset = encodeXOffset;
+}

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

@@ -0,0 +1,24 @@
+import { validateStack, emptyPositionPolicy } from "./common.js";
+
+export function resolveAreaPositionPolicy({ dataset, channel, args, fieldType }) {
+  if (!["quantitative", "temporal"].includes(fieldType)) {
+    throw new Error(
+      "Area position encoding requires quantitative or temporal fields."
+    );
+  }
+  if (args.aggregate !== undefined || args.bin !== undefined) {
+    throw new Error("Area position encoding does not support aggregate or bin.");
+  }
+  if (args.stack === undefined) return emptyPositionPolicy();
+  if (
+    channel !== "y" ||
+    !dataset.transform?.some(transform => transform.type === "density")
+  ) {
+    throw new Error("Area stack currently requires a density y encoding.");
+  }
+  return {
+    bin: undefined,
+    aggregate: undefined,
+    stack: validateStack(args.stack, "Area y encoding")
+  };
+}

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

@@ -0,0 +1,110 @@
+import {
+  validateAggregate,
+  validateAggregateFieldType
+} from "../../../../grammar/aggregate.js";
+import {
+  BAR_ORIENTATIONS,
+  resolveBarOrientation
+} from "../../../../grammar/bars/policy.js";
+import { resolveBin, validateStack } from "./common.js";
+
+export function resolveBarPositionPolicy({
+  program,
+  layer,
+  channel,
+  args,
+  fieldType,
+  field
+}) {
+  let bin;
+  let aggregate;
+  let stack;
+  const xEncoding = layer.encoding?.x;
+  const opposite = layer.encoding?.[channel === "x" ? "y" : "x"];
+  const pendingBoxRange = program.markConfigs[layer.id]?.boxPlot !== undefined;
+
+  if (["nominal", "ordinal", "temporal"].includes(fieldType)) {
+    if (args.aggregate !== undefined || args.bin !== undefined || args.stack !== undefined) {
+      throw new Error(
+        "Categorical bar position does not support bin or aggregate; a binned bar requires a quantitative field."
+      );
+    }
+  } else if (fieldType === "quantitative" && channel === "x" && args.bin !== undefined) {
+    if (args.aggregate !== undefined || args.stack !== undefined) {
+      throw new Error("Binned bar x encoding does not support aggregate or stack.");
+    }
+    bin = resolveBin(args.bin);
+  } else if (
+    fieldType === "quantitative" &&
+    channel === "y" &&
+    xEncoding?.bin !== undefined
+  ) {
+    if (args.bin !== undefined) {
+      throw new Error("Histogram bar y encoding does not support bin.");
+    }
+    if (field !== xEncoding.field) {
+      throw new Error("Bar y field must match the binned x field.");
+    }
+    aggregate = args.aggregate ?? "count";
+    stack = Object.hasOwn(args, "stack") ? args.stack : "zero";
+    if (aggregate !== "count") {
+      throw new Error('Histogram bar y aggregate must be "count".');
+    }
+    stack = validateStack(stack, "Histogram bar y encoding");
+  } else if (fieldType === "quantitative") {
+    if (args.bin !== undefined) {
+      throw new Error(
+        channel === "y"
+          ? "Bar y does not support bin; histogram y requires a binned x encoding."
+          : "Quantitative bar measure encoding does not support bin."
+      );
+    }
+    aggregate = args.aggregate ?? (
+      ["nominal", "ordinal", "temporal"].includes(opposite?.fieldType) &&
+      !pendingBoxRange
+        ? "mean"
+        : undefined
+    );
+    if (pendingBoxRange && args.aggregate === undefined) {
+      return { bin, aggregate, stack };
+    }
+    if (aggregate === undefined) {
+      throw new Error(
+        channel === "x"
+          ? "Quantitative bar x encoding requires bin or aggregate."
+          : "Bar y encoding requires a binned quantitative or ordinal x category, temporal x category, or aggregate."
+      );
+    }
+    stack = Object.hasOwn(args, "stack") ? args.stack : null;
+    aggregate = validateAggregate(aggregate);
+    validateAggregateFieldType(aggregate, fieldType);
+    stack = validateStack(stack, `Bar ${channel} encoding`);
+  } else {
+    throw new Error(
+      "Bar position requires quantitative, temporal, ordinal, or nominal fields."
+    );
+  }
+
+  const candidate = {
+    ...layer,
+    encoding: {
+      ...layer.encoding,
+      [channel]: { field, fieldType, bin, aggregate, stack }
+    }
+  };
+  const orientation = resolveBarOrientation(candidate);
+  if (opposite !== undefined && orientation === undefined && !pendingBoxRange) {
+    throw new Error(
+      `Bar ${channel} encoding requires a quantitative field opposite a categorical position.`
+    );
+  }
+  if (
+    orientation === BAR_ORIENTATIONS.horizontal &&
+    candidate.encoding?.xOffset !== undefined
+  ) {
+    throw new Error(
+      "Horizontal grouped bars require yOffset support, which is not available yet."
+    );
+  }
+  return { bin, aggregate, stack };
+}

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

@@ -0,0 +1,17 @@
+import { STACK_MODES } from "../../../../core/vocabulary.js";
+import { normalizeHistogramBin } from "../../../../grammar/histogram.js";
+
+export function resolveBin(bin) {
+  return normalizeHistogramBin(bin);
+}
+
+export function validateStack(stack, label) {
+  if (stack !== null && !STACK_MODES.includes(stack)) {
+    throw new Error(`${label} has unsupported stack "${stack}".`);
+  }
+  return stack;
+}
+
+export function emptyPositionPolicy() {
+  return { bin: undefined, aggregate: undefined, stack: undefined };
+}

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

@@ -0,0 +1,25 @@
+import { validatePositionFieldCompatibility } from
+  "../../../../grammar/positionCompatibility.js";
+import { resolveAreaPositionPolicy } from "./area.js";
+import { resolveBarPositionPolicy } from "./bar.js";
+import { resolveLinePositionPolicy } from "./line.js";
+import { resolvePointPositionPolicy } from "./point.js";
+import { resolveRulePositionPolicy } from "./rule.js";
+
+const POSITION_POLICIES = Object.freeze({
+  area: resolveAreaPositionPolicy,
+  bar: resolveBarPositionPolicy,
+  line: resolveLinePositionPolicy,
+  point: resolvePointPositionPolicy,
+  rule: resolveRulePositionPolicy
+});
+
+export function resolveMarkPositionPolicy(context) {
+  const { layer, channel, fieldType } = context;
+  validatePositionFieldCompatibility(layer.mark.type, channel, fieldType);
+  const policy = POSITION_POLICIES[layer.mark.type];
+  if (policy === undefined) {
+    throw new Error(`Unsupported position policy for mark "${layer.mark.type}".`);
+  }
+  return policy(context);
+}

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

@@ -0,0 +1,74 @@
+import {
+  validateAggregate,
+  validateAggregateFieldType
+} from "../../../../grammar/aggregate.js";
+import { emptyPositionPolicy } from "./common.js";
+
+function rejectSharedOptions(args, channel) {
+  if (args.bin !== undefined) {
+    throw new Error(`Line ${channel} encoding does not support bin.`);
+  }
+  if (args.stack !== undefined) {
+    throw new Error(`Line ${channel} encoding does not support stack.`);
+  }
+}
+
+export function resolveLinePositionPolicy({
+  layer,
+  dataset,
+  channel,
+  args,
+  fieldType
+}) {
+  const regression = dataset.transform?.some(item => item.type === "regression");
+  const interval = dataset.transform?.some(item => item.type === "interval");
+
+  if (channel === "x") {
+    const horizontalDirect =
+      layer.encoding?.y?.fieldType === "temporal" &&
+      fieldType === "quantitative";
+    if (
+      fieldType !== "temporal" &&
+      !((regression || interval || horizontalDirect) && fieldType === "quantitative")
+    ) {
+      throw new Error(
+        "Line x encoding requires a temporal field or a compatible derived quantitative field."
+      );
+    }
+    if (args.aggregate !== undefined) {
+      throw new Error("Line x encoding does not support aggregate.");
+    }
+    rejectSharedOptions(args, "x");
+    return emptyPositionPolicy();
+  }
+
+  rejectSharedOptions(args, "y");
+  const prospectiveDirect =
+    args.aggregate === undefined &&
+    (fieldType === "temporal" ||
+      (fieldType === "quantitative" && layer.encoding?.x === undefined));
+  if (interval || prospectiveDirect) {
+    if (!["quantitative", "temporal"].includes(fieldType)) {
+      throw new Error(
+        "Direct line y encoding requires a quantitative or temporal field."
+      );
+    }
+    if (args.aggregate !== undefined) {
+      throw new Error("Direct line y encoding does not support aggregate.");
+    }
+    return emptyPositionPolicy();
+  }
+  if (regression) {
+    if (fieldType !== "quantitative") {
+      throw new Error("Regression line y encoding requires a quantitative field.");
+    }
+    if (args.aggregate !== undefined) {
+      throw new Error("Regression line y encoding does not support aggregate.");
+    }
+    return emptyPositionPolicy();
+  }
+
+  const aggregate = validateAggregate(args.aggregate);
+  validateAggregateFieldType(aggregate, fieldType);
+  return { bin: undefined, aggregate, stack: undefined };
+}

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

@@ -0,0 +1,19 @@
+import { emptyPositionPolicy } from "./common.js";
+
+export function resolvePointPositionPolicy({ args, fieldType }) {
+  if (!["quantitative", "temporal", "ordinal", "nominal"].includes(fieldType)) {
+    throw new Error(
+      "Point position encoding requires quantitative, temporal, ordinal, or nominal fields."
+    );
+  }
+  if (args.aggregate !== undefined) {
+    throw new Error("Point position encoding does not support aggregate.");
+  }
+  if (args.bin !== undefined) {
+    throw new Error("Point position encoding does not support bin.");
+  }
+  if (args.stack !== undefined) {
+    throw new Error("Point position encoding does not support stack.");
+  }
+  return emptyPositionPolicy();
+}