ggaction 0.0.1

package/src/actions/encodings/shared.js

@@ -0,0 +1,164 @@
+import { validateUserId } from "../../core/identifiers.js";
+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";
+
+export function validateOptions(args, supported, operation) {
+  validateKeys(args, supported, operation);
+}
+
+export function validateLineSeriesCompatibility(layer, channel, field) {
+  if (layer.mark?.type !== "line") return;
+  for (const companion of ["group", "color", "strokeDash"]) {
+    if (companion === channel) continue;
+    const companionField = layer.encoding?.[companion]?.field;
+    if (companionField !== undefined && companionField !== field) {
+      throw new Error(
+        `Line ${channel} field "${field}" must match ${companion} field "${companionField}".`
+      );
+    }
+  }
+}
+
+export function resolveReassignmentScaleOptions(encoding, options) {
+  if (encoding?.scale === undefined || options?.id !== undefined) return options;
+  return { ...options, id: encoding.scale };
+}
+
+export function applyEncodingScale(
+  program,
+  definition,
+  options = {},
+  { reassignment = false } = {}
+) {
+  const existing = findSemanticScale(program, definition.id);
+  if (existing === undefined) {
+    return program.createScale(definition);
+  }
+  if (existing.type !== definition.type) {
+    throw new Error(
+      `Scale "${definition.id}" cannot change type from "${existing.type}" to "${definition.type}".`
+    );
+  }
+
+  const patch = { id: definition.id };
+  for (const property of [
+    "domain", "range", "nice", "zero", "clamp", "reverse",
+    "base", "exponent", "constant", "paddingInner", "paddingOuter",
+    "padding", "align", "unknown", "interpolate"
+  ]) {
+    if (Object.hasOwn(options, property)) patch[property] = definition[property];
+  }
+  if (Object.hasOwn(options, "palette")) patch.range = definition.range;
+
+  return Object.keys(patch).length === 1 || !reassignment
+    ? program.createScale(definition)
+    : program.editScale(patch);
+}
+
+export function rebindPositionGuides(
+  program,
+  channel,
+  previousScale,
+  nextScale,
+  target
+) {
+  if (previousScale === undefined || previousScale === nextScale) return program;
+
+  const axis = program.semanticSpec.guides.axis?.[channel];
+  const direction = channel === "x" ? "vertical" : "horizontal";
+  const grid = program.semanticSpec.guides.grid?.[direction];
+  const ownsAxis = axis?.scale === previousScale;
+  const ownsGrid = grid?.scale === previousScale;
+  if (!ownsAxis && !ownsGrid) return program;
+
+  const remaining = program.semanticSpec.layers.some(layer =>
+    layer.id !== target && layer.encoding?.[channel]?.scale === previousScale
+  );
+  if (remaining) {
+    throw new Error(
+      `Cannot rebind ${channel} guides from shared scale "${previousScale}" while it has other consumers.`
+    );
+  }
+
+  let next = program;
+  if (ownsAxis) {
+    next = next.editSemantic({
+      property: `guide.axis.${channel}.scale`,
+      value: nextScale
+    });
+    for (const component of ["ticks", "labels", "title"]) {
+      const config = next.guideConfigs.axis?.[channel]?.[component];
+      if (config?.scale === previousScale) {
+        next = next._withGuideConfig(channel, component, {
+          ...config,
+          scale: nextScale
+        });
+      }
+    }
+  }
+  if (ownsGrid) {
+    next = next
+      .editSemantic({
+        property: `guide.grid.${direction}.scale`,
+        value: nextScale
+      })
+      ._withGridConfig(direction, {
+        ...next.guideConfigs.grid[direction],
+        scale: nextScale
+      });
+  }
+  return next;
+}
+
+export function rematerializeExistingLegend(program) {
+  return hasMaterializedLegend(program)
+    ? program.rematerializeLegend()
+    : program;
+}
+
+export function resolveTarget(
+  program,
+  target,
+  supportedTypes = ["point", "line"],
+  label = "position mark"
+) {
+  const requested = target === undefined
+    ? undefined
+    : validateUserId(target, "Mark id");
+  const layer = resolveEligibleLayer(program, {
+    target: requested,
+    predicate: candidate => supportedTypes.includes(candidate.mark?.type),
+    label
+  });
+  const id = layer.id;
+
+  const dataset = findDataset(program, layer.data);
+
+  if (dataset === undefined) {
+    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 graphicType = program.graphicSpec.objects[id]?.type;
+  const matches = Array.isArray(expectedGraphic)
+    ? expectedGraphic.includes(graphicType)
+    : graphicType === expectedGraphic;
+  if (!matches) {
+    const label = Array.isArray(expectedGraphic)
+      ? expectedGraphic.join(" or ")
+      : expectedGraphic;
+    throw new Error(`Mark "${id}" requires ${label} graphics.`);
+  }
+
+  return { id, dataset, layer };
+}

package/src/actions/encodings/strokeDash.js

@@ -0,0 +1,145 @@
+import { action } from "../../core/action.js";
+import {
+  normalizeStrokeDashPattern,
+  readNominalField,
+  validateNominalFieldType
+} from "../../grammar/scales.js";
+import { resolveStrokeDashScaleDefinition } from "../scales/definitions.js";
+import { applyMaterializationPlan } from "../../materialization/dependencies.js";
+import { planEncodingRematerialization } from "../../materialization/encodings.js";
+import {
+  applyEncodingScale,
+  resolveReassignmentScaleOptions,
+  resolveTarget,
+  validateLineSeriesCompatibility,
+  validateOptions
+} from "./shared.js";
+import { findLayer } from "../../selectors/layers.js";
+
+const STROKE_DASH_ENCODING_OPTIONS = Object.freeze([
+  "field", "value", "target", "fieldType", "scale"
+]);
+
+const clearStrokeDashEncoding = action(
+  {
+    op: "clearStrokeDashEncoding",
+    description: "Remove the current semantic stroke-dash assignment."
+  },
+  function ({ target } = {}) {
+    const layer = findLayer(this, target);
+    if (layer?.encoding?.strokeDash === undefined) return this;
+    return this.editSemantic({
+      property: `layer[${target}].encoding.strokeDash`,
+      remove: true
+    });
+  }
+);
+
+function reconcileLegendAfterDashRemoval(program, target) {
+  const config = program.guideConfigs.legend?.series;
+  if (
+    config?.target !== target ||
+    !config.channels.includes("strokeDash")
+  ) {
+    return program;
+  }
+  const layer = findLayer(program, target);
+  const channels = config.channels.filter(
+    channel =>
+      channel !== "strokeDash" &&
+      layer.encoding?.[channel]?.scale !== undefined
+  );
+  if (channels.length === 0) return program.removeCategoricalLegend();
+  return program
+    .editSemantic({
+      property: "guide.legend.series.channels",
+      value: channels
+    })
+    .rematerializeLegend();
+}
+
+const encodeStrokeDash = action(
+  {
+    op: "encodeStrokeDash",
+    description: "Encode a nominal field as line stroke dash."
+  },
+  function (args = {}) {
+    validateOptions(args, STROKE_DASH_ENCODING_OPTIONS, "encodeStrokeDash");
+    const hasField = Object.hasOwn(args, "field");
+    const hasValue = Object.hasOwn(args, "value");
+    if (hasField === hasValue) {
+      throw new Error("encodeStrokeDash requires exactly one of field or value.");
+    }
+    if (hasValue && (args.fieldType !== undefined || args.scale !== undefined)) {
+      throw new Error("Constant stroke dash does not accept fieldType or scale.");
+    }
+    const { id: target, dataset, layer } = resolveTarget(
+      this,
+      args.target,
+      ["line", "rule"],
+      "line or rule mark"
+    );
+    if (hasValue) {
+      normalizeStrokeDashPattern(args.value);
+      let next = layer.encoding?.strokeDash === undefined
+        ? this
+        : this.clearStrokeDashEncoding({ target });
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.strokeDash.datum`,
+        value: args.value
+      });
+      next = reconcileLegendAfterDashRemoval(next, target);
+      return layer.mark.type === "rule"
+        ? next.rematerializeRuleMark({ id: target })
+        : next.rematerializeLineMark({ id: target });
+    }
+
+    const fieldType = validateNominalFieldType(args.fieldType ?? "nominal");
+    validateLineSeriesCompatibility(layer, "strokeDash", args.field);
+    const previous = layer.encoding?.strokeDash;
+    const requestedScale = previous?.field === args.field
+      ? resolveReassignmentScaleOptions(previous, args.scale ?? {})
+      : args.scale ?? {};
+    const scale = resolveStrokeDashScaleDefinition(this, requestedScale);
+    if (Object.hasOwn(scale, "unknown")) {
+      throw new Error(
+        "StrokeDash scale unknown is not supported for grouped line or rule paths."
+      );
+    }
+    readNominalField(dataset.values, args.field);
+
+    let next = previous === undefined
+      ? this
+      : this.clearStrokeDashEncoding({ target });
+    next = next
+      .editSemantic({
+        property: `layer[${target}].encoding.strokeDash.field`,
+        value: args.field
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.strokeDash.fieldType`,
+        value: fieldType
+      })
+      .editSemantic({
+        property: `layer[${target}].encoding.strokeDash.scale`,
+        value: scale.id
+      });
+    next = applyEncodingScale(next, scale, requestedScale, {
+      reassignment: previous?.scale === scale.id
+    });
+
+    return applyMaterializationPlan(
+      next,
+      planEncodingRematerialization(next, {
+        target,
+        channel: "strokeDash",
+        scale: scale.id
+      })
+    );
+  }
+);
+
+export function registerStrokeDashEncodingActions(ProgramClass) {
+  ProgramClass.prototype.encodeStrokeDash = encodeStrokeDash;
+  ProgramClass.prototype.clearStrokeDashEncoding = clearStrokeDashEncoding;
+}

