ggaction 0.0.4 → 0.0.5

package/src/actions/gradientPlots/materialize.js

@@ -0,0 +1,287 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { isPlainObject } from "../../core/immutable.js";
+import { GRADIENT_PROFILE_FIELDS } from "../../grammar/gradientProfile.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues
+} from "../../grammar/scales/index.js";
+import { applyMaterializationPlan } from "../../materialization/dependencies.js";
+import { getSourceDependentMarkSteps } from "../../materialization/marks/index.js";
+import { buildMaterializationPlan } from "../../materialization/planner.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import {
+  createGradientPlotPaint,
+  resolveGradientPlotCategoryColors
+} from "./paint.js";
+import { resolveGradientOrientation } from "./resolve.js";
+
+function position(values, scale) {
+  return ["ordinal", "band", "point"].includes(scale.type)
+    ? mapOrdinalPositionValues(values, scale)
+    : mapContinuousScaleValues(values, scale);
+}
+
+function profileValue(row, key) {
+  return row[GRADIENT_PROFILE_FIELDS[key]];
+}
+
+function axisWithTitle(option, text) {
+  if (option === false) return false;
+  const axis = option ?? {};
+  return {
+    ...axis,
+    title: {
+      ...(axis.title ?? {}),
+      ...(axis.title?.text === undefined ? { text } : {})
+    }
+  };
+}
+
+function gradientAxesOptions(config) {
+  if (config.guides.axes === false) return false;
+  const axes = config.guides.axes ?? {};
+  return {
+    ...axes,
+    x: axisWithTitle(
+      axes.x,
+      config.orientation === "vertical" ? config.category : config.measure
+    ),
+    y: axisWithTitle(
+      axes.y,
+      config.orientation === "vertical" ? config.measure : config.category
+    )
+  };
+}
+
+function bodyItems(program, layer, dataset, config) {
+  const categoryChannel = config.orientation === "vertical" ? "x" : "y";
+  const measureChannel = config.orientation === "vertical" ? "y" : "x";
+  const categoryEncoding = layer.encoding[categoryChannel];
+  const measureEncoding = layer.encoding[measureChannel];
+  const categoryScale = program.resolvedScales[categoryEncoding.scale];
+  const measureScale = program.resolvedScales[measureEncoding.scale];
+  const categories = dataset.values.map(row => row[config.category]);
+  const centers = position(categories, categoryScale);
+  const lower = position(
+    dataset.values.map(row => profileValue(row, "lower")),
+    measureScale
+  );
+  const upper = position(
+    dataset.values.map(row => profileValue(row, "upper")),
+    measureScale
+  );
+  const categoryColors = resolveGradientPlotCategoryColors(
+    program,
+    layer,
+    categories
+  );
+  const thickness = categoryScale.bandwidth * config.width.band;
+  if (!Number.isFinite(thickness) || thickness <= 0) {
+    throw new Error(`Gradient plot "${layer.id}" requires a positive band width.`);
+  }
+  return dataset.values.map((row, index) => {
+    const a = lower[index];
+    const b = upper[index];
+    const geometry = config.orientation === "vertical"
+      ? {
+          x: centers[index] - thickness / 2,
+          y: Math.min(a, b),
+          width: thickness,
+          height: Math.abs(a - b)
+        }
+      : {
+          x: Math.min(a, b),
+          y: centers[index] - thickness / 2,
+          width: Math.abs(a - b),
+          height: thickness
+        };
+    return {
+      type: "rect",
+      properties: {
+        ...geometry,
+        fill: createGradientPlotPaint({
+          values: profileValue(row, "values"),
+          intensities: profileValue(row, "intensities")
+        }, {
+          orientation: config.orientation,
+          valueScale: measureScale,
+          intensityDomain: config.intensityDomain,
+          palette: config.gradient.palette,
+          opacity: config.gradient.opacity,
+          ...(categoryColors === undefined
+            ? {}
+            : { baseColor: categoryColors[index] })
+        }),
+        opacity: 1,
+        stroke: "transparent",
+        strokeWidth: 0
+      }
+    };
+  });
+}
+
+export const materializeGradientPlotFill = action(
+  {
+    op: "materializeGradientPlotFill",
+    description: "Materialize categorical density profiles as gradient strips."
+  },
+  function ({ id } = {}) {
+    const owner = validateUserId(id, "Gradient-plot id");
+    const layer = findLayer(this, owner);
+    const config = this.markConfigs[owner]?.gradientPlot;
+    if (layer?.mark?.type !== "rect" || config?.materialized !== true) {
+      throw new Error(`Unknown materialized gradient plot "${owner}".`);
+    }
+    const dataset = findDataset(this, layer.data);
+    if (dataset === undefined) {
+      throw new Error(`Gradient plot "${owner}" requires profile data.`);
+    }
+    const scaleIds = [...new Set([
+      layer.encoding?.x?.scale,
+      layer.encoding?.y?.scale,
+      layer.encoding?.color?.scale
+    ].filter(Boolean))];
+    let next = this;
+    for (const scale of scaleIds) {
+      next = next.rematerializeScale({ id: scale, marks: false, guides: false });
+    }
+    next = next.editGraphics({
+      target: owner,
+      property: "items",
+      value: bodyItems(next, findLayer(next, owner), dataset, config)
+    });
+    next = applyMaterializationPlan(
+      next,
+      buildMaterializationPlan({
+        marks: getSourceDependentMarkSteps(next, owner)
+      })
+    );
+    if (
+      config.guides?.legend !== false &&
+      config.guides?.legend !== undefined &&
+      next.graphicSpec.objects[`${owner}DensityLegend`] !== undefined
+    ) {
+      next = next.rematerializeGradientPlotLegend({ owner });
+    }
+    return next._withContext({ currentMark: owner, currentData: config.source });
+  }
+);
+
+export const materializeGradientPlot = action(
+  {
+    op: "materializeGradientPlot",
+    description: "Materialize one complete categorical gradient plot."
+  },
+  function ({ id } = {}) {
+    const owner = validateUserId(id, "Gradient-plot id");
+    const layer = findLayer(this, owner);
+    const config = this.markConfigs[owner]?.gradientPlot;
+    if (layer?.mark?.type !== "rect" || config === undefined) {
+      throw new Error(`Unknown gradient plot "${owner}".`);
+    }
+    if (config.materialized) return this.materializeGradientPlotFill({ id: owner });
+    const x = layer.encoding?.x;
+    const y = layer.encoding?.y;
+    if (x?.field === undefined || y?.field === undefined) return this;
+    const orientation = resolveGradientOrientation(x, y);
+    if (orientation === undefined) {
+      throw new Error(
+        "createGradientPlot requires one categorical axis and one quantitative axis."
+      );
+    }
+    const category = orientation === "vertical" ? x : y;
+    const measure = orientation === "vertical" ? y : x;
+    const profileId = `${owner}ProfileData`;
+    const centerId = `${owner}Center`;
+    let next = this.createGradientProfileData({
+      id: profileId,
+      source: layer.data,
+      category: category.field,
+      field: measure.field,
+      ...config.density,
+      center: config.center === false ? "median" : config.center.type
+    });
+    const profile = findDataset(next, profileId);
+    const transform = profile.transform[0];
+    next = next
+      .rebindLayerData({ id: owner, data: profileId })
+      ._withMarkConfig(owner, {
+        ...next.markConfigs[owner],
+        gradientPlot: {
+          ...config,
+          materialized: true,
+          source: layer.data,
+          orientation,
+          category: category.field,
+          categoryType: category.fieldType,
+          measure: measure.field,
+          profileId,
+          centerId,
+          intensityDomain: transform.resolved.intensityDomain
+        }
+      });
+    const measureChannel = orientation === "vertical" ? "y" : "x";
+    const secondaryChannel = `${measureChannel}2`;
+    next = next
+      .editSemantic({
+        property: `layer[${owner}].encoding.${measureChannel}.field`,
+        value: GRADIENT_PROFILE_FIELDS.lower
+      })
+      .editSemantic({
+        property: `layer[${owner}].encoding.${measureChannel}.fieldType`,
+        value: "quantitative"
+      })
+      .editSemantic({
+        property: `layer[${owner}].encoding.${secondaryChannel}.field`,
+        value: GRADIENT_PROFILE_FIELDS.upper
+      })
+      .editSemantic({
+        property: `layer[${owner}].encoding.${secondaryChannel}.fieldType`,
+        value: "quantitative"
+      })
+      .editSemantic({
+        property: `layer[${owner}].encoding.${secondaryChannel}.scale`,
+        value: measure.scale
+      });
+    next = next.materializeGradientPlotFill({ id: owner });
+    if (config.center !== false) {
+      const categoryScale = next.resolvedScales[category.scale];
+      next = next.createGradientPlotCenter({
+        id: centerId,
+        owner,
+        data: profileId,
+        category: category.field,
+        categoryType: category.fieldType,
+        coordinate: layer.coordinate,
+        categoryScale: category.scale,
+        measureScale: measure.scale,
+        orientation,
+        size: Math.max(1, categoryScale.bandwidth * config.width.band - 16),
+        stroke: config.center.stroke,
+        strokeWidth: config.center.strokeWidth
+      });
+    }
+    const guides = config.guides;
+    if (guides !== false) {
+      const wantsStandard = guides.axes !== false || guides.grid !== false;
+      if (wantsStandard) {
+        next = next.createGuides({
+          axes: gradientAxesOptions(next.markConfigs[owner].gradientPlot),
+          grid: guides.grid,
+          legend: false
+        });
+      }
+      if (guides.legend !== false) {
+        const legend = isPlainObject(guides.legend) ? guides.legend : {};
+        next = next.createGradientPlotLegend({
+          owner,
+          title: legend.title ?? "Relative density",
+          position: legend.position ?? "right"
+        });
+      }
+    }
+    return next._withContext({ currentMark: owner, currentData: layer.data });
+  }
+);

