ggaction 0.0.12 → 0.0.13

package/src/actions/encodings/ranged.js

@@ -1,34 +1,27 @@
+import { readAreaEndpoint, validateAreaEndpointPair, normalizeAreaBound } from "../../grammar/areaEndpoints.js";
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { isPlainObject } from "../../core/immutable.js";
-import {
-  readNominalField,
-  readQuantitativeField,
-  readScaleField,
-  readTemporalField,
-  validateSemanticFieldType
-} from "../../grammar/scales/index.js";
-import { normalizeRuleDatum } from "../../grammar/rules.js";
-import {
-  canMaterializeArea,
-  canMaterializeLine,
-  getPositionEncodingMaterializationSteps
-} from "../../materialization/marks/index.js";
+import { readNominalField, readQuantitativeField, readScaleField, readTemporalField, resolveTemporalUnit, validateSemanticFieldType } from "../../grammar/scales/index.js";
+import { normalizePositionDatum } from "../../grammar/positionDatum.js";
+import { normalizeGroupFields } from "../../grammar/pathSeries.js";
+import { assertPathGroupCompatible, validatePathGroupAppearance } from "../../materialization/marks/grouping.js";
+import { canMaterializeArea, canMaterializeLine, getPositionEncodingMaterializationSteps } from "../../materialization/marks/index.js";
 import { findLayer } from "../../selectors/layers.js";
-import {
-  resolveTarget,
-  setEncodingProperties,
-  validateLineSeriesCompatibility,
-  validateOptions
-} from "./shared.js";
+import { resolveTarget, setEncodingProperties, validateOptions } from "./shared.js";
+import { applyTemporalUnit } from "./temporal.js";
+import { deriveAreaSeries } from "../../grammar/areaSeries.js";
+import { resolvePositionEncoding } from "./position/resolve.js";
+import { resolveScalePreview } from "../scales/preview.js";
+import { findUpstreamTransform } from "../../materialization/dataProvenance.js";
 
 const SECONDARY_OPTIONS = Object.freeze([
-  "field", "datum", "target", "fieldType", "scale", "coordinate"
+  "field", "datum", "target", "fieldType", "scale", "coordinate", "temporalUnit"
 ]);
 const RANGE_OPTIONS = Object.freeze([
-  "lower", "upper", "target", "fieldType", "coordinate", "scale"
+  "lower", "upper", "target", "fieldType", "coordinate", "scale", "temporalUnit"
 ]);
-const GROUP_OPTIONS = Object.freeze(["field", "target", "fieldType"]);
+const GROUP_OPTIONS = Object.freeze(["field", "fields", "target", "fieldType"]);
 
 function validateSecondaryScale(args, primaryScale, axisLabel) {
   if (args.scale === undefined) return;
@@ -41,11 +34,11 @@ function validateSecondaryScale(args, primaryScale, axisLabel) {
   }
 }
 