package/src/actions/errorBands/components.js

@@ -0,0 +1,81 @@
+import { action } from "../../core/action.js";
+
+function positionOptions({ target, field, fieldType, coordinate, scale }) {
+  return {
+    target,
+    field,
+    fieldType,
+    coordinate,
+    scale: { id: scale }
+  };
+}
+
+export const createErrorBandBoundary = action(
+  {
+    op: "createErrorBandBoundary",
+    description: "Create one lower or upper error-band boundary line."
+  },
+  function ({
+    id,
+    data,
+    orientation,
+    bound,
+    position,
+    coordinate,
+    intervalScale,
+    positionScale,
+    groupBy,
+    stroke,
+    strokeWidth,
+    strokeDash,
+    opacity,
+    curve
+  } = {}) {
+    let next = this.createLineMark({ id, data, strokeWidth, curve });
+    if (orientation === "vertical") {
+      next = next
+        .encodeY(positionOptions({
+          target: id,
+          field: bound,
+          fieldType: "quantitative",
+          coordinate,
+          scale: intervalScale
+        }))
+        .encodeX(positionOptions({
+          target: id,
+          field: position.field,
+          fieldType: position.fieldType,
+          coordinate,
+          scale: positionScale
+        }));
+    } else {
+      next = next
+        .encodeY(positionOptions({
+          target: id,
+          field: position.field,
+          fieldType: position.fieldType,
+          coordinate,
+          scale: positionScale
+        }))
+        .encodeX(positionOptions({
+          target: id,
+          field: bound,
+          fieldType: "quantitative",
+          coordinate,
+          scale: intervalScale
+        }));
+    }
+    if (groupBy !== undefined) {
+      next = next.encodeGroup({ target: id, field: groupBy });
+    }
+    next = next
+      .editGraphics({ target: id, property: "stroke", value: stroke })
+      .editGraphics({
+        target: id,
+        property: "strokeDash",
+        value: next.graphicSpec.objects[id].items.map(() => strokeDash)
+      })
+      .editGraphics({ target: id, property: "opacity", value: opacity });
+    return next;
+  }
+);

