ggaction 0.0.4 → 0.0.5

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

@@ -0,0 +1,85 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import {
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../../core/validation.js";
+import { validatePointShape } from "../../../grammar/pointShapes.js";
+import { findLayer } from "../../../selectors/layers.js";
+import { rematerializeExistingLegend } from "../../encodings/shared.js";
+import { validateMarkOptions } from "../shared.js";
+
+const OPTIONS = Object.freeze([
+  "target", "shape", "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const editPointMark = action(
+  {
+    op: "editPointMark",
+    description: "Edit constant point-mark appearance."
+  },
+  function (args = {}) {
+    validateMarkOptions(args, OPTIONS, "editPointMark");
+    const editable = ["shape", "fill", "opacity", "stroke", "strokeWidth"];
+    if (!editable.some(property => Object.hasOwn(args, property))) {
+      throw new Error(
+        "editPointMark requires shape, fill, opacity, stroke, or strokeWidth."
+      );
+    }
+    const candidates = this.semanticSpec.layers.filter(
+      layer => layer.mark?.type === "point"
+    );
+    const current = findLayer(this, this.context.currentMark);
+    const requested = args.target ??
+      (current?.mark?.type === "point" ? current.id : undefined);
+    const inferred = requested ?? (candidates.length === 1
+      ? candidates[0].id
+      : undefined);
+    const id = validateUserId(inferred, "Point mark id");
+    const layer = findLayer(this, id);
+    if (layer?.mark?.type !== "point") {
+      throw new Error(`Unknown point mark "${id}".`);
+    }
+    if (Object.hasOwn(args, "shape") && layer.encoding?.shape !== undefined) {
+      throw new Error(
+        "editPointMark shape cannot be combined with a shape encoding."
+      );
+    }
+    if (Object.hasOwn(args, "fill") && layer.encoding?.color !== undefined) {
+      throw new Error(
+        "editPointMark fill cannot be combined with a color encoding."
+      );
+    }
+    const config = { ...this.markConfigs[id] };
+    if (Object.hasOwn(args, "shape")) {
+      config.shape = validatePointShape(args.shape);
+    }
+    if (Object.hasOwn(args, "fill")) {
+      config.fill = validateNonEmptyString(args.fill, "Point fill");
+    }
+    if (Object.hasOwn(args, "opacity")) {
+      config.opacity = validateUnitInterval(args.opacity, "Point opacity");
+    }
+    if (Object.hasOwn(args, "stroke")) {
+      config.stroke = validateNonEmptyString(args.stroke, "Point stroke");
+      config.strokeWidth ??= 1;
+    }
+    if (Object.hasOwn(args, "strokeWidth")) {
+      if (config.stroke === undefined) {
+        throw new Error("Point strokeWidth requires an active stroke.");
+      }
+      config.strokeWidth = validateNonNegativeFinite(
+        args.strokeWidth,
+        "Point strokeWidth"
+      );
+    }
+    const next = this
+      ._withMarkConfig(id, config)
+      .rematerializePointMark({ id });
+    const legend = next.guideConfigs.legend?.series;
+    return legend?.target === id && legend.channels.includes("shape")
+      ? rematerializeExistingLegend(next)
+      : next;
+  }
+);

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

@@ -1 +1,11 @@
-export { registerPointMarkActions } from "./actions.js";
+import { createPointMark } from "./create.js";
+import { editPointMark } from "./edit.js";
+import { rematerializePointMark } from "./materialize.js";
+
+export { registerPointJitterActions } from "./jitter.js";
+
+export function registerPointMarkActions(ProgramClass) {
+  ProgramClass.prototype.createPointMark = createPointMark;
+  ProgramClass.prototype.editPointMark = editPointMark;
+  ProgramClass.prototype.rematerializePointMark = rematerializePointMark;
+}

package/src/actions/marks/point/jitter.js

@@ -0,0 +1,72 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateKeys } from "../../../core/validation.js";
+import { normalizePointJitterPolicy } from "../../../grammar/jitter.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
+import { resolveEligibleLayer } from "../../../selectors/layers.js";
+
+const JITTER_OPTIONS = Object.freeze([
+  "target", "channel", "maxOffset", "seed", "key"
+]);
+const REMOVE_OPTIONS = Object.freeze(["target"]);
+
+function isCartesianPoint(program, layer, channel) {
+  return layer.mark?.type === "point" &&
+    layer.encoding?.[channel]?.scale !== undefined &&
+    layer.encoding?.[channel === "x" ? "y" : "x"]?.scale !== undefined &&
+    findCoordinate(program, layer.coordinate)?.type === "cartesian";
+}
+
+function resolveJitterTarget(program, target, channel) {
+  const requested = target === undefined
+    ? undefined
+    : validateUserId(target, "Point jitter target");
+  return resolveEligibleLayer(program, {
+    target: requested,
+    predicate: layer => isCartesianPoint(program, layer, channel),
+    label: "point jitter"
+  });
+}
+
+export const jitterPoints = action(
+  {
+    op: "jitterPoints",
+    description: "Apply deterministic bounded graphical jitter to a point mark."
+  },
+  function (args = {}) {
+    validateKeys(args, JITTER_OPTIONS, "jitterPoints");
+    const policy = normalizePointJitterPolicy(args);
+    const layer = resolveJitterTarget(this, args.target, policy.channel);
+    return this
+      ._withMaterializationConfig(["jitters", layer.id], policy)
+      .rematerializePointMark({ id: layer.id });
+  }
+);
+
+export const removeJitter = action(
+  {
+    op: "removeJitter",
+    description: "Remove point jitter and restore semantic scale positions."
+  },
+  function (args = {}) {
+    validateKeys(args, REMOVE_OPTIONS, "removeJitter");
+    const requested = args.target === undefined
+      ? undefined
+      : validateUserId(args.target, "Point jitter target");
+    const layer = resolveEligibleLayer(this, {
+      target: requested,
+      predicate: candidate =>
+        candidate.mark?.type === "point" &&
+        this.materializationConfigs.jitters?.[candidate.id] !== undefined,
+      label: "point jitter"
+    });
+    return this
+      ._withoutMaterializationConfig(["jitters", layer.id])
+      .rematerializePointMark({ id: layer.id });
+  }
+);
+
+export function registerPointJitterActions(ProgramClass) {
+  ProgramClass.prototype.jitterPoints = jitterPoints;
+  ProgramClass.prototype.removeJitter = removeJitter;
+}

package/src/actions/marks/point/{actions.js → materialize.js}

@@ -1,103 +1,32 @@
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
-import {
-  validateNonEmptyString,
-  validateNonNegativeFinite,
-  validateUnitInterval
-} from "../../../core/validation.js";
 import { getPointGraphicType } from "../../../grammar/schemas/mark.js";
 import {
   createPointShapeGraphic,
+  resolvePointShapeExtent,
   validatePointShape
 } from "../../../grammar/pointShapes.js";
+import {
+  canonicalJitterScalar,
+  normalizePointJitterPolicy,
+  resolvePointJitter
+} from "../../../grammar/jitter.js";
 import { polarToCartesian, resolvePolarFrame } from "../../../grammar/polar.js";
 import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import { validateMarkOptions } from "../shared.js";
 import {
-  assertMarkAvailable,
-  applyLayeredMarkInheritance,
-  materializeInheritedMark,
-  resolveLayeredMarkInheritance,
-  resolveMarkId,
-  resolveMarkData,
-  validateMarkOptions
-} from "../shared.js";
-import { DEFAULT_COLORS } from "../../../theme/defaults.js";
+  DEFAULT_COLORS,
+  DEFAULT_POINT_RADIUS
+} from "../../../theme/defaults.js";
 import { findDataset } from "../../../selectors/datasets.js";
 import { findLayer } from "../../../selectors/layers.js";
