ggaction 0.0.12 → 0.0.15

package/src/actions/encodings/channels.js

@@ -0,0 +1,415 @@
+import {
+  action,
+  invokeWrappedActionImplementation
+} from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateOptionObject } from "../../core/validation.js";
+import { findLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import { findScaleConsumers } from "../scales/consumers/index.js";
+import { resolveScalePreview, validatePendingMeasuredScale } from
+  "../scales/preview.js";
+import { isPendingMeasuredRadiusConsumer } from
+  "../../materialization/scales/policies/arc.js";
+import {
+  getMarkRematerializationStep,
+  getScaleConsumerMarkSteps,
+  getSourceDependentMarkSteps
+} from "../../materialization/marks/index.js";
+import {
+  applyMaterializationPlan,
+  planScaleGuideRematerialization
+} from "../../materialization/dependencies.js";
+import { buildMaterializationPlan } from "../../materialization/planner.js";
+import { hasMaterializedLegend } from "../../materialization/legends.js";
+import { rebindPositionGuides } from "./shared.js";
+import { withoutPreviewLayerEncodings } from
+  "../primitives/semanticAction.js";
+
+export const ENCODING_CHANNEL_ORDER = Object.freeze([
+  "x", "y", "x2", "y2", "theta", "r", "xOffset", "yOffset",
+  "group", "pathOrder", "color", "stroke", "size", "shape",
+  "opacity", "strokeWidth", "strokeDash", "angle", "text"
+]);
+
+const CHANNEL_METHODS = Object.freeze({
+  x: "encodeX",
+  y: "encodeY",
+  x2: "encodeX2",
+  y2: "encodeY2",
+  theta: "encodeTheta",
+  r: "encodeR",
+  xOffset: "encodeXOffset",
+  yOffset: "encodeYOffset",
+  group: "encodeGroup",
+  pathOrder: "encodePathOrder",
+  color: "encodeColor",
+  stroke: "encodeStroke",
+  size: "encodeSize",
+  shape: "encodeShape",
+  opacity: "encodeOpacity",
+  strokeWidth: "encodeStrokeWidth",
+  strokeDash: "encodeStrokeDash",
+  angle: "encodeAngle",
+  text: "encodeText"
+});
+
+const FORBIDDEN_PAYLOAD_KEYS = Object.freeze(["target", "coordinate", "id"]);
+
+const DEFERRED_MARK_OPERATIONS = Object.freeze([
+  "materializeEmptyMark",
+  "rematerializePointMark",
+  "rematerializeTickMark",
+  "rematerializeLineMark",
+  "rematerializeAreaMark",
+  "rematerializeArcMark",
+  "rematerializeBarMark",
+  "rematerializeRuleMark",
+  "rematerializeTextMark",
+  "rematerializeRectMark",
+  "rematerializeMarkHighlights",
+  "materializeLabelLayout"
+]);
+
+const deferredClassByProgram = new WeakMap();
+
+function sameSetting(left, right) {
+  if (Object.is(left, right)) return true;
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every(
+      (value, index) => sameSetting(value, right[index])
+    );
+  }
+  if (isPlainObject(left) && isPlainObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    return leftKeys.length === rightKeys.length && leftKeys.every(
+      key => Object.hasOwn(right, key) && sameSetting(left[key], right[key])
+    );
+  }
+  return false;
+}
+
+function assertCompatibleScaleRequests(requests) {
+  const patches = new Map();
+  for (const { channel, payload } of requests) {
+    if (!isPlainObject(payload.scale) || payload.scale.id === undefined) continue;
+    const id = payload.scale.id;
+    const previous = patches.get(id) ?? new Map();
+    for (const [property, value] of Object.entries(payload.scale)) {
+      if (property === "id" || value === undefined) continue;
+      const existing = previous.get(property);
+      if (existing !== undefined && !sameSetting(existing.value, value)) {
+        throw new Error(
+          `encodeChannels scale "${id}" has conflicting explicit ${property} requests for ${existing.channel} and ${channel}.`
+        );
+      }
+      if (existing === undefined) previous.set(property, { channel, value });
+    }
+    patches.set(id, previous);
+  }
+}
+
+export function normalizeEncodeChannelsArgs(args) {
+  validateOptionObject(args, ["target", "channels"], "encodeChannels");
+  const target = validateUserId(args.target, "Mark id");
+  if (!isPlainObject(args.channels)) {
+    throw new TypeError("encodeChannels channels must be a plain object.");
+  }
+  const keys = Object.keys(args.channels);
+  if (keys.length === 0) {
+    throw new TypeError("encodeChannels channels must contain at least one channel.");
+  }
+  for (const key of keys) {
+    if (!Object.hasOwn(CHANNEL_METHODS, key)) {
+      throw new Error(`encodeChannels does not support channel "${key}".`);
+    }
+  }
+  const requests = ENCODING_CHANNEL_ORDER
+    .filter(channel => Object.hasOwn(args.channels, channel))
+    .map(channel => {
+      const payload = args.channels[channel];
+      if (!isPlainObject(payload)) {
+        throw new TypeError(
+          `encodeChannels ${channel} payload must be a plain object.`
+        );
+      }
+      for (const key of FORBIDDEN_PAYLOAD_KEYS) {
+        if (Object.hasOwn(payload, key)) {
+          throw new Error(
+            `encodeChannels ${channel} payload cannot specify ${key}.`
+          );
+        }
+      }
+      return Object.freeze({ channel, payload });
+    });
+  assertCompatibleScaleRequests(requests);
+  return Object.freeze({ target, requests: Object.freeze(requests) });
+}
+
+function resolveScaleOnly(program, id) {
+  const semanticScale = findSemanticScale(program, id);
+  if (semanticScale === undefined) {
+    throw new Error(`Unknown scale "${id}".`);
+  }
+  const consumers = findScaleConsumers(program, id);
+  if (
+    semanticScale.radialMapping !== undefined &&
+    consumers.length > 0 &&
+    consumers.every(isPendingMeasuredRadiusConsumer)
+  ) {
+    validatePendingMeasuredScale(program, semanticScale, consumers);
+    return program._withoutResolvedScale(id);
+  }
+  return program._withResolvedScale(
+    id,
+    resolveScalePreview(program, id).resolvedScale
+  );
+}
+
+function deferredProgramClass(ProgramClass) {
+  const existing = deferredClassByProgram.get(ProgramClass);
+  if (existing !== undefined) return existing;
+
+  class DeferredEncodingProgram extends ProgramClass {
+    rematerializeScale({ id } = {}) {
+      return resolveScaleOnly(this, id);
+    }
+
+    rematerializeLegend() {
+      return this;
+    }
+  }
+  for (const operation of DEFERRED_MARK_OPERATIONS) {
+    Object.defineProperty(DeferredEncodingProgram.prototype, operation, {
+      configurable: true,
+      value() {
+        return this;
+      }
+    });
+  }
+  deferredClassByProgram.set(ProgramClass, DeferredEncodingProgram);
+  return DeferredEncodingProgram;
+}
+
+function programState(program) {
+  return Object.freeze({
+    semanticSpec: program.semanticSpec,
+    graphicSpec: program.graphicSpec,
+    resolvedScales: program.resolvedScales,
+    materializationConfigs: program.materializationConfigs,
+    children: program.children,
+    compositionSpec: program.compositionSpec,
+    context: program.context,
+    trace: program.trace,
+    actionStack: program.actionStack,
+    actionSequence: program._actionSequence
+  });
+}
+
+function instantiateProgram(state, ProgramClass) {
+  return new ProgramClass({
+    semanticSpec: state.semanticSpec,
+    graphicSpec: state.graphicSpec,
+    resolvedScales: state.resolvedScales,
+    materializationConfigs: state.materializationConfigs,
+    children: state.children,
+    compositionSpec: state.compositionSpec,
+    context: state.context,
+    trace: state.trace,
+    actionStack: state.actionStack,
+    actionSequence: state.actionSequence
+  });
+}
+
+function createDeferredProgram(program) {
+  return instantiateProgram(
+    programState(program),
+    deferredProgramClass(program.constructor)
+  );
+}
+
+function requestedFieldType(request) {
+  if (request === undefined) return undefined;
+  return request.payload.fieldType ?? "quantitative";
+}
+
+function isCategoricalBarType(fieldType) {
+  return ["nominal", "ordinal", "temporal"].includes(fieldType);
+}
+
+function stageFinalPositionRoles(program, target, requests) {
+  const layer = findLayer(program, target);
+  if (layer?.mark?.type !== "bar") return program;
+  const byChannel = new Map(requests.map(request => [request.channel, request]));
+  const nextX = requestedFieldType(byChannel.get("x"));
+  const nextY = requestedFieldType(byChannel.get("y"));
+  if (nextX === undefined || nextY === undefined) return program;
+  const currentX = layer.encoding?.x?.fieldType;
+  const currentY = layer.encoding?.y?.fieldType;
+  const changesOrientation =
+    isCategoricalBarType(currentX) !== isCategoricalBarType(nextX) &&
+    isCategoricalBarType(currentY) !== isCategoricalBarType(nextY);
+  if (!changesOrientation) return program;
+
+  return withoutPreviewLayerEncodings(program, {
+    id: target,
+    channels: ["x", "y"]
+  });
+}
+
+const INTERNAL_SCALE_CHANNEL = Object.freeze({ r: "radius" });
+
+function requestedScaleIds(originalLayer, finalLayer, requests) {
+  const requestedChannels = new Set(requests.map(({ channel }) =>
+    INTERNAL_SCALE_CHANNEL[channel] ?? channel
+  ));
+  const ids = [];
+  for (const channel of [
+    "x", "y", "x2", "y2", "theta", "radius", "xOffset", "yOffset",
+    "color", "stroke", "size", "shape", "opacity", "strokeWidth",
+    "strokeDash", "angle", "text", "group", "pathOrder"
+  ]) {
+    if (!requestedChannels.has(channel)) continue;
+    for (const layer of [originalLayer, finalLayer]) {
+      const id = layer?.encoding?.[channel]?.scale;
+      if (id !== undefined && !ids.includes(id)) ids.push(id);
+    }
+  }
+  return ids;
+}
+
+function changedScaleIds(before, after) {
+  const beforeById = new Map(before.semanticSpec.scales.map(scale => [scale.id, scale]));
+  return after.semanticSpec.scales
+    .filter(scale => !sameSetting(scale, beforeById.get(scale.id)))
+    .map(scale => scale.id)
+    .sort();
+}
+
+function finalScaleIds(before, after, originalLayer, finalLayer, requests) {
+  const ids = [
+    ...requestedScaleIds(originalLayer, finalLayer, requests),
+    ...changedScaleIds(before, after)
+  ];
+  return [...new Set(ids)].filter(id =>
+    findSemanticScale(after, id) !== undefined &&
+    findScaleConsumers(after, id).length > 0
+  );
+}
+
+const rematerializeEncodingScales = action(
+  {
+    op: "rematerializeEncodingScales",
+    description: "Resolve every scale affected by one atomic encoding assignment."
+  },
+  function ({ ids } = {}) {
+    let next = this;
+    for (const id of ids) next = resolveScaleOnly(next, id);
+    return next;
+  }
+);
+
+function finalMaterializationPlan(program, target, scaleIds) {
+  const layer = findLayer(program, target);
+  const targetStep = layer === undefined
+    ? undefined
+    : getMarkRematerializationStep(program, layer);
+  const directMarks = [
+    ...(targetStep === undefined ? [] : [targetStep]),
+    ...getScaleConsumerMarkSteps(program, scaleIds)
+  ];
+  const marks = [
+    ...directMarks,
+    ...directMarks.flatMap(step =>
+      getSourceDependentMarkSteps(program, step.args.id)
+    )
+  ];
+  const guides = scaleIds.flatMap(id =>
+    planScaleGuideRematerialization(program, id)
+  );
+  if (hasMaterializedLegend(program)) {
+    guides.push({ op: "rematerializeLegend" });
+  }
+  return buildMaterializationPlan({ marks, guides });
+}
+
+function applyEncodingDraft(program, target, requests) {
+  let draft = stageFinalPositionRoles(
+    createDeferredProgram(program),
+    target,
+    requests
+  );
+  for (const { channel, payload } of requests) {
+    const focusedAction = draft[CHANNEL_METHODS[channel]];
+    draft = invokeWrappedActionImplementation(
+      focusedAction,
+      draft,
+      { ...payload, target }
+    );
+  }
+  const originalLayer = findLayer(program, target);
+  const finalLayer = findLayer(draft, target);
+  for (const channel of ["x", "y"]) {
+    const previousScale = originalLayer?.encoding?.[channel]?.scale;
+    const nextScale = finalLayer?.encoding?.[channel]?.scale;
+    if (previousScale !== undefined && nextScale !== undefined) {
+      draft = rebindPositionGuides(
+        draft,
+        channel,
+        previousScale,
+        nextScale,
+        target
+      );
+    }
+  }
+  return draft;
+}
+
+function planEncodingAssignments(program, target, requests) {
+  const originalLayer = findLayer(program, target);
+  const draft = applyEncodingDraft(program, target, requests);
+  const finalLayer = findLayer(draft, target);
+  return Object.freeze({
+    target,
+    originalLayer,
+    finalLayer,
+    state: programState(draft),
+    scaleIds: Object.freeze(finalScaleIds(
+      program,
+      draft,
+      originalLayer,
+      finalLayer,
+      requests
+    ))
+  });
+}
+
+function applyEncodingAssignments(program, plan) {
+  return instantiateProgram(plan.state, program.constructor);
+}
+
+export const encodeChannels = action(
+  {
+    op: "encodeChannels",
+    description: "Atomically assign multiple encoding channels to one mark."
+  },
+  function (args = {}) {
+    const { target, requests } = normalizeEncodeChannelsArgs(args);
+    const plan = planEncodingAssignments(this, target, requests);
+    let next = applyEncodingAssignments(this, plan);
+    const scaleIds = plan.scaleIds;
+    if (scaleIds.length > 0) {
+      next = rematerializeEncodingScales.call(next, { ids: scaleIds });
+    }
+    return applyMaterializationPlan(
+      next,
+      finalMaterializationPlan(next, target, scaleIds)
+    );
+  }
+);
+
+export function registerAtomicEncodingAction(ProgramClass) {
+  ProgramClass.prototype.encodeChannels = encodeChannels;
+}

