ggaction 0.0.1

package/src/actions/marks/area.js

@@ -0,0 +1,369 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../core/validation.js";
+import {
+  deriveAreaSeries,
+  deriveDensityAreaSeries,
+  layoutDensityAreaSeries
+} from "../../grammar/areaSeries.js";
+import { mapContinuousScaleValues, mapOrdinalValues } from "../../grammar/scales.js";
+import {
+  assertMarkAvailable,
+  resolveMarkId,
+  resolveMarkData,
+  validateMarkOptions
+} from "./shared.js";
+import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import {
+  buildAreaCurvePathCommands,
+  validateCurveInterpolation
+} from "../../grammar/curveCommands.js";
+import { buildLinearPathCommands } from "../../grammar/pathCommands.js";
+import { resolveEligibleLayer } from "../../selectors/layers.js";
+import { canMaterializeArea } from "../../materialization/marks.js";
+import { findUpstreamTransform } from "../../materialization/dataProvenance.js";
+import { resolveMarkGraphicPlacement } from
+  "../../materialization/graphicHierarchy.js";
+
+const CREATE_OPTIONS = Object.freeze([
+  "id", "data", "fill", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "fill", "opacity", "stroke", "strokeWidth", "curve"
+]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+
+export function validateAreaCreateOutline(args, operation = "createAreaMark") {
+  if (Object.hasOwn(args, "strokeWidth") && !Object.hasOwn(args, "stroke")) {
+    throw new Error(`${operation} strokeWidth requires stroke.`);
+  }
+  const stroke = Object.hasOwn(args, "stroke")
+    ? validateNonEmptyString(args.stroke, "Area stroke")
+    : undefined;
+  return {
+    stroke,
+    strokeWidth: stroke === undefined
+      ? undefined
+      : validateNonNegativeFinite(args.strokeWidth ?? 1, "Area strokeWidth")
+  };
+}
+
+const createAreaMark = action(
+  {
+    op: "createAreaMark",
+    description: "Create a semantic area mark and empty path collection."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, CREATE_OPTIONS, "createAreaMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "area",
+      label: "Area mark id",
+      markType: "area",
+      operation: "createAreaMark"
+    });
+    const { data } = resolveMarkData(this, args);
+    const fill = validateNonEmptyString(args.fill ?? DEFAULT_COLORS.mark, "Area fill");
+    const opacity = validateUnitInterval(args.opacity ?? 0.2, "Area opacity");
+    const curve = validateCurveInterpolation(args.curve ?? "linear");
+    const { stroke, strokeWidth } = validateAreaCreateOutline(args);
+    assertMarkAvailable(this, id);
+    return this
+      .editSemantic({ property: `layer[${id}].mark.type`, value: "area" })
+      .editSemantic({ property: `layer[${id}].data`, value: data })
+      .createGraphics({
+        id,
+        type: "path",
+        length: 0,
+        ...resolveMarkGraphicPlacement(this, { data, markType: "area" })
+      })
+      ._withMarkConfig(id, {
+        fill,
+        opacity,
+        ...(Object.hasOwn(args, "curve") ? { curve } : {}),
+        ...(stroke === undefined ? {} : { stroke, strokeWidth })
+      });
+  }
+);
+
+const rematerializeAreaMark = action(
+  {
+    op: "rematerializeAreaMark",
+    description: "Recompute grouped closed area paths."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, REMATERIALIZE_OPTIONS, "rematerializeAreaMark");
+    const id = validateUserId(args.id, "Area mark id");
+    const highlights = Object.entries(
+      this.materializationConfigs.highlights ?? {}
+    ).filter(([, config]) => config.target === id);
+    if (highlights.length > 0) {
+      let baseline = this;
+      for (const [highlightId] of highlights) {
+        baseline = baseline._withoutMaterializationConfig(["highlights", highlightId]);
+      }
+      return baseline
+        .editGraphics({ target: id, property: "length", value: 0 })
+        .rematerializeAreaMark({ id })
+        .rematerializeMarkHighlights({ target: id, highlights });
+    }
+    const layer = findLayer(this, id);
+    const dataset = findDataset(this, layer?.data);
+    if (layer?.mark?.type !== "area" || this.graphicSpec.objects[id]?.type !== "path") {
+      throw new Error(`Unknown area mark "${id}".`);
+    }
+    if (dataset === undefined) {
+      throw new Error(`Area mark "${id}" requires an existing dataset.`);
+    }
+    const densityTransform = findUpstreamTransform(
+      this,
+      dataset,
+      "density"
+    );
+    const xScaleId = layer.encoding?.x?.scale;
+    const yScaleId = layer.encoding?.y?.scale;
+    const verticalRange = layer.encoding?.y2?.scale === yScaleId;
+    const horizontalRange = layer.encoding?.x2?.scale === xScaleId;
+    if (
+      xScaleId === undefined ||
+      yScaleId === undefined ||
+      (densityTransform === undefined && verticalRange === horizontalRange)
+    ) {
+      throw new Error(
+        densityTransform === undefined
+          ? `Area mark "${id}" requires exactly one shared x/x2 or y/y2 range.`
+          : `Density area mark "${id}" requires x and y scales.`
+      );
+    }
+    const rawDerived = densityTransform === undefined
+      ? deriveAreaSeries(dataset.values, layer)
+      : deriveDensityAreaSeries(dataset.values, layer, densityTransform);
+    const colorEncoding = layer.encoding?.color;
+    const layout = colorEncoding?.layout ?? "overlay";
+    const derived = densityTransform === undefined
+      ? rawDerived
+      : layoutDensityAreaSeries(rawDerived, layout);
+    let resolved = this
+      .rematerializeScale({ id: xScaleId })
+      .rematerializeScale({ id: yScaleId });
+    if (colorEncoding?.scale !== undefined) {
+      resolved = resolved.rematerializeScale({ id: colorEncoding.scale });
+    }
+    const xScale = resolved.resolvedScales[xScaleId];
+    const yScale = resolved.resolvedScales[yScaleId];
+    const densityScale = densityTransform === undefined
+      ? undefined
+      : derived.mode === "y-density" ? yScale : xScale;
+    if (
+      densityScale !== undefined &&
+      (densityScale.domain[0] > 0 || densityScale.domain[1] < 0)
+    ) {
+      throw new Error(`Density area mark "${id}" requires a scale domain containing zero.`);
+    }
+    const paths = derived.series.map(series => {
+      const curve = this.markConfigs[id]?.curve ?? "linear";
+      if (densityTransform === undefined && derived.orientation === "horizontal") {
+        const y = mapContinuousScaleValues(
+          series.values.map(value => value.y),
+          yScale
+        );
+        const lower = mapContinuousScaleValues(
+          series.values.map(value => value.x),
+          xScale
+        );
+        const upper = mapContinuousScaleValues(
+          series.values.map(value => value.x2),
+          xScale
+        );
+        return buildAreaCurvePathCommands(
+          y.map((value, index) => ({ x: lower[index], y: value })),
+          y.map((value, index) => ({ x: upper[index], y: value })),
+          curve,
+          { independentAxis: "y" }
+        );
+      }
+      if (densityTransform !== undefined && derived.mode === "x-density") {
+        const y = mapContinuousScaleValues(
+          series.values.map(value => value.y),
+          yScale
+        );
+        const upper = mapContinuousScaleValues(
+          series.values.map(value => value.x),
+          xScale
+        );
+        const baseline = mapContinuousScaleValues(
+          [0],
+          densityScale
+        )[0];
+        if (curve === "linear") {
+          return buildLinearPathCommands([
+            { x: baseline, y: y[0] },
+            ...y.map((value, index) => ({ x: upper[index], y: value })),
+            { x: baseline, y: y.at(-1) }
+          ], { close: true });
+        }
+        return buildAreaCurvePathCommands(
+          y.map(value => ({ x: baseline, y: value })),
+          y.map((value, index) => ({ x: upper[index], y: value })),
+          curve,
+          { independentAxis: "y" }
+        );
+      }
+      const x = mapContinuousScaleValues(
+        series.values.map(value => value.x),
+        xScale
+      );
+      const lowerValues = densityTransform === undefined
+        ? series.values.map(value => value.y)
+        : derived.mode === "y-density"
+          ? series.values.map(value => value.lower)
+          : series.values.map(value => value.y);
+      const lower = mapContinuousScaleValues(
+        lowerValues,
+        yScale
+      );
+      const upperValues = densityTransform === undefined
+        ? series.values.map(value => value.y2)
+        : series.values.map(value => value.upper);
+      const upper = mapContinuousScaleValues(
+        upperValues,
+        yScale
+      );
+      if (densityTransform !== undefined && layout === "overlay") {
+        const baseline = mapContinuousScaleValues(
+          [0],
+          yScale
+        )[0];
+        if (curve === "linear") {
+          return buildLinearPathCommands([
+            { x: x[0], y: baseline },
+            ...x.map((value, index) => ({ x: value, y: upper[index] })),
+            { x: x.at(-1), y: baseline }
+          ], { close: true });
+        }
+        return buildAreaCurvePathCommands(
+          x.map(value => ({ x: value, y: baseline })),
+          x.map((value, index) => ({ x: value, y: upper[index] })),
+          curve
+        );
+      }
+      return buildAreaCurvePathCommands(
+        x.map((value, index) => ({ x: value, y: lower[index] })),
+        x.map((value, index) => ({ x: value, y: upper[index] })),
+        curve
+      );
+    });
+    const config = this.markConfigs[id];
+    const fills = colorEncoding?.scale === undefined
+      ? paths.map(() => config.fill)
+      : mapOrdinalValues(
+          derived.series.map(series => series.key[colorEncoding.field]),
+          resolved.resolvedScales[colorEncoding.scale].domain,
+          resolved.resolvedScales[colorEncoding.scale].range
+        );
+    const existingChildren = resolved.graphicSpec.objects[id].items ?? [];
+    const removesOutline = config.stroke === undefined && existingChildren.some(
+      child => child.properties.stroke !== undefined
+    );
+    let next = removesOutline
+      ? resolved
+          .editGraphics({ target: id, property: "length", value: 0 })
+          .editGraphics({ target: id, property: "length", value: paths.length })
+      : resolved.editGraphics({ target: id, property: "length", value: paths.length });
+    next = next
+      .editGraphics({ target: id, property: "commands", value: paths })
+      .editGraphics({ target: id, property: "fill", value: fills })
+      .editGraphics({ target: id, property: "opacity", value: config.opacity });
+    if (config.stroke !== undefined) {
+      next = next
+        .editGraphics({ target: id, property: "stroke", value: config.stroke })
+        .editGraphics({
+          target: id,
+          property: "strokeWidth",
+          value: config.strokeWidth
+        });
+    }
+    return next;
+  }
+);
+
+const editAreaMark = action(
+  {
+    op: "editAreaMark",
+    description: "Edit area curve and constant appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, EDIT_OPTIONS, "editAreaMark");
+    const changes = ["fill", "opacity", "stroke", "strokeWidth", "curve"];
+    if (!changes.some(key => Object.hasOwn(args, key))) {
+      throw new Error(
+        "editAreaMark requires fill, opacity, stroke, strokeWidth, or curve."
+      );
+    }
+    const target = Object.hasOwn(args, "target")
+      ? validateUserId(args.target, "Area mark id")
+      : undefined;
+    const layer = resolveEligibleLayer(this, {
+      target,
+      predicate: candidate => candidate.mark?.type === "area",
+      label: "area mark"
+    });
+    if (Object.hasOwn(args, "fill") && layer.encoding?.color !== undefined) {
+      throw new Error(
+        "editAreaMark fill cannot be combined with a color encoding."
+      );
+    }
+    if (args.stroke === false && Object.hasOwn(args, "strokeWidth")) {
+      throw new Error("editAreaMark cannot set strokeWidth while removing stroke.");
+    }
+
+    let config = { ...this.markConfigs[layer.id] };
+    if (Object.hasOwn(args, "fill")) {
+      config.fill = validateNonEmptyString(args.fill, "Area fill");
+    }
+    if (Object.hasOwn(args, "opacity")) {
+      config.opacity = validateUnitInterval(args.opacity, "Area opacity");
+    }
+    if (Object.hasOwn(args, "curve")) {
+      config.curve = validateCurveInterpolation(args.curve);
+    }
+    if (Object.hasOwn(args, "stroke")) {
+      if (args.stroke === false) {
+        const { stroke: removedStroke, strokeWidth: removedWidth, ...rest } = config;
+        void removedStroke;
+        void removedWidth;
+        config = rest;
+      } else {
+        const hadStroke = config.stroke !== undefined;
+        config.stroke = validateNonEmptyString(args.stroke, "Area stroke");
+        config.strokeWidth = Object.hasOwn(args, "strokeWidth")
+          ? validateNonNegativeFinite(args.strokeWidth, "Area strokeWidth")
+          : hadStroke ? config.strokeWidth : 1;
+      }
+    } else if (Object.hasOwn(args, "strokeWidth")) {
+      if (config.stroke === undefined) {
+        throw new Error("editAreaMark strokeWidth requires an active stroke.");
+      }
+      config.strokeWidth = validateNonNegativeFinite(
+        args.strokeWidth,
+        "Area strokeWidth"
+      );
+    }
+
+    const next = this._withMarkConfig(layer.id, config);
+    return canMaterializeArea(next, layer)
+      ? next.rematerializeAreaMark({ id: layer.id })
+      : next;
+  }
+);
+
+export function registerAreaMarkActions(ProgramClass) {
+  ProgramClass.prototype.createAreaMark = createAreaMark;
+  ProgramClass.prototype.editAreaMark = editAreaMark;
+  ProgramClass.prototype.rematerializeAreaMark = rematerializeAreaMark;
+}

