ggaction 0.0.2 → 0.0.3

package/src/materialization/composition.js

@@ -0,0 +1,152 @@
+import { freezeOwned } from "../core/immutable.js";
+import {
+  requireSingleOrderedGraphicByType
+} from "../grammar/schemas/graphicTree.js";
+import {
+  resolveCompositionLayout,
+  resolveCompositionSnapshotPlacement
+} from "../layout/composition.js";
+import { namespaceGraphicSnapshot } from "./compositionSnapshot.js";
+
+const ZERO_MARGIN = freezeOwned({ top: 0, right: 0, bottom: 0, left: 0 });
+
+export function requireChildCanvas(program, id) {
+  const { object } = requireSingleOrderedGraphicByType(program.graphicSpec, "canvas");
+  const { width, height } = object.properties ?? {};
+  if (!Number.isFinite(width) || width <= 0 || !Number.isFinite(height) || height <= 0) {
+    throw new Error(`Composition child "${id}" requires a complete positive Canvas size.`);
+  }
+  return object;
+}
+
+export function compositionChildDescriptor(id, program) {
+  const canvas = requireChildCanvas(program, id);
+  const size = program.materializationConfigs.canvas?.size ?? {
+    width: "explicit",
+    height: "explicit"
+  };
+  return {
+    id,
+    width: canvas.properties.width,
+    height: canvas.properties.height,
+    widthMode: size.width,
+    heightMode: size.height
+  };
+}
+
+export function resolveCompositionProgramLayout(program) {
+  program._assertCompositionProgram("resolveCompositionProgramLayout");
+  const spec = program.compositionSpec;
+  return resolveCompositionLayout({
+    direction: spec.direction,
+    children: spec.children.map(id => compositionChildDescriptor(id, program.children[id])),
+    gap: spec.gap,
+    align: spec.align,
+    padding: spec.padding
+  });
+}
+
+function resizeChildForSnapshot(program, placement) {
+  const canvas = requireSingleOrderedGraphicByType(program.graphicSpec, "canvas");
+  const widthChanged = canvas.object.properties.width !== placement.width;
+  const heightChanged = canvas.object.properties.height !== placement.height;
+  if (!widthChanged && !heightChanged) return program;
+
+  if (program.compositionSpec !== undefined) {
+    return program;
+  }
+  if (typeof program.editCanvas !== "function") {
+    throw new Error("Automatic composition sizing requires child editCanvas support.");
+  }
+  return program.editCanvas({
+    ...(widthChanged ? { width: placement.width } : {}),
+    ...(heightChanged ? { height: placement.height } : {})
+  });
+}
+
+function resolveSnapshotPlacement(program, placement, layout) {
+  if (program.compositionSpec === undefined) return placement;
+  const canvas = requireSingleOrderedGraphicByType(program.graphicSpec, "canvas");
+  return resolveCompositionSnapshotPlacement({
+    direction: layout.direction,
+    align: layout.align,
+    placement,
+    width: canvas.object.properties.width,
+    height: canvas.object.properties.height
+  });
+}
+
+function itemDefinitions(object) {
+  return object.items.map(item => ({
+    type: item.type ?? object.type,
+    properties: item.properties
+  }));
+}
+
+export function attachSnapshotObject(program, snapshot, id, parent) {
+  const object = snapshot.objects[id];
+  let next = program.createGraphics({
+    id,
+    type: object.type,
+    parent,
+    ...(object.items !== undefined && object.type !== "collection"
+      ? { length: object.items.length }
+      : {})
+  });
+  for (const [property, value] of Object.entries(object.properties ?? {})) {
+    next = next.editGraphics({ target: id, property, value });
+  }
+  if (object.items !== undefined) {
+    next = next.editGraphics({
+      target: id,
+      property: "items",
+      value: itemDefinitions(object)
+    });
+  }
+  for (const childId of object.children ?? []) {
+    next = attachSnapshotObject(next, snapshot, childId, id);
+  }
+  return next;
+}
+
+export function clearCompositionChildren(program) {
+  const canvas = program.graphicSpec.objects.canvas;
+  let next = program;
+  for (const id of canvas?.children ?? []) {
+    next = next.editGraphics({ target: id, remove: true });
+  }
+  return next;
+}
+
+export function materializeCompositionGraphics(program) {
+  program._assertCompositionProgram("materializeCompositionGraphics");
+  const layout = resolveCompositionProgramLayout(program);
+  let next = clearCompositionChildren(program);
+  if (next.graphicSpec.objects.canvas === undefined) {
+    next = next.createGraphics({ id: "canvas", type: "canvas" });
+  }
+  for (const [property, value] of Object.entries({
+    width: layout.width,
+    height: layout.height,
+    background: "white"
+  })) {
+    next = next.editGraphics({ target: "canvas", property, value });
+  }
+
+  for (const placement of layout.children) {
+    const source = program.children[placement.id];
+    const child = resizeChildForSnapshot(source, placement);
+    const snapshotPlacement = resolveSnapshotPlacement(child, placement, layout);
+    const snapshot = namespaceGraphicSnapshot(child.graphicSpec, {
+      namespace: `${program.compositionSpec.id}-${placement.id}`,
+      x: snapshotPlacement.x,
+      y: snapshotPlacement.y
+    });
+    next = attachSnapshotObject(next, snapshot, snapshot.order[0], "canvas");
+  }
+
+  return next._withCanvasConfig({
+    margin: ZERO_MARGIN,
+    size: { width: "auto", height: "auto" }
+  });
+}