package/src/actions/errorBands/create.js

@@ -0,0 +1,159 @@
+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 { resolveErrorBand } from "./resolve.js";
+
+const OPTIONS = Object.freeze([
+  "id",
+  "target",
+  "data",
+  "x",
+  "y",
+  "groupBy",
+  "coordinate",
+  "fill",
+  "opacity",
+  "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
+  };
+}
+
+function positionArgs(resolved) {
+  return {
+    target: resolved.id,
+    field: resolved.position.field,
+    fieldType: resolved.position.fieldType,
+    coordinate: resolved.coordinate,
+    scale: resolved.position.scale
+  };
+}
+
+function rangeArgs(resolved) {
+  return {
+    target: resolved.id,
+    lower: resolved.fields.lower,
+    upper: resolved.fields.upper,
+    fieldType: "quantitative",
+    coordinate: resolved.coordinate,
+    scale: resolved.interval.scale
+  };
+}
+
+export const createErrorBand = action(
+  {
+    op: "createErrorBand",
+    description: "Create a statistical or explicit interval band."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createErrorBand");
+    const resolved = resolveErrorBand(this, args);
+    const curve = validateCurveInterpolation(args.curve ?? "linear");
+    const boundaries = resolveBoundaries(args.boundaries, curve);
+    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
+      });
+    }
+
+    next = next.createAreaMark({
+      id: resolved.id,
+      data: resolved.dataId,
+      ...(args.fill === undefined ? {} : { fill: args.fill }),
+      ...(args.opacity === undefined ? {} : { opacity: args.opacity }),
+      ...(Object.hasOwn(args, "curve") ? { curve } : {})
+    });
+    next = resolved.orientation === "vertical"
+      ? next
+          .encodeX(positionArgs(resolved))
+          .encodeYRange(rangeArgs(resolved))
+      : next
+          .encodeY(positionArgs(resolved))
+          .encodeXRange(rangeArgs(resolved));
+
+    if (resolved.interval.mode === "explicit") {
+      next = next.editSemantic({
+        property: `layer[${resolved.id}].encoding.${resolved.interval.channel}.title`,
+        value: resolved.interval.title
+      });
+    }
+    if (resolved.groupField !== undefined) {
+      next = next.encodeGroup({
+        target: resolved.id,
+        field: resolved.groupField,
+        fieldType: "nominal"
+      });
+    }
+    if (boundaries !== undefined) {
+      const shared = {
+        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,
+        ...boundaries
+      };
+      next = next
+        .createErrorBandBoundary({
+          ...shared,
+          id: `${resolved.id}LowerBoundary`,
+          bound: resolved.fields.lower
+        })
+        .createErrorBandBoundary({
+          ...shared,
+          id: `${resolved.id}UpperBoundary`,
+          bound: resolved.fields.upper
+        });
+    }
+    return next;
+  }
+);

