ggaction 0.0.4 → 0.0.6

package/src/actions/composition/actions.js

@@ -16,7 +16,9 @@ import { materializeFacetGraphics } from "../../materialization/facets.js";
 const CONCAT_OPTIONS = Object.freeze([
   "id", "programs", "gap", "align", "padding"
 ]);
-const LAYOUT_EDIT_OPTIONS = Object.freeze(["gap", "align", "padding"]);
+const LAYOUT_EDIT_OPTIONS = Object.freeze([
+  "columns", "gap", "align", "padding"
+]);
 const REPLACEMENT_OPTIONS = Object.freeze(["target", "program"]);
 
 function normalizeChildEntry(entry, index) {
@@ -149,7 +151,7 @@ export const vconcatAction = concatAction("vertical", "vconcat");
 const editCompositionLayout = action(
   {
     op: "editCompositionLayout",
-    description: "Edit composition spacing and alignment.",
+    description: "Edit composition layout.",
     scope: "composition"
   },
   function (args = {}) {
@@ -164,7 +166,9 @@ const editCompositionLayout = action(
           ...childDescriptor({ id, program: this.children[id] }),
           value: current.facet.values[index]
         })),
-        columns: current.columns,
+        columns: Object.hasOwn(args, "columns")
+          ? args.columns
+          : current.columns,
         gap: Object.hasOwn(args, "gap") ? args.gap : current.gap,
         align: Object.hasOwn(args, "align") ? args.align : current.align,
         padding: Object.hasOwn(args, "padding")
@@ -176,12 +180,18 @@ const editCompositionLayout = action(
         children: this.children,
         compositionSpec: {
           ...current,
+          columns: layout.columns,
           gap: layout.gap,
           align: layout.align,
           padding: layout.padding
         }
       }).materializeComposition();
     }
+    if (Object.hasOwn(args, "columns")) {
+      throw new Error(
+        "editCompositionLayout columns is available only on a facet composition."
+      );
+    }
     const padding = Object.hasOwn(args, "padding")
       ? normalizeCompositionPadding(args.padding, current.padding)
       : current.padding;

package/src/actions/coordinates/parallel.js

@@ -0,0 +1,50 @@
+import { validateUserId } from "../../core/identifiers.js";
+import { findCoordinate } from "../../selectors/coordinates.js";
+
+export function resolveParallelCoordinate(program, {
+  requested,
+  layer,
+  operation,
+  useCurrent = false
+}) {
+  const explicit = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Parallel coordinate id");
+  if (layer?.coordinate !== undefined) {
+    if (explicit !== undefined && explicit !== layer.coordinate) {
+      throw new Error(
+        `Layer "${layer.id}" already uses coordinate "${layer.coordinate}".`
+      );
+    }
+    const coordinate = findCoordinate(program, layer.coordinate);
+    if (coordinate?.type !== "parallel") {
+      throw new Error(`Coordinate "${layer.coordinate}" is not Parallel.`);
+    }
+    return { id: layer.coordinate, create: false };
+  }
+  if (explicit !== undefined) {
+    const coordinate = findCoordinate(program, explicit);
+    if (coordinate !== undefined && coordinate.type !== "parallel") {
+      throw new Error(`Coordinate "${explicit}" is not Parallel.`);
+    }
+    return { id: explicit, create: coordinate === undefined };
+  }
+  const current = useCurrent ? program.context.currentCoordinate : undefined;
+  if (current !== undefined && findCoordinate(program, current)?.type === "parallel") {
+    return { id: current, create: false };
+  }
+  const compatible = program.semanticSpec.coordinates.filter(
+    coordinate => coordinate.type === "parallel"
+  );
+  if (compatible.length > 1) {
+    throw new Error(
+      `${operation} requires coordinate when multiple Parallel coordinates are available.`
+    );
+  }
+  if (compatible.length === 1) return { id: compatible[0].id, create: false };
+  const conflict = findCoordinate(program, "parallel");
+  if (conflict !== undefined) {
+    throw new Error('Coordinate "parallel" already exists with a different type.');
+  }
+  return { id: "parallel", create: true };
+}

package/src/actions/data/bin2d.js

