ggaction 0.0.4 → 0.0.5

package/src/actions/encodings/density.js

@@ -1,6 +1,5 @@
 import { action } from "../../core/action.js";
 import { validateUserId } from "../../core/identifiers.js";
-import { isPlainObject } from "../../core/immutable.js";
 import {
   findDataset,
   findLayer,
@@ -11,15 +10,27 @@ import { applyMaterializationPlan } from
   "../../materialization/dependencies.js";
 import { planDensityRematerialization } from
   "../../materialization/density.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
 import { validateOptions } from "./shared.js";
+import { normalizeDensityPlacement } from "../../grammar/density.js";
+import { scaleEditPatch } from "../scales/patch.js";
+import {
+  requireDensityField,
+  resolveDensityCategoryScaleOptions,
+  resolveDensityPositionDefinition,
+  resolveDensityScaleOptions,
+  resolveDensityTransitionScaleDefinitions
+} from "./density/resolve.js";
 
 const OPTIONS = Object.freeze([
   "field", "target", "source", "groupBy", "bandwidth", "extent", "steps",
   "kernel", "normalization", "as", "densityChannel", "coordinate",
-  "valueScale", "densityScale"
+  "valueScale", "densityScale", "placement"
 ]);
 const EDIT_OPTIONS = Object.freeze([
-  "target", "bandwidth", "extent", "steps", "kernel", "normalization"
+  "target", "bandwidth", "extent", "steps", "kernel", "normalization",
+  "placement"
 ]);
 const EDITABLE = Object.freeze(EDIT_OPTIONS.filter(option => option !== "target"));
 
@@ -42,32 +53,35 @@ function findArea(program, requested) {
   throw new Error("encodeDensity target is ambiguous; provide target.");
 }
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
-
-function scaleOptions(value, defaults, label) {
-  if (value !== undefined && !isPlainObject(value)) {
-    throw new TypeError(`${label} must be a plain object.`);
+function applyDensityPosition(program, layerId, definition, groupBy) {
+  const withCoordinate = value => ({
+    target: layerId,
+    field: value.field,
+    fieldType: value.fieldType,
+    scale: value.scale,
+    ...(value.coordinate === undefined ? {} : { coordinate: value.coordinate })
+  });
+  let next = program
+    .encodeX(withCoordinate(definition.x))
+    .encodeY(withCoordinate(definition.y));
+  if (groupBy !== undefined) {
+    next = next.encodeGroup({ target: layerId, field: groupBy });
   }
-  return { ...defaults, ...(value ?? {}) };
+  return next;
 }
 
 const encodeDensity = action(
   {
     op: "encodeDensity",
-    description: "Derive and encode a baseline-oriented kernel density area."
+    description: "Derive and encode a baseline or categorical kernel-density area."
   },
   function (args = {}) {
     validateOptions(args, OPTIONS, "encodeDensity");
     const layer = findArea(this, args.target);
-    const field = requireField(args.field, "Density field");
+    const field = requireDensityField(args.field, "Density field");
     const groupBy = args.groupBy === undefined
       ? undefined
-      : requireField(args.groupBy, "Density groupBy");
+      : requireDensityField(args.groupBy, "Density groupBy");
     const source = validateUserId(
       args.source ?? layer.data,
       "Density source dataset id"
@@ -82,7 +96,8 @@ const encodeDensity = action(
         `Density area target "${layer.id}" already has positional or group encodings.`
       );
     }
-    const densityChannel = args.densityChannel ?? "y";
+    const categoryPlacement = args.placement?.type === "category";
+    const densityChannel = args.densityChannel ?? (categoryPlacement ? "x" : "y");
     if (!["x", "y"].includes(densityChannel)) {
       throw new Error(`Unsupported densityChannel "${densityChannel}".`);
     }
@@ -94,56 +109,67 @@ const encodeDensity = action(
     if (hasDataset(this, derivedId)) {
       throw new Error(`Dataset "${derivedId}" already exists.`);
     }
-    const valueScale = scaleOptions(
+    const valueScale = resolveDensityScaleOptions(
       args.valueScale,
       { nice: false, zero: false },
       "Density valueScale"
     );
-    const densityScale = scaleOptions(
-      args.densityScale,
-      { nice: true, zero: true },
-      "Density densityScale"
-    );
-    const xIsDensity = densityChannel === "x";
-    const xField = output[xIsDensity ? 1 : 0];
-    const yField = output[xIsDensity ? 0 : 1];
-    const xScale = xIsDensity ? densityScale : valueScale;
-    const yScale = xIsDensity ? valueScale : densityScale;
+    const placement = args.placement === undefined
+      ? undefined
+      : normalizeDensityPlacement(args.placement, {
+          densityChannel,
+          groupBy,
+          categoryField: groupBy ?? `${layer.id}DensityCategory`
+        });
+    if (placement !== undefined && args.densityScale !== undefined) {
+      throw new Error(
+        "Density category placement cannot be combined with densityScale."
+      );
+    }
+    const densityScale = placement === undefined
+      ? resolveDensityScaleOptions(
+          args.densityScale,
+          { nice: true, zero: true },
+          "Density densityScale"
+        )
+      : undefined;
+    const placementScale = placement === undefined
+      ? undefined
+      : resolveDensityCategoryScaleOptions(args.placement.scale);
 
-    let next = this
-      .createDensityData({
-        id: derivedId,
-        source,
-        field,
-        ...(groupBy === undefined ? {} : { groupBy }),
-        ...(args.bandwidth === undefined ? {} : { bandwidth: args.bandwidth }),
-        ...(args.extent === undefined ? {} : { extent: args.extent }),
-        ...(args.steps === undefined ? {} : { steps: args.steps }),
-        ...(args.kernel === undefined ? {} : { kernel: args.kernel }),
-        ...(args.normalization === undefined
-          ? {}
-          : { normalization: args.normalization }),
-        ...(args.as === undefined ? {} : { as: args.as })
-      })
+    const dataArgs = {
+      id: derivedId,
+      source,
+      field,
+      ...(groupBy === undefined ? {} : { groupBy }),
+      ...(args.bandwidth === undefined ? {} : { bandwidth: args.bandwidth }),
+      ...(args.extent === undefined ? {} : { extent: args.extent }),
+      ...(args.steps === undefined ? {} : { steps: args.steps }),
+      ...(args.kernel === undefined ? {} : { kernel: args.kernel }),
+      ...(args.normalization === undefined
+        ? {}
+        : { normalization: args.normalization }),
+      ...(args.as === undefined ? {} : { as: args.as }),
+      ...(placement === undefined ? {} : { placement })
+    };
+    let next = placement === undefined
+      ? this.createDensityData(dataArgs)
+      : this.createCategoricalDensityData(dataArgs);
+    next = next
       .editSemantic({
         property: `layer[${layer.id}].data`,
         value: derivedId
-      })
-      .encodeX({
-        target: layer.id,
-        field: xField,
-        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
-        scale: xScale
-      })
-      .encodeY({
-        target: layer.id,
-        field: yField,
-        ...(args.coordinate === undefined ? {} : { coordinate: args.coordinate }),
-        scale: yScale
       });
-    if (groupBy !== undefined) {
-      next = next.encodeGroup({ target: layer.id, field: groupBy });
-    }
+    next = applyDensityPosition(next, layer.id, resolveDensityPositionDefinition({
+      layer: { densityChannel },
+      output,
+      groupBy,
+      placement,
+      coordinate: args.coordinate,
+      valueScale,
+      densityScale,
+      placementScale
+    }), groupBy);
     return next.rematerializeAreaMark({ id: layer.id });
   }
 );
@@ -164,14 +190,6 @@ function findDensityArea(program, requested) {
   });
 }
 
-function nextDensityRevisionId(program, target) {
-  let revision = 1;
-  while (hasDataset(program, `${target}DensityDataRevision${revision}`)) {
-    revision += 1;
-  }
-  return `${target}DensityDataRevision${revision}`;
-}
-
 const editDensity = action(
   {
     op: "editDensity",
@@ -185,31 +203,118 @@ const editDensity = action(
     const layer = findDensityArea(this, args.target);
     const previous = findDataset(this, layer.data);
     const transform = previous.transform[0];
-    const revisionId = nextDensityRevisionId(this, layer.id);
+    const requestedPlacement = Object.hasOwn(args, "placement")
+      ? normalizeDensityPlacement(args.placement, {
+          densityChannel: transform.placement?.channel ?? "x",
+          groupBy: transform.groupBy,
+          categoryField: transform.groupBy ??
+            transform.placement?.categoryField ??
+            `${layer.id}DensityCategory`
+        })
+      : transform.placement;
+    const colorField = layer.encoding?.color?.field;
+    const availableColorFields = [
+      transform.groupBy,
+      requestedPlacement?.split?.field
+    ].filter(Boolean);
+    if (colorField !== undefined && !availableColorFields.includes(colorField)) {
+      throw new Error(
+        `editDensity placement would remove color field "${colorField}" from the density series.`
+      );
+    }
+    const revision = planDerivedDataRevision(this, {
+      owner: layer.id,
+      role: "DensityData",
+      previous: previous.id,
+      consumers: [layer.id]
+    });
     const option = property => Object.hasOwn(args, property)
       ? args[property]
       : transform[property];
 
-    let next = this
-      .createDensityData({
-        id: revisionId,
-        source: previous.source,
-        field: transform.field,
-        ...(transform.groupBy === undefined
-          ? {}
-          : { groupBy: transform.groupBy }),
-        bandwidth: option("bandwidth"),
-        extent: option("extent"),
-        steps: option("steps"),
-        kernel: option("kernel") ?? "gaussian",
-        normalization: option("normalization") ?? "unit",
-        as: transform.as
-      })
-      .editSemantic({
-        property: `layer[${layer.id}].data`,
-        value: revisionId
-      })
-      .releaseDerivedData({ id: previous.id });
+    const dataArgs = {
+      id: revision.id,
+      source: previous.source,
+      field: transform.field,
+      ...(transform.groupBy === undefined
+        ? {}
+        : { groupBy: transform.groupBy }),
+      bandwidth: option("bandwidth"),
+      extent: option("extent"),
+      steps: option("steps"),
+      kernel: option("kernel") ?? "gaussian",
+      normalization: option("normalization") ?? "unit",
+      as: transform.as,
+      ...(requestedPlacement === undefined
+        ? {}
+        : { placement: requestedPlacement })
+    };
+    let next = requestedPlacement === undefined
+      ? this.createDensityData(dataArgs)
+      : this.createCategoricalDensityData(dataArgs);
+    next = next.rebindLayerData(revision.rebinds[0])
+      .releaseDerivedData(revision.release);
+
+    const changesPlacementMode = Object.hasOwn(args, "placement") &&
+      (transform.placement === undefined) !== (requestedPlacement === undefined);
+    if (changesPlacementMode) {
+      const xScaleId = layer.encoding?.x?.scale;
+      const yScaleId = layer.encoding?.y?.scale;
+      const scaleDefinitions = resolveDensityTransitionScaleDefinitions(
+        this,
+        layer,
+        transform,
+        requestedPlacement,
+        args.placement
+      );
+      next = next
+        .editSemantic({ property: `layer[${layer.id}].encoding.x`, remove: true })
+        .editSemantic({ property: `layer[${layer.id}].encoding.y`, remove: true });
+      next = next
+        .editScale(scaleEditPatch(xScaleId, scaleDefinitions.x))
+        .editScale(scaleEditPatch(yScaleId, scaleDefinitions.y));
+      const densityChannel = requestedPlacement?.channel ?? (
+        layer.encoding.x.field === transform.as[1] ? "x" : "y"
+      );
+      const definition = resolveDensityPositionDefinition({
+        layer: { densityChannel },
+        output: transform.as,
+        groupBy: transform.groupBy,
+        placement: requestedPlacement,
+        coordinate: layer.coordinate,
+        valueScale: {
+          id: requestedPlacement?.channel === "x" ? yScaleId : xScaleId,
+          ...scaleDefinitions[requestedPlacement?.channel === "x" ? "y" : "x"]
+        },
+        densityScale: requestedPlacement === undefined
+          ? {
+              id: densityChannel === "x" ? xScaleId : yScaleId,
+              ...scaleDefinitions[densityChannel]
+            }
+          : undefined,
+        placementScale: requestedPlacement === undefined
+          ? undefined
+          : {
+              id: requestedPlacement.channel === "x" ? xScaleId : yScaleId,
+              ...scaleDefinitions[requestedPlacement.channel]
+            }
+      });
+      next = applyDensityPosition(next, layer.id, definition);
+    } else if (
+      requestedPlacement !== undefined &&
+      Object.hasOwn(args.placement ?? {}, "scale")
+    ) {
+      const channel = requestedPlacement.channel;
+      const scaleId = layer.encoding[channel].scale;
+      const requestedScale = resolveDensityCategoryScaleOptions(
+        args.placement.scale,
+        scaleId
+      );
+      if (requestedScale.id !== scaleId) {
+        throw new Error("editDensity placement scale cannot change its id.");
+      }
+      next = next.editScale(scaleEditPatch(scaleId, requestedScale));
+    }
 
     next = applyMaterializationPlan(
       next,

package/src/actions/encodings/horizon/resolve.js

@@ -0,0 +1,283 @@
+import { validateUserId } from "../../../core/identifiers.js";
+import { isPlainObject } from "../../../core/immutable.js";
+import { validateOptionObject } from "../../../core/validation.js";
+import { resolvePalette } from "../../../grammar/palettes.js";
+import {
+  normalizeTemporalValue,
+  readNominalField
+} from "../../../grammar/scales/index.js";
+import {
+  findDataset,
+  findSemanticScale,
+  hasDataset,
+  resolveEligibleLayer
+} from "../../../selectors/index.js";
+
+export function findHorizonArea(program, requested) {
+  const target = requested === undefined
+    ? undefined
+    : validateUserId(requested, "Horizon target id");
+  return resolveEligibleLayer(program, {
+    target,
+    label: "Horizon area",
+    predicate: layer => layer.mark?.type === "area"
+  });
+}
+
+export function resolveHorizonSource(program, layer, requested) {
+  const id = validateUserId(
+    requested ?? layer.data ?? program.context.currentData,
+    "Horizon source dataset id"
+  );
+  if (!hasDataset(program, id)) {
+    throw new Error(`Unknown Horizon source dataset "${id}".`);
+  }
+  return findDataset(program, id);
+}
+
+function fieldOption(value, role) {
+  if (typeof value === "string") return { field: value };
+  if (!isPlainObject(value)) {
+    throw new TypeError(`Horizon ${role} must be a field string or plain object.`);
+  }
+  validateOptionObject(
+    value,
+    ["field", "fieldType", "scale"],
+    `Horizon ${role}`
+  );
+  return value;
+}
+
+function inferredFieldType(rows, field, role) {
+  if (role === "y") {
+    const valid = rows.filter(row => Number.isFinite(row?.[field]));
+    if (valid.length === 0) {
+      throw new TypeError(`Horizon y field "${field}" requires a finite value.`);
+    }
+    return "quantitative";
+  }
+  if (rows.every(row => Number.isFinite(row?.[field]))) return "quantitative";
+  for (const [index, row] of rows.entries()) {
+    normalizeTemporalValue(row?.[field], field, index);
+  }
+  return "temporal";
+}
+
+function compatibleEncoding(encoding, role) {
+  return encoding?.field !== undefined && (
+    role === "x"
+      ? ["quantitative", "temporal"].includes(encoding.fieldType)
+      : encoding.fieldType === "quantitative"
+  );
+}
+
+function uniqueStoredEncoding(program, dataset, role) {
+  const candidates = program.semanticSpec.layers
+    .filter(layer => layer.data === dataset.id)
+    .map(layer => layer.encoding?.[role])
+    .filter(encoding => compatibleEncoding(encoding, role));
+  const unique = new Map(candidates.map(encoding => [
+    JSON.stringify([
+      encoding.field,
+      encoding.fieldType,
+      encoding.scale,
+      encoding.title
+    ]),
+    encoding
+  ]));
+  if (unique.size > 1) {
+    throw new Error(`Horizon ${role} inference is ambiguous; provide ${role}.`);
+  }
+  return [...unique.values()][0];
+}
+
+export function resolveHorizonField(program, layer, dataset, requested, role) {
+  const existing = compatibleEncoding(layer.encoding?.[role], role)
+    ? layer.encoding[role]
+    : undefined;
+  if (requested === undefined) {
+    const inferred = existing ?? uniqueStoredEncoding(program, dataset, role);
+    if (inferred === undefined) {
+      throw new Error(`encodeHorizon requires ${role} or one inferable ${role} encoding.`);
+    }
+    return {
+      field: inferred.field,
+      fieldType: inferred.fieldType,
+      ...(role === "x" && inferred.scale !== undefined
+        ? { scale: { id: inferred.scale } }
+        : {}),
+      ...(inferred.title === undefined ? {} : { title: inferred.title })
+    };
+  }
+  const option = fieldOption(requested, role);
+  if (typeof option.field !== "string" || option.field.length === 0) {
+    throw new TypeError(`Horizon ${role} field must be a non-empty string.`);
+  }
+  const matching = existing?.field === option.field ? existing : undefined;
+  if (option.scale !== undefined && !isPlainObject(option.scale)) {
+    throw new TypeError(`Horizon ${role} scale must be a plain object.`);
+  }
+  const fieldType = option.fieldType ?? matching?.fieldType ??
+    inferredFieldType(dataset.values, option.field, role);
+  if (
+    (role === "x" && !["quantitative", "temporal"].includes(fieldType)) ||
+    (role === "y" && fieldType !== "quantitative")
+  ) {
+    throw new Error(
+      `Horizon ${role} fieldType must be ${role === "x" ? "quantitative or temporal" : "quantitative"}.`
+    );
+  }
+  return {
+    field: option.field,
+    fieldType,
+    ...(option.scale !== undefined
+      ? { scale: option.scale }
+      : role === "x" && matching?.scale !== undefined
+        ? { scale: { id: matching.scale } }
+        : {}),
+    ...(matching?.title === undefined ? {} : { title: matching.title })
+  };
+}
+
+export function resolveHorizonGroupBy(layer, dataset, requested) {
+  if (requested === false) {
+    throw new Error("encodeHorizon groupBy must be a field string when provided.");
+  }
+  const value = requested ?? layer.encoding?.group?.field;
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("Horizon groupBy must be a non-empty string.");
+  }
+  readNominalField(dataset.values, value);
+  return value;
+}
+
+export function horizonOutputFields(target) {
+  const prefix = `${target}Horizon`;
+  return {
+    x: `${prefix}X`, lower: `${prefix}Lower`, upper: `${prefix}Upper`,
+    group: `${prefix}Group`, color: `${prefix}Color`, sign: `${prefix}Sign`,
+    band: `${prefix}Band`, segment: `${prefix}Segment`
+  };
+}
+
+export function resolveHorizonPaletteColors(transform) {
+  const domain = [];
+  const range = [];
+  for (const sign of ["negative", "positive"]) {
+    const palette = transform.palette[sign];
+    const dense = palette.count === undefined && transform.bands > 1
+      ? resolvePalette({ ...palette, count: transform.bands * 2 }, transform.bands * 2)
+      : resolvePalette(palette, transform.bands);
+    const colors = palette.count === undefined && transform.bands > 1
+      ? Array.from({ length: transform.bands }, (_, index) =>
+          index === transform.bands - 1 ? dense.at(-1) : dense[index * 2])
+      : dense;
+    for (let band = 0; band < transform.bands; band += 1) {
+      domain.push(`${sign}:${band}`);
+      range.push(colors[band]);
+    }
+  }
+  return { domain, range };
+}
+
+export function resolveFoldedHorizonScaleOptions(target, requested) {
+  if (requested !== undefined && !isPlainObject(requested)) {
+    throw new TypeError("Horizon y scale must be a plain object.");
+  }
+  const options = requested ?? {};
+  if (
+    options.domain !== undefined &&
+    (!Array.isArray(options.domain) ||
+      options.domain.length !== 2 ||
+      options.domain[0] !== 0 ||
+      options.domain[1] !== 1)
+  ) {
+    throw new Error("Horizon y scale domain must be [0, 1].");
+  }
+  if (options.type !== undefined && options.type !== "linear") {
+    throw new Error('Horizon y scale type must be "linear".');
+  }
+  return {
+    ...options,
+    id: options.id ?? `${target}HorizonAmplitude`,
+    type: "linear",
+    domain: [0, 1],
+    nice: false,
+    zero: true
+  };
+}
+
+export function inferHorizonTitle(field) {
+  const words = field.replaceAll("_", " ");
+  return words.length === 0 ? field : words[0].toUpperCase() + words.slice(1);
+}
+
+export function validateUnusedHorizonEncodings(layer) {
+  const conflicts = ["x2", "y2", "color", "pathOrder"].filter(
+    channel => layer.encoding?.[channel] !== undefined
+  );
+  if (conflicts.length > 0) {
+    throw new Error(
+      `Horizon area target "${layer.id}" already has unsupported ${conflicts.join(", ")} encoding.`
+    );
+  }
+}
+
+export function findExistingHorizonScale(program, id, label) {
+  const scale = findSemanticScale(program, id);
+  if (scale === undefined) throw new Error(`${label} scale "${id}" is missing.`);
+  return scale;
+}
+
+export function resolveEditedHorizonField(
+  program,
+  layer,
+  source,
+  transform,
+  requested,
+  role
+) {
+  if (requested === undefined) {
+    return {
+      ...transform[role],
+      ...(role === "x" ? { title: layer.encoding.x.title } : {})
+    };
+  }
+  const prior = transform[role];
+  return resolveHorizonField(program, {
+    ...layer,
+    encoding: {
+      ...layer.encoding,
+      [role]: {
+        field: prior.field,
+        fieldType: prior.fieldType,
+        scale: layer.encoding[role].scale,
+        ...(role === "x" && layer.encoding.x.title !== undefined
+          ? { title: layer.encoding.x.title }
+          : {})
+      }
+    }
+  }, source, requested, role);
+}
+
+export function resolveEditedHorizonGroupBy(source, previous, requested) {
+  if (requested === undefined) return previous;
+  if (requested === false) return undefined;
+  if (typeof requested !== "string" || requested.length === 0) {
+    throw new TypeError("Horizon groupBy must be a field string or false.");
+  }
+  readNominalField(source.values, requested);
+  return requested;
+}
+
+export function mergeHorizonPalette(previous, requested) {
+  if (requested === undefined) return previous;
+  if (!isPlainObject(requested)) {
+    throw new TypeError("Horizon palette must be a plain object.");
+  }
+  return {
+    positive: requested.positive ?? previous.positive,
+    negative: requested.negative ?? previous.negative
+  };
+}