ggaction 0.0.21 → 0.0.22

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

@@ -1,4 +1,5 @@
-import { validateGraphicItemLimit } from "../../../core/validation.js";
+import { materializeMarkClip } from "../../../materialization/markClip.js";
+import { validateGraphicItemLimit, validateWorkLimit } from "../../../core/validation.js";
 import { editGraphicProperties } from "../../primitives/graphicProperties.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
@@ -187,47 +188,40 @@ function applyPointJitter(program, {
   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 = resolveCoordinateBounds(program, layer.coordinate);
-  const entries = resolveJitterEntries({
-    policy,
-    dataset,
-    x,
-    y,
-    area,
-    shapes,
-    angles,
-    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;
+  const channels = policy.channel === "both" ? ["x", "y"] : [policy.channel];
+  const resolutions = {}, positions = { x, y };
+  for (const channel of channels) {
+    const scale = program.resolvedScales[layer.encoding?.[channel]?.scale];
+    if (scale === undefined) {
+      throw new Error(`Point jitter on "${id}" requires a resolved ${channel} scale.`);
+    }
+    // Resolve from the same unjittered positions, using each axis in the stable
+    // hash. Both is exactly the independent X and Y assignments together.
+    const axisPolicy = { ...policy, channel };
+    const entries = resolveJitterEntries({
+      policy: axisPolicy, dataset, x, y, area, shapes, angles,
+      config, graphic, existingChildren
+    });
+    const resolution = resolvePointJitter({
+      target: id, policy: axisPolicy, scale, entries,
+      plotMinimum: channel === "x" ? bounds.x : bounds.y,
+      plotMaximum: channel === "x" ? bounds.x + bounds.width : bounds.y + bounds.height
+    });
+    resolutions[channel] = resolution;
+    positions[channel] = [...positions[channel]];
+    for (const item of resolution.items) positions[channel][item.index] += item.finalOffset;
   }
+  const resolved = policy.channel === "both"
+    ? { algorithm: policy.algorithm, itemCount: resolutions.x.itemCount, axes: resolutions }
+    : resolutions[policy.channel];
   return {
     program: program._withMaterializationConfig(["jitters", id], {
       ...policy,
-      resolved: resolution
+      resolved
     }),
-    x: policy.channel === "x" ? values : x,
-    y: policy.channel === "y" ? values : y
+    x: positions.x,
+    y: positions.y
   };
 }
 
@@ -368,6 +362,9 @@ export const rematerializePointMark = /* @__PURE__ */ action(
     const strokeDetails = requestedStrokeDetails(config, "Point mark");
     const fill = mappedFill ?? config.fill ?? DEFAULT_POINT_FILL;
     const shapes = encodedShape ?? dataset.values.map(() => config.shape ?? "circle");
+    validateWorkLimit(shapes.reduce((sum, shape) => sum +
+      (typeof shape === "object" ? validatePointShape(shape).polygon.length + 1 : 0), 0),
+    "Point polygon materialization");
     const existingChildren = graphic.items ?? [];
     const constantShape = validatePointShape(config.shape ?? "circle");
     const requiresMixedCollection =
@@ -456,11 +453,11 @@ export const rematerializePointMark = /* @__PURE__ */ action(
           ...strokeDetails
         });
       });
-      return jittered.program.editGraphics({
+      return materializeMarkClip(jittered.program.editGraphics({
         target: id,
         property: "items",
         value: items
-      });
+      }), id);
     }
 
     let next = graphic.items.length === dataset.values.length
@@ -555,6 +552,6 @@ export const rematerializePointMark = /* @__PURE__ */ action(
     for (const [property, value] of Object.entries(strokeDetails)) {
       next = next.editGraphics({ target: id, property, value });
     }
-    return next;
+    return materializeMarkClip(next, id);
   }
 );

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