-import { rematerializeExistingLegend } from "../../encodings/shared.js";
-import { resolveMarkGraphicPlacement } from
-  "../../../materialization/graphicHierarchy.js";
 import { rematerializeHighlightBaseline } from "../lifecycle.js";
 import { resolveRowEncodingValues } from
   "../../../materialization/rowEncoding.js";
 
-const POINT_MARK_OPTIONS = Object.freeze([
-  "id", "data", "shape", "fill", "opacity", "stroke", "strokeWidth"
-]);
-const EDIT_POINT_OPTIONS = Object.freeze([
-  "target", "shape", "fill", "opacity", "stroke", "strokeWidth"
-]);
 const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
 const DEFAULT_POINT_FILL = DEFAULT_COLORS.mark;
 
-const createPointMark = action(
-  {
-    op: "createPointMark",
-    description: "Create a semantic point mark and concrete point graphics."
-  },
-  function (args = {}) {
-    validateMarkOptions(args, POINT_MARK_OPTIONS, "createPointMark");
-    const id = resolveMarkId(this, args.id, {
-      defaultId: "point",
-      label: "Point mark id",
-      markType: "point",
-      operation: "createPointMark"
-    });
-    const inherited = resolveLayeredMarkInheritance(this, args, "point");
-    const { data, dataset } = resolveMarkData(this, {
-      ...args,
-      ...(args.data === undefined &&
-        this.context.currentData === undefined &&
-        inherited?.data !== undefined
-        ? { data: inherited.data }
-        : {})
-    });
-    const shape = Object.hasOwn(args, "shape") ? args.shape : "circle";
-    validatePointShape(shape);
-    const resolvedType = getPointGraphicType(shape);
-    const graphicType = resolvedType === "path" ? "circle" : resolvedType;
-
-    assertMarkAvailable(this, id);
-
-    let next = this
-      .editSemantic({
-        property: `layer[${id}].mark.type`,
-        value: "point"
-      })
-      .editSemantic({
-        property: `layer[${id}].data`,
-        value: data
-      });
-    next = applyLayeredMarkInheritance(next, id, inherited)
-      .createGraphics({
-        id,
-        type: graphicType,
-        length: dataset.values.length,
-        ...resolveMarkGraphicPlacement(next, { data, markType: "point" })
-      })
-      ._withMarkConfig(id, { shape });
-    const created = materializeInheritedMark(next, id);
-    const appearance = Object.fromEntries(
-      ["fill", "opacity", "stroke", "strokeWidth"]
-        .filter(property => Object.hasOwn(args, property))
-        .map(property => [property, args[property]])
-    );
-    return Object.keys(appearance).length === 0
-      ? created
-      : created.editPointMark({ target: id, ...appearance });
-  }
-);
-
 function resolvePointPositions(program, layer, dataset) {
   const hasPolar = layer.encoding?.theta !== undefined ||
     layer.encoding?.radius !== undefined;
@@ -154,7 +83,122 @@ function existingArea(child, parentType) {
   return undefined;
 }
 
-const rematerializePointMark = action(
+function resolvedPointArea(area, index, config, existingChildren, graphicType) {
+  return area?.[index] ?? (
+    config.radius === undefined
+      ? existingArea(existingChildren[index], graphicType) ??
+        Math.PI * DEFAULT_POINT_RADIUS ** 2
+      : Math.PI * config.radius ** 2
+  );
+}
+
+function resolveJitterEntries({
+  policy,
+  dataset,
+  x,
+  y,
+  area,
+  shapes,
+  config,
+  graphic,
+  existingChildren
+}) {
+  const seen = new Set();
+  return dataset.values.flatMap((row, index) => {
+    if (!Number.isFinite(x?.[index]) || !Number.isFinite(y?.[index])) return [];
+    const identity = policy.key === undefined ? index : row[policy.key];
+    const canonical = canonicalJitterScalar(
+      identity,
+      policy.key === undefined
+        ? "Point jitter source index"
+        : `Point jitter key field "${policy.key}"`
+    );
+    if (seen.has(canonical)) {
+      throw new Error(
+        `Point jitter key field "${policy.key}" must be unique for materialized items.`
+      );
+    }
+    seen.add(canonical);
+    const resolvedArea = resolvedPointArea(
+      area,
+      index,
+      config,
+      existingChildren,
+      graphic.type
+    );
+    const extent = resolvePointShapeExtent({
+      shape: shapes[index],
+      area: resolvedArea,
+      strokeWidth: config.stroke === undefined ? 0 : config.strokeWidth ?? 1
+    });
+    return [{
+      index,
+      identity,
+      base: policy.channel === "x" ? x[index] : y[index],
+      halfExtent: extent[policy.channel]
+    }];
+  });
+}
+
+function applyPointJitter(program, {
+  id,
+  layer,
+  dataset,
+  x,
+  y,
+  area,
+  shapes,
+  config,
+  graphic,
+  existingChildren
+}) {
+  const stored = program.materializationConfigs.jitters?.[id];
+  if (stored === undefined) return { program, x, y };
+  const policy = normalizePointJitterPolicy(stored);
+  const encoding = layer.encoding?.[policy.channel];
+  const scale = program.resolvedScales[encoding?.scale];
+  if (scale === undefined) {
+    throw new Error(
+      `Point jitter on "${id}" requires a resolved ${policy.channel} scale.`
+    );
+  }
+  const bounds = resolveGraphicBounds(program);
+  const entries = resolveJitterEntries({
+    policy,
+    dataset,
+    x,
+    y,
+    area,
+    shapes,
+    config,
+    graphic,
+    existingChildren
+  });
+  const resolution = resolvePointJitter({
+    target: id,
+    policy,
+    scale,
+    entries,
+    plotMinimum: policy.channel === "x" ? bounds.x : bounds.y,
+    plotMaximum: policy.channel === "x"
+      ? bounds.x + bounds.width
+      : bounds.y + bounds.height
+  });
+  const values = [...(policy.channel === "x" ? x : y)];
+  for (const item of resolution.items) {
+    values[item.index] += item.finalOffset;
+  }
+  return {
+    program: program._withMaterializationConfig(["jitters", id], {
+      ...policy,
+      resolved: resolution
+    }),
+    x: policy.channel === "x" ? values : x,
+    y: policy.channel === "y" ? values : y
+  };
+}
+
+export const rematerializePointMark = action(
   {
     op: "rematerializePointMark",
     description: "Recompute concrete point geometry and appearance."
@@ -183,7 +227,7 @@ const rematerializePointMark = action(
       throw new Error(`Point mark "${id}" requires an existing dataset.`);
     }
 
-    const { x, y } = resolvePointPositions(this, layer, dataset);
+    const positions = resolvePointPositions(this, layer, dataset);
     const mappedFill = resolveRowEncodingValues(this, layer, dataset, "color");
     const area = resolveRowEncodingValues(this, layer, dataset, "size");
     const encodedShape = resolveRowEncodingValues(this, layer, dataset, "shape");
@@ -197,6 +241,19 @@ const rematerializePointMark = action(
       encodedShape !== undefined ||
       graphic.type === "collection" ||
       getPointGraphicType(constantShape) !== graphic.type;
+    const jittered = applyPointJitter(this, {
+      id,
+      layer,
+      dataset,
+      x: positions.x,
+      y: positions.y,
+      area,
+      shapes,
+      config,
+      graphic,
+      existingChildren
+    });
+    const { x, y } = jittered;
 
     if (requiresMixedCollection) {
       const items = dataset.values.map((_, index) => {
@@ -205,11 +262,13 @@ const rematerializePointMark = action(
         const color = mappedFill?.[index] ?? config.fill ??
           existing.fill ?? DEFAULT_POINT_FILL;
         const opacity = encodedOpacity?.[index] ?? config.opacity ?? existing.opacity;
-        const resolvedArea = area?.[index] ??
-          (config.radius === undefined
-            ? existingArea(existingChildren[index], graphic.type)
-            :
-            Math.PI * config.radius ** 2);
+        const resolvedArea = resolvedPointArea(
+          area,
+          index,
+          config,
+          existingChildren,
+          graphic.type
+        );
         const centerX = x?.[index] ?? existing.x;
         const centerY = y?.[index] ?? existing.y;
         if (
@@ -237,12 +296,16 @@ const rematerializePointMark = action(
           opacity
         });
       });
-      return this.editGraphics({ target: id, property: "items", value: items });
+      return jittered.program.editGraphics({
+        target: id,
+        property: "items",
+        value: items
+      });
     }
 
     let next = graphic.items.length === dataset.values.length
-      ? this
-      : this.editGraphics({
+      ? jittered.program
+      : jittered.program.editGraphics({
           target: id,
           property: "length",
           value: dataset.values.length
@@ -254,14 +317,32 @@ const rematerializePointMark = action(
     }
     if (graphic.type === "circle") {
       const radii = area === undefined
-        ? config.radius
+        ? config.radius ?? (
+          x !== undefined && y !== undefined
+            ? dataset.values.map((_, index) => {
+                const existing = existingChildren[index]?.properties?.radius;
+                return Number.isFinite(existing)
+                  ? existing
+                  : DEFAULT_POINT_RADIUS;
+              })
+            : undefined
+        )
         : area.map(value => Math.sqrt(value / Math.PI));
       if (radii !== undefined) {
         next = next.editGraphics({ target: id, property: "radius", value: radii });
       }
-    } else if (area !== undefined || config.radius !== undefined) {
+    } else if (
+      area !== undefined ||
+      config.radius !== undefined ||
+      (x !== undefined && y !== undefined)
+    ) {
       const sides = area === undefined
-        ? config.radius * Math.sqrt(Math.PI)
+        ? dataset.values.map((_, index) => {
+          const existing = existingArea(existingChildren[index], graphic.type);
+          return Math.sqrt(
+            existing ?? Math.PI * (config.radius ?? DEFAULT_POINT_RADIUS) ** 2
+          );
+        })
         : area.map(value => Math.sqrt(value));
       const centersX = x ?? existingChildren.map(child => child.properties.x);
       const centersY = y ?? existingChildren.map(child => child.properties.y);
@@ -301,79 +382,3 @@ const rematerializePointMark = action(
     return next;
   }
 );
-
-const editPointMark = action(
-  {
-    op: "editPointMark",
-    description: "Edit constant point-mark appearance."
-  },
-  function (args = {}) {
-    validateMarkOptions(args, EDIT_POINT_OPTIONS, "editPointMark");
-    const editable = ["shape", "fill", "opacity", "stroke", "strokeWidth"];
-    if (!editable.some(property => Object.hasOwn(args, property))) {
-      throw new Error(
-        "editPointMark requires shape, fill, opacity, stroke, or strokeWidth."
-      );
-    }
-    const candidates = this.semanticSpec.layers.filter(
-      layer => layer.mark?.type === "point"
-    );
-    const current = findLayer(this, this.context.currentMark);
-    const requested = args.target ??
-      (current?.mark?.type === "point" ? current.id : undefined);
-    const inferred = requested ?? (candidates.length === 1
-      ? candidates[0].id
-      : undefined);
-    const id = validateUserId(inferred, "Point mark id");
-    const layer = findLayer(this, id);
-    if (layer?.mark?.type !== "point") {
-      throw new Error(`Unknown point mark "${id}".`);
-    }
-    if (Object.hasOwn(args, "shape") && layer.encoding?.shape !== undefined) {
-      throw new Error(
-        "editPointMark shape cannot be combined with a shape encoding."
-      );
-    }
-    if (Object.hasOwn(args, "fill") && layer.encoding?.color !== undefined) {
-      throw new Error(
-        "editPointMark fill cannot be combined with a color encoding."
-      );
-    }
-    const config = { ...this.markConfigs[id] };
-    if (Object.hasOwn(args, "shape")) {
-      config.shape = validatePointShape(args.shape);
-    }
-    if (Object.hasOwn(args, "fill")) {
-      config.fill = validateNonEmptyString(args.fill, "Point fill");
-    }
-    if (Object.hasOwn(args, "opacity")) {
-      config.opacity = validateUnitInterval(args.opacity, "Point opacity");
-    }
-    if (Object.hasOwn(args, "stroke")) {
-      config.stroke = validateNonEmptyString(args.stroke, "Point stroke");
-      config.strokeWidth ??= 1;
-    }
-    if (Object.hasOwn(args, "strokeWidth")) {
-      if (config.stroke === undefined) {
-        throw new Error("Point strokeWidth requires an active stroke.");
-      }
-      config.strokeWidth = validateNonNegativeFinite(
-        args.strokeWidth,
-        "Point strokeWidth"
-      );
-    }
-    const next = this
-      ._withMarkConfig(id, config)
-      .rematerializePointMark({ id });
-    const legend = next.guideConfigs.legend?.series;
-    return legend?.target === id && legend.channels.includes("shape")
-      ? rematerializeExistingLegend(next)
-      : next;
-  }
-);
-
-export function registerPointMarkActions(ProgramClass) {
-  ProgramClass.prototype.createPointMark = createPointMark;
-  ProgramClass.prototype.editPointMark = editPointMark;
-  ProgramClass.prototype.rematerializePointMark = rematerializePointMark;
-}

package/src/actions/marks/rect/actions.js

@@ -102,6 +102,9 @@ const rematerializeRectMark = action(
     if (graphic?.type !== "rect" || !Array.isArray(graphic.items)) {
       throw new Error(`Rect mark "${id}" requires rect collection graphics.`);
     }
+    if (this.markConfigs[id]?.gradientPlot?.materialized === true) {
+      return this.materializeGradientPlotFill({ id });
+    }
     const dataset = findDataset(this, layer.data);
     if (dataset === undefined) {
       throw new Error(`Rect mark "${id}" requires an existing dataset.`);

package/src/actions/marks/remove.js

@@ -27,7 +27,8 @@ function ownedChildren(program, id) {
     config.regression?.lineId,
     config.boxPlot?.whiskerId,
     config.boxPlot?.medianId,
-    config.boxPlot?.outlierId
+    config.boxPlot?.outlierId,
+    config.gradientPlot?.centerId
   ].concat(
     program.semanticSpec.layers
       .filter(layer => layer.source === id)
@@ -88,7 +89,8 @@ function ownedDerivedData(program, ids) {
       config.errorBand?.data,
       config.regression?.dataId,
       config.boxPlot?.summaryId,
-      config.boxPlot?.outlierDataId
+      config.boxPlot?.outlierDataId,
+      config.gradientPlot?.profileId
     ]) {
       if (candidate !== undefined) candidates.add(candidate);
     }
@@ -189,6 +191,13 @@ export const removeMark = action(
     const selectionCleanup = cleanupSelectionState(next, ids);
     next = selectionCleanup.program;
     for (const id of ids) {
+      const labelLayout = next.materializationConfigs.labelLayouts?.[id];
+      if (
+        labelLayout?.leaderId !== undefined &&
+        next.graphicSpec.objects[labelLayout.leaderId] !== undefined
+      ) {
+        next = next.editGraphics({ target: labelLayout.leaderId, remove: true });
+      }
       if (findLayer(next, id) !== undefined) {
         next = next.editSemantic({ property: `layer[${id}]`, remove: true });
       }
@@ -196,6 +205,8 @@ export const removeMark = action(
         next = next.editGraphics({ target: id, remove: true });
       }
       next = next._withoutMaterializationConfig(["marks", id]);
+      next = next._withoutMaterializationConfig(["jitters", id]);
+      next = next._withoutMaterializationConfig(["labelLayouts", id]);
     }
 
     next = cleanupPositionGuides(next, positionScales);