ggaction 0.0.4 → 0.0.5

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

package/src/actions/gradientPlots/edit.js

@@ -0,0 +1,153 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { validateKeys } from "../../core/validation.js";
+import { planDerivedDataRevision } from "../../materialization/dataProvenance.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { removeGradientPlotLegend } from "./components.js";
+import {
+  resolveGradientAppearance,
+  resolveGradientCenter,
+  resolveGradientDensity,
+  resolveGradientWidth
+} from "./options.js";
+import { resolveGradientOwner } from "./resolve.js";
+
+const OPTIONS = Object.freeze([
+  "target", "density", "width", "gradient", "center"
+]);
+
+function patch(value, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`editGradientPlot ${label} must be a plain object.`);
+  }
+  return value;
+}
+
+function removeCenter(program, id) {
+  let next = program;
+  if (findLayer(next, id) !== undefined) {
+    next = next.editSemantic({ property: `layer[${id}]`, remove: true });
+  }
+  if (next.graphicSpec.objects[id] !== undefined) {
+    next = next.editGraphics({ target: id, remove: true });
+  }
+  return next._withoutMaterializationConfig(["marks", id]);
+}
+
+export const editGradientPlot = action(
+  {
+    op: "editGradientPlot",
+    description: "Edit one stable categorical gradient plot."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "editGradientPlot");
+    if (!OPTIONS.slice(1).some(key => Object.hasOwn(args, key))) {
+      throw new Error("editGradientPlot requires at least one gradient-plot option.");
+    }
+    const owner = resolveGradientOwner(this, args.target, "editGradientPlot");
+    const current = this.markConfigs[owner.id].gradientPlot;
+    const density = Object.hasOwn(args, "density")
+      ? resolveGradientDensity(patch(args.density, "density"), current.density, "editGradientPlot")
+      : current.density;
+    const width = Object.hasOwn(args, "width")
+      ? resolveGradientWidth(patch(args.width, "width"), current.width, "editGradientPlot")
+      : current.width;
+    const gradient = Object.hasOwn(args, "gradient")
+      ? resolveGradientAppearance(
+          patch(args.gradient, "gradient"),
+          current.gradient,
+          "editGradientPlot"
+        )
+      : current.gradient;
+    const center = Object.hasOwn(args, "center")
+      ? resolveGradientCenter(
+          args.center === false ? false : patch(args.center, "center"),
+          current.center === false ? undefined : current.center,
+          "editGradientPlot"
+        )
+      : current.center;
+    const densityChanged = JSON.stringify(density) !== JSON.stringify(current.density);
+    const centerTypeChanged = center !== false && current.center !== false &&
+      center.type !== current.center.type;
+    const statistical = densityChanged || centerTypeChanged;
+    let next = this;
+    let profileId = current.profileId;
+    if (statistical) {
+      const consumers = [owner.id, ...(findLayer(next, current.centerId) ? [current.centerId] : [])];
+      const revision = planDerivedDataRevision(next, {
+        owner: owner.id,
+        role: "ProfileData",
+        previous: current.profileId,
+        consumers
+      });
+      profileId = revision.id;
+      next = next.createGradientProfileData({
+        id: profileId,
+        source: current.source,
+        category: current.category,
+        field: current.measure,
+        ...density,
+        center: center === false ? "median" : center.type
+      });
+      for (const rebind of revision.rebinds) next = next.rebindLayerData(rebind);
+      next = next.releaseDerivedData(revision.release);
+    }
+    const profile = findDataset(next, profileId);
+    next = next._withMarkConfig(owner.id, {
+      ...next.markConfigs[owner.id],
+      gradientPlot: {
+        ...current,
+        density,
+        width,
+        gradient,
+        center,
+        profileId,
+        intensityDomain: profile.transform[0].resolved.intensityDomain
+      }
+    });
+    const hadCenter = findLayer(next, current.centerId) !== undefined;
+    if (center === false && hadCenter) {
+      next = removeCenter(next, current.centerId);
+    } else if (center !== false && !hadCenter) {
+      const categoryEncoding = owner.encoding[current.orientation === "vertical" ? "x" : "y"];
+      const measureEncoding = owner.encoding[current.orientation === "vertical" ? "y" : "x"];
+      next = next.createGradientPlotCenter({
+        id: current.centerId,
+        owner: owner.id,
+        data: profileId,
+        category: current.category,
+        categoryType: current.categoryType,
+        coordinate: owner.coordinate,
+        categoryScale: categoryEncoding.scale,
+        measureScale: measureEncoding.scale,
+        orientation: current.orientation,
+        size: 1,
+        stroke: center.stroke,
+        strokeWidth: center.strokeWidth
+      });
+    } else if (center !== false) {
+      next = next
+        .encodeStroke({ target: current.centerId, value: center.stroke })
+        .encodeStrokeWidth({ target: current.centerId, value: center.strokeWidth });
+    }
+    next = next.materializeGradientPlotFill({ id: owner.id });
+    if (center !== false && findLayer(next, current.centerId) !== undefined) {
+      const categoryChannel = current.orientation === "vertical" ? "x" : "y";
+      const categoryScale = next.resolvedScales[owner.encoding[categoryChannel].scale];
+      next = next.materializeRuleSpan({
+        id: current.centerId,
+        orientation: current.orientation === "vertical" ? "horizontal" : "vertical",
+        size: Math.max(1, categoryScale.bandwidth * width.band - 16)
+      });
+    }
+    if (current.guides?.legend !== false && current.guides?.legend !== undefined) {
+      next = removeGradientPlotLegend(next, owner.id)
+        .createGradientPlotLegend({
+          owner: owner.id,
+          ...current.guides.legend
+        });
+    }
+    return next._withContext({ currentMark: owner.id, currentData: current.source });
+  }
+);

package/src/actions/gradientPlots/index.js

@@ -0,0 +1,24 @@
+import {
+  createGradientPlotCenter,
+  createGradientPlotLegend,
+  rematerializeGradientPlotLegend
+} from "./components.js";
+import { createGradientPlot } from "./create.js";
+import { editGradientPlot } from "./edit.js";
+import {
+  materializeGradientPlot,
+  materializeGradientPlotFill
+} from "./materialize.js";
+import { rebindGradientPlotProfile } from "./rebind.js";
+
+export function registerGradientPlotActions(ProgramClass) {
+  ProgramClass.prototype.createGradientPlot = createGradientPlot;
+  ProgramClass.prototype.editGradientPlot = editGradientPlot;
+  ProgramClass.prototype.materializeGradientPlot = materializeGradientPlot;
+  ProgramClass.prototype.materializeGradientPlotFill = materializeGradientPlotFill;
+  ProgramClass.prototype.createGradientPlotCenter = createGradientPlotCenter;
+  ProgramClass.prototype.createGradientPlotLegend = createGradientPlotLegend;
+  ProgramClass.prototype.rematerializeGradientPlotLegend =
+    rematerializeGradientPlotLegend;
+  ProgramClass.prototype.rebindGradientPlotProfile = rebindGradientPlotProfile;
+}