package/src/actions/encodings/color/continuous.js

@@ -1,18 +1,11 @@
 import {
   readQuantitativeField,
   readScaleField,
-  readTemporalField
+  readTemporalField,
+  resolveTemporalUnit
 } from "../../../grammar/scales/index.js";
-import {
-  BAR_GRAINS,
-  resolveBarChannels,
-  resolveBarGrain
-} from "../../../grammar/bars/policy.js";
-import {
-  validateAggregate,
-  validateAggregateFieldType,
-  validateAggregateFieldValues
-} from "../../../grammar/aggregate.js";
+import { validateContinuousColorConsumer } from "../../../grammar/scales/colorConsumers.js";
+import { validateAggregateFieldValues } from "../../../grammar/aggregate.js";
 import {
   resolveQuantitativeColorScaleDefinition
 } from "../../scales/definitions.js";
@@ -20,7 +13,10 @@ import {
   resolveReassignmentScaleOptions,
   resolveTarget
 } from "../shared.js";
-import { applyMaterializationPlan } from "../../../materialization/dependencies.js";
+import {
+  applyDetachedScaleRematerialization,
+  applyMaterializationPlan
+} from "../../../materialization/dependencies.js";
 import {
   planEncodingRematerialization
 } from "../../../materialization/encodings.js";
