ggaction 0.0.12 → 0.0.15

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

@@ -11,9 +11,16 @@ import {
   normalizePointJitterPolicy,
   resolvePointJitter
 } from "../../../grammar/jitter.js";
-import { polarToCartesian, resolvePolarFrame } from "../../../grammar/polar.js";
+import {
+  normalizePointPackingPolicy,
+  resolvePointPacking
+} from "../../../grammar/pointPacking.js";
+import { polarToCartesian } from "../../../grammar/polar.js";
 import { resolveDirectionValues } from "../../../grammar/direction.js";
-import { resolveGraphicBounds } from "../../../layout/canvas.js";
+import {
+  resolveCoordinateBounds,
+  resolveCoordinatePolarFrame
+} from "../../../materialization/coordinateBounds.js";
 import { validateMarkOptions } from "../shared.js";
 import {
   DEFAULT_COLORS,
@@ -21,12 +28,17 @@ import {
 } from "../../../theme/defaults.js";
 import { findDataset } from "../../../selectors/datasets.js";
 import { findLayer } from "../../../selectors/layers.js";
+import { canMaterializePoint } from "../../../materialization/marks/capabilities.js";
 import { rematerializeHighlightBaseline } from "../lifecycle.js";
 import {
   resolveRowEncodingValues,
   resolveRowPositionValues
 } from
   "../../../materialization/rowEncoding.js";
+import { offsetCategoryPositions } from
+  "../../../materialization/categorySlotOffset.js";
+import { requestedStrokeDetails } from
+  "../../../grammar/strokeStyle.js";
 
 const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
 const DEFAULT_POINT_FILL = DEFAULT_COLORS.mark;
@@ -45,7 +57,7 @@ function resolvePointPositions(program, layer, dataset) {
   if (theta === undefined || radius === undefined) {
     return { x: undefined, y: undefined };
   }
-  const frame = resolvePolarFrame(resolveGraphicBounds(program));
+  const frame = resolveCoordinatePolarFrame(program, layer.coordinate);
   const positions = theta.map((angle, index) => {
     const distance = radius[index];
     return Number.isFinite(angle) && Number.isFinite(distance)
@@ -69,7 +81,11 @@ function incompleteShapeGraphic(shape, properties, angle) {
     ? "path"
     : getPointGraphicType(shape);
   const incomplete = type === "path"
-    ? { fill: properties.fill, opacity: properties.opacity }
+    ? {
+        fill: properties.fill,
+        opacity: properties.opacity,
+        ...requestedStrokeDetails(properties, "Point mark")
+      }
     : properties;
   return { type, properties: compactProperties(incomplete) };
 }
@@ -173,7 +189,7 @@ function applyPointJitter(program, {
       `Point jitter on "${id}" requires a resolved ${policy.channel} scale.`
     );
   }
-  const bounds = resolveGraphicBounds(program);
+  const bounds = resolveCoordinateBounds(program, layer.coordinate);
   const entries = resolveJitterEntries({
     policy,
     dataset,
@@ -210,6 +226,80 @@ function applyPointJitter(program, {
   };
 }
 
+function applyPointPacking(program, {
+  id,
+  layer,
+  dataset,
+  x,
+  y,
+  area,
+  shapes,
+  angles,
+  config,
+  graphic,
+  existingChildren
+}) {
+  const stored = program.materializationConfigs.pointPacking?.[id];
+  if (stored === undefined) return { program, x, y };
+  const policy = normalizePointPackingPolicy(stored);
+  const encoding = layer.encoding?.[policy.channel];
+  const scale = program.resolvedScales[encoding?.scale];
+  if (scale === undefined) {
+    throw new Error(`Point packing on "${id}" requires a resolved ${policy.channel} scale.`);
+  }
+  const seen = new Set();
+  const entries = dataset.values.flatMap((row, index) => {
+    if (!Number.isFinite(x?.[index]) || !Number.isFinite(y?.[index])) return [];
+    const rawIdentity = policy.key === undefined ? index : row[policy.key];
+    const identity = canonicalJitterScalar(
+      rawIdentity,
+      policy.key === undefined
+        ? "Point packing source index"
+        : `Point packing key field "${policy.key}"`
+    );
+    if (seen.has(identity)) {
+      throw new Error(`Point packing key field "${policy.key}" must be unique for materialized items.`);
+    }
+    seen.add(identity);
+    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,
+      angle: angles?.[index]
+    });
+    return [{
+      index,
+      identity,
+      base: policy.channel === "x" ? x[index] : y[index],
+      fixed: policy.channel === "x" ? y[index] : x[index],
+      halfExtent: extent[policy.channel],
+      fixedHalfExtent: extent[policy.channel === "x" ? "y" : "x"]
+    }];
+  });
+  const bounds = resolveCoordinateBounds(program, layer.coordinate);
+  const resolution = resolvePointPacking({
+    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.final;
+  return {
+    program: program._withMaterializationConfig(["pointPacking", id], {
+      ...policy,
+      resolved: resolution
+    }),
+    x: policy.channel === "x" ? values : x,
+    y: policy.channel === "y" ? values : y
+  };
+}
+
 export const rematerializePointMark = action(
   {
     op: "rematerializePointMark",
@@ -251,8 +341,13 @@ export const rematerializePointMark = action(
       throw new Error(`Point mark "${id}" requires an existing dataset.`);
     }
 
+    if (graphic.items.length === 0 && !canMaterializePoint(resolved, layer)) {
+      return resolved;
+    }
+
     const positions = resolvePointPositions(resolved, layer, dataset);
     const mappedFill = resolveRowEncodingValues(resolved, layer, dataset, "color");
+    const mappedStroke = resolveRowEncodingValues(resolved, layer, dataset, "stroke");
     const area = resolveRowEncodingValues(resolved, layer, dataset, "size");
     const encodedShape = resolveRowEncodingValues(resolved, layer, dataset, "shape");
     const encodedOpacity = resolveRowEncodingValues(
@@ -263,6 +358,7 @@ export const rematerializePointMark = action(
     );
     const angles = resolveDirectionValues(dataset.values, layer.encoding?.angle);
     const config = resolved.markConfigs[id] ?? {};
+    const strokeDetails = requestedStrokeDetails(config, "Point mark");
     const fill = mappedFill ?? config.fill ?? DEFAULT_POINT_FILL;
     const shapes = encodedShape ?? dataset.values.map(() => config.shape ?? "circle");
     const existingChildren = graphic.items ?? [];
@@ -272,7 +368,13 @@ export const rematerializePointMark = action(
       angles !== undefined ||
       graphic.type === "collection" ||
       getPointGraphicType(constantShape) !== graphic.type;
-    const jittered = applyPointJitter(resolved, {
+    if (
+      resolved.materializationConfigs.jitters?.[id] !== undefined &&
+      resolved.materializationConfigs.pointPacking?.[id] !== undefined
+    ) {
+      throw new Error(`Point mark "${id}" cannot combine jitter and packing.`);
+    }
+    const packed = applyPointPacking(resolved, {
       id,
       layer,
       dataset,
@@ -285,7 +387,20 @@ export const rematerializePointMark = action(
       graphic,
       existingChildren
     });
-    const { x, y } = jittered;
+    const jittered = applyPointJitter(packed.program, {
+      id,
+      layer,
+      dataset,
+      x: packed.x,
+      y: packed.y,
+      area,
+      shapes,
+      angles,
+      config,
+      graphic,
+      existingChildren
+    });
+    const { x, y } = offsetCategoryPositions(jittered.program, layer, jittered);
 
     if (requiresMixedCollection) {
       const items = dataset.values.map((_, index) => {
@@ -313,7 +428,8 @@ export const rematerializePointMark = action(
             x: centerX,
             y: centerY,
             fill: color,
-            opacity
+            opacity,
+            ...strokeDetails
           }, angle);
         }
         return createPointShapeGraphic({
@@ -322,12 +438,15 @@ export const rematerializePointMark = action(
           y: centerY,
           area: resolvedArea,
           fill: color,
-          ...(typeof config.stroke === "string" ? { stroke: config.stroke } : {}),
-          ...(config.strokeWidth === undefined
-            ? {}
-            : { strokeWidth: config.strokeWidth }),
+          ...(typeof (mappedStroke?.[index] ?? config.stroke) === "string"
+            ? { stroke: mappedStroke?.[index] ?? config.stroke }
+            : {}),
+          ...((mappedStroke !== undefined || config.strokeWidth !== undefined)
+            ? { strokeWidth: config.strokeWidth ?? 1 }
+            : {}),
           opacity,
-          angle
+          angle,
+          ...strokeDetails
         });
       });
       return jittered.program.editGraphics({
@@ -399,15 +518,31 @@ export const rematerializePointMark = action(
       next = next
         .editGraphics({ target: id, property: "width", value: sides })
         .editGraphics({ target: id, property: "height", value: sides })
-        .editGraphics({ target: id, property: "stroke", value: fill ?? DEFAULT_POINT_FILL })
-        .editGraphics({ target: id, property: "strokeWidth", value: 0 });
+        .editGraphics({
+          target: id,
+          property: "stroke",
+          value: mappedStroke ?? fill ?? DEFAULT_POINT_FILL
+        })
+        .editGraphics({
+          target: id,
+          property: "strokeWidth",
+          value: mappedStroke === undefined ? 0 : config.strokeWidth ?? 1
+        });
     }
     if (config.opacity !== undefined) {
       next = next.editGraphics({ target: id, property: "opacity", value: config.opacity });
     } else if (encodedOpacity !== undefined) {
       next = next.editGraphics({ target: id, property: "opacity", value: encodedOpacity });
     }
-    if (config.stroke === false) {
+    if (mappedStroke !== undefined) {
+      next = next
+        .editGraphics({ target: id, property: "stroke", value: mappedStroke })
+        .editGraphics({
+          target: id,
+          property: "strokeWidth",
+          value: config.strokeWidth ?? 1
+        });
+    } else if (config.stroke === false) {
       next = next
         .editGraphics({ target: id, property: "stroke", value: "transparent" })
         .editGraphics({ target: id, property: "strokeWidth", value: 0 });
@@ -419,6 +554,9 @@ export const rematerializePointMark = action(
         value: config.strokeWidth
       });
     }
+    for (const [property, value] of Object.entries(strokeDetails)) {
+      next = next.editGraphics({ target: id, property, value });
+    }
     return next;
   }
 );

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

@@ -0,0 +1,68 @@
+import { action } from "../../../core/action.js";
+import { validateUserId } from "../../../core/identifiers.js";
+import { validateKeys } from "../../../core/validation.js";
+import { normalizePointPackingPolicy } from "../../../grammar/pointPacking.js";
+import { findCoordinate } from "../../../selectors/coordinates.js";
+import { resolveEligibleLayer } from "../../../selectors/layers.js";
+
+const OPTIONS = Object.freeze([
+  "target", "channel", "maxOffset", "padding", "key", "overflow"
+]);
+const REMOVE_OPTIONS = Object.freeze(["target"]);
+
+function isPackablePoint(program, layer, channel) {
+  const packed = layer.encoding?.[channel];
+  const fixed = layer.encoding?.[channel === "x" ? "y" : "x"];
+  return layer.mark?.type === "point" &&
+    ["nominal", "ordinal"].includes(packed?.fieldType) &&
+    ["quantitative", "temporal"].includes(fixed?.fieldType) &&
+    packed.scale !== undefined && fixed.scale !== undefined &&
+    findCoordinate(program, layer.coordinate)?.type === "cartesian";
+}
+
+function target(program, requested, channel) {
+  return resolveEligibleLayer(program, {
+    target: requested === undefined ? undefined : validateUserId(requested, "Point packing target"),
+    predicate: layer => isPackablePoint(program, layer, channel),
+    label: "point packing"
+  });
+}
+
+export const packPoints = action(
+  { op: "packPoints", description: "Pack point glyphs deterministically within categorical slots." },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "packPoints");
+    const policy = normalizePointPackingPolicy(args);
+    const layer = target(this, args.target, policy.channel);
+    if (this.materializationConfigs.jitters?.[layer.id] !== undefined) {
+      throw new Error(`Point packing on "${layer.id}" conflicts with point jitter.`);
+    }
+    return this
+      ._withMaterializationConfig(["pointPacking", layer.id], policy)
+      .rematerializePointMark({ id: layer.id });
+  }
+);
+
+export const removePointPacking = action(
+  { op: "removePointPacking", description: "Remove point packing and restore semantic positions." },
+  function (args = {}) {
+    validateKeys(args, REMOVE_OPTIONS, "removePointPacking");
+    const requested = args.target === undefined
+      ? undefined
+      : validateUserId(args.target, "Point packing target");
+    const layer = resolveEligibleLayer(this, {
+      target: requested,
+      predicate: candidate => candidate.mark?.type === "point" &&
+        this.materializationConfigs.pointPacking?.[candidate.id] !== undefined,
+      label: "point packing"
+    });
+    return this
+      ._withoutMaterializationConfig(["pointPacking", layer.id])
+      .rematerializePointMark({ id: layer.id });
+  }
+);
+
+export function registerPointPackingActions(ProgramClass) {
+  ProgramClass.prototype.packPoints = packPoints;
+  ProgramClass.prototype.removePointPacking = removePointPacking;
+}

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

@@ -19,12 +19,20 @@ import {
   resolveMarkId,
   validateMarkOptions
 } from "../shared.js";
+import { replaceGraphicItems } from "../../primitives/editGraphics.js";
 import { resolveMarkGraphicPlacement } from
   "../../../materialization/graphicHierarchy.js";
+import { rematerializeExistingLegend } from "../../encodings/shared.js";
 import { rematerializeHighlightBaseline } from "../lifecycle.js";
+import {
+  requestedRectStyleDetails
+} from "../../../grammar/roundedRect.js";
+import { STROKE_STYLE_PROPERTIES } from
+  "../../../grammar/strokeStyle.js";
 
 const STYLE_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth"
+  "fill", "opacity", "stroke", "strokeWidth", "cornerRadius",
+  ...STROKE_STYLE_PROPERTIES
 ]);
 const CREATE_OPTIONS = Object.freeze(["id", "data", ...STYLE_OPTIONS]);
 const EDIT_OPTIONS = Object.freeze(["target", ...STYLE_OPTIONS]);
@@ -45,6 +53,7 @@ const createRectMark = action(
   { op: "createRectMark", description: "Create a semantic rectangular cell layer." },
   function (args = {}) {
     validateMarkOptions(args, CREATE_OPTIONS, "createRectMark");
+    requestedRectStyleDetails(args, "createRectMark");
     const id = resolveMarkId(this, args.id, {
       defaultId: "rect",
       label: "Rect mark id",
@@ -99,7 +108,13 @@ const rematerializeRectMark = action(
     const layer = findLayer(this, id);
     const graphic = this.graphicSpec.objects[id];
     if (layer?.mark?.type !== "rect") throw new Error(`Unknown rect mark "${id}".`);
-    if (graphic?.type !== "rect" || !Array.isArray(graphic.items)) {
+    const roundedCollection = graphic?.type === "collection" &&
+      Object.hasOwn(this.markConfigs[id] ?? {}, "cornerRadius") &&
+      graphic.items?.every(item => ["rect", "path"].includes(item.type));
+    if (
+      (graphic?.type !== "rect" && !roundedCollection) ||
+      !Array.isArray(graphic.items)
+    ) {
       throw new Error(`Rect mark "${id}" requires rect collection graphics.`);
     }
     if (this.markConfigs[id]?.gradientPlot?.materialized === true) {
@@ -110,13 +125,11 @@ const rematerializeRectMark = action(
       throw new Error(`Rect mark "${id}" requires an existing dataset.`);
     }
     if (!canMaterializeRect(this, layer)) {
-      return graphic.items.length === 0
-        ? this
-        : this.editGraphics({ target: id, property: "items", value: [] });
+      return replaceGraphicItems(this, id, "rect", []);
     }
     let next = this;
     if (args.scales !== false) {
-      const ids = new Set(["x", "y", "x2", "y2", "color"].flatMap(channel => {
+      const ids = new Set(["x", "y", "x2", "y2", "color", "stroke"].flatMap(channel => {
         const scale = layer.encoding?.[channel]?.scale;
         return scale === undefined ? [] : [scale];
       }));
@@ -124,11 +137,12 @@ const rematerializeRectMark = action(
         next = next.rematerializeScale({ id: scale, marks: false });
       }
     }
-    return next.editGraphics({
-      target: id,
-      property: "items",
-      value: resolveRectGraphicItems(next, layer, dataset)
-    });
+    return replaceGraphicItems(
+      next,
+      id,
+      "rect",
+      resolveRectGraphicItems(next, layer, dataset)
+    );
   }
 );
 
@@ -136,6 +150,7 @@ const editRectMark = action(
   { op: "editRectMark", description: "Edit rectangular cell appearance." },
   function (args = {}) {
     validateMarkOptions(args, EDIT_OPTIONS, "editRectMark");
+    requestedRectStyleDetails(args, "editRectMark");
     if (!STYLE_OPTIONS.some(option => Object.hasOwn(args, option))) {
       throw new Error("editRectMark requires at least one editable property.");
     }
@@ -143,6 +158,11 @@ const editRectMark = action(
     if (Object.hasOwn(args, "fill") && layer.encoding?.color !== undefined) {
       throw new Error("editRectMark fill cannot be combined with a color encoding.");
     }
+    if (Object.hasOwn(args, "stroke") && layer.encoding?.stroke !== undefined) {
+      throw new Error(
+        "editRectMark stroke conflicts with a field encoding; use encodeStroke with value to replace it."
+      );
+    }
     const next = this._withMarkConfig(
       layer.id,
       {
@@ -155,9 +175,10 @@ const editRectMark = action(
           : this.markConfigs[layer.id]?.fillExplicit ?? false
       }
     );
-    return canMaterializeRect(next, layer)
+    const materialized = canMaterializeRect(next, layer)
       ? next.rematerializeRectMark({ id: layer.id })
       : next;
+    return rematerializeExistingLegend(materialized);
   }
 );