ggaction 0.0.13 → 0.0.15

package/src/actions/data/regression.js

@@ -3,8 +3,9 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import {
   deriveRegression,
-  normalizeRegressionParameters
+  normalizeRegressionTransform
 } from "../../grammar/regression/index.js";
+import { resolveDatasetReference } from "../../selectors/datasets.js";
 import { derivedMaterializer } from "./shared.js";
 
 const OPTIONS = Object.freeze([
@@ -34,31 +35,25 @@ export const createRegressionData = action(
   { op: "createRegressionData", description: "Create grouped regression values and optional interval bounds." },
   function (args = {}) {
     validateKeys(args, OPTIONS, "createRegressionData");
-    const parameters = normalizeRegressionParameters(args);
     const id = validateUserId(args.id, "Regression dataset id");
-    const source = validateUserId(
+    const requestedSource = validateUserId(
       args.source ?? this.context.currentData,
       "Source dataset id"
     );
-    const transform = {
-      type: "regression",
-      method: parameters.method,
-      x: args.x,
-      y: args.y,
-      ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
-      ...(parameters.method === "polynomial"
-        ? { degree: parameters.degree }
-        : {}),
-      ...(parameters.method === "loess"
-        ? { span: parameters.span }
-        : {
-            confidenceMethod: parameters.confidenceMethod,
-            level: parameters.level,
-            interval: parameters.interval
-          })
-    };
-    return this
+    const source = resolveDatasetReference(
+      this,
+      requestedSource,
+      "Regression source dataset"
+    ).id;
+    const transform = normalizeRegressionTransform(args);
+    const next = this
       .createDerivedData({ id, source, transform: [transform] })
       .materializeRegressionData({ id });
+    return this.actionStack.length === 1
+      ? next._withMaterializationConfig(
+          ["data", "regression", id],
+          { current: id }
+        )
+      : next;
   }
 );

package/src/actions/data/revisionBindings.js

@@ -0,0 +1,145 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { datasetTransformOutputRoles } from "../../grammar/transforms.js";
+import { requireLayer } from "../../selectors/layers.js";
+
+const DATA_REFERENCE_KEYS = new Set([
+  "data", "dataset", "dataId", "filteredData", "originalData",
+  "outlierDataId", "profileId", "source", "summaryId"
+]);
+
+export function outputFieldChanges(previous, next) {
+  const before = datasetTransformOutputRoles(previous);
+  const after = datasetTransformOutputRoles(next);
+  const family = previous.type === "bin2d" ? "2D bin " : "";
+  const counts = new Map();
+  const retainedFields = new Set(Object.values(after));
+  for (const field of Object.values(before)) {
+    counts.set(field, (counts.get(field) ?? 0) + 1);
+  }
+  return new Map(Object.entries(before).flatMap(([role, field]) => {
+    if (field === after[role] || retainedFields.has(field)) return [];
+    if (counts.get(field) !== 1) {
+      throw new Error(
+        `Cannot rebind ambiguous derived output field "${field}".`
+      );
+    }
+    return [[field, { role, next: after[role], family }]];
+  }));
+}
+
+function changedConsumerField(field, changes) {
+  const change = changes.get(field);
+  if (change === undefined) return field;
+  if (change.next === undefined) {
+    throw new Error(
+      `Cannot remove referenced ${change.family}${change.role} output field "${field}".`
+    );
+  }
+  return change.next;
+}
+
+export function rebindLayerOutputFields(program, id, changes) {
+  const layer = requireLayer(program, id);
+  let next = program;
+  const changed = field => changedConsumerField(field, changes);
+  const editField = (property, field) => {
+    if (field === undefined) return;
+    const value = changed(field);
+    if (value !== field) next = next.editSemantic({ property, value });
+  };
+  for (const [channel, encoding] of Object.entries(layer.encoding ?? {})) {
+    editField(`layer[${id}].encoding.${channel}.field`, encoding?.field);
+    const summary = encoding?.categoryOrder?.by;
+    if (summary?.field !== undefined) {
+      const field = changed(summary.field);
+      if (field !== summary.field) {
+        next = next.editSemantic({
+          property: `layer[${id}].encoding.${channel}.categoryOrder`,
+          value: { ...encoding.categoryOrder, by: { ...summary, field } }
+        });
+      }
+    }
+  }
+  editField(
+    `layer[${id}].encoding.theta.weight`,
+    layer.encoding?.theta?.weight
+  );
+
+  const parallel = layer.encoding?.parallel;
+  if (parallel?.dimensions !== undefined) {
+    const dimensions = parallel.dimensions.map(dimension => ({
+      ...dimension,
+      field: changed(dimension.field)
+    }));
+    if (dimensions.some((dimension, index) =>
+      dimension.field !== parallel.dimensions[index].field
+    )) {
+      next = next.editSemantic({
+        property: `layer[${id}].encoding.parallel.dimensions`,
+        value: dimensions
+      });
+    }
+  }
+  editField(`layer[${id}].encoding.parallel.key`, parallel?.key);
+
+  for (const [selectionId, config] of Object.entries(
+    program.materializationConfigs.selections ?? {}
+  )) {
+    if (config.target !== id) continue;
+    const selector = { ...config.selector };
+    if (selector.field !== undefined) selector.field = changed(selector.field);
+    if (selector.groupBy !== undefined) {
+      selector.groupBy = selector.groupBy.map(changed);
+    }
+    if (JSON.stringify(selector) !== JSON.stringify(config.selector)) {
+      next = next._withSelectionConfig(selectionId, { ...config, selector });
+    }
+  }
+
+  const jitter = program.materializationConfigs.jitters?.[id];
+  const key = jitter?.key === undefined ? undefined : changed(jitter.key);
+  if (key !== undefined && key !== jitter.key) {
+    next = next._withMaterializationConfig(
+      ["jitters", id],
+      { ...jitter, key }
+    );
+  }
+  return next;
+}
+
+function replaceReferences(value, replacements, key) {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const items = value.map(item => {
+      const next = replaceReferences(item, replacements);
+      changed ||= next !== item;
+      return next;
+    });
+    return changed ? items : value;
+  }
+  if (!isPlainObject(value)) {
+    return DATA_REFERENCE_KEYS.has(key) && replacements.has(value)
+      ? replacements.get(value)
+      : value;
+  }
+  let changed = false;
+  const result = {};
+  for (const [childKey, child] of Object.entries(value)) {
+    const next = replaceReferences(child, replacements, childKey);
+    changed ||= next !== child;
+    result[childKey] = next;
+  }
+  return changed ? result : value;
+}
+
+export function rebindMaterializationDataReferences(program, replacements) {
+  if (replacements.size === 0) return program;
+  let next = program;
+  for (const [key, config] of Object.entries(program.materializationConfigs)) {
+    const replaced = replaceReferences(config, replacements, key);
+    if (replaced !== config) {
+      next = next._withMaterializationConfig([key], replaced);
+    }
+  }
+  return next;
+}

package/src/actions/data/shared.js

@@ -1,7 +1,10 @@
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
-import { findDataset } from "../../selectors/datasets.js";
+import {
+  findDataset,
+  resolveDatasetReference
+} from "../../selectors/datasets.js";
 
 export const MATERIALIZE_OPTIONS = Object.freeze(["id"]);
 
@@ -61,12 +64,25 @@ export function derivedCreator(
   return action({ op, description }, function (args = {}) {
     validateKeys(args, options, op);
     const id = validateUserId(args.id, idLabel);
-    const source = validateUserId(
+    const requestedSource = validateUserId(
       requireSource ? args.source : args.source ?? this.context.currentData,
       sourceLabel
     );
-    return this
-      .createDerivedData({ id, source, transform: [transform(args, id)] })
+    const source = resolveDatasetReference(
+      this,
+      requestedSource,
+      sourceLabel
+    ).id;
+    const standalone = this.actionStack.length === 1;
+    const requestedTransform = transform(args, id);
+    const next = this
+      .createDerivedData({ id, source, transform: [requestedTransform] })
       [materialize]({ id });
+    return standalone
+      ? next._withMaterializationConfig(
+          ["data", requestedTransform.type, id],
+          { current: id }
+        )
+      : next;
   });
 }

package/src/actions/data/summary.js

@@ -5,7 +5,7 @@ import {
 import { derivedCreator, derivedMaterializer } from "./shared.js";
 
 const OPTIONS = Object.freeze([
-  "id", "source", "groupBy", "aggregates", "members"
+  "id", "source", "groupBy", "aggregates", "members", "weight"
 ]);
 
 export const materializeSummaryData = derivedMaterializer(

package/src/actions/data/timeUnit.js

@@ -4,7 +4,10 @@ import {
 } from "../../grammar/timeUnit.js";
 import { derivedCreator, derivedMaterializer } from "./shared.js";
 
-const OPTIONS = Object.freeze(["id", "source", "field", "unit", "as", "temporalUnit"]);
+const OPTIONS = Object.freeze([
+  "id", "source", "field", "unit", "as", "temporalUnit", "timeZone",
+  "weekStartsOn", "weekRule"
+]);
 
 export const materializeTimeUnitData = derivedMaterializer(
   "materializeTimeUnitData",

package/src/actions/data/window.js

@@ -5,7 +5,7 @@ import {
 import { derivedCreator, derivedMaterializer } from "./shared.js";
 
 const OPTIONS = Object.freeze([
-  "id", "source", "partitionBy", "sortBy", "operations"
+  "id", "source", "partitionBy", "sortBy", "operations", "temporalUnit"
 ]);
 
 export const materializeWindowData = derivedMaterializer(

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;
+}