-function validateSecondaryField(dataset, field, fieldType) {
+function validateSecondaryField(dataset, field, fieldType, temporalUnit) {
   if (["nominal", "ordinal"].includes(fieldType)) {
     readNominalField(dataset.values, field);
   } else if (fieldType === "temporal") {
-    readTemporalField(dataset.values, field);
+    readTemporalField(dataset.values, field, temporalUnit);
   } else {
     readQuantitativeField(dataset.values, field);
   }
@@ -75,12 +68,14 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
   validateSecondaryScale(args, primary.scale, primaryChannel);
 
   const rule = layer.mark.type === "rule";
+  const area = layer.mark.type === "area";
+  const rect = layer.mark.type === "rect";
   const hasField = Object.hasOwn(args, "field");
   const hasDatum = Object.hasOwn(args, "datum");
-  if (rule && hasField === hasDatum) {
-    throw new Error(`${operation} requires exactly one of field or datum for a rule mark.`);
+  if ((rule || area || rect) && hasField === hasDatum) {
+    throw new Error(`${operation} requires exactly one of field or datum for a ${layer.mark.type} mark.`);
   }
-  if (!rule && (!hasField || hasDatum)) {
+  if (!rule && !area && !rect && (!hasField || hasDatum)) {
     throw new Error(`${operation} requires a field for a ranged mark.`);
   }
   if (rule && args.fieldType === undefined) {
@@ -114,14 +109,20 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
       `${operation} fieldType must match the primary ${primaryChannel} fieldType.`
     );
   }
-  if (hasField && layer.mark.type === "rect") {
-    readScaleField(dataset.values, args.field, fieldType, { allowUnknown: true });
-  } else if (hasField) validateSecondaryField(dataset, args.field, fieldType);
-  else normalizeRuleDatum(args.datum, fieldType, channel);
-
   const previous = layer.encoding?.[channel];
+  const temporalUnit = resolveTemporalUnit(args, fieldType, previous);
+  if (area) {
+    const endpoint = { ...(hasField ? { field: args.field } : { datum: args.datum }), fieldType };
+    validateAreaEndpointPair(primary, endpoint);
+    readAreaEndpoint(dataset.values, endpoint, layer.mark.missing);
+  } else if (hasField && layer.mark.type === "rect") {
+    readScaleField(dataset.values, args.field, fieldType, { allowUnknown: true, temporalUnit });
+  } else if (hasField) validateSecondaryField(dataset, args.field, fieldType, temporalUnit);
+  else normalizePositionDatum(args.datum, fieldType, channel, temporalUnit, rule ? "Rule" : "Rect");
+
   let next = program;
   if (layer.mark.type === "bar") {
+    if (layer.layout?.mode !== undefined && layer.layout.mode !== "overlay") throw new Error("Ranged bars support only overlay layout; clear series layout before assigning endpoints.");
     for (const property of ["aggregate", "stack", "bin"]) {
       if (layer.encoding?.[primaryChannel]?.[property] !== undefined) {
         next = next.editSemantic({
@@ -146,6 +147,7 @@ function encodeSecondaryPosition(program, channel, args, operation, types) {
     scale: primary.scale
   });
 
+  next = applyTemporalUnit(next, target, channel, temporalUnit, previous);
   const updated = findLayer(next, target);
   for (const step of getPositionEncodingMaterializationSteps(
     next,
@@ -189,91 +191,91 @@ const encodeY2 = action(
   }
 );
 
-const encodeYRange = action(
-  {
-    op: "encodeYRange",
-    description: "Atomically encode lower and upper area bounds."
-  },
-  function (args = {}) {
-    validateOptions(args, RANGE_OPTIONS, "encodeYRange");
-    const target = args.target;
-    const lower = this.encodeY({
-      field: args.lower,
-      ...(target === undefined ? {} : { target }),
-      fieldType: args.fieldType ?? "quantitative",
-      ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
-      ...(args.scale === undefined ? {} : { scale: args.scale })
-    });
-    return lower.encodeY2({
-      field: args.upper,
-      ...(target === undefined ? {} : { target }),
+function rangeAction(channel) {
+  const primary = channel === "x" ? "encodeX" : "encodeY";
+  const secondary = channel === "x" ? "encodeX2" : "encodeY2";
+  const op = channel === "x" ? "encodeXRange" : "encodeYRange";
+  return action({ op, description: "Atomically encode lower and upper bounds." }, function (args = {}) {
+    validateOptions(args, RANGE_OPTIONS, op);
+    const common = {
+      ...(args.target === undefined ? {} : { target: args.target }),
+      ...(Object.hasOwn(args, "temporalUnit") ? { temporalUnit: args.temporalUnit } : {}),
       fieldType: args.fieldType ?? "quantitative"
-    });
-  }
-);
-
-const encodeXRange = action(
-  {
-    op: "encodeXRange",
-    description: "Atomically encode lower and upper horizontal area bounds."
-  },
-  function (args = {}) {
-    validateOptions(args, RANGE_OPTIONS, "encodeXRange");
-    const target = args.target;
-    const lower = this.encodeX({
-      field: args.lower,
-      ...(target === undefined ? {} : { target }),
-      fieldType: args.fieldType ?? "quantitative",
+    };
+    const { layer, dataset } = resolveTarget(this, args.target, ["area", "bar", "rect", "rule"], "ranged mark");
+    let next = this;
+    let lower = { field: args.lower }, upper = { field: args.upper };
+    if (layer.mark.type === "area") {
+      common.target = layer.id;
+      const prepared = prepareAreaRange(this, layer, dataset, channel, args, common);
+      lower = prepared.lower; upper = prepared.upper;
+      const secondaryChannel = `${channel}2`;
+      if (layer.encoding?.[secondaryChannel] !== undefined) next = next.editSemantic({ property: `layer[${layer.id}].encoding.${secondaryChannel}`, remove: true });
+      next = setEncodingProperties(next, layer.id, secondaryChannel, prepared.secondary);
+      common.target = layer.id;
+    }
+    return next[primary]({
+      ...common, ...lower,
       ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
       ...(args.scale === undefined ? {} : { scale: args.scale })
-    });
-    return lower.encodeX2({
-      field: args.upper,
-      ...(target === undefined ? {} : { target }),
-      fieldType: args.fieldType ?? "quantitative"
-    });
-  }
-);
+    })[secondary]({ ...common, ...upper });
+  });
+}
+
+const encodeYRange = rangeAction("y");
+const encodeXRange = rangeAction("x");
 
 const encodeGroup = action(
   {
     op: "encodeGroup",
-    description: "Split path geometry by a nominal field without a scale."
+    description: "Split path geometry by nominal identity fields without a scale."
   },
   function (args = {}) {
     validateOptions(args, GROUP_OPTIONS, "encodeGroup");
     const { id: target, dataset, layer } = resolveTarget(
       this,
       args.target,
-      ["line", "area"],
-      "path mark"
+      ["line", "area", "bar"],
+      "series mark"
     );
     if ((args.fieldType ?? "nominal") !== "nominal") {
       throw new Error("encodeGroup requires a nominal field.");
     }
-    const densityTransform = dataset.transform?.length === 1 &&
-      dataset.transform[0].type === "density"
-      ? dataset.transform[0]
-      : undefined;
-    if (densityTransform !== undefined && densityTransform.groupBy !== args.field) {
-      throw new Error(
-        densityTransform.groupBy === undefined
-          ? `Ungrouped density area mark "${target}" cannot encode group.`
-          : `Density area mark "${target}" must group by "${densityTransform.groupBy}".`
-      );
+    const hasFields = Object.hasOwn(args, "fields");
+    if (hasFields === Object.hasOwn(args, "field")) {
+      throw new Error("encodeGroup requires exactly one of field or fields.");
     }
-    readNominalField(dataset.values, args.field);
-    validateLineSeriesCompatibility(layer, "group", args.field);
-    const next = this
-      .editSemantic({
-        property: `layer[${target}].encoding.group.field`,
-        value: args.field
-      })
-      .editSemantic({
-        property: `layer[${target}].encoding.group.fieldType`,
-        value: "nominal"
+    if (hasFields ? !Array.isArray(args.fields) : typeof args.field !== "string") {
+      throw new TypeError("encodeGroup field must be a string and fields must be an array.");
+    }
+    const fields = normalizeGroupFields(hasFields ? args.fields : args.field);
+    const group = {
+      ...(fields.length === 1 ? { field: fields[0] } : { fields }),
+      fieldType: "nominal"
+    };
+    assertPathGroupCompatible(this, layer, dataset, group);
+    for (const field of fields) readNominalField(dataset.values, field);
+    if (layer.mark.type !== "bar") validatePathGroupAppearance(this, {
+      ...layer, encoding: { ...layer.encoding, group }
+    }, dataset);
+    let next = this;
+    const alternate = fields.length === 1 ? "fields" : "field";
+    if (layer.encoding?.group?.[alternate] !== undefined) {
+      next = next.editSemantic({
+        property: `layer[${target}].encoding.group.${alternate}`, remove: true
       });
+    }
+    if (layer.encoding?.group?.inferredFrom !== undefined) next = next.editSemantic({ property: `layer[${target}].encoding.group.inferredFrom`, remove: true });
+    next = setEncodingProperties(next, target, "group", group);
+    if (layer.mark.type === "bar") {
+      const mode = layer.layout?.mode;
+      if (mode !== undefined) return next.layoutSeries({ target, mode });
+      if (layer.encoding?.x?.scale === undefined || layer.encoding?.y?.scale === undefined) return next;
+      for (const step of getPositionEncodingMaterializationSteps(next, findLayer(next, target), layer.encoding?.y?.scale)) next = next[step.op](step.args);
+      return next;
+    }
     if (layer.mark.type === "area") {
+      if (layer.layout?.mode !== undefined) return next.layoutSeries({ target, mode: layer.layout.mode });
       const updated = findLayer(next, target);
       return canMaterializeArea(next, updated)
         ? next.rematerializeAreaMark({ id: target })
@@ -297,3 +299,27 @@ export function registerRangedEncodingActions(ProgramClass) {
   ProgramClass.prototype.encodeXRange = encodeXRange;
   ProgramClass.prototype.encodeYRange = encodeYRange;
 }
+
+export function prepareAreaRange(program, layer, dataset, channel, args, common) {
+  const lower = normalizeAreaBound(args.lower), upper = normalizeAreaBound(args.upper);
+  validateAreaEndpointPair(lower, upper);
+  if (common.fieldType !== "quantitative") throw new Error("Area range requires quantitative endpoints.");
+  readAreaEndpoint(dataset.values, { ...upper, fieldType: "quantitative" }, layer.mark.missing);
+  const resolved = resolvePositionEncoding(program, channel, { ...common, ...lower,
+    ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
+    ...(args.scale === undefined ? {} : { scale: args.scale }) }, `encode${channel.toUpperCase()}Range`);
+  const secondary = { ...upper, fieldType: "quantitative", scale: resolved.scale.id };
+  const primary = { ...lower, fieldType: "quantitative", scale: resolved.scale.id };
+  const updated = { ...layer, coordinate: resolved.coordinate.id,
+    encoding: { ...layer.encoding, [channel]: primary, [`${channel}2`]: secondary } };
+  const scales = program.semanticSpec.scales.filter(scale => scale.id !== resolved.scale.id);
+  const preview = { ...program, markConfigs: program.markConfigs, canvasConfig: program.canvasConfig,
+    semanticSpec: { ...program.semanticSpec,
+      layers: program.semanticSpec.layers.map(item => item.id === layer.id ? updated : item),
+      scales: [...scales, resolved.scale] } };
+  resolveScalePreview(preview, resolved.scale.id);
+  if (canMaterializeArea(preview, updated) && !findUpstreamTransform(program, dataset, "density")) {
+    deriveAreaSeries(dataset.values, updated);
+  }
+  return { lower, upper, secondary };
+}

package/src/actions/encodings/remove.js

@@ -15,8 +15,16 @@ import {
   getSourceDependentMarkSteps
 } from "../../materialization/marks/index.js";
 import { findLayer } from "../../selectors/layers.js";
-import { removeLegendKinds } from "../guides/legends/remove.js";
+import {
+  removeLegendKinds,
+  resolveCategoricalLegendRevision,
+  createCategoricalLegendFromConfig
+} from "../guides/legends/lifecycle.js";
 import { clearMarkGraphic } from "./shared.js";
+import { applyDetachedScaleRematerialization } from "../../materialization/dependencies.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { assertPathGroupCompatible, validatePathGroupAppearance } from "../../materialization/marks/grouping.js";
+import { assertEncodingSelectionCompatibility } from "../../materialization/selection/compatibility.js";
 
 const OPTIONS = Object.freeze(["target", "channel"]);
 const REMOVABLE_CHANNELS = Object.freeze([
@@ -36,10 +44,6 @@ const SPECIALIZED_LEGEND_KIND = Object.freeze({
   opacity: Object.freeze(["opacity"]),
   strokeWidth: Object.freeze(["strokeWidth"])
 });
-const LEGEND_OPTION_KEYS = Object.freeze([
-  "position", "align", "direction", "columns", "offset", "titlePosition",
-  "title", "symbol", "labels", "titleStyle", "itemGap", "border"
-]);
 
 function resolveTarget(program, requested, channel) {
   const candidates = program.semanticSpec.layers.filter(
@@ -77,7 +81,7 @@ function activeCascade(layer, channel) {
     channels.add("y2");
     channels.add("yOffset");
   }
-  if (channel === "color" && layer.mark?.type === "bar") {
+  if (channel === "color" && layer.mark?.type === "bar" && layer.layout === undefined) {
     if (resolveBarColorLayout(layer) === "group") {
       channels.add(resolveBarOffsetChannel(layer));
     }
@@ -85,6 +89,7 @@ function activeCascade(layer, channel) {
   if (
     channel === "group" &&
     layer.mark?.type === "area" &&
+    layer.layout === undefined &&
     layer.encoding?.color?.field !== undefined &&
     layer.encoding.color.field === layer.encoding.group?.field
   ) {
@@ -93,21 +98,6 @@ function activeCascade(layer, channel) {
   return [...channels].filter(active => layer.encoding?.[active] !== undefined);
 }
 
-function assertSelectionCompatibility(program, target, channels) {
-  for (const [id, selection] of Object.entries(
-    program.materializationConfigs.selections ?? {}
-  )) {
-    if (
-      selection.target === target &&
-      channels.includes(selection.selector?.channel)
-    ) {
-      throw new Error(
-        `Cannot remove ${selection.selector.channel} encoding while selection "${id}" references that channel.`
-      );
-    }
-  }
-}
-
 function removeChannelConfigs(program, target, channels) {
   let next = program;
   for (const channel of channels) {
@@ -182,16 +172,9 @@ function reconcileCategoricalLegend(program, target, channels) {
   if (remaining.length === 0) {
     return removeLegendKinds(program, [kind]);
   }
+  const revision = resolveCategoricalLegendRevision(program, kind, config, remaining);
   const next = removeLegendKinds(program, [kind]);
-  const options = { target, channels: remaining };
-  for (const property of LEGEND_OPTION_KEYS) {
-    if (
-      (property === "columns" && config[property] === undefined) ||
-      (property === "title" && config.inferredTitle)
-    ) continue;
-    options[property] = config[property];
-  }
-  return next.createLegend(options);
+  return createCategoricalLegendFromConfig(next, revision.config, revision.order);
 }
 
 function cleanupLegends(program, target, channels) {
@@ -228,8 +211,30 @@ export const removeEncoding = action(
       );
     }
     const layer = resolveTarget(this, args.target, args.channel);
+    if (args.channel === "group" && layer.layout?.mode !== undefined && layer.layout.mode !== "overlay") throw new Error("Remove active series layout before removing its group.");
+    if (args.channel === "theta" && layer.mark.type === "arc" &&
+      ["count", "sum"].includes(layer.encoding?.radius?.aggregate)) {
+      throw new Error("Remove measured radius before removing its category theta encoding.");
+    }
     const channels = activeCascade(layer, args.channel);
-    assertSelectionCompatibility(this, layer.id, channels);
+    assertEncodingSelectionCompatibility(this, layer.id, channels);
+    for (const kind of ["series", "color"]) {
+      const config = this.guideConfigs.legend?.[kind];
+      const order = this.semanticSpec.guides.legend?.[kind]?.order;
+      if (config?.target === layer.id && channels.includes(order?.channel) &&
+        config.channels.some(channel => !channels.includes(channel))) {
+        throw new Error('Reset linked legend order to "scale" before removing its position encoding.');
+      }
+    }
+    if (["line", "area"].includes(layer.mark?.type)) {
+      const dataset = findDataset(this, layer.data);
+      if (args.channel === "group") {
+        assertPathGroupCompatible(this, layer, dataset, undefined);
+      }
+      const encoding = { ...layer.encoding };
+      for (const channel of channels) delete encoding[channel];
+      validatePathGroupAppearance(this, { ...layer, encoding }, dataset);
+    }
     const removedPositions = channels
       .filter(channel => POSITION_ENCODING_CHANNELS.includes(channel))
       .map(channel => ({
@@ -249,7 +254,7 @@ export const removeEncoding = action(
     next = restoreBarBaseline(next, layer, channels);
     next = cleanupLegends(next, layer.id, channels);
     next = cleanupPositionGuides(next, removedPositions);
-    return rematerializeTarget(next, layer.id);
+    return applyDetachedScaleRematerialization(rematerializeTarget(next, layer.id), [layer]);
   }
 );
 

package/src/actions/encodings/ruleAppearance.js

@@ -7,6 +7,7 @@ import { readQuantitativeField } from "../../grammar/scales/index.js";
 import { resolveStrokeWidthScaleDefinition } from "../scales/definitions.js";
 import {
   applyEncodingScale,
+  applyDetachedScaleRematerialization,
   rematerializeEncoding,
   resolveReassignmentScaleOptions,
   resolveTarget,
@@ -14,6 +15,8 @@ import {
   validateOptions
 } from "./shared.js";
 import { findLayer } from "../../selectors/layers.js";
+import { validatePathSeriesAppearance } from "../../grammar/pathSeries.js";
+import { assertEncodingSelectionCompatibility } from "../../materialization/selection/compatibility.js";
 
 const STROKE_OPTIONS = Object.freeze(["target", "value"]);
 const WIDTH_OPTIONS = Object.freeze([
@@ -40,7 +43,7 @@ const encodeStroke = action(
 const encodeStrokeWidth = action(
   {
     op: "encodeStrokeWidth",
-    description: "Set a constant graphical stroke width on a rule mark."
+    description: "Assign constant or field-driven line or rule stroke width."
   },
   function (args = {}) {
     validateOptions(args, WIDTH_OPTIONS, "encodeStrokeWidth");
@@ -50,9 +53,14 @@ const encodeStrokeWidth = action(
       throw new Error("encodeStrokeWidth requires exactly one of value or field.");
     }
     if (hasValue) {
-      const { id } = resolveTarget(this, args.target, ["rule"], "rule mark");
+      if (args.fieldType !== undefined || args.scale !== undefined) {
+        throw new Error("Constant stroke width does not accept fieldType or scale.");
+      }
+      validateRuleStrokeWidth(args.value);
+      const { id, layer } = resolveTarget(this, args.target, ["rule", "line"], "rule or line mark");
+      assertEncodingSelectionCompatibility(this, id, ["strokeWidth"]);
       let next = this.guideConfigs.legend?.strokeWidth?.target === id
-        ? this.removeLegend({ target: id })
+        ? this.removeLegend({ target: id, channels: ["strokeWidth"] })
         : this;
       if (findLayer(next, id)?.encoding?.strokeWidth !== undefined) {
         next = next.editSemantic({
@@ -60,12 +68,15 @@ const encodeStrokeWidth = action(
           remove: true
         });
       }
-      return next
-        ._withMarkConfig(id, {
+      next = next._withMarkConfig(id, {
           ...next.markConfigs[id],
-          strokeWidth: validateRuleStrokeWidth(args.value)
-        })
-        .rematerializeRuleMark({ id });
+          strokeWidth: args.value
+        });
+      if (layer.mark.type === "line") {
+        return rematerializeEncoding(next, id, "strokeWidth", undefined, layer);
+      }
+      next = next.rematerializeRuleMark({ id });
+      return applyDetachedScaleRematerialization(next, [layer]);
     }
     const { id, dataset, layer } = resolveTarget(
       this,
@@ -83,6 +94,9 @@ const encodeStrokeWidth = action(
         `encodeStrokeWidth field "${args.field}" cannot contain negative values.`
       );
     }
+    validatePathSeriesAppearance(dataset.values, {
+      ...layer, encoding: { ...layer.encoding, strokeWidth: { field: args.field, fieldType } }
+    });
     const previous = layer.encoding?.strokeWidth;
     const requestedScale = resolveReassignmentScaleOptions(
       previous,
@@ -100,7 +114,7 @@ const encodeStrokeWidth = action(
     next = applyEncodingScale(next, scale, requestedScale, {
       reassignment: previous?.scale === scale.id
     });
-    return rematerializeEncoding(next, id, "strokeWidth", scale.id);
+    return rematerializeEncoding(next, id, "strokeWidth", scale.id, layer);
   }
 );
 

package/src/actions/encodings/seriesLayout.js

@@ -0,0 +1,104 @@
+import { action } from "../../core/action.js";
+import { validateColorLayout } from "../../grammar/seriesLayout.js";
+import { deriveAreaSeries, deriveDensityAreaSeries, layoutDensityAreaSeries } from "../../grammar/areaSeries.js";
+import { readSeriesIdentity } from "../../grammar/pathSeries.js";
+import { BAR_GRAINS, resolveBarChannels, resolveBarGrain } from "../../grammar/bars/policy.js";
+import { deriveBarAggregates } from "../../grammar/bars/aggregate.js";
+import { findSemanticScale, hasSemanticScaleReferences } from "../../selectors/scales.js";
+import { findUpstreamTransform } from "../../materialization/dataProvenance.js";
+import { resolveOffsetScaleDefinition } from "../scales/definitions.js";
+import { resolveScalePreview } from "../scales/preview.js";
+import { getPositionEncodingMaterializationSteps } from "../../materialization/marks/index.js";
+import { resolveTarget, setEncodingProperties, validateOptions } from "./shared.js";
+
+export function stackLayoutMode(stack) {
+  return stack === "normalize" ? "fill" : stack === "center" ? "center" : stack === null ? "overlay" : "stack";
+}
+
+export const layoutSeries = action({ op: "layoutSeries", description: "Assign series placement independently of color." }, function (args = {}) {
+  validateOptions(args, ["target", "mode"], "layoutSeries");
+  const mode = validateColorLayout(args.mode);
+  const { id: target, layer, dataset } = resolveTarget(this, args.target, ["bar", "area"], "series mark");
+  const encoding = Object.fromEntries(Object.entries(layer.encoding ?? {}).map(([key, value]) => [key, { ...value }]));
+  const group = encoding.group;
+  const color = encoding.color;
+  if (group === undefined && color?.field !== undefined && ["nominal", "ordinal"].includes(color.fieldType)) {
+    encoding.group = { field: color.field, fieldType: "nominal", inferredFrom: "color" };
+  }
+  for (const channel of ["x", "y"]) if (encoding[channel]) delete encoding[channel].stack;
+  if (color) delete color.layout;
+  const updated = { ...layer, layout: { mode }, encoding };
+  const density = findUpstreamTransform(this, dataset, "density");
+  const horizon = findUpstreamTransform(this, dataset, "horizon");
+  let endpoint, offset, offsetScale, offsetChannel;
+  if (layer.mark.type === "area") {
+    if (horizon !== undefined) throw new Error("Horizon owns its layout; layoutSeries is not supported.");
+    if (mode === "group") throw new Error("Area does not support group layout.");
+    if (density !== undefined) layoutDensityAreaSeries(deriveDensityAreaSeries(dataset.values, updated, density), mode);
+    else {
+      if (mode !== "overlay" && encoding.x2 === undefined && encoding.y2 === undefined && encoding.y?.fieldType === "quantitative") {
+        endpoint = { channel: "y2", datum: 0, fieldType: "quantitative", scale: encoding.y.scale };
+        encoding.y2 = { datum: 0, fieldType: "quantitative", scale: encoding.y.scale };
+      }
+      if (encoding.x?.scale === undefined || encoding.y?.scale === undefined) throw new Error("Area layout requires complete positions.");
+      deriveAreaSeries(dataset.values, updated);
+    }
+  } else {
+    const channels = resolveBarChannels(updated), grain = resolveBarGrain(updated);
+    if (grain === undefined || encoding.x?.scale === undefined || encoding.y?.scale === undefined) throw new Error("Series layout requires a complete bar.");
+    if (mode === "center") throw new Error("Centered bars are not supported.");
+    if (grain === BAR_GRAINS.ranged && mode !== "overlay") throw new Error("Ranged bars support only overlay layout.");
+    if (grain === BAR_GRAINS.aggregate) deriveBarAggregates(dataset.values, updated);
+    if (mode === "group" && grain === BAR_GRAINS.aggregate) {
+      if (encoding.group === undefined) throw new Error("Grouped bars require a group encoding.");
+      readSeriesIdentity(dataset.values, updated);
+      offsetChannel = `${channels.category}Offset`;
+      offsetScale = resolveOffsetScaleDefinition(this, { id: encoding[offsetChannel]?.scale ?? offsetChannel }, offsetChannel);
+      offset = { ...(encoding.group.field === undefined ? {} : { field: encoding.group.field }), fieldType: encoding[offsetChannel]?.fieldType ?? "nominal", scale: offsetScale.id };
+      encoding[offsetChannel] = offset;
+    } else for (const channel of ["xOffset", "yOffset"]) delete encoding[channel];
+  }
+  const scales = offsetScale === undefined ? this.semanticSpec.scales
+    : [...this.semanticSpec.scales.filter(scale => scale.id !== offsetScale.id), offsetScale];
+  const preview = { ...this, markConfigs: this.markConfigs, canvasConfig: this.canvasConfig,
+    resolvedScales: { ...this.resolvedScales },
+    semanticSpec: { ...this.semanticSpec, scales,
+      layers: this.semanticSpec.layers.map(item => item.id === target ? updated : item) } };
+  for (const id of new Set([encoding.x?.scale, encoding.y?.scale, offset?.scale].filter(Boolean))) {
+    preview.resolvedScales[id] = resolveScalePreview(preview, id).resolvedScale;
+  }
+  let next = this.editSemantic({ property: `layer[${target}].layout.mode`, value: mode });
+  if (group === undefined && encoding.group !== undefined) next = setEncodingProperties(next, target, "group", encoding.group);
+  for (const channel of ["x", "y"]) if (Object.hasOwn(layer.encoding?.[channel] ?? {}, "stack")) {
+    next = next.editSemantic({ property: `layer[${target}].encoding.${channel}.stack`, remove: true });
+  }
+  if (color && Object.hasOwn(layer.encoding.color, "layout")) next = next.editSemantic({ property: `layer[${target}].encoding.color.layout`, remove: true });
+  if (endpoint !== undefined) {
+    next = next[endpoint.channel === "y2" ? "encodeY2" : "encodeX2"]({ target, datum: 0 });
+  }
+  if (layer.mark.type === "bar") {
+    for (const channel of ["xOffset", "yOffset"]) {
+      if (layer.encoding?.[channel] !== undefined) next = next.editSemantic({ property: `layer[${target}].encoding.${channel}`, remove: true });
+      if (channel !== offsetChannel) next = next._withoutMaterializationConfig(["marks", target, channel]);
+    }
+    if (offset !== undefined) {
+      next = offset.field === undefined
+        ? setEncodingProperties(next, target, offsetChannel, offset).createScale(offsetScale)
+        : next[offsetChannel === "xOffset" ? "encodeXOffset" : "encodeYOffset"]({ target, field: offset.field, fieldType: offset.fieldType, scale: offsetScale });
+      if (findSemanticScale(this, offsetScale.id) === undefined) next = next._withMarkConfig(target, { ...next.markConfigs[target], seriesOffsetScale: offsetScale.id });
+    } else {
+      const owned = next.markConfigs[target]?.seriesOffsetScale;
+      if (owned !== undefined) {
+        const referenced = hasSemanticScaleReferences(next.semanticSpec, owned);
+        if (!referenced) next = next.editSemantic({ property: `scale[${owned}]`, remove: true });
+        next = next._withoutMaterializationConfig(["marks", target, "seriesOffsetScale"]);
+      }
+    }
+  }
+  for (const step of getPositionEncodingMaterializationSteps(next, updated, encoding.y.scale)) next = next[step.op](step.args);
+  return next;
+});
+
+export function registerSeriesLayoutAction(ProgramClass) {
+  ProgramClass.prototype.layoutSeries = layoutSeries;
+}