@@ -0,0 +1,260 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveBin2DRows,
+  normalizeBin2DTransform,
+  requestedBin2DTransform
+} from "../../grammar/bin2d.js";
+import { applyLayerDataRematerialization } from
+  "../../materialization/dependencies.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
+import {
+  findDataset,
+  findDatasetConsumer
+} from "../../selectors/datasets.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.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 (
+    current?.source === undefined ||
+    current.transform?.length !== 1 ||
+    current.transform[0].type !== "bin2d"
+  ) {
+    throw new Error(`2D bin owner "${id}" has no current derived dataset.`);
+  }
+  return current;
+}
+
+function directLayerConsumers(program, data) {
+  return program.semanticSpec.layers
+    .filter(layer => layer.data === data)
+    .map(layer => layer.id);
+}
+
+function rejectDerivedConsumers(program, data) {
+  const dependent = findDatasetConsumer(program, data);
+  if (dependent !== undefined) {
+    throw new Error(
+      `Cannot replace 2D bin dataset "${data}" while derived dataset ` +
+      `"${dependent.id}" depends on it.`
+    );
+  }
+}
+
+function preflight(program, sourceId, transform) {
+  const source = findDataset(program, sourceId);
+  if (source?.values === undefined) {
+    throw new Error(`Source dataset "${sourceId}" has no values.`);
+  }
+  deriveBin2DRows(source.values, transform);
+}
+
+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.`
+    );
+  }
+}
+
+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 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
+      });
+  }
+);
+
+export const createBin2DData = action(
+  {
+    op: "createBin2DData",
+    description: "Create or revise immutable rectangular 2D-bin values."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createBin2DData");
+    const owner = validateUserId(args.id, "2D bin dataset id");
+    const config = ownerConfig(this, owner);
+    const previous = config === undefined
+      ? undefined
+      : requireCurrentBin2D(this, owner, config);
+    const source = validateUserId(
+      args.source ?? previous?.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    const transform = normalizeBin2DTransform({ ...args, id: owner });
+    preflight(this, source, transform);
+
+    if (previous === undefined) {
+      return this
+        .createDerivedData({ id: owner, source, transform: [transform] })
+        .materializeBin2DData({ id: owner })
+        ._withMaterializationConfig(
+          ["data", "bin2d", owner],
+          { current: owner }
+        );
+    }
+
+    return applyBin2DRevision(this, {
+      owner,
+      previous,
+      source,
+      transform
+    });
+  }
+);
+
+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.");
+    }
+    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/density.js

@@ -8,6 +8,23 @@ const OPTIONS = Object.freeze([
   "id", "source", "field", "groupBy", "bandwidth", "extent", "steps",
   "kernel", "normalization", "as"
 ]);
+const CATEGORICAL_OPTIONS = Object.freeze([...OPTIONS, "placement"]);
+
+function densityTransform(args, placement) {
+  return {
+    type: "density",
+    field: args.field,
+    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+    bandwidth: args.bandwidth ?? "auto",
+    extent: args.extent ?? "auto",
+    steps: args.steps ?? 100,
+    kernel: args.kernel ?? "gaussian",
+    normalization: args.normalization ?? "unit",
+    as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
+    resolve: "shared",
+    ...(placement === undefined ? {} : { placement })
+  };
+}
 
 export const materializeDensityData = action(
   { op: "materializeDensityData", description: "Materialize one grouped kernel-density dataset." },
@@ -26,7 +43,10 @@ export const materializeDensityData = action(
           ...transform,
           resolved: {
             bandwidth: result.bandwidth,
-            extent: result.extent
+            extent: result.extent,
+            ...(result.splitDomain === undefined
+              ? {}
+              : { splitDomain: result.splitDomain })
           }
         }]
       })
@@ -49,20 +69,41 @@ export const createDensityData = action(
     if (typeof args.field !== "string" || args.field.length === 0) {
       throw new TypeError("createDensityData requires a non-empty field string.");
     }
-    const transform = {
-      type: "density",
-      field: args.field,
-      ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
-      bandwidth: args.bandwidth ?? "auto",
-      extent: args.extent ?? "auto",
-      steps: args.steps ?? 100,
-      kernel: args.kernel ?? "gaussian",
-      normalization: args.normalization ?? "unit",
-      as: args.as ?? [`${args.field}_value`, `${args.field}_density`],
-      resolve: "shared"
-    };
+    const transform = densityTransform(args);
     return this
       .createDerivedData({ id, source, transform: [transform] })
       .materializeDensityData({ id });
   }
 );
+
+export const createCategoricalDensityData = action(
+  {
+    op: "createCategoricalDensityData",
+    description: "Create category-placed kernel-density values."
+  },
+  function (args = {}) {
+    validateKeys(args, CATEGORICAL_OPTIONS, "createCategoricalDensityData");
+    const id = validateUserId(args.id, "Density dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Source dataset id"
+    );
+    if (typeof args.field !== "string" || args.field.length === 0) {
+      throw new TypeError(
+        "createCategoricalDensityData requires a non-empty field string."
+      );
+    }
+    if (args.placement?.type !== "category") {
+      throw new Error(
+        "createCategoricalDensityData requires normalized category placement."
+      );
+    }
+    return this
+      .createDerivedData({
+        id,
+        source,
+        transform: [densityTransform(args, args.placement)]
+      })
+      .materializeDensityData({ id });
+  }
+);

package/src/actions/data/derived.js

@@ -3,9 +3,11 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { hasDataset } from "../../selectors/index.js";
 import { findDataset } from "../../selectors/datasets.js";
+import { requireLayer } from "../../selectors/layers.js";
 
 const OPTIONS = Object.freeze(["id", "source", "transform"]);
 const RELEASE_OPTIONS = Object.freeze(["id"]);
+const REBIND_OPTIONS = Object.freeze(["id", "data"]);
 
 export const createDerivedData = action(
   { op: "createDerivedData", description: "Create an immutable derived dataset definition." },
@@ -50,3 +52,23 @@ export const releaseDerivedData = action(
         });
   }
 );
+
+export const rebindLayerData = action(
+  {
+    op: "rebindLayerData",
+    description: "Rebind one semantic layer to an existing dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, REBIND_OPTIONS, "rebindLayerData");
+    const id = validateUserId(args.id, "Layer id");
+    const data = validateUserId(args.data, "Layer dataset id");
+    requireLayer(this, id);
+    if (!hasDataset(this, data)) {
+      throw new Error(`Layer dataset "${data}" does not exist.`);
+    }
+    return this.editSemantic({
+      property: `layer[${id}].data`,
+      value: data
+    });
+  }
+);

package/src/actions/data/filter.js

@@ -125,6 +125,11 @@ export const filterMarks = action(
         candidate.data !== undefined &&
         findSelectionPolicy(candidate.mark?.type) !== undefined
     });
+    if (this.markConfigs[layer.id]?.itemFilterable === false) {
+      throw new Error(
+        `filterMarks does not support composite mark "${layer.id}"; filter its source dataset first.`
+      );
+    }
     const derivedId = `${layer.id}FilteredData`;
     if (hasDataset(this, derivedId)) {
       throw new Error(`Dataset "${derivedId}" already exists.`);

package/src/actions/data/gradientProfile.js

@@ -0,0 +1,65 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveGradientProfiles,
+  normalizeGradientProfileTransform
+} from "../../grammar/gradientProfile.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "category", "field", "bandwidth", "extent", "steps",
+  "kernel", "normalization", "center", "as"
+]);
+
+export const materializeGradientProfileData = action(
+  {
+    op: "materializeGradientProfileData",
+    description: "Materialize one categorical density-profile dataset."
+  },
+  function (args = {}) {
+    validateKeys(
+      args,
+      MATERIALIZE_OPTIONS,
+      "materializeGradientProfileData"
+    );
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "gradientProfile"
+    );
+    const result = deriveGradientProfiles(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{
+          ...transform,
+          resolved: {
+            bandwidth: result.bandwidth,
+            extent: result.extent,
+            intensityDomain: result.intensityDomain
+          }
+        }]
+      })
+      .editSemantic({ property: `dataset[${id}].values`, value: result.values });
+  }
+);
+
+export const createGradientProfileData = action(
+  {
+    op: "createGradientProfileData",
+    description: "Create one immutable categorical density-profile dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createGradientProfileData");
+    const id = validateUserId(args.id, "Gradient profile dataset id");
+    const source = validateUserId(
+      args.source ?? this.context.currentData,
+      "Gradient profile source dataset id"
+    );
+    const transform = normalizeGradientProfileTransform(args);
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeGradientProfileData({ id });
+  }
+);

package/src/actions/data/horizon.js

@@ -0,0 +1,71 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import {
+  deriveHorizon,
+  validateHorizonTransform
+} from "../../grammar/horizon.js";
+import { MATERIALIZE_OPTIONS, requireDerivedDataset } from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "source", "x", "y", "groupBy", "bands", "baseline", "extent",
+  "resolve", "missing", "overflow", "palette", "as"
+]);
+
+function requestedTransform(args) {
+  return validateHorizonTransform({
+    type: "horizon",
+    x: args.x,
+    y: args.y,
+    ...(args.groupBy === undefined ? {} : { groupBy: args.groupBy }),
+    bands: args.bands ?? 3,
+    baseline: args.baseline ?? 0,
+    extent: args.extent ?? "auto",
+    resolve: args.resolve ?? "shared",
+    missing: args.missing ?? "break",
+    overflow: args.overflow ?? "clip",
+    palette: args.palette ?? {},
+    as: args.as
+  });
+}
+
+export const materializeHorizonData = action(
+  {
+    op: "materializeHorizonData",
+    description: "Materialize one immutable Horizon band dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, MATERIALIZE_OPTIONS, "materializeHorizonData");
+    const { id, source, transform } = requireDerivedDataset(
+      this,
+      args.id,
+      "horizon"
+    );
+    const result = deriveHorizon(source.values, transform);
+    return this
+      .editSemantic({
+        property: `dataset[${id}].transform`,
+        value: [{ ...result.transform, resolved: result.resolved }]
+      })
+      .editSemantic({
+        property: `dataset[${id}].values`,
+        value: result.values
+      });
+  }
+);
+
+export const createHorizonData = action(
+  {
+    op: "createHorizonData",
+    description: "Create one immutable Horizon band dataset."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "createHorizonData");
+    const id = validateUserId(args.id, "Horizon dataset id");
+    const source = validateUserId(args.source, "Horizon source dataset id");
+    const transform = requestedTransform(args);
+    return this
+      .createDerivedData({ id, source, transform: [transform] })
+      .materializeHorizonData({ id });
+  }
+);