package/src/materialization/compositionSnapshot.js

@@ -0,0 +1,114 @@
+import { cloneAndFreeze, freezeOwned, isPlainObject } from "../core/immutable.js";
+import {
+  requireSingleOrderedGraphicByType,
+  walkGraphicTreeEvents
+} from "../grammar/schemas/graphicTree.js";
+
+function validateNamespace(namespace) {
+  if (typeof namespace !== "string" || namespace.length === 0) {
+    throw new TypeError("Graphic snapshot namespace must be a non-empty string.");
+  }
+  return namespace;
+}
+
+function validatePlacement(value, property) {
+  if (!Number.isFinite(value)) {
+    throw new TypeError(`Graphic snapshot ${property} must be a finite number.`);
+  }
+  return value;
+}
+
+function validateCanvas(canvas, id) {
+  const { width, height } = canvas.properties ?? {};
+  if (!Number.isFinite(width) || width <= 0) {
+    throw new RangeError(`Child Canvas "${id}" width must be a positive finite number.`);
+  }
+  if (!Number.isFinite(height) || height <= 0) {
+    throw new RangeError(`Child Canvas "${id}" height must be a positive finite number.`);
+  }
+}
+
+export function namespaceGraphicId(namespace, id) {
+  const encode = value => Array.from(value, character =>
+    character.codePointAt(0).toString(16).padStart(6, "0")
+  ).join("");
+  return `g${encode(namespace)}_${encode(id)}`;
+}
+
+function rewriteItem(item, namespace) {
+  if (!isPlainObject(item) || typeof item.id !== "string" || item.id.length === 0) {
+    throw new TypeError("Graphic snapshot items require non-empty string ids.");
+  }
+  return freezeOwned({
+    ...cloneAndFreeze(item),
+    id: namespaceGraphicId(namespace, item.id)
+  });
+}
+
+function rewriteObject(object, namespace, rootCanvasId, placement, extraRoots) {
+  const children = object.children ?? [];
+  const rewritten = {
+    ...cloneAndFreeze(object),
+    ...(object.items === undefined
+      ? {}
+      : { items: freezeOwned(object.items.map(item => rewriteItem(item, namespace))) }),
+    ...(children.length === 0 && rootCanvasId === undefined
+      ? {}
+      : {
+          children: freezeOwned([
+            ...children.map(id => namespaceGraphicId(namespace, id)),
+            ...(rootCanvasId === undefined
+              ? []
+                : extraRoots.map(id => namespaceGraphicId(namespace, id)))
+          ])
+        })
+  };
+  if (rootCanvasId !== undefined) {
+    rewritten.properties = freezeOwned({
+      ...rewritten.properties,
+      x: placement.x,
+      y: placement.y
+    });
+  }
+  return freezeOwned(rewritten);
+}
+
+export function namespaceGraphicSnapshot(
+  graphicSpec,
+  { namespace, x = 0, y = 0 } = {}
+) {
+  const resolvedNamespace = validateNamespace(namespace);
+  const placement = {
+    x: validatePlacement(x, "x"),
+    y: validatePlacement(y, "y")
+  };
+  if (
+    !isPlainObject(graphicSpec) ||
+    !isPlainObject(graphicSpec.objects) ||
+    !Array.isArray(graphicSpec.order)
+  ) {
+    throw new TypeError("Graphic snapshot requires objects and order.");
+  }
+  walkGraphicTreeEvents(graphicSpec, {});
+  const { id: canvasId, object: canvas } =
+    requireSingleOrderedGraphicByType(graphicSpec, "canvas");
+  validateCanvas(canvas, canvasId);
+  const extraRoots = graphicSpec.order.filter(id => id !== canvasId);
+  const objects = Object.fromEntries(Object.entries(graphicSpec.objects).map(
+    ([id, object]) => [
+      namespaceGraphicId(resolvedNamespace, id),
+      rewriteObject(
+        object,
+        resolvedNamespace,
+        id === canvasId ? canvasId : undefined,
+        placement,
+        id === canvasId ? extraRoots : []
+      )
+    ]
+  ));
+  const rootId = namespaceGraphicId(resolvedNamespace, canvasId);
+  return freezeOwned({
+    objects: freezeOwned(objects),
+    order: freezeOwned([rootId])
+  });
+}

