ggaction 0.0.4 → 0.0.6

package/src/actions/facets/actions.js

@@ -1,5 +1,5 @@
 import { action } from "../../core/action.js";
-import { isPlainObject } from "../../core/immutable.js";
+import { freezeOwned, isPlainObject } from "../../core/immutable.js";
 import {
   validateNonEmptyString,
   validateNonNegativeFinite,
@@ -9,12 +9,13 @@ import {
 import { resolveFacetDefinition } from "../../grammar/facets/index.js";
 import { normalizeFacetScalePolicies } from
   "../../grammar/facets/scales.js";
+import { FACET_SCALE_CHANNELS } from "../../grammar/facets/scales.js";
 import { resolveFacetLayout } from "../../layout/facets.js";
 import { compositionChildDescriptor } from
   "../../materialization/composition.js";
 import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../../theme/defaults.js";
 import { deriveFacetChildren } from "./derive.js";
-import { rebindLayerData, replayDerivedData } from "./replay.js";
+import { replayDerivedData } from "./replay.js";
 import { composeFacetGuides } from "./guides.js";
 
 const FACET_OPTIONS = Object.freeze([
@@ -73,6 +74,76 @@ function requireFacetProgram(program, operation) {
   }
 }
 
+function currentFacetDefinition(program) {
+  const current = program.compositionSpec;
+  return resolveFacetDefinition(program.semanticSpec, {
+    id: current.id,
+    data: current.facet.data,
+    field: current.facet.field,
+    values: current.facet.values
+  });
+}
+
+function facetUnitTemplate(program) {
+  const seed = program.children[program.compositionSpec.children[0]];
+  if (seed === undefined) {
+    throw new Error(`Facet "${program.compositionSpec.id}" requires a retained child.`);
+  }
+  const { facets: _facets, ...unitConfigs } = program.materializationConfigs;
+  return new program.constructor({
+    semanticSpec: program.semanticSpec,
+    graphicSpec: seed.graphicSpec,
+    resolvedScales: program.resolvedScales,
+    materializationConfigs: freezeOwned({
+      ...unitConfigs,
+      canvas: seed.materializationConfigs.canvas
+    }),
+    children: {},
+    context: program.context,
+    trace: program.trace,
+    actionStack: program.actionStack,
+    actionSequence: program._actionSequence
+  });
+}
+
+function applicableScaleRequest(program, channels) {
+  return Object.fromEntries(FACET_SCALE_CHANNELS.flatMap(channel =>
+    program.semanticSpec.layers.some(
+      layer => layer.encoding?.[channel]?.scale !== undefined
+    )
+      ? [[channel, channels[channel]]]
+      : []
+  ));
+}
+
+function rederiveFacet(program, { scales, guides }) {
+  const current = program.compositionSpec;
+  const definition = currentFacetDefinition(program);
+  const request = applicableScaleRequest(program, scales);
+  const normalized = normalizeFacetScalePolicies(program.semanticSpec, request);
+  const derived = deriveFacetChildren(facetUnitTemplate(program), definition, {
+    closeInheritedAction: true,
+    stripTitle: true,
+    scales: request
+  });
+  const compositionSpec = {
+    ...current,
+    facet: {
+      ...current.facet,
+      scales: normalized.channels,
+      guides
+    }
+  };
+  let next = program._withCompositionState({
+    children: derived.children,
+    compositionSpec
+  });
+  for (const id of compositionSpec.children) {
+    next = next.useProgram({ id });
+  }
+  return next.materializeComposition();
+}
+
 export const facet = action(
   {
     op: "facet",
@@ -153,10 +224,73 @@ export const editFacetHeaders = action(
   }
 );
 
+export const editFacetScales = action(
+  {
+    op: "editFacetScales",
+    description: "Edit facet scale-resolution policies and rederive every cell.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    requireFacetProgram(this, "editFacetScales");
+    validateOptionObject(args, FACET_SCALE_CHANNELS, "editFacetScales", {
+      allowEmpty: false,
+      emptyMessage: "editFacetScales requires at least one channel policy change."
+    });
+    for (const channel of Object.keys(args)) {
+      if (!this.semanticSpec.layers.some(
+        layer => layer.encoding?.[channel]?.scale !== undefined
+      )) {
+        throw new Error(
+          `Facet scale channel "${channel}" is not used by an affected layer.`
+        );
+      }
+    }
+    const current = this.compositionSpec.facet;
+    const scales = { ...current.scales, ...args };
+    if (FACET_SCALE_CHANNELS.every(
+      channel => scales[channel] === current.scales[channel]
+    )) {
+      throw new Error("editFacetScales requires at least one channel policy change.");
+    }
+    const request = applicableScaleRequest(this, scales);
+    const normalized = normalizeFacetScalePolicies(this.semanticSpec, request);
+    const applyEdit = program => rederiveFacet(program, {
+      scales: normalized.channels,
+      guides: current.guides
+    });
+    applyEdit(this);
+    return applyEdit(this);
+  }
+);
+
+export const editFacetGuides = action(
+  {
+    op: "editFacetGuides",
+    description: "Edit facet guide ownership and rederive every cell.",
+    scope: "composition"
+  },
+  function (args = {}) {
+    requireFacetProgram(this, "editFacetGuides");
+    validateOptionObject(args, GUIDE_OPTIONS, "editFacetGuides", {
+      allowEmpty: false,
+      emptyMessage: "editFacetGuides requires at least one guide policy."
+    });
+    const current = this.compositionSpec.facet;
+    const guides = normalizeGuides({ ...current.guides, ...args });
+    const applyEdit = program => rederiveFacet(program, {
+      scales: current.scales,
+      guides
+    });
+    applyEdit(this);
+    return applyEdit(this);
+  }
+);
+
 export function registerFacetActions(ProgramClass) {
   ProgramClass.prototype.replayDerivedData = replayDerivedData;
-  ProgramClass.prototype.rebindLayerData = rebindLayerData;
   ProgramClass.prototype.composeFacetGuides = composeFacetGuides;
   ProgramClass.prototype.facet = facet;
   ProgramClass.prototype.editFacetHeaders = editFacetHeaders;
+  ProgramClass.prototype.editFacetScales = editFacetScales;
+  ProgramClass.prototype.editFacetGuides = editFacetGuides;
 }

package/src/actions/facets/derive.js

@@ -12,6 +12,7 @@ import { buildMaterializationPlan } from "../../materialization/planner.js";
 import { requireDataset } from "../../selectors/datasets.js";
 import { requireLayer } from "../../selectors/layers.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { findTransformPolicy } from "../../grammar/transforms.js";
 
 function sharedHistogramBoundaries(program) {
   const boundaries = new Map();
@@ -59,6 +60,23 @@ function replayDatasetId(cell, owner) {
   return `${cell.id}-${owner}-data`;
 }
 
+function rebindReplayedGradientPlots(child, base, datasets) {
+  let next = child;
+  for (const [id, markConfig] of Object.entries(base.markConfigs)) {
+    const gradientPlot = markConfig.gradientPlot;
+    if (gradientPlot?.materialized !== true) continue;
+    const profile = datasets.get(gradientPlot.profileId);
+    const source = datasets.get(gradientPlot.source);
+    if (profile === undefined || source === undefined) {
+      throw new Error(
+        `Facet gradient plot "${id}" is missing replayed profile dependencies.`
+      );
+    }
+    next = next.rebindGradientPlotProfile({ id, profile, source });
+  }
+  return next;
+}
+
 function cellMaterializationPlan(program) {
   const scaleIds = [...new Set(program.semanticSpec.layers.flatMap(layer =>
     Object.values(layer.encoding ?? {})
@@ -72,7 +90,13 @@ function cellMaterializationPlan(program) {
   return buildMaterializationPlan({ scales });
 }
 
-function deriveCellProgram(base, definition, cell, histogramBoundaries) {
+function deriveCellProgram(
+  base,
+  definition,
+  cell,
+  histogramBoundaries,
+  scales
+) {
   let child = base.filterData({
     id: cell.data,
     source: definition.data,
@@ -88,10 +112,15 @@ function deriveCellProgram(base, definition, cell, histogramBoundaries) {
       );
     }
     const id = replayDatasetId(cell, replay.id);
+    const policy = findTransformPolicy(replay.transform.type);
+    const transform = policy?.facetReplayTransform?.(
+      replay.transform,
+      { scales }
+    ) ?? replay.transform;
     child = child.replayDerivedData({
       id,
       source,
-      transform: replay.transform
+      transform
     });
     datasets.set(replay.id, id);
   }
@@ -109,6 +138,7 @@ function deriveCellProgram(base, definition, cell, histogramBoundaries) {
       histogramBoundaries.get(layer.id)
     );
   }
+  child = rebindReplayedGradientPlots(child, base, datasets);
   return applyMaterializationPlan(child, cellMaterializationPlan(child));
 }
 
@@ -163,7 +193,7 @@ export function deriveFacetChildren(
     : new Map();
   const independentlyResolved = Object.fromEntries(definition.cells.map(cell => [
     cell.id,
-    deriveCellProgram(template, definition, cell, bins)
+    deriveCellProgram(template, definition, cell, bins, resolutionRequest)
   ]));
   const resolution = resolveFacetScaleDomains(
     template.semanticSpec,

package/src/actions/facets/replay.js

@@ -2,33 +2,25 @@ import { action } from "../../core/action.js";
 import { isPlainObject } from "../../core/immutable.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
+import { findTransformPolicy } from "../../grammar/transforms.js";
 import { hasDataset } from "../../selectors/datasets.js";
-import { requireLayer } from "../../selectors/layers.js";
 
 const REPLAY_OPTIONS = Object.freeze(["id", "source", "transform"]);
-const REBIND_OPTIONS = Object.freeze(["id", "data"]);
-const MATERIALIZERS = Object.freeze({
-  filter: "materializeFilteredData",
-  regression: "materializeRegressionData",
-  density: "materializeDensityData",
-  interval: "materializeIntervalData",
-  boxSummary: "materializeBoxSummaryData",
-  boxOutlier: "materializeBoxOutlierData"
-});
 
 function requestedTransform(transform) {
   if (!isPlainObject(transform)) {
     throw new TypeError("replayDerivedData transform must be a plain object.");
   }
-  const materialize = MATERIALIZERS[transform.type];
-  if (materialize === undefined) {
+  const policy = findTransformPolicy(transform.type);
+  if (policy?.facetTopology === undefined) {
     throw new Error(
       `replayDerivedData does not support transform "${transform.type ?? "unknown"}".`
     );
   }
-  if (transform.type !== "density") return { transform, materialize };
-  const { resolved: _resolved, ...requested } = transform;
-  return { transform: requested, materialize };
+  return {
+    transform: policy.replayTransform?.(transform) ?? transform,
+    materialize: policy.materializeOp
+  };
 }
 
 export const replayDerivedData = action(
@@ -46,24 +38,3 @@ export const replayDerivedData = action(
       [resolved.materialize]({ id });
   }
 );
-
-export const rebindLayerData = action(
-  {
-    op: "rebindLayerData",
-    description: "Rebind one facet-cell layer to its replayed dataset."
-  },
-  function (args = {}) {
-    validateKeys(args, REBIND_OPTIONS, "rebindLayerData");
-    const id = validateUserId(args.id, "Facet layer id");
-    const data = validateUserId(args.data, "Facet layer dataset id");
-    requireLayer(this, id);
-    if (!hasDataset(this, data)) {
-      throw new Error(`Facet layer dataset "${data}" does not exist.`);
-    }
-    return this.editSemantic({
-      property: `layer[${id}].data`,
-      value: data
-    });
-  }
-);
-

package/src/actions/gradientPlots/components.js

@@ -0,0 +1,177 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+import { GRADIENT_PROFILE_FIELDS } from "../../grammar/gradientProfile.js";
+import { resolveGraphicBounds } from "../../layout/canvas.js";
+import { findLayer } from "../../selectors/layers.js";
+import { createDensityLegendPaint } from "./paint.js";
+
+const CENTER_OPTIONS = Object.freeze([
+  "id", "owner", "data", "category", "categoryType", "coordinate",
+  "categoryScale", "measureScale", "orientation", "size", "stroke",
+  "strokeWidth"
+]);
+const LEGEND_OPTIONS = Object.freeze(["owner", "title", "position"]);
+
+export const createGradientPlotCenter = action(
+  {
+    op: "createGradientPlotCenter",
+    description: "Create the optional center rule for one gradient plot."
+  },
+  function (args = {}) {
+    validateKeys(args, CENTER_OPTIONS, "createGradientPlotCenter");
+    const categoryAction = args.orientation === "vertical" ? "encodeX" : "encodeY";
+    const measureAction = args.orientation === "vertical" ? "encodeY" : "encodeX";
+    const spanOrientation = args.orientation === "vertical" ? "horizontal" : "vertical";
+    let next = this.createRuleMark({ id: args.id, data: args.data });
+    next = next[categoryAction]({
+      target: args.id,
+      field: args.category,
+      fieldType: args.categoryType,
+      coordinate: args.coordinate,
+      scale: { id: args.categoryScale }
+    });
+    next = next[measureAction]({
+      target: args.id,
+      field: GRADIENT_PROFILE_FIELDS.center,
+      fieldType: "quantitative",
+      coordinate: args.coordinate,
+      scale: { id: args.measureScale }
+    });
+    return next
+      .encodeStroke({ target: args.id, value: args.stroke })
+      .encodeStrokeWidth({ target: args.id, value: args.strokeWidth })
+      .materializeRuleSpan({
+        id: args.id,
+        orientation: spanOrientation,
+        size: args.size
+      });
+  }
+);
+
+function legendIds(owner) {
+  return {
+    strip: `${owner}DensityLegend`,
+    labels: `${owner}DensityLegendLabels`,
+    title: `${owner}DensityLegendTitle`
+  };
+}
+
+function requireLegendOwner(program, owner) {
+  const layer = findLayer(program, owner);
+  const config = program.markConfigs[owner]?.gradientPlot;
+  if (layer === undefined || config?.materialized !== true) {
+    throw new Error(`Unknown gradient-plot legend owner "${owner}".`);
+  }
+  return { layer, config };
+}
+
+export const rematerializeGradientPlotLegend = action(
+  {
+    op: "rematerializeGradientPlotLegend",
+    description: "Rematerialize one gradient plot density legend."
+  },
+  function ({ owner } = {}) {
+    const { config } = requireLegendOwner(this, owner);
+    const ids = legendIds(owner);
+    const bounds = resolveGraphicBounds(this);
+    const position = config.guides.legend.position;
+    if (position !== "right") {
+      throw new Error('Gradient plot density legend currently requires position "right".');
+    }
+    const x = bounds.x + bounds.width + 50;
+    const y = bounds.y + 50;
+    const width = 22;
+    const height = Math.min(170, Math.max(80, bounds.height - 110));
+    return this
+      .editGraphics({ target: ids.strip, property: "x", value: x })
+      .editGraphics({ target: ids.strip, property: "y", value: y })
+      .editGraphics({ target: ids.strip, property: "width", value: width })
+      .editGraphics({ target: ids.strip, property: "height", value: height })
+      .editGraphics({
+        target: ids.strip,
+        property: "fill",
+        value: createDensityLegendPaint(config.gradient.opacity)
+      })
+      .editGraphics({ target: ids.strip, property: "stroke", value: "#cbd5e1" })
+      .editGraphics({ target: ids.strip, property: "strokeWidth", value: 1 })
+      .editGraphics({ target: ids.labels, property: "x", value: x + width + 10 })
+      .editGraphics({ target: ids.labels, property: "y", value: [y + height, y] })
+      .editGraphics({ target: ids.labels, property: "text", value: ["Low", "High"] })
+      .editGraphics({ target: ids.labels, property: "fill", value: "#64748b" })
+      .editGraphics({ target: ids.labels, property: "fontSize", value: 11 })
+      .editGraphics({ target: ids.labels, property: "fontFamily", value: "sans-serif" })
+      .editGraphics({ target: ids.labels, property: "textAlign", value: "left" })
+      .editGraphics({ target: ids.labels, property: "textBaseline", value: "middle" })
+      .editGraphics({ target: ids.title, property: "x", value: x })
+      .editGraphics({ target: ids.title, property: "y", value: y - 18 })
+      .editGraphics({ target: ids.title, property: "text", value: config.guides.legend.title })
+      .editGraphics({ target: ids.title, property: "fill", value: "#334155" })
+      .editGraphics({ target: ids.title, property: "fontSize", value: 12 })
+      .editGraphics({ target: ids.title, property: "fontFamily", value: "sans-serif" })
+      .editGraphics({ target: ids.title, property: "fontWeight", value: 600 })
+      .editGraphics({ target: ids.title, property: "textAlign", value: "left" })
+      .editGraphics({ target: ids.title, property: "textBaseline", value: "middle" });
+  }
+);
+
+export const createGradientPlotLegend = action(
+  {
+    op: "createGradientPlotLegend",
+    description: "Create the neutral density legend owned by one gradient plot."
+  },
+  function (args = {}) {
+    validateKeys(args, LEGEND_OPTIONS, "createGradientPlotLegend");
+    requireLegendOwner(this, args.owner);
+    if (args.position !== undefined && args.position !== "right") {
+      throw new Error('Gradient plot density legend currently requires position "right".');
+    }
+    if (args.title !== undefined && (typeof args.title !== "string" || args.title.length === 0)) {
+      throw new TypeError("Gradient plot density legend title must be a non-empty string.");
+    }
+    const ids = legendIds(args.owner);
+    const densityScale = `${args.owner}Density`;
+    let next = this
+      .editSemantic({ property: `scale[${densityScale}].type`, value: "sequential" })
+      .editSemantic({
+        property: `scale[${densityScale}].domain`,
+        value: this.markConfigs[args.owner].gradientPlot.intensityDomain
+      })
+      .editSemantic({
+        property: `scale[${densityScale}].range`,
+        value: { palette: { name: "greys" } }
+      })
+      .editSemantic({ property: "guide.legend.color.scale", value: densityScale })
+      .editSemantic({
+        property: "guide.legend.color.title",
+        value: args.title ?? "Relative density"
+      })
+      .createGraphics({ id: ids.strip, type: "rect", parent: "canvas" })
+      .createGraphics({ id: ids.labels, type: "text", length: 2, parent: "canvas" })
+      .createGraphics({ id: ids.title, type: "text", parent: "canvas" });
+    next = next._withMarkConfig(args.owner, {
+      ...next.markConfigs[args.owner],
+      gradientPlot: {
+        ...next.markConfigs[args.owner].gradientPlot,
+        guides: {
+          ...next.markConfigs[args.owner].gradientPlot.guides,
+          legend: {
+            title: args.title ?? "Relative density",
+            position: args.position ?? "right"
+          }
+        }
+      }
+    });
+    return next.rematerializeGradientPlotLegend({ owner: args.owner });
+  }
+);
+
+export function removeGradientPlotLegend(program, owner) {
+  const ids = legendIds(owner);
+  let next = program;
+  for (const id of Object.values(ids)) {
+    if (next.graphicSpec.objects[id] !== undefined) {
+      next = next.editGraphics({ target: id, remove: true });
+    }
+  }
+  return next;
+}

package/src/actions/gradientPlots/create.js

@@ -0,0 +1,96 @@
+import { action } from "../../core/action.js";
+import { validateKeys } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findSemanticScale } from "../../selectors/scales.js";
+import {
+  GRADIENT_PLOT_OPTIONS,
+  gradientEncodingArgs,
+  resolveGradientAppearance,
+  resolveGradientCenter,
+  resolveGradientDensity,
+  resolveGradientGuides,
+  resolveGradientPosition,
+  resolveGradientWidth
+} from "./options.js";
+import {
+  normalizeGradientPositionTypes,
+  resolveGradientPlotId,
+  resolveGradientSourceLayer
+} from "./resolve.js";
+
+export const createGradientPlot = action(
+  {
+    op: "createGradientPlot",
+    description: "Create a categorical density gradient plot."
+  },
+  function (args = {}) {
+    validateKeys(args, GRADIENT_PLOT_OPTIONS, "createGradientPlot");
+    const id = resolveGradientPlotId(this, args.id);
+    const source = resolveGradientSourceLayer(this, args.target);
+    const data = args.data ?? source?.data ?? this.context.currentData ??
+      (this.semanticSpec.datasets.length === 1
+        ? this.semanticSpec.datasets[0].id
+        : undefined);
+    if (findDataset(this, data) === undefined) {
+      throw new Error("createGradientPlot requires data or one inferable dataset.");
+    }
+    const positions = normalizeGradientPositionTypes(
+      resolveGradientPosition(args.x, "x") ?? source?.encoding?.x,
+      resolveGradientPosition(args.y, "y") ?? source?.encoding?.y
+    );
+    if (
+      positions.x !== undefined && positions.y !== undefined &&
+      positions.orientation === undefined
+    ) {
+      throw new Error(
+        "createGradientPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const density = resolveGradientDensity(args.density);
+    const width = resolveGradientWidth(args.width);
+    const gradient = resolveGradientAppearance(args.gradient);
+    const center = resolveGradientCenter(args.center);
+    const guides = resolveGradientGuides(args.guides);
+    const category = positions.orientation === "vertical"
+      ? positions.x
+      : positions.orientation === "horizontal"
+        ? positions.y
+        : undefined;
+    const categoryScaleId = typeof category?.scale === "string"
+      ? category.scale
+      : category?.scale?.id;
+    const categoryScale = findSemanticScale(this, categoryScaleId);
+    let next = categoryScale?.type === "point"
+      ? this.editScale({ id: categoryScaleId, type: "band" })
+      : this;
+    next = next.createRectMark({ id, data })._withMarkConfig(id, {
+      ...this.markConfigs[id],
+      gradientPlot: {
+        materialized: false,
+        density,
+        width,
+        gradient,
+        center,
+        guides
+      },
+      itemFilterable: false,
+      stroke: false,
+      strokeWidth: 0
+    });
+    if (positions.x !== undefined) {
+      next = next.encodeX({
+        ...gradientEncodingArgs(positions.x),
+        target: id,
+        coordinate: args.coordinate ?? source?.coordinate
+      });
+    }
+    if (positions.y !== undefined) {
+      next = next.encodeY({
+        ...gradientEncodingArgs(positions.y),
+        target: id,
+        coordinate: args.coordinate ?? source?.coordinate
+      });
+    }
+    return next.materializeGradientPlot({ id });
+  }
+);