package/src/actions/gradientPlots/options.js

@@ -0,0 +1,120 @@
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateKeys,
+  validateNonEmptyString,
+  validateNonNegativeFinite,
+  validateUnitInterval
+} from "../../core/validation.js";
+import { normalizePalette } from "../../grammar/palettes.js";
+
+export const GRADIENT_PLOT_OPTIONS = Object.freeze([
+  "id", "target", "data", "x", "y", "coordinate", "density", "width",
+  "gradient", "center", "guides"
+]);
+
+function plain(value, keys, label, operation) {
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError(`${operation} ${label} must be a plain object.`);
+  }
+  validateKeys(value, keys, `${operation} ${label}`);
+  return value;
+}
+
+export function resolveGradientPosition(value, label, operation = "createGradientPlot") {
+  if (value === undefined) return undefined;
+  if (typeof value === "string") return { field: value };
+  return plain(value, ["field", "fieldType", "scale"], label, operation);
+}
+
+export function gradientEncodingArgs(value) {
+  return {
+    ...value,
+    ...(typeof value.scale === "string" ? { scale: { id: value.scale } } : {})
+  };
+}
+
+export function resolveGradientDensity(value, previous, operation = "createGradientPlot") {
+  const options = plain(value, [
+    "bandwidth", "extent", "steps", "kernel", "normalization"
+  ], "density", operation);
+  return Object.freeze({
+    bandwidth: options.bandwidth ?? previous?.bandwidth ?? "auto",
+    extent: options.extent ?? previous?.extent ?? "auto",
+    steps: options.steps ?? previous?.steps ?? 64,
+    kernel: options.kernel ?? previous?.kernel ?? "gaussian",
+    normalization: options.normalization ?? previous?.normalization ?? "unit"
+  });
+}
+
+export function resolveGradientWidth(value, previous, operation = "createGradientPlot") {
+  const options = plain(value, ["band"], "width", operation);
+  const band = options.band ?? previous?.band ?? 0.7;
+  if (!Number.isFinite(band) || band <= 0 || band >= 1) {
+    throw new RangeError(
+      `${operation} width.band must be greater than 0 and less than 1.`
+    );
+  }
+  return Object.freeze({ band });
+}
+
+function opacityPair(value, fallback, operation) {
+  const opacity = value ?? fallback ?? [0, 1];
+  if (!Array.isArray(opacity) || opacity.length !== 2) {
+    throw new TypeError(`${operation} gradient.opacity must contain two values.`);
+  }
+  const normalized = opacity.map((item, index) =>
+    validateUnitInterval(item, `${operation} gradient.opacity[${index}]`)
+  );
+  return Object.freeze(normalized);
+}
+
+export function resolveGradientAppearance(
+  value,
+  previous,
+  operation = "createGradientPlot"
+) {
+  const options = plain(value, ["palette", "opacity"], "gradient", operation);
+  const palette = options.palette === undefined
+    ? previous?.palette ?? "blues"
+    : normalizePalette(options.palette);
+  return Object.freeze({
+    palette,
+    opacity: opacityPair(options.opacity, previous?.opacity, operation)
+  });
+}
+
+export function resolveGradientCenter(
+  value,
+  previous,
+  operation = "createGradientPlot"
+) {
+  if (value === false) return false;
+  const options = plain(
+    value,
+    ["type", "stroke", "strokeWidth"],
+    "center",
+    operation
+  );
+  const type = options.type ?? previous?.type ?? "median";
+  if (!["mean", "median"].includes(type)) {
+    throw new Error(`${operation} center.type must be mean or median.`);
+  }
+  return Object.freeze({
+    type,
+    stroke: options.stroke === undefined
+      ? previous?.stroke ?? "#0f172a"
+      : validateNonEmptyString(options.stroke, `${operation} center.stroke`),
+    strokeWidth: options.strokeWidth === undefined
+      ? previous?.strokeWidth ?? 1.5
+      : validateNonNegativeFinite(
+          options.strokeWidth,
+          `${operation} center.strokeWidth`
+        )
+  });
+}
+
+export function resolveGradientGuides(value, operation = "createGradientPlot") {
+  if (value === false) return false;
+  return Object.freeze(plain(value, ["axes", "grid", "legend"], "guides", operation));
+}