package/src/materialization/dependencies.js

@@ -1,4 +1,9 @@
-import { getMarkMaterializationStep } from "./marks.js";
+import {
+  canDeferScaleConsumerApplication,
+  getExistingMarkRematerializationStep,
+  getMarkMaterializationStep,
+  getSourceDependentMarkSteps
+} from "./marks.js";
 import { requireLayer } from "../selectors/layers.js";
 import {
   applyMaterializationPlan,
@@ -8,22 +13,34 @@ import {
   hasMaterializedLegend,
   materializedLegendUsesScale
 } from "./legends.js";
+import { POSITION_ENCODING_CHANNELS } from "../core/vocabulary.js";
 
 function usesPositionalScale(program, id) {
   return program.semanticSpec.layers.some(layer =>
-    ["x", "y", "x2", "y2", "xOffset"].some(
+    POSITION_ENCODING_CHANNELS.some(
       channel => layer.encoding?.[channel]?.scale === id
     )
   );
 }
 
+function usesRadialScale(program, id) {
+  return program.semanticSpec.layers.some(layer =>
+    layer.encoding?.radius?.scale === id
+  );
+}
+
 function needsCanvasScaleRematerialization(program, scale) {
   return (
     (scale.range === "auto" ||
+      usesRadialScale(program, scale.id) ||
       program.semanticSpec.guides.axis?.x?.scale === scale.id ||
       program.semanticSpec.guides.axis?.y?.scale === scale.id ||
+      program.semanticSpec.guides.axis?.theta?.scale === scale.id ||
+      program.semanticSpec.guides.axis?.radius?.scale === scale.id ||
       program.semanticSpec.guides.grid?.horizontal?.scale === scale.id ||
-      program.semanticSpec.guides.grid?.vertical?.scale === scale.id) &&
+      program.semanticSpec.guides.grid?.vertical?.scale === scale.id ||
+      program.semanticSpec.guides.grid?.theta?.scale === scale.id ||
+      program.semanticSpec.guides.grid?.radial?.scale === scale.id) &&
     program.resolvedScales[scale.id] !== undefined &&
     usesPositionalScale(program, scale.id)
   );
@@ -37,20 +54,36 @@ function hasTitle(program) {
 }
 
 export function planCanvasRematerialization(program) {
+  const marks = [];
+  for (const layer of program.semanticSpec.layers) {
+    const step = getMarkMaterializationStep(program, layer);
+    if (step !== undefined) marks.push(step);
+  }
+  const deferredMarkIds = new Set(
+    marks
+      .map(step => step.args.id)
+  );
   const scales = [];
   for (const scale of program.semanticSpec.scales) {
     if (needsCanvasScaleRematerialization(program, scale)) {
+      const deferredConsumers = program.semanticSpec.layers.filter(layer =>
+        canDeferScaleConsumerApplication(layer) &&
+        Object.values(layer.encoding ?? {}).some(
+          encoding => encoding?.scale === scale.id
+        )
+      );
+      const canDeferMarks = deferredConsumers.length === 0 ||
+        deferredConsumers.every(layer => deferredMarkIds.has(layer.id));
       scales.push({
         op: "rematerializeScale",
-        args: { id: scale.id, guides: false }
+        args: {
+          id: scale.id,
+          guides: false,
+          ...(canDeferMarks ? { marks: 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)
@@ -87,12 +120,27 @@ export function planScaleGuideRematerialization(program, id) {
       }
     }
   }
+  for (const channel of ["theta", "radius"]) {
+    const prefix = channel === "theta" ? "Theta" : "Radial";
+    for (const component of ["line", "ticks", "labels", "title"]) {
+      if (guideConfigs.axis?.[channel]?.[component]?.scale === id) {
+        const suffix = component[0].toUpperCase() + component.slice(1);
+        guides.push({ op: `edit${prefix}Axis${suffix}` });
+      }
+    }
+  }
   if (guideConfigs.grid?.horizontal?.scale === id) {
     guides.push({ op: "rematerializeHorizontalGrid" });
   }
   if (guideConfigs.grid?.vertical?.scale === id) {
     guides.push({ op: "rematerializeVerticalGrid" });
   }
+  if (guideConfigs.grid?.theta?.scale === id) {
+    guides.push({ op: "rematerializeThetaGrid" });
+  }
+  if (guideConfigs.grid?.radial?.scale === id) {
+    guides.push({ op: "rematerializeRadialGrid" });
+  }
   if (materializedLegendUsesScale(program, id)) {
     guides.push({ op: "rematerializeLegend" });
   }
@@ -106,22 +154,29 @@ export function planLayerDataRematerialization(program, id) {
       .map(encoding => encoding?.scale)
       .filter(scale => scale !== undefined)
   )];
+  const markStep = getMarkMaterializationStep(program, layer);
   const scales = scaleIds.map(scale => ({
       op: "rematerializeScale",
-      args: { id: scale, guides: false }
+      args: {
+        id: scale,
+        guides: false,
+        ...(markStep === undefined ? {} : { marks: false })
+      }
     }));
-  const markStep = getMarkMaterializationStep(program, layer);
-  const marks = markStep === undefined ? [] : [markStep];
+  const marks = [
+    ...(markStep === undefined ? [] : [markStep]),
+    ...getSourceDependentMarkSteps(program, id)
+  ];
   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 } }]
-    : [] });
+  const existingStep = getExistingMarkRematerializationStep(program, layer);
+  return buildMaterializationPlan({
+    marks: existingStep === undefined ? [] : [existingStep]
+  });
 }
 
 export function applyLayerDataRematerialization(program, id) {

package/src/materialization/encodings.js

@@ -1,7 +1,10 @@
 import { hasMaterializedLegend } from "./legends.js";
 import { requireLayer } from "../selectors/layers.js";
-import { getMarkRematerializationStep } from "./marks.js";
+import {
+  getEncodingMaterializationStages
+} from "./marks.js";
 import { buildMaterializationPlan } from "./planner.js";
+import { getSourceDependentMarkSteps } from "./marks.js";
 
 export function planEncodingRematerialization(program, {
   target,
@@ -14,33 +17,16 @@ export function planEncodingRematerialization(program, {
     `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 { scales, marks: directMarks } = getEncodingMaterializationStages(
+    program,
+    layer,
+    channel,
+    scale
+  );
+  const marks = [
+    ...directMarks,
+    ...getSourceDependentMarkSteps(program, target)
+  ];
 
   const guides = [];
   if (hasMaterializedLegend(program)) {