package/src/actions/marks/bar/create.js

@@ -0,0 +1,46 @@
+import { action } from "../../../core/action.js";
+import {
+  assertMarkAvailable,
+  resolveMarkId,
+  resolveMarkData,
+  validateMarkOptions
+} from "../shared.js";
+import { resolveMarkGraphicPlacement } from
+  "../../../materialization/graphicHierarchy.js";
+
+const CREATE_OPTIONS = Object.freeze(["id", "data"]);
+
+export const createBarMark = action(
+  {
+    op: "createBarMark",
+    description: "Create a semantic bar mark and empty rect collection."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, CREATE_OPTIONS, "createBarMark");
+    const id = resolveMarkId(this, args.id, {
+      defaultId: "bar",
+      label: "Bar mark id",
+      markType: "bar",
+      operation: "createBarMark"
+    });
+    const { data } = resolveMarkData(this, args);
+
+    assertMarkAvailable(this, id);
+
+    return this
+      .editSemantic({
+        property: `layer[${id}].mark.type`,
+        value: "bar"
+      })
+      .editSemantic({
+        property: `layer[${id}].data`,
+        value: data
+      })
+      .createGraphics({
+        id,
+        type: "rect",
+        length: 0,
+        ...resolveMarkGraphicPlacement(this, { data, markType: "bar" })
+      });
+  }
+);

