ggaction 0.0.3 → 0.0.5

package/src/materialization/guides/resources.js

@@ -5,27 +5,66 @@ const CATEGORICAL_COMPONENTS = Object.freeze([
   "Labels", "Title", "Background"
 ]);
 
-const LEGEND_GRAPHICS = Object.freeze({
-  series: Object.freeze(CATEGORICAL_COMPONENTS.map(
-    component => `seriesLegend${component}`
-  )),
-  color: Object.freeze(CATEGORICAL_COMPONENTS.map(
-    component => `colorLegend${component}`
-  )),
-  size: Object.freeze([
-    "sizeLegendSymbols", "sizeLegendLabels", "sizeLegendTitle"
-  ]),
-  gradient: Object.freeze([
-    "colorGradientBackground", "colorGradientStrips", "colorGradientTicks",
-    "colorGradientLabels", "colorGradientTitle"
-  ]),
-  interval: Object.freeze([
-    "colorLegendSymbols", "colorLegendLabels", "colorLegendTitle"
-  ]),
-  opacity: Object.freeze([
-    "opacityLegendBackground", "opacityLegendSymbols", "opacityLegendLabels",
-    "opacityLegendTitle"
-  ])
+const LEGEND_RESOURCE_POLICIES = Object.freeze({
+  series: Object.freeze({
+    semanticKind: "series",
+    family: "categorical",
+    rematerializeOp: undefined,
+    graphicIds: Object.freeze(CATEGORICAL_COMPONENTS.map(
+      component => `seriesLegend${component}`
+    ))
+  }),
+  color: Object.freeze({
+    semanticKind: "color",
+    family: "categorical",
+    rematerializeOp: undefined,
+    graphicIds: Object.freeze(CATEGORICAL_COMPONENTS.map(
+      component => `colorLegend${component}`
+    ))
+  }),
+  size: Object.freeze({
+    semanticKind: "size",
+    family: "size",
+    rematerializeOp: "rematerializeSizeLegend",
+    graphicIds: Object.freeze([
+      "sizeLegendSymbols", "sizeLegendLabels", "sizeLegendTitle"
+    ])
+  }),
+  gradient: Object.freeze({
+    semanticKind: "color",
+    family: "continuous",
+    rematerializeOp: "rematerializeGradientLegend",
+    graphicIds: Object.freeze([
+      "colorGradientBackground", "colorGradientStrips", "colorGradientTicks",
+      "colorGradientLabels", "colorGradientTitle"
+    ])
+  }),
+  interval: Object.freeze({
+    semanticKind: "color",
+    family: "interval",
+    rematerializeOp: "rematerializeIntervalLegend",
+    graphicIds: Object.freeze([
+      "colorLegendSymbols", "colorLegendLabels", "colorLegendTitle"
+    ])
+  }),
+  opacity: Object.freeze({
+    semanticKind: "opacity",
+    family: "continuous",
+    rematerializeOp: "rematerializeOpacityLegend",
+    graphicIds: Object.freeze([
+      "opacityLegendBackground", "opacityLegendSymbols", "opacityLegendLabels",
+      "opacityLegendTitle"
+    ])
+  }),
+  strokeWidth: Object.freeze({
+    semanticKind: "strokeWidth",
+    family: "strokeWidth",
+    rematerializeOp: "rematerializeStrokeWidthLegend",
+    graphicIds: Object.freeze([
+      "strokeWidthLegendSymbols", "strokeWidthLegendLabels",
+      "strokeWidthLegendTitle"
+    ])
+  })
 });
 
 export function axisGraphicIds(channel) {
@@ -34,11 +73,22 @@ export function axisGraphicIds(channel) {
 }
 
 export function legendGraphicIds(kind) {
-  const ids = LEGEND_GRAPHICS[kind];
-  if (ids === undefined) {
+  return legendResourcePolicy(kind).graphicIds;
+}
+
+export function legendResourcePolicy(kind) {
+  const policy = LEGEND_RESOURCE_POLICIES[kind];
+  if (policy === undefined) {
     throw new Error(`Unknown legend graphic kind "${kind}".`);
   }
-  return ids;
+  return policy;
+}
+
+export function legendResourcePolicies() {
+  return Object.entries(LEGEND_RESOURCE_POLICIES).map(([kind, policy]) => ({
+    kind,
+    ...policy
+  }));
 }
 
 export function allLegendGraphicIds(kinds) {

package/src/materialization/horizon.js

@@ -0,0 +1,29 @@
+import { getMarkMaterializationStep } from "./marks/index.js";
+import { buildMaterializationPlan } from "./planner.js";
+import { requireLayer } from "../selectors/layers.js";
+
+export function planHorizonRematerialization(program, target) {
+  const layer = requireLayer(
+    program,
+    target,
+    `Unknown Horizon materialization target "${target}"`
+  );
+  const scaleIds = new Set([
+    layer.encoding?.x?.scale,
+    layer.encoding?.y?.scale,
+    layer.encoding?.color?.scale
+  ].filter(Boolean));
+  const ordered = [
+    layer,
+    ...program.semanticSpec.layers.filter(candidate => candidate.id !== target)
+  ];
+  const marks = ordered.flatMap(candidate => {
+    const consumesScale = Object.values(candidate.encoding ?? {}).some(
+      encoding => scaleIds.has(encoding?.scale)
+    );
+    if (!consumesScale) return [];
+    const step = getMarkMaterializationStep(program, candidate);
+    return step === undefined ? [] : [step];
+  });
+  return buildMaterializationPlan({ marks });
+}

package/src/materialization/layout.js

@@ -0,0 +1,15 @@
+const LAYOUT_CONSUMER_POLICIES = Object.freeze([
+  Object.freeze({
+    applies(program) {
+      return program.semanticSpec.title.text !== undefined &&
+        program.titleConfig !== undefined;
+    },
+    step: Object.freeze({ op: "rematerializeTitle" })
+  })
+]);
+
+export function planLayoutRematerialization(program) {
+  return LAYOUT_CONSUMER_POLICIES.flatMap(policy =>
+    policy.applies(program) ? [policy.step] : []
+  );
+}

package/src/materialization/marks/capabilities.js

@@ -0,0 +1,161 @@
+import { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import { findCoordinate } from "../../selectors/coordinates.js";
+import { isAggregate } from "../../grammar/aggregate.js";
+import {
+  BAR_GRAINS,
+  resolveBarColorLayout,
+  resolveBarOffsetChannel,
+  resolveBarGrain
+} from "../../grammar/bars/policy.js";
+import { resolveRuleMode } from "../../grammar/rules.js";
+import { findUpstreamTransform } from "../dataProvenance.js";
+import { resolveRectMode } from "../../grammar/rects.js";
+
+function hasCartesianPositionScales(layer) {
+  return (
+    layer.encoding?.x?.scale !== undefined &&
+    layer.encoding?.y?.scale !== undefined
+  );
+}
+
+function hasPolarPositionScales(layer) {
+  return (
+    layer.encoding?.theta?.scale !== undefined &&
+    layer.encoding?.radius?.scale !== undefined
+  );
+}
+
+export function canMaterializePoint(_program, layer) {
+  return layer.mark?.type === "point" && (
+    hasCartesianPositionScales(layer) || hasPolarPositionScales(layer)
+  );
+}
+
+export function canMaterializeLine(program, layer) {
+  const parallel = layer.encoding?.parallel;
+  if (parallel !== undefined) {
+    const coordinate = findCoordinate(program, layer.coordinate);
+    return layer.mark?.type === "line" &&
+      coordinate?.type === "parallel" &&
+      parallel.dimensions?.length >= 2 &&
+      parallel.dimensions.every(dimension => dimension.scale !== undefined);
+  }
+  const dataset = findDataset(program, layer.data);
+  const interval = dataset?.transform?.some(item => item.type === "interval");
+  if (hasPolarPositionScales(layer)) {
+    return (
+      layer.mark?.type === "line" &&
+      ["quantitative", "temporal", "ordinal", "nominal"].includes(
+        layer.encoding.theta.fieldType
+      ) &&
+      layer.encoding.radius.fieldType === "quantitative"
+    );
+  }
+  return (
+    layer.mark?.type === "line" &&
+    hasCartesianPositionScales(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" || !hasCartesianPositionScales(layer)) {
+    return false;
+  }
+  const dataset = findDataset(program, layer.data);
+  const densityTransform = findUpstreamTransform(program, dataset, "density");
+  if (isIntentionallyEmptyArea(program, layer)) return false;
+  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 isIntentionallyEmptyArea(program, layer) {
+  if (
+    layer.mark?.type !== "area" ||
+    !Array.isArray(program.semanticSpec?.datasets)
+  ) return false;
+  const dataset = findDataset(program, layer.data);
+  return dataset?.values?.length === 0 &&
+    findUpstreamTransform(program, dataset, "horizon") !== undefined;
+}
+
+export function canMaterializeArc(_program, layer) {
+  if (
+    layer.mark?.type !== "arc" ||
+    layer.encoding?.theta?.scale === undefined ||
+    !["nominal", "ordinal"].includes(layer.encoding.theta.fieldType)
+  ) {
+    return false;
+  }
+  if (["count", "sum"].includes(layer.encoding.theta.aggregate)) {
+    return layer.encoding?.radius === undefined;
+  }
+  return (
+    layer.encoding.theta.aggregate === undefined &&
+    layer.encoding?.radius?.scale !== undefined &&
+    layer.encoding.radius.fieldType === "quantitative"
+  );
+}
+
+export function canMaterializeBar(program, layer) {
+  if (layer.mark?.type !== "bar" || !hasCartesianPositionScales(layer)) {
+    return false;
+  }
+  const grain = resolveBarGrain(layer);
+  if (![BAR_GRAINS.histogram, BAR_GRAINS.aggregate, BAR_GRAINS.ranged].includes(grain)) {
+    return false;
+  }
+  if (
+    grain === BAR_GRAINS.aggregate &&
+    resolveBarColorLayout(layer) === "group"
+  ) {
+    const offsetChannel = resolveBarOffsetChannel(layer);
+    return (
+      layer.encoding?.color?.field !== undefined &&
+      layer.encoding?.[offsetChannel]?.field === layer.encoding.color.field &&
+      layer.encoding[offsetChannel].scale !== undefined
+    );
+  }
+  return true;
+}
+
+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 && hasCartesianPositionScales(layer)) ||
+    (fixedSpan !== undefined && hasCartesianPositionScales(layer))
+  );
+}
+
+export function canMaterializeText(program, layer) {
+  if (layer.mark?.type !== "text" || layer.encoding?.text === undefined) {
+    return false;
+  }
+  if (layer.source !== undefined) {
+    const source = findLayer(program, layer.source);
+    return source !== undefined &&
+      ["point", "bar", "rule", "rect"].includes(source.mark?.type) &&
+      Array.isArray(program.graphicSpec.objects[source.id]?.items);
+  }
+  return hasCartesianPositionScales(layer);
+}
+
+export function canMaterializeRect(_program, layer) {
+  return resolveRectMode(layer) !== undefined;
+}

package/src/materialization/marks/index.js

@@ -0,0 +1,108 @@
+import { POSITION_CHANNELS } from "../../core/vocabulary.js";
+import { getMarkMaterializationPolicy } from "./policies.js";
+
+export {
+  canMaterializeArc,
+  canMaterializeArea,
+  canMaterializeBar,
+  canMaterializeLine,
+  canMaterializePoint,
+  canMaterializeRect,
+  canMaterializeRule,
+  canMaterializeText
+} from "./capabilities.js";
+
+export function getMarkRematerializationStep(layer) {
+  const policy = getMarkMaterializationPolicy(layer);
+  return policy === undefined
+    ? undefined
+    : { op: policy.op, args: { id: layer.id } };
+}
+
+export function getMarkMaterializationStep(program, layer) {
+  const policy = getMarkMaterializationPolicy(layer);
+  if (policy === undefined || !policy.canMaterialize(program, layer)) {
+    return undefined;
+  }
+  return getMarkRematerializationStep(layer);
+}
+
+export function getSourceDependentMarkSteps(program, sourceId) {
+  return program.semanticSpec.layers.flatMap(layer =>
+    layer.source === sourceId &&
+    getMarkMaterializationPolicy(layer)?.sourceDependent === true
+      ? [getMarkMaterializationStep(program, layer)].filter(
+          step => step !== undefined
+        )
+      : []
+  );
+}
+
+export function getPositionEncodingMaterializationSteps(program, layer, scaleId) {
+  const policy = getMarkMaterializationPolicy(layer);
+  if (policy === undefined) return [];
+  const scale = { op: "rematerializeScale", args: { id: scaleId } };
+  const complete = policy.canMaterialize(program, layer);
+  const mark = getMarkRematerializationStep(layer);
+  if (!complete) {
+    if (policy.positionEncoding.incomplete === "scale") return [scale];
+    return policy.positionEncoding.scaleFirst ? [scale, mark] : [mark];
+  }
+  return policy.positionEncoding.scaleFirst ? [scale, mark] : [mark];
+}
+
+export function getScaleConsumerMaterializationMode(layer, channel) {
+  const policy = getMarkMaterializationPolicy(layer);
+  if (policy === undefined) return "direct";
+  if (POSITION_CHANNELS.includes(channel)) {
+    return policy.scaleApplication.position ?? policy.scaleApplication.default;
+  }
+  if (policy.scaleApplication.deferredChannels?.includes(channel)) {
+    return "defer";
+  }
+  return policy.scaleApplication.default;
+}
+
+export function canDeferScaleConsumerApplication(layer) {
+  return getMarkMaterializationPolicy(layer)?.scaleApplication.deferWithMark === true;
+}
+
+export function getExistingMarkRematerializationStep(program, layer) {
+  const policy = getMarkMaterializationPolicy(layer);
+  if (
+    policy?.rematerializeIncompleteExisting !== true ||
+    program.graphicSpec.objects[layer.id] === undefined
+  ) {
+    return undefined;
+  }
+  return getMarkRematerializationStep(layer);
+}
+
+export function getEncodingMaterializationStages(program, layer, channel, scale) {
+  const policy = getMarkMaterializationPolicy(layer);
+  if (policy === undefined) return { scales: [], marks: [] };
+  const scales = policy.encoding?.scaleFirst === true && scale !== undefined
+    ? [{
+        op: "rematerializeScale",
+        args: { id: scale, guides: false, marks: false }
+      }]
+    : [];
+  const shared = policy.encoding?.sharedChannels?.includes(channel) === true &&
+    scale !== undefined;
+  const candidates = shared
+    ? program.semanticSpec.layers.filter(candidate =>
+        candidate.mark?.type === layer.mark?.type &&
+        candidate.encoding?.[channel]?.scale === scale
+      )
+    : [layer];
+  const marks = candidates.flatMap(candidate => {
+    if (policy.encoding?.skipRematerialization?.(program, candidate) === true) {
+      return [];
+    }
+    const step = policy.encoding?.completeOnly === true
+      ? getMarkMaterializationStep(program, candidate)
+      : getMarkRematerializationStep(candidate);
+    return step === undefined ? [] : [step];
+  });
+  return { scales, marks };
+}

package/src/materialization/marks/pathOrder.js

@@ -0,0 +1,71 @@
+import { isAggregate } from "../../grammar/aggregate.js";
+import { findTransformPolicy } from "../../grammar/transforms.js";
+import { findDataset } from "../../selectors/datasets.js";
+
+function hasRowPreservingProvenance(program, dataset) {
+  const visited = new Set();
+  let current = dataset;
+  while (current?.source !== undefined) {
+    if (visited.has(current.id) || current.transform?.length !== 1) return false;
+    visited.add(current.id);
+    const policy = findTransformPolicy(current.transform[0].type);
+    if (
+      policy?.facetTopology !== "rowPreserving" &&
+      policy?.provenanceTransparent !== true
+    ) {
+      return false;
+    }
+    current = findDataset(program, current.source);
+    if (current === undefined) return false;
+  }
+  return current !== undefined;
+}
+
+function isPolar(layer) {
+  return layer.encoding?.theta !== undefined ||
+    layer.encoding?.radius !== undefined;
+}
+
+function isCompositePath(program, layer) {
+  const config = program.markConfigs[layer.id];
+  return config?.errorBand !== undefined ||
+    config?.errorBandBoundary !== undefined ||
+    config?.regression !== undefined;
+}
+
+export function pathOrderCompatibility(program, layer) {
+  if (!["line", "area"].includes(layer?.mark?.type)) {
+    return { compatible: false, reason: "requires a line or area mark" };
+  }
+  if (isPolar(layer)) {
+    return { compatible: false, reason: "does not support Polar paths" };
+  }
+  const dataset = findDataset(program, layer.data);
+  if (dataset === undefined) {
+    return { compatible: false, reason: "requires an existing dataset" };
+  }
+  if (!hasRowPreservingProvenance(program, dataset)) {
+    return {
+      compatible: false,
+      reason: "requires raw or row-preserving source data"
+    };
+  }
+  if (isCompositePath(program, layer)) {
+    return {
+      compatible: false,
+      reason: "does not support generated error or regression paths"
+    };
+  }
+  if (layer.mark.type === "line" && isAggregate(layer.encoding?.y?.aggregate)) {
+    return { compatible: false, reason: "does not support aggregate lines" };
+  }
+  return { compatible: true, dataset };
+}
+
+export function assertPathOrderCompatible(program, layer, operation) {
+  const result = pathOrderCompatibility(program, layer);
+  if (!result.compatible) {
+    throw new Error(`${operation} ${result.reason} on mark "${layer?.id}".`);
+  }
+  return result.dataset;
+}

package/src/materialization/marks/policies.js

@@ -0,0 +1,91 @@
+import {
+  canMaterializeArc,
+  canMaterializeArea,
+  canMaterializeBar,
+  canMaterializeLine,
+  canMaterializePoint,
+  canMaterializeRect,
+  canMaterializeRule,
+  canMaterializeText,
+  isIntentionallyEmptyArea
+} from "./capabilities.js";
+
+const MARK_MATERIALIZATION_POLICIES = Object.freeze({
+  point: Object.freeze({
+    canMaterialize: canMaterializePoint,
+    op: "rematerializePointMark",
+    positionEncoding: Object.freeze({ incomplete: "mark", scaleFirst: true }),
+    encoding: Object.freeze({ scaleFirst: true }),
+    scaleApplication: Object.freeze({
+      deferWithMark: true,
+      position: "rematerialize",
+      deferredChannels: Object.freeze(["size", "shape"]),
+      default: "direct"
+    }),
+    rematerializeIncompleteExisting: true
+  }),
+  line: Object.freeze({
+    canMaterialize: canMaterializeLine,
+    op: "rematerializeLineMark",
+    positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: false }),
+    scaleApplication: Object.freeze({ default: "defer" })
+  }),
+  area: Object.freeze({
+    canMaterialize: canMaterializeArea,
+    op: "rematerializeAreaMark",
+    positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: true }),
+    encoding: Object.freeze({
+      sharedChannels: Object.freeze(["color"]),
+      skipRematerialization: isIntentionallyEmptyArea
+    }),
+    scaleApplication: Object.freeze({ default: "defer" })
+  }),
+  arc: Object.freeze({
+    canMaterialize: canMaterializeArc,
+    op: "rematerializeArcMark",
+    positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: false }),
+    encoding: Object.freeze({ completeOnly: true }),
+    scaleApplication: Object.freeze({ default: "defer" })
+  }),
+  bar: Object.freeze({
+    canMaterialize: canMaterializeBar,
+    op: "rematerializeBarMark",
+    positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: false }),
+    scaleApplication: Object.freeze({ default: "defer" })
+  }),
+  rule: Object.freeze({
+    canMaterialize: canMaterializeRule,
+    op: "rematerializeRuleMark",
+    positionEncoding: Object.freeze({ incomplete: "mark", scaleFirst: false }),
+    scaleApplication: Object.freeze({ default: "defer" })
+  }),
+  text: Object.freeze({
+    canMaterialize: canMaterializeText,
+    op: "rematerializeTextMark",
+    positionEncoding: Object.freeze({ incomplete: "mark", scaleFirst: true }),
+    encoding: Object.freeze({ scaleFirst: true }),
+    scaleApplication: Object.freeze({
+      deferWithMark: true,
+      position: "rematerialize",
+      default: "defer"
+    }),
+    rematerializeIncompleteExisting: true,
+    sourceDependent: true
+  }),
+  rect: Object.freeze({
+    canMaterialize: canMaterializeRect,
+    op: "rematerializeRectMark",
+    positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: true }),
+    encoding: Object.freeze({ scaleFirst: true }),
+    scaleApplication: Object.freeze({
+      deferWithMark: true,
+      position: "rematerialize",
+      default: "defer"
+    }),
+    rematerializeIncompleteExisting: true
+  })
+});
+
+export function getMarkMaterializationPolicy(layer) {
+  return MARK_MATERIALIZATION_POLICIES[layer.mark?.type];
+}

package/src/materialization/rect.js

@@ -1,7 +1,7 @@
 import {
   mapOrdinalPositionValues,
   readScaleField
-} from "../grammar/scales.js";
+} from "../grammar/scales/index.js";
 import { RECT_MODES, resolveRectMode } from "../grammar/rects.js";
 import { DEFAULT_RECT_MARK } from "./rectConfig.js";
 import { mapScaleConsumerValues } from "./scales/map.js";

package/src/materialization/rowEncoding.js

@@ -5,7 +5,7 @@ import {
   readQuantitativeField,
   readScaleField,
   readTemporalField
-} from "../grammar/scales.js";
+} from "../grammar/scales/index.js";
 import { mapScaleConsumerValues } from "./scales/map.js";
 
 export function resolveRowEncodingValues(program, layer, dataset, channel) {