package/src/actions/gradientPlots/paint.js

@@ -0,0 +1,107 @@
+import { resolveContinuousPalette } from "../../grammar/palettes.js";
+import { mapScaleConsumerValues } from "../../materialization/scales/map.js";
+
+function parseHex(value) {
+  const match = value.match(/^#([0-9a-f]{6})$/i);
+  if (!match) throw new Error(`Gradient plot requires a six-digit hex color, received "${value}".`);
+  return [0, 2, 4].map(offset =>
+    Number.parseInt(match[1].slice(offset, offset + 2), 16)
+  );
+}
+
+function interpolate(left, right, amount) {
+  return left.map((channel, index) =>
+    Math.round(channel + (right[index] - channel) * amount)
+  );
+}
+
+function alphaColor(rgb, opacity) {
+  return `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${Number(opacity.toFixed(6))})`;
+}
+
+function paletteColor(colors, amount) {
+  const bounded = Math.max(0, Math.min(1, amount));
+  const scaled = bounded * (colors.length - 1);
+  const left = Math.floor(scaled);
+  const right = Math.min(colors.length - 1, left + 1);
+  return interpolate(parseHex(colors[left]), parseHex(colors[right]), scaled - left);
+}
+
+function categoricalRamp(base) {
+  const rgb = parseHex(base);
+  const pale = interpolate([255, 255, 255], rgb, 0.2);
+  return [
+    `#${pale.map(value => value.toString(16).padStart(2, "0")).join("")}`,
+    base
+  ];
+}
+
+export function resolveGradientPlotCategoryColors(program, layer, categories) {
+  if (layer.encoding?.color === undefined) return undefined;
+  const scale = program.resolvedScales[layer.encoding.color.scale];
+  if (scale === undefined) {
+    throw new Error(`Gradient plot "${layer.id}" requires a resolved color scale.`);
+  }
+  return mapScaleConsumerValues(categories, scale, "color");
+}
+
+export function createGradientPlotPaint(profile, {
+  orientation,
+  valueScale,
+  intensityDomain,
+  palette,
+  opacity,
+  baseColor
+}) {
+  const values = profile.values;
+  const intensities = profile.intensities;
+  const mapped = mapScaleConsumerValues(values, valueScale, "position");
+  const startPosition = mapped[0];
+  const endPosition = mapped.at(-1);
+  if (!Number.isFinite(startPosition) || !Number.isFinite(endPosition) || startPosition === endPosition) {
+    throw new Error("Gradient plot requires distinct mapped profile endpoints.");
+  }
+  const increasing = startPosition < endPosition;
+  const start = orientation === "vertical"
+    ? { x: 0.5, y: increasing ? 0 : 1 }
+    : { x: increasing ? 0 : 1, y: 0.5 };
+  const end = orientation === "vertical"
+    ? { x: 0.5, y: increasing ? 1 : 0 }
+    : { x: increasing ? 1 : 0, y: 0.5 };
+  const colors = baseColor === undefined
+    ? resolveContinuousPalette(palette, 11)
+    : categoricalRamp(baseColor);
+  const maximum = intensityDomain[1];
+  const stops = values.map((_, index) => {
+    const fraction = intensities[index] / maximum;
+    const offset = Number(
+      ((mapped[index] - startPosition) / (endPosition - startPosition)).toFixed(12)
+    );
+    return {
+      offset: Object.is(offset, -0) ? 0 : offset,
+      color: alphaColor(
+        paletteColor(colors, fraction),
+        opacity[0] + (opacity[1] - opacity[0]) * fraction
+      )
+    };
+  });
+  return {
+    type: "linear-gradient",
+    from: start,
+    to: end,
+    stops
+  };
+}
+
+export function createDensityLegendPaint(opacity) {
+  const colors = ["#e2e8f0", "#334155"];
+  return {
+    type: "linear-gradient",
+    from: { x: 0.5, y: 1 },
+    to: { x: 0.5, y: 0 },
+    stops: colors.map((color, index) => ({
+      offset: index,
+      color: alphaColor(parseHex(color), opacity[index])
+    }))
+  };
+}

package/src/actions/gradientPlots/rebind.js

@@ -0,0 +1,51 @@
+import { action } from "../../core/action.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { validateKeys } from "../../core/validation.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+
+const OPTIONS = Object.freeze(["id", "profile", "source"]);
+
+export const rebindGradientPlotProfile = action(
+  {
+    op: "rebindGradientPlotProfile",
+    description: "Rebind one gradient plot to a replayed profile revision."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "rebindGradientPlotProfile");
+    const id = validateUserId(args.id, "Gradient-plot id");
+    const profileId = validateUserId(
+      args.profile,
+      "Gradient profile dataset id"
+    );
+    const source = validateUserId(args.source, "Gradient profile source id");
+    const layer = findLayer(this, id);
+    const config = this.markConfigs[id]?.gradientPlot;
+    const profile = findDataset(this, profileId);
+    const transform = profile?.transform?.[0];
+    if (layer?.mark?.type !== "rect" || config?.materialized !== true) {
+      throw new Error(`Unknown materialized gradient plot "${id}".`);
+    }
+    if (layer.data !== profileId || transform?.type !== "gradientProfile") {
+      throw new Error(
+        `Gradient plot "${id}" must use gradient profile dataset "${profileId}".`
+      );
+    }
+    if (profile.source !== source || findDataset(this, source) === undefined) {
+      throw new Error(
+        `Gradient profile dataset "${profileId}" must use source "${source}".`
+      );
+    }
+    return this
+      ._withMarkConfig(id, {
+        ...this.markConfigs[id],
+        gradientPlot: {
+          ...config,
+          source,
+          profileId,
+          intensityDomain: transform.resolved.intensityDomain
+        }
+      })
+      ._withContext({ currentMark: id, currentData: source });
+  }
+);

