ggaction 0.0.1

package/src/materialization/density.js

@@ -0,0 +1,29 @@
+import { getMarkMaterializationStep } from "./marks.js";
+import { requireLayer } from "../selectors/layers.js";
+import { buildMaterializationPlan } from "./planner.js";
+
+export function planDensityRematerialization(program, target) {
+  const layer = requireLayer(
+    program,
+    target,
+    `Unknown density materialization target "${target}"`
+  );
+  const scaleIds = new Set([
+    layer.encoding?.x?.scale,
+    layer.encoding?.y?.scale
+  ].filter(Boolean));
+  const orderedLayers = [
+    layer,
+    ...program.semanticSpec.layers.filter(candidate => candidate.id !== target)
+  ];
+  const plan = [];
+  for (const candidate of orderedLayers) {
+    const usesAffectedScale = Object.values(candidate.encoding ?? {}).some(
+      encoding => scaleIds.has(encoding?.scale)
+    );
+    if (!usesAffectedScale) continue;
+    const step = getMarkMaterializationStep(program, candidate);
+    if (step !== undefined) plan.push(step);
+  }
+  return buildMaterializationPlan({ marks: plan });
+}

package/src/materialization/dependencies.js

@@ -0,0 +1,134 @@
+import { getMarkMaterializationStep } from "./marks.js";
+import { requireLayer } from "../selectors/layers.js";
+import {
+  applyMaterializationPlan,
+  buildMaterializationPlan
+} from "./planner.js";
+import {
+  hasMaterializedLegend,
+  materializedLegendUsesScale
+} from "./legends.js";
+
+function usesPositionalScale(program, id) {
+  return program.semanticSpec.layers.some(layer =>
+    ["x", "y", "x2", "y2", "xOffset"].some(
+      channel => layer.encoding?.[channel]?.scale === id
+    )
+  );
+}
+
+function needsCanvasScaleRematerialization(program, scale) {
+  return (
+    (scale.range === "auto" ||
+      program.semanticSpec.guides.axis?.x?.scale === scale.id ||
+      program.semanticSpec.guides.axis?.y?.scale === scale.id ||
+      program.semanticSpec.guides.grid?.horizontal?.scale === scale.id ||
+      program.semanticSpec.guides.grid?.vertical?.scale === scale.id) &&
+    program.resolvedScales[scale.id] !== undefined &&
+    usesPositionalScale(program, scale.id)
+  );
+}
+
+function hasTitle(program) {
+  return (
+    program.semanticSpec.title.text !== undefined &&
+    program.titleConfig !== undefined
+  );
+}
+
+export function planCanvasRematerialization(program) {
+  const scales = [];
+  for (const scale of program.semanticSpec.scales) {
+    if (needsCanvasScaleRematerialization(program, scale)) {
+      scales.push({
+        op: "rematerializeScale",
+        args: { id: scale.id, guides: false }
+      });
+    }
+  }
+  const marks = [];
+  for (const layer of program.semanticSpec.layers) {
+    const step = getMarkMaterializationStep(program, layer);
+    if (step !== undefined) marks.push(step);
+  }
+  const guides = program.semanticSpec.scales.flatMap(scale =>
+    needsCanvasScaleRematerialization(program, scale)
+      ? planScaleGuideRematerialization(program, scale.id)
+      : []
+  );
+  if (hasMaterializedLegend(program)) {
+    guides.push({ op: "rematerializeLegend" });
+  }
+  const layout = hasTitle(program) ? [{ op: "rematerializeTitle" }] : [];
+  return buildMaterializationPlan({ scales, marks, guides, layout });
+}
+
+export function planScaleGuideRematerialization(program, id) {
+  const guides = [];
+  const objects = program.graphicSpec?.objects ?? {};
+  const guideConfigs = program.guideConfigs ?? {};
+  if (
+    objects.xAxisLine &&
+    program.semanticSpec.guides.axis?.x?.scale === id
+  ) {
+    guides.push({ op: "editXAxisLine" });
+  }
+  if (
+    objects.yAxisLine &&
+    program.semanticSpec.guides.axis?.y?.scale === id
+  ) {
+    guides.push({ op: "editYAxisLine" });
+  }
+  for (const channel of ["x", "y"]) {
+    for (const component of ["ticks", "labels", "title"]) {
+      if (guideConfigs.axis?.[channel]?.[component]?.scale === id) {
+        const suffix = component[0].toUpperCase() + component.slice(1);
+        guides.push({ op: `edit${channel.toUpperCase()}Axis${suffix}` });
+      }
+    }
+  }
+  if (guideConfigs.grid?.horizontal?.scale === id) {
+    guides.push({ op: "rematerializeHorizontalGrid" });
+  }
+  if (guideConfigs.grid?.vertical?.scale === id) {
+    guides.push({ op: "rematerializeVerticalGrid" });
+  }
+  if (materializedLegendUsesScale(program, id)) {
+    guides.push({ op: "rematerializeLegend" });
+  }
+  return buildMaterializationPlan({ guides });
+}
+
+export function planLayerDataRematerialization(program, id) {
+  const layer = requireLayer(program, id);
+  const scaleIds = [...new Set(
+    Object.values(layer.encoding ?? {})
+      .map(encoding => encoding?.scale)
+      .filter(scale => scale !== undefined)
+  )];
+  const scales = scaleIds.map(scale => ({
+      op: "rematerializeScale",
+      args: { id: scale, guides: false }
+    }));
+  const markStep = getMarkMaterializationStep(program, layer);
+  const marks = markStep === undefined ? [] : [markStep];
+  if (scales.length > 0 || marks.length > 0) {
+    const guides = scaleIds.flatMap(scale =>
+      planScaleGuideRematerialization(program, scale)
+    );
+    return buildMaterializationPlan({ scales, marks, guides });
+  }
+  return buildMaterializationPlan({ marks: layer.mark?.type === "point" &&
+    program.graphicSpec.objects[layer.id] !== undefined
+    ? [{ op: "rematerializePointMark", args: { id: layer.id } }]
+    : [] });
+}
+
+export function applyLayerDataRematerialization(program, id) {
+  return applyMaterializationPlan(
+    program,
+    planLayerDataRematerialization(program, id)
+  );
+}
+
+export { applyMaterializationPlan } from "./planner.js";

