ggaction 0.0.4 → 0.0.6

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,124 @@ 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: typeof config.stroke === "string"
+        ? config.strokeWidth ?? 1
+        : 0
+    });
+    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 +229,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 +243,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 +264,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 (
@@ -230,19 +291,23 @@ const rematerializePointMark = action(
           y: centerY,
           area: resolvedArea,
           fill: color,
-          ...(config.stroke === undefined ? {} : { stroke: config.stroke }),
+          ...(typeof config.stroke === "string" ? { stroke: config.stroke } : {}),
           ...(config.strokeWidth === undefined
             ? {}
             : { strokeWidth: config.strokeWidth }),
           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 +319,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);
@@ -290,7 +373,11 @@ const rematerializePointMark = action(
     } else if (encodedOpacity !== undefined) {
       next = next.editGraphics({ target: id, property: "opacity", value: encodedOpacity });
     }
-    if (config.stroke !== undefined) {
+    if (config.stroke === false) {
+      next = next
+        .editGraphics({ target: id, property: "stroke", value: "transparent" })
+        .editGraphics({ target: id, property: "strokeWidth", value: 0 });
+    } else if (config.stroke !== undefined) {
       next = next.editGraphics({ target: id, property: "stroke", value: config.stroke });
       next = next.editGraphics({
         target: id,
@@ -301,79 +388,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);

package/src/actions/marks/rule/actions.js

@@ -104,7 +104,17 @@ const createRuleMark = action(
         length: 0,
         ...resolveMarkGraphicPlacement(created, { data, markType: "rule" })
       })
-      ._withMarkConfig(id, DEFAULT_RULE_CONFIG);
+      ._withMarkConfig(id, {
+        ...DEFAULT_RULE_CONFIG,
+        ...(inherited === undefined
+          ? {}
+          : {
+              inheritedPosition: {
+                source: inherited.source,
+                channels: Object.keys(inherited.encoding)
+              }
+            })
+      });
     return materializeInheritedMark(created, id);
   }
 );
@@ -143,7 +153,7 @@ const rematerializeRuleMark = action(
     }
 
     const scaleIds = [...new Set(
-      ["x", "y", "x2", "y2", "strokeDash", "opacity"]
+      ["x", "y", "x2", "y2", "strokeDash", "strokeWidth", "opacity"]
         .map(channel => layer.encoding?.[channel]?.scale)
         .filter(scale => scale !== undefined)
     )];
@@ -153,6 +163,11 @@ const rematerializeRuleMark = action(
     }
 
     const derived = deriveRuleValues(dataset.values, layer);
+    if (derived.values.strokeWidth?.some(value => value < 0)) {
+      throw new RangeError(
+        `Rule strokeWidth field "${layer.encoding.strokeWidth.field}" cannot contain negative values.`
+      );
+    }
     const mapped = {};
     for (const channel of ["x", "y", "x2", "y2"]) {
       const encoding = layer.encoding?.[channel];
@@ -223,9 +238,13 @@ const rematerializeRuleMark = action(
       }
     }
 
-    const resolvedConfig = resolved.markConfigs[id] ?? DEFAULT_RULE_CONFIG;
+    const resolvedConfig = {
+      ...DEFAULT_RULE_CONFIG,
+      ...resolved.markConfigs[id]
+    };
     const dashEncoding = layer.encoding?.strokeDash;
     const opacityEncoding = layer.encoding?.opacity;
+    const strokeWidthEncoding = layer.encoding?.strokeWidth;
     const strokeDash = dashEncoding?.scale === undefined
       ? Array.from(
           { length: derived.length },
@@ -244,6 +263,12 @@ const rematerializeRuleMark = action(
           derived.values.opacity,
           resolved.resolvedScales[opacityEncoding.scale]
         );
+    const strokeWidth = strokeWidthEncoding?.scale === undefined
+      ? resolvedConfig.strokeWidth
+      : mapContinuousScaleValues(
+          derived.values.strokeWidth,
+          resolved.resolvedScales[strokeWidthEncoding.scale]
+        );
 
     return resolved
       .editGraphics({ target: id, property: "length", value: derived.length })
@@ -255,7 +280,7 @@ const rematerializeRuleMark = action(
       .editGraphics({
         target: id,
         property: "strokeWidth",
-        value: resolvedConfig.strokeWidth
+        value: strokeWidth
       })
       .editGraphics({ target: id, property: "strokeDash", value: strokeDash })
       .editGraphics({ target: id, property: "opacity", value: opacity });

package/src/actions/marks/text/actions.js

@@ -24,14 +24,19 @@ const STYLE_OPTIONS = Object.freeze([
 ]);
 const CREATE_OPTIONS = Object.freeze(["id", "data", "text", ...STYLE_OPTIONS]);
 const EDIT_OPTIONS = Object.freeze(["target", ...STYLE_OPTIONS]);
-const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id", "replayLayout"]);
 const SOURCE_TYPES = new Set(["point", "bar", "rule", "rect"]);
 
+function sourceMatchesData(program, layer, requestedData) {
+  if (requestedData === undefined || layer?.data === requestedData) return true;
+  return program.markConfigs[layer.id]?.gradientPlot?.source === requestedData;
+}
+
 function eligibleSource(program, layer, requestedData) {
   if (
     !SOURCE_TYPES.has(layer?.mark?.type) ||
     layer.data === undefined ||
-    (requestedData !== undefined && layer.data !== requestedData)
+    !sourceMatchesData(program, layer, requestedData)
   ) return false;
   const encodings = resolveCompatibleEncodings(program, layer, "text");
   return encodings.x !== undefined && encodings.y !== undefined;
@@ -133,6 +138,10 @@ const rematerializeTextMark = action(
   function (args = {}) {
     validateMarkOptions(args, REMATERIALIZE_OPTIONS, "rematerializeTextMark");
     const id = validateUserId(args.id, "Text mark id");
+    const replayLayout = args.replayLayout ?? true;
+    if (typeof replayLayout !== "boolean") {
+      throw new TypeError("rematerializeTextMark replayLayout must be a boolean.");
+    }
     const layer = findLayer(this, id);
     const graphic = this.graphicSpec.objects[id];
     if (layer?.mark?.type !== "text") throw new Error(`Unknown text mark "${id}".`);
@@ -140,11 +149,14 @@ const rematerializeTextMark = action(
       throw new Error(`Text mark "${id}" requires text collection graphics.`);
     }
     if (!canMaterializeText(this, layer)) {
-      return graphic.items.length === 0
+      const next = graphic.items.length === 0
         ? this
         : this.editGraphics({ target: id, property: "length", value: 0 });
+      return replayLayout && next.materializationConfigs.labelLayouts?.[id] !== undefined
+        ? next.materializeLabelLayout({ id, rematerializeBase: false })
+        : next;
     }
-    return this.editGraphics({
+    const next = this.editGraphics({
       target: id,
       property: "items",
       value: resolveTextGraphicItems(
@@ -153,6 +165,9 @@ const rematerializeTextMark = action(
         this.markConfigs[id] ?? DEFAULT_TEXT_MARK
       )
     });
+    return replayLayout && next.materializationConfigs.labelLayouts?.[id] !== undefined
+      ? next.materializeLabelLayout({ id, rematerializeBase: false })
+      : next;
   }
 );
 

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

@@ -1 +1,7 @@
-export { registerTextMarkActions } from "./actions.js";
+import { registerTextMarkActions as registerTextCoreActions } from "./actions.js";
+import { registerTextLabelLayoutActions } from "./layout.js";
+
+export function registerTextMarkActions(ProgramClass) {
+  registerTextCoreActions(ProgramClass);
+  registerTextLabelLayoutActions(ProgramClass);
+}