package/src/actions/errorBands/index.js

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

package/src/actions/errorBands/resolve.js

@@ -0,0 +1,28 @@
+import { resolveIntervalComposite } from "../intervals/resolve.js";
+
+const ERROR_BAND_POLICY = Object.freeze({
+  operation: "createErrorBand",
+  resourceLabel: "error-band",
+  defaultId: "errorBand",
+  ownerLabel: "Error-band id",
+  positionTypes: Object.freeze(["quantitative", "temporal"]),
+  defaultPositionType: "quantitative",
+  defaultIntervalChannel: "y",
+  scaleDefaults: fieldType => fieldType === "temporal"
+    ? { nice: true }
+    : { nice: true, zero: false },
+  intervalScaleDefaults: Object.freeze({ nice: true, zero: false }),
+  allowExplicitGrouping: true,
+  ambiguousMessage:
+    "createErrorBand cannot infer the interval axis when both positions are quantitative; provide an interval option."
+});
+
+export function resolveErrorBand(program, args) {
+  const resolved = resolveIntervalComposite(program, args, ERROR_BAND_POLICY);
+  if (resolved.groupField === resolved.position.field) {
+    throw new Error(
+      "createErrorBand groupBy must differ from the independent position field."
+    );
+  }
+  return resolved;
+}

package/src/actions/errorBars/components.js

@@ -0,0 +1,62 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+
+const OPTIONS = Object.freeze([
+  "id",
+  "data",
+  "orientation",
+  "positionField",
+  "positionFieldType",
+  "intervalField",
+  "coordinate",
+  "positionScale",
+  "intervalScale",
+  "capSize",
+  "stroke",
+  "strokeWidth",
+  "strokeDash",
+  "opacity"
+]);
+
+export const createErrorBarCap = action(
+  {
+    op: "createErrorBarCap",
+    description: "Create one fixed-pixel error-bar cap."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createErrorBarCap");
+    if (!["vertical", "horizontal"].includes(args.orientation)) {
+      throw new Error(`Unsupported error-bar orientation "${args.orientation}".`);
+    }
+    const positionChannel = args.orientation === "vertical" ? "x" : "y";
+    const intervalChannel = args.orientation === "vertical" ? "y" : "x";
+    const positionAction = positionChannel === "x" ? "encodeX" : "encodeY";
+    const intervalAction = intervalChannel === "x" ? "encodeX" : "encodeY";
+
+    return 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 }
+      })
+      .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: args.orientation === "vertical" ? "horizontal" : "vertical",
+        size: args.capSize
+      });
+  }
+);