package/src/materialization/encodings.js

@@ -0,0 +1,50 @@
+import { hasMaterializedLegend } from "./legends.js";
+import { requireLayer } from "../selectors/layers.js";
+import { getMarkRematerializationStep } from "./marks.js";
+import { buildMaterializationPlan } from "./planner.js";
+
+export function planEncodingRematerialization(program, {
+  target,
+  channel,
+  scale
+}) {
+  const layer = requireLayer(
+    program,
+    target,
+    `Unknown encoding materialization target "${target}"`
+  );
+
+  const scales = [];
+  if (layer.mark?.type === "point" && scale !== undefined) {
+    scales.push({
+      op: "rematerializeScale",
+      args: { id: scale, guides: false }
+    });
+  }
+
+  const marks = [];
+  if (
+    layer.mark?.type === "area" &&
+    channel === "color" &&
+    scale !== undefined
+  ) {
+    for (const candidate of program.semanticSpec.layers) {
+      if (
+        candidate.mark?.type === "area" &&
+        candidate.encoding?.color?.scale === scale
+      ) {
+        const step = getMarkRematerializationStep(candidate);
+        if (step !== undefined) marks.push(step);
+      }
+    }
+  } else {
+    const step = getMarkRematerializationStep(layer);
+    if (step !== undefined) marks.push(step);
+  }
+
+  const guides = [];
+  if (hasMaterializedLegend(program)) {
+    guides.push({ op: "rematerializeLegend" });
+  }
+  return buildMaterializationPlan({ scales, marks, guides });
+}

package/src/materialization/graphicHierarchy.js