package/src/actions/gradientPlots/resolve.js

@@ -0,0 +1,81 @@
+import { resolveOptionalUserId, validateUserId } from "../../core/identifiers.js";
+import { findLayer, hasLayer } from "../../selectors/layers.js";
+
+const CATEGORICAL = Object.freeze(["nominal", "ordinal", "temporal"]);
+
+export function resolveGradientOrientation(x, y) {
+  const xType = x?.fieldType;
+  const yType = y?.fieldType;
+  if (CATEGORICAL.includes(xType) && (yType === undefined || yType === "quantitative")) {
+    return "vertical";
+  }
+  if ((xType === undefined || xType === "quantitative") && CATEGORICAL.includes(yType)) {
+    return "horizontal";
+  }
+  return undefined;
+}
+
+export function normalizeGradientPositionTypes(x, y) {
+  const orientation = resolveGradientOrientation(x, y);
+  if (orientation === "vertical") {
+    return { x, y: { fieldType: "quantitative", ...y }, orientation };
+  }
+  if (orientation === "horizontal") {
+    return { x: { fieldType: "quantitative", ...x }, y, orientation };
+  }
+  return { x, y, orientation };
+}
+
+export function resolveGradientSourceLayer(program, target) {
+  if (target !== undefined) {
+    const id = validateUserId(target, "Gradient plot source layer id");
+    const layer = findLayer(program, id);
+    if (layer === undefined) {
+      throw new Error(`Unknown gradient plot source layer "${id}".`);
+    }
+    return layer;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current?.encoding?.x !== undefined || current?.encoding?.y !== undefined) {
+    return current;
+  }
+  const eligible = program.semanticSpec.layers.filter(layer =>
+    layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
+  );
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length > 1) {
+    throw new Error(
+      "createGradientPlot target is ambiguous; provide target or explicit x and y."
+    );
+  }
+  return undefined;
+}
+
+export function resolveGradientPlotId(program, requested) {
+  return resolveOptionalUserId(requested, {
+    defaultId: "gradientPlot",
+    label: "Gradient-plot id",
+    operation: "createGradientPlot",
+    ambiguous: hasLayer(program, "gradientPlot") ||
+      program.graphicSpec.objects.gradientPlot !== undefined
+  });
+}
+
+export function resolveGradientOwner(program, requested, operation) {
+  const eligible = program.semanticSpec.layers.filter(
+    layer => program.markConfigs[layer.id]?.gradientPlot?.materialized === true
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Gradient-plot owner id");
+    const layer = findLayer(program, id);
+    if (layer === undefined || !eligible.includes(layer)) {
+      throw new Error(`Unknown gradient-plot owner "${id}".`);
+    }
+    return layer;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current !== undefined && eligible.includes(current)) return current;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) throw new Error(`${operation} requires a gradient plot.`);
+  throw new Error(`${operation} target is ambiguous; provide target.`);
+}