@@ -29,6 +25,8 @@ import {
   resolveColorScaleOptions
 } from "./policy.js";
 
+import { applyTemporalUnit } from "../temporal.js";
+
 export function encodeContinuousColor(program, args) {
   if (!["quantitative", "temporal"].includes(args.fieldType)) {
     throw new Error(`Unsupported color field type "${args.fieldType}".`);
@@ -43,6 +41,7 @@ export function encodeContinuousColor(program, args) {
     "continuous color mark"
   );
   assertNoConstantColor(program, layer);
+  const temporalUnit = resolveTemporalUnit(args, args.fieldType, layer.encoding?.color);
   const requestedScale = resolveReassignmentScaleOptions(
     layer.encoding?.color,
     resolveColorScaleOptions(args)
@@ -52,61 +51,22 @@ export function encodeContinuousColor(program, args) {
     args.fieldType,
     requestedScale
   );
-  if (Object.hasOwn(scale, "unknown") && layer.mark.type !== "point") {
-    throw new Error(
-      "Continuous color scale unknown currently requires a row-owned point mark."
-    );
-  }
-  if (
-    layer.mark.type === "bar" &&
-    ["nominal", "ordinal"].includes(layer.encoding?.color?.fieldType)
-  ) {
-    throw new Error(
-      "Continuous bar color cannot replace an existing nominal color layout."
-    );
-  }
-  let aggregate;
-  if (["point", "rect"].includes(layer.mark.type)) {
-    if (args.aggregate !== undefined) {
-      throw new Error(`${layer.mark.type} continuous color does not support aggregate.`);
-    }
-  } else {
-    if (args.fieldType !== "quantitative") {
-      throw new Error("Aggregate bar color currently requires a quantitative field.");
-    }
-    if (resolveBarGrain(layer) !== BAR_GRAINS.aggregate) {
-      throw new Error(
-        "Continuous bar color requires a complete categorical aggregate bar."
-      );
-    }
-    const channels = resolveBarChannels(layer);
-    const measure = layer.encoding?.[channels.measure];
-    aggregate = args.aggregate ?? (
-      measure?.field === args.field ? measure.aggregate : undefined
-    );
-    if (aggregate === undefined) {
-      throw new Error(
-        "Continuous bar color requires aggregate when its field differs from the measure field."
-      );
-    }
-    aggregate = validateAggregate(aggregate);
-    validateAggregateFieldType(aggregate, args.fieldType);
-    validateAggregateFieldValues(dataset.values, args.field, args.fieldType);
-  }
+  const aggregate = validateContinuousColorConsumer(layer, args, scale, { inferAggregate: true });
+  if (aggregate !== undefined) validateAggregateFieldValues(dataset.values, args.field, args.fieldType);
   if (layer.mark.type === "rect") {
     readScaleField(dataset.values, args.field, args.fieldType, {
-      allowUnknown: true
+      allowUnknown: true, temporalUnit
     });
   } else if (Object.hasOwn(scale, "unknown")) {
     readScaleField(dataset.values, args.field, args.fieldType, {
-      allowUnknown: true
+      allowUnknown: true, temporalUnit
     });
   } else if (args.fieldType === "temporal") {
-    readTemporalField(dataset.values, args.field);
+    readTemporalField(dataset.values, args.field, temporalUnit);
   } else {
     readQuantitativeField(dataset.values, args.field);
   }
-  const next = program
+  const next = applyTemporalUnit(program, target, "color", temporalUnit, layer.encoding?.color)
     .editSemantic({
       property: `layer[${target}].encoding.color.field`,
       value: args.field
@@ -126,12 +86,12 @@ export function encodeContinuousColor(program, args) {
         value: aggregate
       });
   const scaled = encoded.setQuantitativeColorScale(scale);
-  return applyMaterializationPlan(
+  return applyDetachedScaleRematerialization(applyMaterializationPlan(
     scaled,
     planEncodingRematerialization(scaled, {
       target,
       channel: "color",
       scale: scale.id
     })
-  );
+  ), [layer]);
 }

package/src/actions/encodings/color/index.js

@@ -1,7 +1,9 @@
+import { inferSeriesGroup } from "../shared.js";
 import { action } from "../../../core/action.js";
 import {
   readNominalField,
   readScaleField,
+  resolveTemporalUnit,
   validateCategoricalFieldType
 } from "../../../grammar/scales/index.js";
 import {
@@ -12,19 +14,21 @@ import {
   applyEncodingScale,
   resolveReassignmentScaleOptions,
   resolveTarget,
-  validateLineSeriesCompatibility,
   validateOptions
 } from "../shared.js";
-import { applyMaterializationPlan } from "../../../materialization/dependencies.js";
+import {
+  applyDetachedScaleRematerialization,
+  applyMaterializationPlan
+} from "../../../materialization/dependencies.js";
 import {
   planEncodingRematerialization
 } from "../../../materialization/encodings.js";
 import { findUpstreamTransform } from
   "../../../materialization/dataProvenance.js";
+import { validatePathSeriesAppearance } from "../../../grammar/pathSeries.js";
 import { encodeContinuousColor } from "./continuous.js";
 import {
-  applyColorLayoutCompanion,
-  preSynchronizeGroupedOffset
+  applyColorLayoutCompanion
 } from "./layout.js";
 import {
   assertNoConstantColor,
@@ -33,6 +37,8 @@ import {
   resolveColorScaleOptions
 } from "./policy.js";
 
+import { applyTemporalUnit } from "../temporal.js";
+
 const encodeColor = action(
   {
     op: "encodeColor",
@@ -51,6 +57,7 @@ const encodeColor = action(
       throw new Error("Categorical color does not support aggregate.");
     }
     const fieldType = validateCategoricalFieldType(requestedFieldType);
+    resolveTemporalUnit(args, fieldType);
     const { id: target, dataset, layer } = resolveTarget(
       this,
       args.target,
@@ -78,10 +85,13 @@ const encodeColor = action(
     }
     const layout = resolveColorLayout(layer, args.layout, barGrain);
     const createsCenterGroup = layer.mark.type === "area" &&
-      layout === "center" && layer.encoding?.group?.field === undefined;
+      layout === "center" && layer.encoding?.group === undefined;
+    const ordinaryGroup = layer.mark.type === "area" && !createsCenterGroup &&
+      densityTransform === undefined && horizonTransform === undefined;
     if (
       layer.mark.type === "area" &&
       !createsCenterGroup &&
+      !ordinaryGroup &&
       (layer.encoding?.group?.field === undefined ||
         layer.encoding.group.field !== args.field) &&
       !densitySeriesFields.includes(args.field) &&
@@ -91,7 +101,11 @@ const encodeColor = action(
         "Area color encoding must match an existing group encoding."
       );
     }
-    validateLineSeriesCompatibility(layer, "color", args.field);
+    if (layer.mark.type === "line" || ordinaryGroup) {
+      validatePathSeriesAppearance(dataset.values, {
+        ...layer, encoding: { ...layer.encoding, color: { field: args.field, fieldType } }
+      });
+    }
     const requestedScale = resolveReassignmentScaleOptions(
       layer.encoding?.color,
       resolveColorScaleOptions(args)
@@ -114,10 +128,10 @@ const encodeColor = action(
       readNominalField(dataset.values, args.field);
     }
 
-    let next = createsCenterGroup
-      ? this.encodeGroup({ target, field: args.field })
+    let next = layer.mark.type === "bar" || createsCenterGroup
+      ? inferSeriesGroup(this, layer, args.field, "color")
       : this;
-    next = next.editSemantic({
+    next = applyTemporalUnit(next, target, "color", undefined, layer.encoding?.color).editSemantic({
       property: `layer[${target}].encoding.color.field`,
       value: args.field
     })
@@ -129,40 +143,33 @@ const encodeColor = action(
         property: `layer[${target}].encoding.color.scale`,
         value: scale.id
       });
-    if (layout !== undefined) {
+    if (layout !== undefined && (layer.mark.type === "arc" || horizonTransform !== undefined)) {
       next = next.editSemantic({
         property: `layer[${target}].encoding.color.layout`,
         value: layout
       });
     }
-    next = preSynchronizeGroupedOffset(next, {
-      target,
-      layer,
-      layout,
-      field: args.field,
-      fieldType,
-      scale,
-      requestedScale
-    });
     next = applyEncodingScale(next, scale, requestedScale, {
-      reassignment: layer.encoding?.color?.scale === scale.id
+      reassignment: layer.encoding?.color?.scale === scale.id,
+      allowTypeChange: true
     });
     next = applyColorLayoutCompanion(next, {
       target,
       layer,
       layout,
       scale,
-      field: args.field
+      field: args.field,
+      horizon: horizonTransform !== undefined
     });
 
-    return applyMaterializationPlan(
+    return applyDetachedScaleRematerialization(applyMaterializationPlan(
       next,
       planEncodingRematerialization(next, {
         target,
         channel: "color",
         scale: scale.id
       })
-    );
+    ), [layer]);
   }
 );