@@ -0,0 +1,104 @@
+import {
+  findGraphicParent,
+  graphicSiblings
+} from "../grammar/schemas/graphicTree.js";
+import { findDataset } from "../selectors/datasets.js";
+
+export const CANVAS_GRAPHIC_ID = "canvas";
+export const PLOT_GRAPHIC_ID = "plot-main";
+
+export function assertCanvasHierarchyAvailable(program) {
+  const canvasByType = Object.entries(program.graphicSpec.objects).find(
+    ([, graphic]) => graphic.type === "canvas"
+  );
+  if (canvasByType !== undefined) {
+    throw new Error("createCanvas requires a program without a canvas.");
+  }
+  for (const id of [CANVAS_GRAPHIC_ID, PLOT_GRAPHIC_ID]) {
+    if (program.graphicSpec.objects[id] !== undefined) {
+      throw new Error(`createCanvas requires the reserved graphic id "${id}".`);
+    }
+  }
+}
+
+export function resolvePlotGraphicPlacement(program, relative = {}) {
+  const canvas = program.graphicSpec.objects[CANVAS_GRAPHIC_ID];
+  const plot = program.graphicSpec.objects[PLOT_GRAPHIC_ID];
+
+  if (canvas === undefined && plot === undefined) return relative;
+  if (canvas?.type !== "canvas") {
+    throw new Error("Ordinary mark attachment requires the canonical canvas.");
+  }
+  if (plot?.type !== "collection") {
+    throw new Error("Ordinary mark attachment requires the canonical plot container.");
+  }
+  const parent = findGraphicParent(program.graphicSpec, PLOT_GRAPHIC_ID);
+  if (parent?.kind !== "parent" || parent.id !== CANVAS_GRAPHIC_ID) {
+    throw new Error("The canonical plot container must be attached to the canvas.");
+  }
+  return { parent: PLOT_GRAPHIC_ID, ...relative };
+}
+
+export function resolveMarkGraphicPlacement(program, { data, markType }) {
+  const dataset = findDataset(program, data);
+  const transform = dataset?.transform?.length === 1
+    ? dataset.transform[0]
+    : undefined;
+  if (transform?.type !== "regression") {
+    const axis = program.graphicSpec.objects[PLOT_GRAPHIC_ID]?.children?.find(
+      id => /^(x|y)Axis/.test(id)
+    );
+    return resolvePlotGraphicPlacement(
+      program,
+      axis === undefined ? {} : { before: axis }
+    );
+  }
+  const eligible = program.semanticSpec.layers.filter(layer =>
+    layer.data === dataset.source &&
+    program.graphicSpec.objects[layer.id] !== undefined
+  );
+  const namespaced = eligible.filter(layer =>
+    `${layer.id}RegressionData` === dataset.id
+  );
+  const sources = namespaced.length === 1 ? namespaced : eligible;
+  if (sources.length !== 1) {
+    throw new Error(
+      "Regression graphic placement requires one source mark layer."
+    );
+  }
+  const anchor = sources[0].id;
+  return resolvePlotGraphicPlacement(
+    program,
+    markType === "area" ? { before: anchor } : { after: anchor }
+  );
+}
+
+export function resolveCanvasGraphicPlacement(program, relative = {}) {
+  const canvas = program.graphicSpec.objects[CANVAS_GRAPHIC_ID];
+  if (canvas?.type !== "canvas") {
+    throw new Error("Canvas-owned graphics require the canonical canvas.");
+  }
+  return { parent: CANVAS_GRAPHIC_ID, ...relative };
+}
+
+export function resolveLegendGraphicPlacement(program, relative = {}) {
+  const title = program.graphicSpec.objects[CANVAS_GRAPHIC_ID]?.children?.find(
+    id => id === "chartTitle" || id === "chartSubtitle"
+  );
+  const hasRelativeAnchor = relative.before !== undefined ||
+    relative.after !== undefined;
+  return resolveCanvasGraphicPlacement(program, {
+    ...(title === undefined || hasRelativeAnchor ? {} : { before: title }),
+    ...relative
+  });
+}
+
+export function preserveGraphicPlacement(program, id) {
+  const parent = findGraphicParent(program.graphicSpec, id);
+  const siblings = graphicSiblings(program.graphicSpec, id);
+  const next = siblings[siblings.indexOf(id) + 1];
+  return {
+    ...(parent?.kind === "parent" ? { parent: parent.id } : {}),
+    ...(next === undefined ? {} : { before: next })
+  };
+}