@@ -1,3 +1,5 @@
+import { materializeMarkClip } from "../../../materialization/markClip.js";
+import { requestedMarkClip, validateMarkClipCoordinate } from "../../../selectors/markClip.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import {
@@ -33,7 +35,7 @@ import { applyItemMissingPolicy, validateItemMissing } from
   "../../../grammar/itemMissing.js";
 
 const STYLE_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth", ...RECT_RADIUS_PROPERTIES,
+  "clip", "fill", "opacity", "stroke", "strokeWidth", ...RECT_RADIUS_PROPERTIES,
   ...STROKE_STYLE_PROPERTIES
 ]);
 const CREATE_OPTIONS = Object.freeze(["id", "data", "missing", ...STYLE_OPTIONS]);
@@ -55,6 +57,7 @@ const createRectMark = /* @__PURE__ */ action(
   { op: "createRectMark", description: "Create a semantic rectangular cell layer." },
   function (args = {}) {
     validateMarkOptions(args, CREATE_OPTIONS, "createRectMark");
+    requestedMarkClip(args);
     requestedRectStyleDetails(args, "createRectMark");
     const id = resolveMarkId(this, args.id, {
       defaultId: "rect",
@@ -109,6 +112,7 @@ const rematerializeRectMark = /* @__PURE__ */ action(
     const highlighted = rematerializeHighlightBaseline(this, {
       target: id,
       operation: "rematerializeRectMark",
+      scales: args.scales,
       resetProperty: "items",
       resetValue: []
     });
@@ -126,7 +130,7 @@ const rematerializeRectMark = /* @__PURE__ */ action(
       throw new Error(`Rect mark "${id}" requires rect collection graphics.`);
     }
     if (this.markConfigs[id]?.gradientPlot?.materialized === true) {
-      return this.materializeGradientPlotFill({ id });
+      return materializeMarkClip(this.materializeGradientPlotFill({ id, scales: args.scales }), id);
     }
     const sourceDataset = findDataset(this, layer.data);
     if (sourceDataset === undefined) {
@@ -146,12 +150,12 @@ const rematerializeRectMark = /* @__PURE__ */ action(
         next = next.rematerializeScale({ id: scale, marks: false });
       }
     }
-    return replaceGraphicItems(
+    return materializeMarkClip(replaceGraphicItems(
       next,
       id,
       "rect",
       resolveRectGraphicItems(next, layer, dataset)
-    );
+    ), id);
   }
 );
 
@@ -159,6 +163,7 @@ const editRectMark = /* @__PURE__ */ action(
   { op: "editRectMark", description: "Edit rectangular cell appearance." },
   function (args = {}) {
     validateMarkOptions(args, EDIT_OPTIONS, "editRectMark");
+    requestedMarkClip(args);
     requestedRectStyleDetails(args, "editRectMark");
     if (!["missing", ...STYLE_OPTIONS].some(option => Object.hasOwn(args, option))) {
       throw new Error("editRectMark requires at least one editable property.");
@@ -172,6 +177,12 @@ const editRectMark = /* @__PURE__ */ action(
         "editRectMark stroke conflicts with a field encoding; use encodeStroke with value to replace it."
       );
     }
+    validateMarkClipCoordinate(this, layer, args.clip ?? this.markConfigs[layer.id]?.clip);
+    for (const channel of ["opacity", "strokeWidth"]) {
+      if (Object.hasOwn(args, channel) && layer.encoding?.[channel] !== undefined) {
+        throw new Error(`editRectMark ${channel} conflicts with a field encoding; use ${channel === "opacity" ? "encodeOpacity" : "encodeStrokeWidth"} with value to replace it.`);
+      }
+    }
     const semantic = Object.hasOwn(args, "missing")
       ? this.editSemantic({
           property: `layer[${layer.id}].mark.missing`,
@@ -185,6 +196,7 @@ const editRectMark = /* @__PURE__ */ action(
           args,
           semantic.markConfigs[layer.id] ?? DEFAULT_RECT_MARK
         ),
+        ...requestedMarkClip(args),
         fillExplicit: Object.hasOwn(args, "fill")
           ? true
           : semantic.markConfigs[layer.id]?.fillExplicit ?? false

package/src/actions/marks/references.js

@@ -1,4 +1,5 @@
 import { isSourceOwnedText } from "../../grammar/text.js";
+import { GRADIENT_PROFILE_FIELDS } from "../../grammar/gradientProfile.js";
 import { action, closedAction } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
@@ -12,7 +13,7 @@ import {
 import { findLayer, resolveEligibleLayer } from "../../selectors/layers.js";
 import { resolveConsumerValuesForDataset } from
   "../scales/consumers/index.js";
-import { resolveMarkItems } from
+import { findSelectionPolicy, resolveMarkItems } from
   "../../materialization/selection/policies/index.js";
 import { getMarkMaterializationPolicy } from
   "../../materialization/marks/policies.js";
@@ -22,11 +23,17 @@ import { withRematerializedDerivedDataset } from
 import {
   deriveStatisticalReferenceValues,
   normalizeReferenceField,
+  normalizeReferenceGroupBy,
   normalizeReferencePopulation,
   normalizeReferenceStatistics,
   normalizeStatisticalReferenceTransform,
-  validateStatisticalReferenceTransform
+  validateStatisticalReferenceTransform,
+  partitionReferenceRows
 } from "../../grammar/statisticalReference.js";
+import { scalarKey } from "../../grammar/transformKeys.js";
+import { deriveLineSeries, resolveLineBins } from "../../grammar/lineSeries.js";
+import { isAggregate } from "../../grammar/aggregate.js";
+import { findSemanticScale } from "../../selectors/scales.js";
 import {
   resolveFacadeData,
   resolveFacadeId,
@@ -39,7 +46,7 @@ const COMMON_OPTIONS = Object.freeze([
   "id", "x", "y", "space", "source", "data", "coordinate", "temporalUnit"
 ]);
 const DYNAMIC_OPTIONS = Object.freeze([
-  "id", "source", "axis", "population", "field", "statistic", "statistics"
+  "id", "source", "axis", "population", "field", "groupBy", "statistic", "statistics"
 ]);
 const LINE_STYLE = Object.freeze([
   "stroke", "strokeWidth", "strokeDash", "opacity", ...STROKE_STYLE_PROPERTIES
@@ -211,6 +218,12 @@ function requireStatisticalSource(program, config, referenceId) {
     );
   }
   const encoding = source.encoding?.[config.axis];
+  const sourceTransform = findDataset(program, source.data)?.transform?.[0];
+  if (sourceTransform?.type === "horizon" && config.axis === "y") {
+    throw new Error(
+      `Statistical reference "${referenceId}" cannot summarize Horizon folded Y coordinates. Use a quantitative X axis.`
+    );
+  }
   if (
     encoding?.fieldType !== "quantitative" ||
     typeof encoding.scale !== "string" ||
@@ -233,14 +246,14 @@ function requireStatisticalSource(program, config, referenceId) {
   return { source, encoding };
 }
 
-function resolvePopulationDataset(program, source, population, referenceId) {
+function resolveBoundPopulation(program, source, config, referenceId) {
   let dataset = findDataset(program, source.data);
   if (dataset === undefined || !Array.isArray(dataset.values)) {
     throw new Error(
       `Statistical reference "${referenceId}" source requires materialized data.`
     );
   }
-  if (population === "visibleItems") return dataset;
+  if (config.population === "visibleItems") return { dataset };
   while (
     dataset.transform?.length === 1 &&
     dataset.transform[0].type === "markFilter" &&
@@ -254,7 +267,58 @@ function resolvePopulationDataset(program, source, population, referenceId) {
     }
     dataset = parent;
   }
-  return dataset;
+  const transform = dataset.transform?.length === 1 ? dataset.transform[0] : undefined;
+  const axisField = source.encoding[config.axis].field;
+  let field;
+  if (transform?.type === "density" && axisField === transform.as[0]) {
+    field = transform.field;
+  } else if (transform?.type === "ecdf" && axisField === transform.as.value) {
+    field = transform.field;
+  } else if (transform?.type === "boxSummary" && transform.method !== "precomputed" &&
+      Object.values(transform.as).includes(axisField)) {
+    field = transform.field;
+  } else if (transform?.type === "gradientProfile" &&
+      [GRADIENT_PROFILE_FIELDS.lower, GRADIENT_PROFILE_FIELDS.upper,
+        GRADIENT_PROFILE_FIELDS.center].includes(axisField)) {
+    field = transform.field;
+  } else if (transform?.type === "summary") {
+    const endpointOwner = Object.entries(program.markConfigs).some(([id, config]) =>
+      config.endpointPlot && (id === source.id ||
+        Object.values(config.endpointPlot.roles).includes(source.id)));
+    if (endpointOwner) field = transform.aggregates.find(aggregate => aggregate.as === axisField)?.field;
+  } else if (transform?.type === "horizon" && axisField === transform.as.x) {
+    field = transform.x.field;
+  }
+  if (field !== undefined) {
+    const observationField = field;
+    const parent = findDataset(program, dataset.source);
+    if (parent === undefined || !Array.isArray(parent.values)) {
+      throw new Error(`Statistical reference "${referenceId}" bound data is unavailable.`);
+    }
+    if (config.field.kind === "explicit") {
+      // Explicit output fields remain available; original observation fields
+      // resolve against the statistical owner's input rather than sampled rows.
+      if (!parent.values.every(row => Object.hasOwn(row, config.field.field))) return { dataset };
+      field = config.field.field;
+    }
+    const groupFields = transform.category === undefined
+      ? [...(Array.isArray(transform.groupBy) ? transform.groupBy
+        : transform.groupBy === undefined ? [] : [transform.groupBy]),
+        ...(transform.placement?.split?.field === undefined ? [] : [transform.placement.split.field])]
+      : [transform.category];
+    const groupKey = row => JSON.stringify(groupFields.map(key => row?.[key]));
+    const observedGroups = new Set(dataset.values.map(row =>
+      transform.type === "horizon" && groupFields.length
+        ? JSON.stringify([row[transform.as.group]]) : groupKey(row)));
+    return {
+      dataset: { ...parent, values: parent.values.filter(row =>
+        Number.isFinite(row?.[transform.field ?? observationField]) &&
+        (transform.type !== "horizon" || Number.isFinite(row?.[transform.y.field])) &&
+        observedGroups.has(groupKey(row))) },
+      field
+    };
+  }
+  return { dataset };
 }
 
 function strictFieldValues(rows, field, label) {
@@ -341,6 +405,29 @@ function resolvePopulationValues(
           `Statistical reference "${referenceId}" boundData`
         );
   }
+  const gradient = program.markConfigs[source.id]?.gradientPlot;
+  if (config.population === "boundData") {
+    const { field } = resolveBoundPopulation(program, source, config, referenceId);
+    if (field !== undefined) return strictFieldValues(dataset.values, field,
+      `Statistical reference "${referenceId}" boundData`);
+    if (source.mark.type === "line" && isAggregate(source.encoding?.y?.aggregate)) {
+      const x = source.encoding.x;
+      const bins = x.bin === undefined ? undefined : resolveLineBins(
+        dataset.values, source, findSemanticScale(program, x.scale)
+      );
+      const derived = deriveLineSeries(dataset.values, source, {
+        ...(bins === undefined ? {} : { xBinBoundaries: bins.boundaries }),
+        allowSingleton: true
+      });
+      return config.axis === "x" ? derived.xValues : derived.yValues;
+    }
+  }
+  if (gradient?.materialized &&
+      config.axis === (gradient.orientation === "vertical" ? "y" : "x")) {
+    return strictFieldValues(dataset.values, config.population === "boundData"
+      ? gradient.measure : GRADIENT_PROFILE_FIELDS.center,
+    `Statistical reference "${referenceId}" ${config.population}`);
+  }
   return resolveConsumerValuesForDataset(program, {
     layer: source,
     channel: config.axis,
@@ -348,7 +435,7 @@ function resolvePopulationValues(
   }, dataset);
 }
 
-function statisticalRows(program, referenceId, dataset) {
+function statisticalRows(program, referenceId) {
   const config = program.markConfigs[referenceId]?.statisticalReference;
   const { source, encoding } = requireStatisticalSource(
     program,
@@ -369,27 +456,43 @@ function statisticalRows(program, referenceId, dataset) {
     config.population,
     `Statistical reference "${referenceId}" population`
   );
-  const values = resolvePopulationValues(
-    program,
-    source,
-    encoding,
-    { ...config, population, statistics },
-    dataset,
-    referenceId
-  );
-  const resolved = deriveStatisticalReferenceValues(
-    values,
-    statistics,
-    `Statistical reference "${referenceId}"`
-  );
-  if (resolved.length === 2 && resolved[0] > resolved[1]) {
+  const { dataset } = resolveBoundPopulation(program, source, { ...config, population }, referenceId);
+  const groupBy = normalizeReferenceGroupBy(config.groupBy);
+  if (population === "visibleItems" && findSelectionPolicy(source.mark?.type) === undefined) {
     throw new Error(
-      `Statistical reference band "${referenceId}" lower statistic exceeds its upper statistic.`
+      `Statistical reference "${referenceId}" visibleItems population is unavailable for ${source.mark?.type} marks. Use boundData.`
     );
   }
-  return resolved.length === 1
-    ? [{ value: resolved[0] }]
-    : [{ lower: resolved[0], upper: resolved[1] }];
+  let visibleGroups;
+  if (groupBy !== undefined && population === "visibleItems") {
+    if (SERIES_MARKS.has(source.mark?.type) || source.encoding?.parallel !== undefined) {
+      throw new Error(`Statistical reference "${referenceId}" visibleItems population is ambiguous for series marks.`);
+    }
+    visibleGroups = new Map();
+    for (const item of resolveMarkItems(program, source.id)) {
+      if (!Object.hasOwn(item.fields, groupBy)) {
+        throw new Error(`Statistical reference "${referenceId}" groupBy field "${groupBy}" is not scalar at a visible item. Use boundData.`);
+      }
+      const key = scalarKey(item.fields[groupBy], "Statistical reference groupBy");
+      if (!visibleGroups.has(key)) visibleGroups.set(key, []);
+      visibleGroups.get(key).push(item.fields);
+    }
+  }
+  const groups = partitionReferenceRows(dataset.values, groupBy)
+    .filter(group => !visibleGroups || visibleGroups.has(group.key));
+  if (!groups.length) throw new Error(`Statistical reference "${referenceId}" population must contain at least one value.`);
+  return groups.map(group => {
+    const values = visibleGroups && config.field.kind === "explicit"
+      ? strictFieldValues(visibleGroups.get(group.key), config.field.field, `Statistical reference "${referenceId}" visibleItems`)
+      : resolvePopulationValues(program, source, encoding,
+          { ...config, population, statistics }, { ...dataset, values: group.rows }, referenceId);
+    const resolved = deriveStatisticalReferenceValues(values, statistics, `Statistical reference "${referenceId}"`);
+    if (resolved.length === 2 && resolved[0] > resolved[1]) {
+      throw new Error(`Statistical reference band "${referenceId}" lower statistic exceeds its upper statistic.`);
+    }
+    return { ...(groupBy === undefined ? {} : { group: group.group }),
+      ...(resolved.length === 1 ? { value: resolved[0] } : { lower: resolved[0], upper: resolved[1] }) };
+  });
 }
 
 function replaceStatisticalDataset(program, id, source, transform, values) {
@@ -471,12 +574,12 @@ export const materializeStatisticalReferenceData = /* @__PURE__ */ closedAction(
     description: "Materialize one owned statistical reference value dataset."
   }, MATERIALIZE_OPTIONS,
   function (args = {}) {
-    const { id, source, transform } = requireDerivedDataset(
+    const { id, transform } = requireDerivedDataset(
       this,
       args.id,
       "statisticalReference"
     );
-    const values = statisticalRows(this, transform.target, source);
+    const values = statisticalRows(this, transform.target);
     return this.editSemantic({
       property: `dataset[${id}].values`,
       value: values
@@ -494,8 +597,8 @@ export const rematerializeStatisticalReference = /* @__PURE__ */ closedAction(
     const config = this.markConfigs[id]?.statisticalReference;
     const { source } = requireStatisticalSource(this, config, id);
     const population = normalizeReferencePopulation(config.population);
-    const dataset = resolvePopulationDataset(this, source, population, id);
-    const values = statisticalRows(this, id, dataset);
+    const { dataset } = resolveBoundPopulation(this, source, { ...config, population }, id);
+    const values = statisticalRows(this, id);
     const transform = normalizeStatisticalReferenceTransform({ target: id });
     let next = replaceStatisticalDataset(
       this,
@@ -511,15 +614,23 @@ export const rematerializeStatisticalReference = /* @__PURE__ */ closedAction(
       });
     }
     next = syncReferenceEncoding(next, id, source, config);
+    const appearanceScales = new Set(["stroke", "strokeWidth", "strokeDash", "opacity", "color"]
+      .map(channel => findLayer(next, id).encoding?.[channel]?.scale).filter(Boolean));
+    for (const scale of appearanceScales) {
+      next = next.rematerializeScale({ id: scale, marks: false, guides: false });
+    }
+    // References do not contribute to their source's positional scale domain.
+    // Re-entering that scale's mark plan here would rematerialize the source
+    // and its dependent reference recursively (notably gradient strips).
     next = config.statistics.length === 1
-      ? next.rematerializeRuleMark({ id })
-      : next.rematerializeRectMark({ id });
+      ? next.rematerializeRuleMark({ id, scales: false })
+      : next.rematerializeRectMark({ id, scales: false });
     return next._withContext(this.context);
   }
 );
 
 function isDynamicReference(args) {
-  return ["axis", "population", "field", "statistic", "statistics"]
+  return ["axis", "population", "field", "groupBy", "statistic", "statistics"]
     .some(key => Object.hasOwn(args, key));
 }
 
@@ -558,18 +669,19 @@ function normalizeDynamicReference(program, args, band) {
     axis: args.axis,
     population: normalizeReferencePopulation(args.population, `${operation} population`),
     field: normalizeReferenceField(args.field, `${operation} field`),
+    ...(args.groupBy === undefined ? {} : { groupBy: normalizeReferenceGroupBy(args.groupBy) }),
     statistics,
     dataId: `${id}-statistical-reference-data`
   };
   const preview = program._withMarkConfig(id, { statisticalReference: config });
   const { source } = requireStatisticalSource(preview, config, id);
-  const dataset = resolvePopulationDataset(
+  const { dataset } = resolveBoundPopulation(
     program,
     source,
-    config.population,
+    config,
     id
   );
-  statisticalRows(preview, id, dataset);
+  statisticalRows(preview, id);
   if (hasDataset(program, config.dataId) || hasDatasetOwner(program, config.dataId)) {
     throw new Error(`Dataset "${config.dataId}" already exists.`);
   }
@@ -654,3 +766,39 @@ export const createReferenceBand = /* @__PURE__ */ action(
     return createReference(this, args, true);
   }
 );
+
+
+export const createStatisticalReference = /* @__PURE__ */ action(
+  {
+    op: "createStatisticalReference",
+    description: "Create a statistical reference line or central interval through one public action."
+  },
+  function (args = {}) {
+    const band = Object.hasOwn(args, "statistics");
+    validateFacadeOptions(args, ["id", "source", "axis", "population", "field", "groupBy",
+      ...(band ? ["statistics", ...BAND_STYLE] : ["statistic", ...LINE_STYLE])], "createStatisticalReference");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "statisticalReference", operation: "createStatisticalReference"
+    });
+    // The existing owners retain statistical population, scale exclusion,
+    // source replay, persistence and removal semantics, with wrapped trace steps.
+    if (band) {
+      return this.createReferenceBand({ fill: "#6b7280", opacity: 0.18, ...args, id });
+    }
+    const next = this.createReferenceLine({ statistic: { op: "mean" }, stroke: "#222222",
+      strokeWidth: 2.5, strokeDash: "solid", ...args, id });
+    const color = findLayer(this, args.source)?.encoding?.color;
+    // Reuse the source scale: a fresh palette would assign different colors
+    // after filtering, domain sorting, or a custom range.
+    if (args.stroke === undefined && args.groupBy !== undefined &&
+        color?.field === args.groupBy && color.scale !== undefined &&
+        color.aggregate === undefined) {
+      return next.encodeStroke({
+        target: id, field: "group", fieldType: color.fieldType,
+        ...(color.temporalUnit === undefined ? {} : { temporalUnit: color.temporalUnit }),
+        scale: { id: color.scale }
+      });
+    }
+    return next;
+  }
+);

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

@@ -1,3 +1,4 @@
+import { requestedMarkClip, validateMarkClipCoordinate } from "../../../selectors/markClip.js";
 import { action } from "../../../core/action.js";
 import { validateUserId } from "../../../core/identifiers.js";
 import { validatePositiveFinite } from "../../../core/validation.js";
@@ -5,7 +6,6 @@ import {
   mapContinuousScaleValues,
   mapOrdinalOffsetValues,
   mapOrdinalPositionValues,
-  mapOrdinalValues,
   normalizeStrokeDashPattern
 } from "../../../grammar/scales/index.js";
 import { deriveRuleValues, resolveRuleMode } from "../../../grammar/rules.js";
@@ -43,12 +43,12 @@ import { applyItemMissingPolicy, validateItemMissing } from
   "../../../grammar/itemMissing.js";
 
 const APPEARANCE_OPTIONS = Object.freeze([
-  "stroke", "strokeWidth", "strokeDash", "opacity",
+  "clip", "stroke", "strokeWidth", "strokeDash", "opacity",
   ...STROKE_STYLE_PROPERTIES
 ]);
 const CREATE_OPTIONS = Object.freeze(["id", "data", "missing", ...APPEARANCE_OPTIONS]);
 const EDIT_OPTIONS = Object.freeze(["target", "missing", ...APPEARANCE_OPTIONS]);
-const REMATERIALIZE_OPTIONS = Object.freeze(["id"]);
+const REMATERIALIZE_OPTIONS = Object.freeze(["id", "scales"]);
 const SPAN_OPTIONS = Object.freeze(["id", "orientation", "size"]);
 const DEFAULT_RULE_CONFIG = Object.freeze({
   stroke: DEFAULT_COLORS.mark,
@@ -102,6 +102,7 @@ const createRuleMark = /* @__PURE__ */ action(
   },
   function (args = {}) {
     validateMarkOptions(args, CREATE_OPTIONS, "createRuleMark");
+    requestedMarkClip(args);
     const strokeDetails = requestedStrokeDetails(args, "createRuleMark");
     const id = resolveMarkId(this, args.id, {
       defaultId: "rule",
@@ -137,6 +138,7 @@ const createRuleMark = /* @__PURE__ */ action(
       })
       ._withMarkConfig(id, {
         ...DEFAULT_RULE_CONFIG,
+        ...requestedMarkClip(args),
         ...strokeDetails,
         ...(inherited === undefined
           ? {}
@@ -155,6 +157,7 @@ const editRuleMark = /* @__PURE__ */ action(
   { op: "editRuleMark", description: "Edit constant rule appearance through its encoding owners." },
   function (args = {}) {
     validateMarkOptions(args, EDIT_OPTIONS, "editRuleMark");
+    requestedMarkClip(args);
     const strokeDetails = requestedStrokeDetails(args, "editRuleMark");
     if (args.target !== undefined) validateUserId(args.target, "Rule mark id");
     const layer = resolveEligibleLayer(this, {
@@ -162,9 +165,10 @@ const editRuleMark = /* @__PURE__ */ action(
       predicate: candidate => candidate.mark?.type === "rule",
       label: "rule mark"
     });
+    validateMarkClipCoordinate(this, layer, args.clip ?? this.markConfigs[layer.id]?.clip);
     const appearance = planRuleAppearance(args, layer);
     if (appearance.length === 0 && Object.keys(strokeDetails).length === 0 &&
-        !Object.hasOwn(args, "missing")) {
+        !Object.hasOwn(args, "missing") && !Object.hasOwn(args, "clip")) {
       throw new Error("editRuleMark requires missing or an appearance change.");
     }
     const semantic = Object.hasOwn(args, "missing")
@@ -175,6 +179,7 @@ const editRuleMark = /* @__PURE__ */ action(
       : this;
     const configured = semantic._withMarkConfig(layer.id, {
       ...semantic.markConfigs[layer.id],
+      ...requestedMarkClip(args),
       ...strokeDetails
     });
     const materialized = appearance.length === 0
@@ -191,10 +196,14 @@ const rematerializeRuleMark = /* @__PURE__ */ action(
   },
   function (args = {}) {
     validateMarkOptions(args, REMATERIALIZE_OPTIONS, "rematerializeRuleMark");
+    if (args.scales !== undefined && typeof args.scales !== "boolean") {
+      throw new TypeError("rematerializeRuleMark scales must be a boolean.");
+    }
     const id = validateUserId(args.id, "Rule mark id");
     const highlighted = rematerializeHighlightBaseline(this, {
       target: id,
       operation: "rematerializeRuleMark",
+      scales: args.scales,
       resetProperty: "length",
       resetValue: 0
     });
@@ -226,8 +235,10 @@ const rematerializeRuleMark = /* @__PURE__ */ action(
         .filter(scale => scale !== undefined)
     )];
     let resolved = this;
-    for (const scaleId of scaleIds) {
-      resolved = resolved.rematerializeScale({ id: scaleId });
+    if (args.scales !== false) {
+      for (const scaleId of scaleIds) {
+        resolved = resolved.rematerializeScale({ id: scaleId });
+      }
     }
 
     const derived = deriveRuleValues(dataset.values, layer);
@@ -356,10 +367,10 @@ const rematerializeRuleMark = /* @__PURE__ */ action(
             dashEncoding?.datum ?? resolvedConfig.strokeDash
           )
         )
-      : mapOrdinalValues(
+      : mapScaleConsumerValues(
           derived.values.strokeDash,
-          resolved.resolvedScales[dashEncoding.scale].domain,
-          resolved.resolvedScales[dashEncoding.scale].range
+          resolved.resolvedScales[dashEncoding.scale],
+          "strokeDash"
         );
     const opacity = opacityEncoding?.scale === undefined
       ? resolvedConfig.opacity

package/src/actions/marks/shared.js

@@ -1,3 +1,4 @@
+import { materializeMarkClip } from "../../materialization/markClip.js";
 import { isSourceOwnedText } from "../../grammar/text.js";
 import {
   resolveOptionalUserId,
@@ -243,5 +244,5 @@ export function editMarkGraphic(program, target, properties) {
   for (const [property, value] of Object.entries(properties)) {
     program = program.editGraphics({ target, property, value });
   }
-  return program;
+  return materializeMarkClip(program, target);
 }