ggaction 0.0.5 → 0.0.7

package/src/actions/data/bin2d.js

@@ -3,7 +3,8 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import {
   deriveBin2DRows,
-  normalizeBin2DTransform
+  normalizeBin2DTransform,
+  requestedBin2DTransform
 } from "../../grammar/bin2d.js";
 import { applyLayerDataRematerialization } from
   "../../materialization/dependencies.js";
@@ -13,16 +14,48 @@ import {
   findDataset,
   findDatasetConsumer
 } from "../../selectors/datasets.js";
-import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+export { materializeBin2DData } from "./bin2dMaterialize.js";
 
 const OPTIONS = Object.freeze([
   "id", "source", "x", "y", "bins", "extent", "includeEmpty", "members", "as"
 ]);
+const EDIT_OPTIONS = Object.freeze([
+  "target", "source", "x", "y", "bins", "extent", "includeEmpty", "members", "as"
+]);
+const EDITABLE = Object.freeze(EDIT_OPTIONS.slice(1));
+const OUTPUT_FIELDS = Object.freeze([
+  "x0", "x1", "y0", "y1", "count"
+]);
 
 function ownerConfig(program, id) {
   return program.materializationConfigs.data?.bin2d?.[id];
 }
 
+function ownerEntries(program) {
+  return Object.entries(program.materializationConfigs.data?.bin2d ?? {});
+}
+
+function resolveBin2DOwner(program, requested) {
+  if (requested !== undefined) {
+    const owner = validateUserId(requested, "2D bin owner id");
+    if (ownerConfig(program, owner) === undefined) {
+      throw new Error(`Unknown 2D bin owner "${owner}".`);
+    }
+    return owner;
+  }
+  const owners = ownerEntries(program);
+  const current = owners.filter(([, config]) =>
+    config?.current === program.context.currentData
+  );
+  if (current.length === 1) return current[0][0];
+  if (current.length > 1) {
+    throw new Error("2D bin owner is ambiguous; provide target.");
+  }
+  if (owners.length === 1) return owners[0][0];
+  if (owners.length === 0) throw new Error("No 2D bin owner is available.");
+  throw new Error("2D bin owner is ambiguous; provide target.");
+}
+
 function requireCurrentBin2D(program, id, config) {
   const current = findDataset(program, config.current);
   if (
@@ -59,30 +92,73 @@ function preflight(program, sourceId, transform) {
   deriveBin2DRows(source.values, transform);
 }
 
-export const materializeBin2DData = action(
-  {
-    op: "materializeBin2DData",
-    description: "Materialize one immutable rectangular 2D-bin dataset."
-  },
-  function (args = {}) {
-    validateKeys(args, MATERIALIZE_OPTIONS, "materializeBin2DData");
-    const { id, source, transform } = requireDerivedDataset(
-      this,
-      args.id,
-      "bin2d"
+function requireCompleteEditOutputFields(value, members) {
+  const required = [...OUTPUT_FIELDS, ...(members ? ["members"] : [])];
+  const missing = required.find(field => !Object.hasOwn(value, field));
+  if (missing !== undefined) {
+    throw new Error(
+      `editBin2DData as requires the complete "${missing}" output field.`
     );
-    const result = deriveBin2DRows(source.values, transform);
-    return this
-      .editSemantic({
-        property: `dataset[${id}].transform`,
-        value: [{ ...transform, resolved: result.resolved }]
-      })
-      .editSemantic({
-        property: `dataset[${id}].values`,
-        value: result.values
-      });
   }
-);
+}
+
+function editedTransform(owner, previous, args) {
+  const prior = requestedBin2DTransform(previous.transform[0]);
+  const option = property => Object.hasOwn(args, property)
+    ? args[property]
+    : prior[property];
+  const members = option("members");
+  let as = option("as");
+  if (!Object.hasOwn(args, "as")) {
+    as = { ...as };
+    if (members && as.members === undefined) {
+      as.members = `__${owner}_members`;
+    } else if (!members) {
+      delete as.members;
+    }
+  }
+  const transform = normalizeBin2DTransform({
+    id: owner,
+    x: option("x"),
+    y: option("y"),
+    bins: option("bins"),
+    extent: option("extent"),
+    includeEmpty: option("includeEmpty"),
+    members,
+    as
+  });
+  if (Object.hasOwn(args, "as")) {
+    requireCompleteEditOutputFields(args.as, members);
+  }
+  return transform;
+}
+
+function sameRequestedTransform(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function applyBin2DRevision(program, { owner, previous, source, transform }) {
+  rejectDerivedConsumers(program, previous.id);
+  const consumers = directLayerConsumers(program, previous.id);
+  const revision = planDerivedDataRevision(program, {
+    owner,
+    role: "Bin2DData",
+    previous: previous.id,
+    consumers
+  });
+  let next = program
+    .createDerivedData({ id: revision.id, source, transform: [transform] })
+    .materializeBin2DData({ id: revision.id });
+  for (const rebind of revision.rebinds) {
+    next = next.rebindLayerData(rebind);
+    next = applyLayerDataRematerialization(next, rebind.id);
+  }
+  next = next.releaseDerivedData(revision.release);
+  return next._withMaterializationConfig(
+    ["data", "bin2d", owner],
+    { current: revision.id }
+  );
+}
 
 export const createBin2DData = action(
   {
@@ -113,25 +189,47 @@ export const createBin2DData = action(
         );
     }
 
-    rejectDerivedConsumers(this, previous.id);
-    const consumers = directLayerConsumers(this, previous.id);
-    const revision = planDerivedDataRevision(this, {
+    return applyBin2DRevision(this, {
       owner,
-      role: "Bin2DData",
-      previous: previous.id,
-      consumers
+      previous,
+      source,
+      transform
     });
-    let next = this
-      .createDerivedData({ id: revision.id, source, transform: [transform] })
-      .materializeBin2DData({ id: revision.id });
-    for (const rebind of revision.rebinds) {
-      next = next.rebindLayerData(rebind);
-      next = applyLayerDataRematerialization(next, rebind.id);
+  }
+);
+
+export const editBin2DData = action(
+  {
+    op: "editBin2DData",
+    description: "Partially revise one logical rectangular 2D-bin owner."
+  },
+  function (args = {}) {
+    validateKeys(args, EDIT_OPTIONS, "editBin2DData");
+    if (!EDITABLE.some(option => Object.hasOwn(args, option))) {
+      throw new Error("editBin2DData requires at least one transform or source option.");
     }
-    next = next.releaseDerivedData(revision.release);
-    return next._withMaterializationConfig(
-      ["data", "bin2d", owner],
-      { current: revision.id }
+    const owner = resolveBin2DOwner(this, args.target);
+    const previous = requireCurrentBin2D(this, owner, ownerConfig(this, owner));
+    const source = validateUserId(
+      args.source ?? previous.source,
+      "2D bin source dataset id"
     );
+    const transform = editedTransform(owner, previous, args);
+    if (
+      source === previous.source &&
+      sameRequestedTransform(
+        transform,
+        requestedBin2DTransform(previous.transform[0])
+      )
+    ) {
+      throw new Error("editBin2DData requires an actual transform or source change.");
+    }
+    preflight(this, source, transform);
+    const revision = { owner, previous, source, transform };
+
+    // Execute one speculative immutable branch so every consumer plan is known
+    // to succeed before the returned action trace records its first child.
+    applyBin2DRevision(this, revision);
+    return applyBin2DRevision(this, revision);
   }
 );

package/src/actions/data/bin2dMaterialize.js

@@ -0,0 +1,29 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+import { deriveBin2DRows } from "../../grammar/bin2d.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+export const materializeBin2DData = action(
+  {
+    op: "materializeBin2DData",
+    description: "Materialize one immutable rectangular 2D-bin dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeBin2DData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "bin2d"
+    );
+    const result = deriveBin2DRows(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{ ...transform, resolved: result.resolved }]
+      })
+      .editSemantic({
+        property: `dataset[${id}].values`,
+        value: result.values
+      });
+  }
+);

package/src/actions/data/index.js

@@ -23,7 +23,11 @@ import {
 import { createIntervalData, materializeIntervalData } from "./interval.js";
 import { createHorizonData, materializeHorizonData } from "./horizon.js";
 import { createWindowData, materializeWindowData } from "./window.js";
-import { createBin2DData, materializeBin2DData } from "./bin2d.js";
+import {
+  createBin2DData,
+  editBin2DData,
+  materializeBin2DData
+} from "./bin2d.js";
 import { createBoxSummaryData, createBoxOutlierData, materializeBoxSummaryData, materializeBoxOutlierData } from "./box.js";
 
 export function registerDataActions(ProgramClass) {
@@ -51,6 +55,7 @@ export function registerDataActions(ProgramClass) {
   ProgramClass.prototype.createWindowData = createWindowData;
   ProgramClass.prototype.materializeWindowData = materializeWindowData;
   ProgramClass.prototype.createBin2DData = createBin2DData;
+  ProgramClass.prototype.editBin2DData = editBin2DData;
   ProgramClass.prototype.materializeBin2DData = materializeBin2DData;
   ProgramClass.prototype.createBoxSummaryData = createBoxSummaryData;
   ProgramClass.prototype.createBoxOutlierData = createBoxOutlierData;

package/src/actions/data/intervalEdit.js

@@ -0,0 +1,76 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { validateKeys } from "../../core/validation.js";
+import { normalizeIntervalParameters } from "../../grammar/interval.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
+import { findDataset } from "../../selectors/datasets.js";
+
+const STATISTICS_OPTIONS = Object.freeze(["center", "extent", "level"]);
+
+export function planIntervalEdit(program, {
+  owner,
+  data,
+  consumers,
+  statistics,
+  operation
+}) {
+  if (!isPlainObject(statistics)) {
+    throw new TypeError(`${operation} statistics must be a plain object.`);
+  }
+  validateKeys(statistics, STATISTICS_OPTIONS, `${operation} statistics`);
+  if (!STATISTICS_OPTIONS.some(key => Object.hasOwn(statistics, key))) {
+    throw new Error(
+      `${operation} statistics requires center, extent, or level.`
+    );
+  }
+  const previous = findDataset(program, data);
+  const transform = previous?.transform?.length === 1
+    ? previous.transform[0]
+    : undefined;
+  if (transform?.type !== "interval") {
+    throw new Error(
+      `${operation} statistics requires a statistical interval owner; ` +
+      "explicit interval fields cannot be converted by edit."
+    );
+  }
+  const center = Object.hasOwn(statistics, "center")
+    ? statistics.center
+    : transform.center;
+  const extent = Object.hasOwn(statistics, "extent")
+    ? statistics.extent
+    : transform.extent;
+  const raw = { center, extent };
+  if (Object.hasOwn(statistics, "level")) {
+    raw.level = statistics.level;
+  } else if (extent === "ci" && transform.extent === "ci") {
+    raw.level = transform.level;
+  }
+  const parameters = normalizeIntervalParameters(raw);
+  const current = {
+    center: transform.center,
+    extent: transform.extent,
+    ...(transform.level === undefined ? {} : { level: transform.level })
+  };
+  const changed = JSON.stringify(parameters) !== JSON.stringify(current);
+  if (!changed) return { changed, parameters };
+
+  const revision = planDerivedDataRevision(program, {
+    owner,
+    role: "IntervalData",
+    previous: previous.id,
+    consumers
+  });
+  return {
+    changed,
+    parameters,
+    revision,
+    dataArgs: {
+      id: revision.id,
+      source: previous.source,
+      field: transform.field,
+      groupBy: transform.groupBy,
+      ...parameters,
+      as: transform.as
+    }
+  };
+}

package/src/actions/distributions/revision.js

@@ -0,0 +1,326 @@
+import { DEFAULT_TICK_COUNT } from "../guides/tickValues.js";
+import { findLayer } from "../../selectors/layers.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import { resolvePositionScaleDefinition } from "../scales/definitions.js";
+
+const POSITION_CHANNELS = Object.freeze(["x", "y", "x2", "y2"]);
+
+export function resolveDistributionScalePlan(program, {
+  channel,
+  fieldType,
+  requested,
+  fallback,
+  defaults
+}) {
+  const options = requested === undefined
+    ? { id: fallback }
+    : typeof requested === "string"
+      ? { id: requested }
+      : { ...requested, id: requested.id ?? fallback };
+  const existing = findSemanticScale(program, options.id);
+  return {
+    id: options.id,
+    definition: resolvePositionScaleDefinition(
+      program,
+      channel,
+      fieldType,
+      options,
+      defaults
+    ),
+    create: existing === undefined,
+    edit: existing !== undefined && typeof requested === "object" &&
+      Object.keys(requested).some(key => key !== "id")
+      ? options
+      : undefined
+  };
+}
+
+export function setCartesianPosition(program, id, channel, {
+  field,
+  fieldType,
+  scale,
+  title
+}) {
+  let next = program
+    .editSemantic({
+      property: `layer[${id}].encoding.${channel}.field`,
+      value: field
+    })
+    .editSemantic({
+      property: `layer[${id}].encoding.${channel}.fieldType`,
+      value: fieldType
+    })
+    .editSemantic({
+      property: `layer[${id}].encoding.${channel}.scale`,
+      value: scale
+    });
+  if (title !== undefined) {
+    next = next.editSemantic({
+      property: `layer[${id}].encoding.${channel}.title`,
+      value: title
+    });
+  }
+  return next;
+}
+
+export function setCartesianRange(
+  program,
+  id,
+  channel,
+  lower,
+  upper,
+  scale,
+  title
+) {
+  return setCartesianPosition(program, id, channel, {
+    field: lower,
+    fieldType: "quantitative",
+    scale,
+    title
+  })
+    .editSemantic({
+      property: `layer[${id}].encoding.${channel}2.field`,
+      value: upper
+    })
+    .editSemantic({
+      property: `layer[${id}].encoding.${channel}2.fieldType`,
+      value: "quantitative"
+    })
+    .editSemantic({
+      property: `layer[${id}].encoding.${channel}2.scale`,
+      value: scale
+    });
+}
+
+function axisMethods(channel) {
+  const prefix = channel === "x" ? "X" : "Y";
+  return {
+    ticks: `edit${prefix}AxisTicks`,
+    labels: `edit${prefix}AxisLabels`,
+    title: `edit${prefix}AxisTitle`
+  };
+}
+
+function isDiscretePosition(scale) {
+  return ["ordinal", "band", "point"].includes(scale?.type);
+}
+
+function normalizeTickConfig(config, scale) {
+  if (config === undefined) return undefined;
+  if (isDiscretePosition(scale)) {
+    if (config.mode === "count" || config.inferredValues === true) {
+      const next = {
+        ...config,
+        mode: "values",
+        values: scale.domain,
+        inferredValues: true
+      };
+      delete next.count;
+      return next;
+    }
+    return config;
+  }
+  if (config.mode === "values" && config.inferredValues === true) {
+    const next = {
+      ...config,
+      mode: "count",
+      count: DEFAULT_TICK_COUNT,
+      inferredValues: true
+    };
+    delete next.values;
+    return next;
+  }
+  return config;
+}
+
+function outsideConsumer(program, owned, channel, scale) {
+  return program.semanticSpec.layers.some(layer =>
+    !owned.has(layer.id) && layer.encoding?.[channel]?.scale === scale
+  );
+}
+
+export function assertDistributionScaleHandoff(program, {
+  owned,
+  oldXScale,
+  oldYScale,
+  newXScale,
+  newYScale
+}) {
+  const ids = new Set(owned);
+  for (const [channel, previous, next] of [
+    ["x", oldXScale, newXScale],
+    ["y", oldYScale, newYScale]
+  ]) {
+    if (
+      previous !== next &&
+      outsideConsumer(program, ids, channel, previous)
+    ) {
+      throw new Error(
+        `Cannot hand off ${channel} scale "${previous}" while unrelated consumers remain.`
+      );
+    }
+  }
+}
+
+export function clearCartesianPositions(program, id) {
+  const layer = findLayer(program, id);
+  if (layer === undefined) return program;
+  let next = program;
+  for (const channel of POSITION_CHANNELS) {
+    if (layer.encoding?.[channel] === undefined) continue;
+    next = next.editSemantic({
+      property: `layer[${id}].encoding.${channel}`,
+      remove: true
+    });
+  }
+  return next;
+}
+
+function rebindAxis(program, channel, {
+  previousScale,
+  nextScale,
+  previousTitle,
+  nextTitle
+}) {
+  const semantic = program.semanticSpec.guides.axis?.[channel];
+  if (semantic?.scale !== previousScale) return program;
+  let next = program.editSemantic({
+    property: `guide.axis.${channel}.scale`,
+    value: nextScale
+  });
+  if (semantic.title === previousTitle) {
+    next = next.editSemantic({
+      property: `guide.axis.${channel}.title`,
+      value: nextTitle
+    });
+  }
+  const scale = next.resolvedScales[nextScale];
+  const ticks = normalizeTickConfig(
+    next.guideConfigs.axis?.[channel]?.ticks,
+    scale
+  );
+  if (ticks !== undefined) {
+    next = next._withGuideConfig(channel, "ticks", {
+      ...ticks,
+      scale: nextScale
+    });
+  }
+  const labels = next.guideConfigs.axis?.[channel]?.labels;
+  if (labels !== undefined) {
+    const tickConfig = next.guideConfigs.axis[channel].ticks;
+    next = next._withGuideConfig(channel, "labels", {
+      ...labels,
+      scale: nextScale,
+      mode: tickConfig.mode,
+      inferredValues: tickConfig.inferredValues,
+      ...(tickConfig.mode === "values"
+        ? { values: tickConfig.values }
+        : { count: tickConfig.count })
+    });
+    if (tickConfig.mode === "values") {
+      const config = next.guideConfigs.axis[channel].labels;
+      if (Object.hasOwn(config, "count")) {
+        const { count: _count, ...withoutCount } = config;
+        next = next._withGuideConfig(channel, "labels", withoutCount);
+      }
+    } else {
+      const config = next.guideConfigs.axis[channel].labels;
+      if (Object.hasOwn(config, "values")) {
+        const { values: _values, ...withoutValues } = config;
+        next = next._withGuideConfig(channel, "labels", withoutValues);
+      }
+    }
+  }
+  const title = next.guideConfigs.axis?.[channel]?.title;
+  if (title !== undefined) {
+    next = next._withGuideConfig(channel, "title", {
+      ...title,
+      scale: nextScale
+    });
+  }
+  const methods = axisMethods(channel);
+  if (ticks !== undefined) next = next[methods.ticks]();
+  if (labels !== undefined) next = next[methods.labels]();
+  if (title !== undefined) next = next[methods.title]();
+  return next;
+}
+
+function gridDirection(channel) {
+  return channel === "x" ? "vertical" : "horizontal";
+}
+
+function rebindGrid(program, {
+  previousMeasureChannel,
+  nextMeasureChannel,
+  previousScale,
+  nextScale
+}) {
+  const previousDirection = gridDirection(previousMeasureChannel);
+  const nextDirection = gridDirection(nextMeasureChannel);
+  const stored = program.guideConfigs.grid?.[previousDirection];
+  const semantic = program.semanticSpec.guides.grid?.[previousDirection];
+  if (stored === undefined || semantic?.scale !== previousScale) return program;
+  if (previousDirection === nextDirection) {
+    return program
+      .editSemantic({
+        property: `guide.grid.${previousDirection}.scale`,
+        value: nextScale
+      })
+      ._withGridConfig(previousDirection, {
+        ...stored,
+        scale: nextScale
+      })[`rematerialize${previousDirection === "horizontal" ? "Horizontal" : "Vertical"}Grid`]();
+  }
+  if (program.semanticSpec.guides.grid?.[nextDirection] !== undefined) {
+    throw new Error(
+      `Cannot hand off the ${previousDirection} grid because a ${nextDirection} grid already exists.`
+    );
+  }
+  const options = {
+    scale: nextScale,
+    coordinate: stored.coordinate,
+    color: stored.color,
+    lineWidth: stored.lineWidth,
+    strokeDash: stored.strokeDash,
+    ...(stored.inferredValues === true
+      ? {}
+      : stored.mode === "values"
+        ? { values: stored.values }
+        : { count: stored.count })
+  };
+  return program
+    .removeGrid({ [previousDirection]: true })
+    [`create${nextDirection === "horizontal" ? "Horizontal" : "Vertical"}Grid`](options);
+}
+
+export function rebindDistributionGuides(program, {
+  oldXScale,
+  oldYScale,
+  newXScale,
+  newYScale,
+  oldXTitle,
+  oldYTitle,
+  newXTitle,
+  newYTitle,
+  oldMeasureChannel,
+  newMeasureChannel
+}) {
+  let next = rebindAxis(program, "x", {
+    previousScale: oldXScale,
+    nextScale: newXScale,
+    previousTitle: oldXTitle,
+    nextTitle: newXTitle
+  });
+  next = rebindAxis(next, "y", {
+    previousScale: oldYScale,
+    nextScale: newYScale,
+    previousTitle: oldYTitle,
+    nextTitle: newYTitle
+  });
+  return rebindGrid(next, {
+    previousMeasureChannel: oldMeasureChannel,
+    nextMeasureChannel: newMeasureChannel,
+    previousScale: oldMeasureChannel === "x" ? oldXScale : oldYScale,
+    nextScale: newMeasureChannel === "x" ? newXScale : newYScale
+  });
+}