package/src/materialization/legends.js

@@ -0,0 +1,20 @@
+import { LEGEND_CONFIG_KINDS } from "../core/vocabulary.js";
+
+export function hasMaterializedLegend(program) {
+  return LEGEND_CONFIG_KINDS.some(kind => {
+    const config = program.guideConfigs?.legend?.[kind];
+    if (config === undefined) return false;
+    if (kind === "series" || kind === "color") {
+      return program.semanticSpec.guides.legend?.[kind] !== undefined;
+    }
+    return true;
+  });
+}
+
+export function materializedLegendUsesScale(program, id) {
+  return LEGEND_CONFIG_KINDS.some(kind => {
+    const config = program.guideConfigs?.legend?.[kind];
+    if (config === undefined) return false;
+    return config.scale === id || config.scales?.includes(id);
+  });
+}

package/src/materialization/marks.js

@@ -0,0 +1,110 @@
+import { findDataset } from "../selectors/datasets.js";
+import { isAggregate } from "../grammar/aggregate.js";
+import { BAR_GRAINS, resolveBarGrain } from "../grammar/bars/policy.js";
+import { resolveRuleMode } from "../grammar/rules.js";
+import { findUpstreamTransform } from "./dataProvenance.js";
+
+function hasPositionScales(layer) {
+  return (
+    layer.encoding?.x?.scale !== undefined &&
+    layer.encoding?.y?.scale !== undefined
+  );
+}
+
+export function canMaterializePoint(_program, layer) {
+  return layer.mark?.type === "point" && hasPositionScales(layer);
+}
+
+export function canMaterializeLine(program, layer) {
+  const dataset = findDataset(program, layer.data);
+  const interval = dataset?.transform?.some(item => item.type === "interval");
+  return (
+    layer.mark?.type === "line" &&
+    hasPositionScales(layer) &&
+    (isAggregate(layer.encoding.y.aggregate) ||
+      (layer.encoding.x.fieldType === "quantitative" &&
+        layer.encoding.y.fieldType === "quantitative") ||
+      ((interval || layer.encoding.y.aggregate === undefined) &&
+        ["quantitative", "temporal"].includes(layer.encoding.x.fieldType) &&
+        ["quantitative", "temporal"].includes(layer.encoding.y.fieldType) &&
+        layer.encoding.x.fieldType !== layer.encoding.y.fieldType))
+  );
+}
+
+export function canMaterializeArea(program, layer) {
+  if (layer.mark?.type !== "area" || !hasPositionScales(layer)) {
+    return false;
+  }
+
+  const dataset = findDataset(program, layer.data);
+  const densityTransform = findUpstreamTransform(program, dataset, "density");
+  const completeDensity =
+    densityTransform !== undefined &&
+    (densityTransform.groupBy === undefined ||
+      layer.encoding?.group?.field === densityTransform.groupBy);
+
+  return (
+    completeDensity ||
+    layer.encoding?.y2?.scale === layer.encoding.y.scale ||
+    layer.encoding?.x2?.scale === layer.encoding.x.scale
+  );
+}
+
+export function canMaterializeBar(program, layer) {
+  if (layer.mark?.type !== "bar" || !hasPositionScales(layer)) {
+    return false;
+  }
+  const grain = resolveBarGrain(layer);
+  return grain === BAR_GRAINS.histogram || (
+    [BAR_GRAINS.aggregate, BAR_GRAINS.ranged].includes(grain) &&
+    program.markConfigs[layer.id]?.barWidth !== undefined
+  );
+}
+
+export function canMaterializeRule(program, layer) {
+  const fixedSpan = program.markConfigs[layer.id]?.fixedSpan;
+  const boxSpanOwner = program.markConfigs[layer.id]?.boxSpanOwner;
+  return layer.mark?.type === "rule" && (
+    resolveRuleMode(layer) !== undefined ||
+    (boxSpanOwner !== undefined && hasPositionScales(layer)) ||
+    (fixedSpan !== undefined && hasPositionScales(layer))
+  );
+}
+
+const MARK_MATERIALIZATION_POLICIES = Object.freeze({
+  point: Object.freeze({
+    canMaterialize: canMaterializePoint,
+    op: "rematerializePointMark"
+  }),
+  line: Object.freeze({
+    canMaterialize: canMaterializeLine,
+    op: "rematerializeLineMark"
+  }),
+  area: Object.freeze({
+    canMaterialize: canMaterializeArea,
+    op: "rematerializeAreaMark"
+  }),
+  bar: Object.freeze({
+    canMaterialize: canMaterializeBar,
+    op: "rematerializeBarMark"
+  }),
+  rule: Object.freeze({
+    canMaterialize: canMaterializeRule,
+    op: "rematerializeRuleMark"
+  })
+});
+
+export function getMarkRematerializationStep(layer) {
+  const policy = MARK_MATERIALIZATION_POLICIES[layer.mark?.type];
+  return policy === undefined
+    ? undefined
+    : { op: policy.op, args: { id: layer.id } };
+}
+
+export function getMarkMaterializationStep(program, layer) {
+  const policy = MARK_MATERIALIZATION_POLICIES[layer.mark?.type];
+  if (policy === undefined || !policy.canMaterialize(program, layer)) {
+    return undefined;
+  }
+  return getMarkRematerializationStep(layer);
+}