package/src/actions/marks/bar/edit.js

@@ -0,0 +1,90 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../../core/validation.js";
+import { canMaterializeBar } from "../../../materialization/marks.js";
+import { DEFAULT_BAR_STROKE_WIDTH } from "../../../materialization/bars/resolve.js";
+import { resolveEligibleLayer } from "../../../selectors/layers.js";
+import { validateMarkOptions } from "../shared.js";
+
+const EDIT_OPTIONS = Object.freeze([
+  "target", "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const editBarMark = action(
+  {
+    op: "editBarMark",
+    description: "Edit whole-bar fill, opacity, and outline appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, EDIT_OPTIONS, "editBarMark");
+    const changes = ["fill", "opacity", "stroke", "strokeWidth"];
+    if (!changes.some(key => Object.hasOwn(args, key))) {
+      throw new Error(
+        "editBarMark requires fill, opacity, stroke, or strokeWidth."
+      );
+    }
+    const requested = Object.hasOwn(args, "target")
+      ? validateUserId(args.target, "Bar mark id")
+      : undefined;
+    const layer = resolveEligibleLayer(this, {
+      target: requested,
+      predicate: candidate => candidate.mark?.type === "bar",
+      label: "bar mark"
+    });
+    if (Object.hasOwn(args, "fill") && layer.encoding?.color !== undefined) {
+      throw new Error(
+        "editBarMark fill cannot be combined with a color encoding."
+      );
+    }
+    if (args.stroke === false && Object.hasOwn(args, "strokeWidth")) {
+      throw new Error(
+        "editBarMark cannot set strokeWidth while removing stroke."
+      );
+    }
+
+    const config = { ...this.markConfigs[layer.id] };
+    const appearance = { ...config.barAppearance };
+    if (Object.hasOwn(args, "fill")) {
+      appearance.fill = validateNonEmptyString(args.fill, "Bar fill");
+    }
+    if (Object.hasOwn(args, "opacity")) {
+      appearance.opacity = validateUnitInterval(args.opacity, "Bar opacity");
+    }
+    if (Object.hasOwn(args, "stroke")) {
+      if (args.stroke === false) {
+        appearance.stroke = false;
+      } else {
+        const restoresStroke = appearance.stroke === false;
+        appearance.stroke = validateNonEmptyString(args.stroke, "Bar stroke");
+        if (Object.hasOwn(args, "strokeWidth")) {
+          appearance.strokeWidth = validateNonNegativeFinite(
+            args.strokeWidth,
+            "Bar strokeWidth"
+          );
+        } else if (restoresStroke) {
+          appearance.strokeWidth = DEFAULT_BAR_STROKE_WIDTH;
+        }
+      }
+    } else if (Object.hasOwn(args, "strokeWidth")) {
+      if (appearance.stroke === false) {
+        throw new Error("editBarMark strokeWidth requires an active stroke.");
+      }
+      appearance.strokeWidth = validateNonNegativeFinite(
+        args.strokeWidth,
+        "Bar strokeWidth"
+      );
+    }
+
+    const next = this._withMarkConfig(layer.id, {
+      ...config,
+      barAppearance: appearance
+    });
+    return canMaterializeBar(next, layer)
+      ? next.rematerializeBarMark({ id: layer.id })
+      : next;
+  }
+);

package/src/actions/marks/bar/index.js

@@ -0,0 +1,9 @@
+import { createBarMark } from "./create.js";
+import { editBarMark } from "./edit.js";
+import { rematerializeBarMark } from "./materialize.js";
+
+export function registerBarMarkActions(ProgramClass) {
+  ProgramClass.prototype.createBarMark = createBarMark;
+  ProgramClass.prototype.editBarMark = editBarMark;
+  ProgramClass.prototype.rematerializeBarMark = rematerializeBarMark;
+}

package/src/actions/marks/bar/materialize.js

@@ -0,0 +1,130 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateMarkOptions } from "../shared.js";
+import { deriveAggregateRectangles } from "../../../materialization/bars/aggregate.js";
+import { deriveHistogramRectangles } from "../../../materialization/bars/histogram.js";
+import { requireCompleteBar } from "../../../materialization/bars/resolve.js";
+import { deriveRangedRectangles } from "../../../materialization/bars/ranged.js";
+import { BAR_GRAINS } from "../../../grammar/bars/policy.js";
+
+const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+
+function editRectangles(program, id, rectangles) {
+  let next = program
+    .editGraphics({ target: id, property: "length", value: rectangles.length })
+    .editGraphics({
+      target: id,
+      property: "x",
+      value: rectangles.map(rect => rect.x)
+    })
+    .editGraphics({
+      target: id,
+      property: "y",
+      value: rectangles.map(rect => rect.y)
+    })
+    .editGraphics({
+      target: id,
+      property: "width",
+      value: rectangles.map(rect => rect.width)
+    })
+    .editGraphics({
+      target: id,
+      property: "height",
+      value: rectangles.map(rect => rect.height)
+    })
+    .editGraphics({
+      target: id,
+      property: "fill",
+      value: rectangles.map(rect => rect.fill)
+    })
+    .editGraphics({
+      target: id,
+      property: "stroke",
+      value: rectangles.map(rect => rect.stroke)
+    })
+    .editGraphics({
+      target: id,
+      property: "strokeWidth",
+      value: rectangles.map(rect => rect.strokeWidth)
+    });
+  if (rectangles.some(rect => rect.opacity !== undefined)) {
+    next = next.editGraphics({
+      target: id,
+      property: "opacity",
+      value: rectangles.map(rect => rect.opacity ?? 1)
+    });
+  }
+  return next;
+}
+
+export const rematerializeBarMark = action(
+  {
+    op: "rematerializeBarMark",
+    description: "Recompute concrete bar graphics from complete semantics."
+  },
+  function (args = {}) {
+    validateMarkOptions(
+      args,
+      REMATERIALIZE_OPTIONS,
+      "rematerializeBarMark"
+    );
+    const id = validateUserId(args.id, "Bar mark id");
+    const highlights = Object.entries(
+      this.materializationConfigs.highlights ?? {}
+    ).filter(([, config]) => config.target === id);
+    if (highlights.length > 0) {
+      let baseline = this;
+      for (const [highlightId] of highlights) {
+        baseline = baseline._withoutMaterializationConfig([
+          "highlights",
+          highlightId
+        ]);
+      }
+      return baseline
+        .editGraphics({ target: id, property: "length", value: 0 })
+        .rematerializeBarMark({ id })
+        .rematerializeMarkHighlights({ target: id, highlights });
+    }
+    const required = requireCompleteBar(this, id);
+    let resolved = this
+      .rematerializeScale({ id: required.xEncoding.scale })
+      .rematerializeScale({ id: required.yEncoding.scale });
+
+    const colorScaleId = required.layer.encoding?.color?.scale;
+    if (colorScaleId !== undefined) {
+      resolved = resolved.rematerializeScale({ id: colorScaleId });
+    }
+
+    if (required.materialization === "aggregate") {
+      const offsetScaleId = required.layer.encoding?.xOffset?.scale;
+      if (offsetScaleId !== undefined) {
+        resolved = resolved.rematerializeScale({ id: offsetScaleId });
+      }
+      const width = resolved.markConfigs[id]?.barWidth;
+      if (width === undefined) {
+        return resolved.editGraphics({
+          target: id,
+          property: "length",
+          value: 0
+        });
+      }
+      return editRectangles(
+        resolved,
+        id,
+        deriveAggregateRectangles(required, resolved, width)
+      );
+    }
+
+    if (required.materialization === BAR_GRAINS.ranged) {
+      const width = resolved.markConfigs[id]?.barWidth;
+      if (width === undefined) return resolved.editGraphics({ target: id, property: "length", value: 0 });
+      return editRectangles(resolved, id, deriveRangedRectangles(required, resolved, width));
+    }
+
+    return editRectangles(
+      resolved,
+      id,
+      deriveHistogramRectangles(required, resolved)
+    );
+  }
+);

package/src/actions/marks/index.js

@@ -0,0 +1,13 @@
+import { registerBarMarkActions } from "./bar/index.js";
+import { registerAreaMarkActions } from "./area.js";
+import { registerLineMarkActions } from "./line.js";
+import { registerPointMarkActions } from "./point.js";
+import { registerRuleMarkActions } from "./rule.js";
+
+export function registerMarkActions(ProgramClass) {
+  registerPointMarkActions(ProgramClass);
+  registerAreaMarkActions(ProgramClass);
+  registerLineMarkActions(ProgramClass);
+  registerBarMarkActions(ProgramClass);
+  registerRuleMarkActions(ProgramClass);
+}