package/src/materialization/planner.js

@@ -0,0 +1,38 @@
+const STAGES = Object.freeze([
+  "scales",
+  "marks",
+  "guides",
+  "layout",
+  "highlights"
+]);
+
+function stepKey(step) {
+  return JSON.stringify([step.op, step.args ?? null]);
+}
+
+export function buildMaterializationPlan(stages = {}) {
+  const plan = [];
+  const seen = new Set();
+
+  for (const stage of STAGES) {
+    for (const step of stages[stage] ?? []) {
+      if (step === undefined) continue;
+      const key = stepKey(step);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      plan.push(step);
+    }
+  }
+
+  return plan;
+}
+
+export function applyMaterializationPlan(program, plan) {
+  let next = program;
+  for (const step of buildMaterializationPlan({ marks: plan })) {
+    next = step.args === undefined
+      ? next[step.op]()
+      : next[step.op](step.args);
+  }
+  return next;
+}

package/src/materialization/selection/filter.js

@@ -0,0 +1,40 @@
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  normalizeMarkSelector,
+  selectMarkItemKeys
+} from "../../grammar/markSelection.js";
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { resolveMarkSelection } from "./state.js";
+
+function resolvePointRows(program, layer, selector) {
+  const dataset = findDataset(program, layer.data);
+  if (dataset === undefined) {
+    throw new Error(`Point mark "${layer.id}" requires an existing dataset.`);
+  }
+  const items = dataset.values.map((row, index) => ({
+    key: `${layer.id}/point/${index}`,
+    fields: isPlainObject(row) ? { ...row } : {},
+    channels: {},
+    properties: {},
+    members: [row]
+  }));
+  return {
+    selector,
+    items,
+    keys: selectMarkItemKeys(items, selector)
+  };
+}
+
+export function resolveMarkFilterSelection(program, target, selector) {
+  const normalized = normalizeMarkSelector(selector);
+  const layer = findLayer(program, target);
+  if (
+    layer?.mark?.type === "point" &&
+    normalized.grain === "item" &&
+    normalized.field !== undefined
+  ) {
+    return resolvePointRows(program, layer, normalized);
+  }
+  return resolveMarkSelection(program, target, normalized);
+}