ggaction 0.0.2 → 0.0.3

package/src/materialization/facetGuides.js

@@ -0,0 +1,426 @@
+import { isPlainObject } from "../core/immutable.js";
+import { unionConcreteGraphicBounds } from
+  "../grammar/schemas/graphicBounds.js";
+import {
+  planFacetGuideOwnership,
+  resolveSharedFacetLegends
+} from "../grammar/facets/guides.js";
+import { mapOrdinalValues } from "../grammar/scales.js";
+import { findLayer } from "../selectors/layers.js";
+import { findSemanticScale } from "../selectors/scales.js";
+import { axisGraphicIds, allLegendGraphicIds } from
+  "./guides/resources.js";
+import { attachSnapshotObject } from "./composition.js";
+import { namespaceGraphicId } from "./compositionSnapshot.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../theme/defaults.js";
+
+const LEGEND_SOURCE_CANVAS = Object.freeze({
+  width: 640,
+  height: 400,
+  margin: Object.freeze({ top: 40, right: 170, bottom: 60, left: 70 })
+});
+
+function legendKinds(program) {
+  return Object.keys(program.guideConfigs.legend ?? {});
+}
+
+function textItem(text, x, y, options = {}) {
+  return {
+    type: "text",
+    properties: {
+      x,
+      y,
+      text: String(text),
+      fill: options.color ?? DEFAULT_COLORS.strongText,
+      fontSize: options.fontSize ?? 12,
+      fontFamily: options.fontFamily ?? DEFAULT_FONT_FAMILY,
+      fontWeight: options.fontWeight ?? "normal",
+      textAlign: options.textAlign ?? "left",
+      textBaseline: options.textBaseline ?? "middle"
+    }
+  };
+}
+
+function collection(program, id, items) {
+  return program
+    .createGraphics({ id, type: "collection", parent: "canvas" })
+    .editGraphics({ target: id, property: "items", value: items });
+}
+
+function resolveLegacyCategoricalLegend(program) {
+  const encodings = program.semanticSpec.layers.flatMap(layer =>
+    layer.encoding?.color === undefined
+      ? []
+      : [{ layer, encoding: layer.encoding.color }]
+  );
+  if (encodings.length === 0) return undefined;
+  const fields = new Set(encodings.map(entry => entry.encoding.field));
+  const scales = new Set(encodings.map(entry => entry.encoding.scale));
+  const marks = new Set(encodings.map(entry => entry.layer.mark?.type));
+  if (fields.size !== 1 || scales.size !== 1 || marks.size !== 1) {
+    throw new Error(
+      "Shared facet legend requires one compatible color field, scale, and mark recipe."
+    );
+  }
+  if (encodings.some(entry =>
+    !["nominal", "ordinal"].includes(entry.encoding.fieldType)
+  )) {
+    return undefined;
+  }
+  const firstId = program.compositionSpec.children[0];
+  const scaleId = encodings[0].encoding.scale;
+  const scale = program.children[firstId].resolvedScales[scaleId];
+  if (scale?.type !== "ordinal") return undefined;
+  const config = {
+    kind: "color",
+    target: encodings[0].layer.id,
+    field: encodings[0].encoding.field,
+    scale: scaleId,
+    title: encodings[0].encoding.field
+  };
+  const compatibility = resolveSharedFacetLegends(
+    program.compositionSpec.children.map(id => ({
+      id,
+      guideConfigs: { legend: { color: config } },
+      resolvedScales: program.children[id].resolvedScales
+    }))
+  );
+  return {
+    mode: "legacyCategorical",
+    compatibility,
+    reservation: { gap: 18, width: 132 },
+    legend: {
+      field: config.field,
+      mark: encodings[0].layer.mark.type,
+      domain: scale.domain,
+      colors: mapOrdinalValues(scale.domain, scale.domain, scale.range)
+    }
+  };
+}
+
+function materializeLegacyCategoricalLegend(program, prepared, layout) {
+  const legend = prepared.legend;
+  const items = [textItem(legend.field, layout.legend.x, layout.legend.y, {
+    fontSize: 12,
+    fontWeight: 700,
+    textBaseline: "top"
+  })];
+  legend.domain.forEach((value, index) => {
+    const y = layout.legend.y + 29 + index * 26;
+    items.push(legend.mark === "point"
+      ? {
+          type: "circle",
+          properties: {
+            x: layout.legend.x + 7,
+            y,
+            radius: 5.5,
+            fill: legend.colors[index],
+            stroke: "#ffffff",
+            strokeWidth: 0.35,
+            opacity: 1
+          }
+        }
+      : {
+          type: "rect",
+          properties: {
+            x: layout.legend.x + 1,
+            y: y - 6,
+            width: 12,
+            height: 12,
+            fill: legend.colors[index],
+            stroke: "#ffffff",
+            strokeWidth: 0.6,
+            opacity: 1
+          }
+        });
+    items.push(textItem(value, layout.legend.x + 22, y, {
+      fontSize: 10.5
+    }));
+  });
+  return collection(
+    program,
+    `${program.compositionSpec.id}-legend`,
+    items
+  );
+}
+
+function legendCandidates(program) {
+  const layers = program.semanticSpec.layers;
+  const color = layers.filter(layer => {
+    const encoding = layer.encoding?.color;
+    return encoding?.scale !== undefined &&
+      findSemanticScale(program, encoding.scale) !== undefined;
+  });
+  if (color.length === 1) {
+    const layer = color[0];
+    return {
+      target: layer.id,
+      channels: ["color", "shape", "strokeDash"].filter(
+        channel => layer.encoding?.[channel]?.scale !== undefined
+      )
+    };
+  }
+  if (color.length > 1) {
+    throw new Error(
+      "Shared facet legend requires one unambiguous color legend target."
+    );
+  }
+  for (const channel of ["shape", "strokeDash", "size", "opacity"]) {
+    const candidates = layers.filter(
+      layer => layer.encoding?.[channel]?.scale !== undefined
+    );
+    if (candidates.length === 1) {
+      return { target: candidates[0].id, channels: [channel] };
+    }
+    if (candidates.length > 1) {
+      throw new Error(
+        `Shared facet legend requires one unambiguous ${channel} legend target.`
+      );
+    }
+  }
+  throw new Error("Shared facet legend requires one eligible encoded scale.");
+}
+
+function compactNumber(value) {
+  if (Math.abs(value) >= 1_000_000_000) {
+    return `${+(value / 1_000_000_000).toFixed(1)}B`;
+  }
+  if (Math.abs(value) >= 1_000_000) {
+    return `${Math.round(value / 1_000_000)}M`;
+  }
+  if (Math.abs(value) >= 1_000) {
+    return `${Math.round(value / 1_000)}K`;
+  }
+  return String(+value.toPrecision(3));
+}
+
+function continuousValues(domain, count) {
+  return Array.from(
+    { length: count },
+    (_, index) => domain[0] + index / (count - 1) * (domain[1] - domain[0])
+  );
+}
+
+function prepareAutoLegendSource(child) {
+  const request = legendCandidates(child);
+  const canvas = child.graphicSpec.objects.canvas;
+  let source = child
+    ._withCanvasConfig({
+      margin: LEGEND_SOURCE_CANVAS.margin,
+      size: { width: "explicit", height: "explicit" }
+    })
+    .editGraphics({
+      target: "canvas",
+      property: "width",
+      value: LEGEND_SOURCE_CANVAS.width
+    })
+    .editGraphics({
+      target: "canvas",
+      property: "height",
+      value: LEGEND_SOURCE_CANVAS.height
+    });
+  if (canvas?.properties.background !== undefined) {
+    source = source.editGraphics({
+      target: "canvas",
+      property: "background",
+      value: canvas.properties.background
+    });
+  }
+  const scale = findSemanticScale(
+    source,
+    findLayer(source, request.target)?.encoding?.color?.scale
+  );
+  const gradient = scale?.type === "sequential";
+  source = source.createLegend({
+    target: request.target,
+    channels: request.channels,
+    ...(gradient ? {
+      count: 5,
+      gradient: { length: 180, thickness: 12 },
+      labels: { offset: 9, fontSize: 10 },
+      titleStyle: { color: DEFAULT_COLORS.strongText, fontSize: 11 }
+    } : {})
+  });
+  if (gradient) {
+    const resolved = source.resolvedScales[scale.id];
+    source = source
+      .editGraphics({
+        target: "colorGradientLabels",
+        property: "text",
+        value: continuousValues(resolved.domain, 5).map(compactNumber)
+      })
+      .editGraphics({
+        target: "colorGradientTitle",
+        property: "y",
+        value: source.graphicSpec.objects.colorGradientTitle.properties.y + 8
+      });
+  }
+  return source;
+}
+
+function compatibleLegendChildren(program, source, inferred) {
+  return program.compositionSpec.children.map(id => {
+    const child = program.children[id];
+    return {
+      id,
+      guideConfigs: inferred ? source.guideConfigs : child.guideConfigs,
+      resolvedScales: child.resolvedScales
+    };
+  });
+}
+
+export function prepareSharedFacetLegend(program) {
+  if (program.compositionSpec.facet.guides.legend !== "shared") {
+    return undefined;
+  }
+  const firstId = program.compositionSpec.children[0];
+  const first = program.children[firstId];
+  const inferred = legendKinds(first).length === 0;
+  if (inferred) {
+    const legacy = resolveLegacyCategoricalLegend(program);
+    if (legacy !== undefined) return legacy;
+  }
+  const source = inferred ? prepareAutoLegendSource(first) : first;
+  const kinds = legendKinds(source);
+  const compatibility = resolveSharedFacetLegends(
+    compatibleLegendChildren(program, source, inferred)
+  );
+  const roots = allLegendGraphicIds(kinds).filter(
+    id => source.graphicSpec.objects[id] !== undefined
+  );
+  if (roots.length === 0) {
+    throw new Error("Shared facet legend has no concrete guide graphics.");
+  }
+  const bounds = unionConcreteGraphicBounds(source.graphicSpec, roots);
+  if (bounds === undefined) {
+    throw new Error("Shared facet legend has no measurable concrete bounds.");
+  }
+  const gradient = kinds.includes("gradient");
+  return {
+    mode: "promoted",
+    source,
+    inferred,
+    kinds,
+    roots,
+    bounds,
+    compatibility,
+    reservation: {
+      gap: gradient ? 24 : 18,
+      width: gradient ? 112 : Math.max(132, Math.ceil(bounds.right - bounds.left))
+    }
+  };
+}
+
+function copyLegendConfig(program, source) {
+  let next = program;
+  for (const [kind, config] of Object.entries(source.guideConfigs.legend ?? {})) {
+    next = next._withLegendConfig(kind, config);
+  }
+  return next;
+}
+
+function removeNamespacedGraphics(program, namespace, ids) {
+  let next = program;
+  for (const id of ids) {
+    const target = namespaceGraphicId(namespace, id);
+    if (next.graphicSpec.objects[target] !== undefined) {
+      next = next.editGraphics({ target, remove: true });
+    }
+  }
+  return next;
+}
+
+function gradientAnchor(prepared, plot, layout) {
+  const strips = prepared.source.graphicSpec.objects.colorGradientStrips;
+  if (strips?.items?.[0] === undefined) return undefined;
+  const properties = strips.items[0].properties;
+  const length = prepared.source.guideConfigs.legend.gradient.gradient.length;
+  return {
+    sourceX: properties.x,
+    sourceY: properties.y,
+    targetX: layout.legend.x,
+    targetY: plot.y + (plot.height - length) / 2
+  };
+}
+
+function legendTranslation(prepared, plot, layout) {
+  const gradient = gradientAnchor(prepared, plot, layout);
+  if (gradient !== undefined) {
+    return {
+      x: gradient.targetX - gradient.sourceX,
+      y: gradient.targetY - gradient.sourceY
+    };
+  }
+  const height = prepared.bounds.bottom - prepared.bounds.top;
+  return {
+    x: layout.legend.x - prepared.bounds.left,
+    y: plot.y + Math.max(0, (plot.height - height) / 2) - prepared.bounds.top
+  };
+}
+
+function attachParentLegend(program, prepared, plot, layout) {
+  const translation = legendTranslation(prepared, plot, layout);
+  const canvas = prepared.source.graphicSpec.objects.canvas;
+  const id = `${program.compositionSpec.id}-shared-legend`;
+  let next = copyLegendConfig(program, prepared.source)
+    .createGraphics({ id, type: "canvas", parent: "canvas" });
+  for (const [property, value] of Object.entries({
+    x: translation.x,
+    y: translation.y,
+    width: canvas.properties.width,
+    height: canvas.properties.height,
+    background: "transparent"
+  })) {
+    next = next.editGraphics({ target: id, property, value });
+  }
+  for (const root of prepared.roots) {
+    next = attachSnapshotObject(next, prepared.source.graphicSpec, root, id);
+  }
+  return next;
+}
+
+export function applyFacetGuideComposition(program, { layout, plot } = {}) {
+  if (!isPlainObject(layout) || !Array.isArray(layout.children)) {
+    throw new TypeError("Facet guide composition requires a resolved layout.");
+  }
+  if (!isPlainObject(plot)) {
+    throw new TypeError("Facet guide composition requires resolved plot bounds.");
+  }
+  const prepared = prepareSharedFacetLegend(program);
+  const children = layout.children.map(cell => {
+    const child = program.children[cell.id];
+    return {
+      id: cell.id,
+      axes: Object.keys(child.guideConfigs.axis ?? {})
+        .filter(channel => ["x", "y"].includes(channel)),
+      legendKinds: legendKinds(child)
+    };
+  });
+  const ownership = planFacetGuideOwnership({
+    placements: layout.children,
+    children,
+    axes: program.compositionSpec.facet.guides.axes,
+    legend: program.compositionSpec.facet.guides.legend,
+    ...(prepared === undefined ? {} : { sharedLegends: prepared.compatibility })
+  });
+  let next = program;
+  for (const cell of layout.children) {
+    const namespace = `${program.compositionSpec.id}-${cell.id}`;
+    const childPlan = ownership.children[cell.id];
+    for (const channel of childPlan.removeAxes) {
+      next = removeNamespacedGraphics(next, namespace, axisGraphicIds(channel));
+    }
+    if (childPlan.removeLegends.length > 0) {
+      next = removeNamespacedGraphics(
+        next,
+        namespace,
+        allLegendGraphicIds(childPlan.removeLegends)
+      );
+    }
+  }
+  if (prepared === undefined) return next;
+  if (prepared.mode === "legacyCategorical") {
+    return materializeLegacyCategoricalLegend(next, prepared, layout);
+  }
+  return attachParentLegend(next, prepared, plot, layout);
+}

package/src/materialization/facets.js

@@ -0,0 +1,214 @@
+import { resolveGraphicBounds } from "../layout/canvas.js";
+import { resolvePlacedPlotBounds } from "../layout/composition.js";
+import {
+  alignedTextAnchor,
+  buildTitleReadingBlock
+} from "../layout/title.js";
+import { resolveFacetLayout } from "../layout/facets.js";
+import { namespaceGraphicSnapshot } from "./compositionSnapshot.js";
+import { prepareSharedFacetLegend } from "./facetGuides.js";
+import {
+  attachSnapshotObject,
+  clearCompositionChildren,
+  compositionChildDescriptor
+} from "./composition.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../theme/defaults.js";
+
+const ZERO_MARGIN = Object.freeze({ top: 0, right: 0, bottom: 0, left: 0 });
+
+function facetConfig(program) {
+  const config = program.materializationConfigs.facets?.[program.compositionSpec.id];
+  if (config === undefined) {
+    throw new Error(`Facet "${program.compositionSpec.id}" requires materialization config.`);
+  }
+  return config;
+}
+
+function titleLayout(program) {
+  if (program.semanticSpec.title.text === undefined) {
+    return { height: 0 };
+  }
+  const config = program.titleConfig;
+  if (config === undefined) {
+    throw new Error("Facet title requires chart title configuration.");
+  }
+  if (config.position !== "top") {
+    throw new Error("Facet parent title currently supports only top position.");
+  }
+  const block = buildTitleReadingBlock({
+    text: program.semanticSpec.title.text,
+    subtitle: program.semanticSpec.title.subtitle
+  }, config);
+  const top = 8 + config.offset;
+  if (top < 0) {
+    throw new Error("Facet parent title offset places text outside the Canvas.");
+  }
+  return { config, block, top, height: Math.ceil(top + block.height) };
+}
+
+function textItem(text, x, y, options = {}) {
+  return {
+    type: "text",
+    properties: {
+      x,
+      y,
+      text: String(text),
+      fill: options.color ?? DEFAULT_COLORS.strongText,
+      fontSize: options.fontSize ?? 12,
+      fontFamily: options.fontFamily ?? DEFAULT_FONT_FAMILY,
+      fontWeight: options.fontWeight ?? "normal",
+      textAlign: options.textAlign ?? "left",
+      textBaseline: options.textBaseline ?? "middle"
+    }
+  };
+}
+
+function collection(program, id, items) {
+  return program
+    .createGraphics({ id, type: "collection", parent: "canvas" })
+    .editGraphics({ target: id, property: "items", value: items });
+}
+
+function materializeHeaders(program, layout, plots, config) {
+  const plotById = new Map(plots.map(plot => [plot.id, plot]));
+  const items = layout.children.map(cell => {
+    const plot = plotById.get(cell.id);
+    if (plot === undefined) {
+      throw new Error(`Facet header requires plot bounds for "${cell.id}".`);
+    }
+    return textItem(
+      cell.value,
+      cell.x + plot.x + plot.width / 2,
+      cell.y + config.offset,
+      {
+        color: config.color,
+        fontSize: config.fontSize,
+        fontFamily: config.fontFamily,
+        fontWeight: config.fontWeight,
+        textAlign: "center",
+        textBaseline: "top"
+      }
+    );
+  });
+  return collection(program, `${program.compositionSpec.id}-headers`, items);
+}
+
+function materializeTitleComponent(program, id, lines, centers, style, plot, top) {
+  if (lines.length === 0) return program;
+  const x = alignedTextAnchor(plot.x, plot.width, program.titleConfig.align);
+  const count = lines.length;
+  let next = program.createGraphics({
+    id,
+    type: "text",
+    ...(count > 1 ? { length: count } : {}),
+    parent: "canvas"
+  });
+  for (const [property, value] of Object.entries({
+    x,
+    y: count === 1 ? top + centers[0] : centers.map(center => top + center),
+    text: count === 1 ? lines[0] : lines,
+    fill: style.color,
+    fontSize: style.fontSize,
+    fontFamily: style.fontFamily,
+    fontWeight: style.fontWeight,
+    textAlign: program.titleConfig.align,
+    textBaseline: "middle"
+  })) {
+    next = next.editGraphics({ target: id, property, value });
+  }
+  return next;
+}
+
+function materializeTitle(program, plot, title) {
+  let next = materializeTitleComponent(
+    program,
+    "chartTitle",
+    title.block.titleLines,
+    title.block.titleCenters,
+    title.config.titleStyle,
+    plot,
+    title.top
+  );
+  if (title.block.subtitleLines.length > 0) {
+    next = materializeTitleComponent(
+      next,
+      "chartSubtitle",
+      title.block.subtitleLines,
+      title.block.subtitleCenters,
+      title.config.subtitleStyle,
+      plot,
+      title.top
+    );
+  }
+  return next;
+}
+
+export function resolveFacetProgramLayout(program, preparedLegend) {
+  program._assertCompositionProgram("resolveFacetProgramLayout");
+  if (program.compositionSpec.type !== "facet") {
+    throw new Error("resolveFacetProgramLayout requires a facet composition.");
+  }
+  const title = titleLayout(program);
+  const spec = program.compositionSpec;
+  const layout = resolveFacetLayout({
+    children: spec.children.map((id, index) => ({
+      ...compositionChildDescriptor(id, program.children[id]),
+      value: spec.facet.values[index]
+    })),
+    columns: spec.columns,
+    gap: spec.gap,
+    align: spec.align,
+    padding: spec.padding,
+    titleHeight: title.height,
+    sharedLegend: spec.facet.guides.legend === "shared",
+    ...(preparedLegend === undefined ? {} : {
+      sharedLegendGap: preparedLegend.reservation.gap,
+      sharedLegendWidth: preparedLegend.reservation.width
+    })
+  });
+  const plots = spec.children.map(id => ({
+    id,
+    ...resolveGraphicBounds(program.children[id])
+  }));
+  const plot = resolvePlacedPlotBounds({
+    placements: layout.children,
+    plots
+  });
+  return { layout, title, plot, plots };
+}
+
+export function materializeFacetGraphics(program) {
+  const preparedLegend = prepareSharedFacetLegend(program);
+  const { layout, title, plot, plots } = resolveFacetProgramLayout(
+    program,
+    preparedLegend
+  );
+  const config = facetConfig(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 child = program.children[placement.id];
+    const snapshot = namespaceGraphicSnapshot(child.graphicSpec, {
+      namespace: `${program.compositionSpec.id}-${placement.id}`,
+      x: placement.x,
+      y: placement.y
+    });
+    next = attachSnapshotObject(next, snapshot, snapshot.order[0], "canvas");
+  }
+  next = materializeHeaders(next, layout, plots, config.headers);
+  next = next.composeFacetGuides({ layout, plot });
+  if (title.height > 0) next = materializeTitle(next, plot, title);
+  return next._withCanvasConfig({
+    margin: ZERO_MARGIN,
+    size: { width: "auto", height: "auto" }
+  });
+}

package/src/materialization/graphicHierarchy.js

@@ -7,6 +7,16 @@ import { findDataset } from "../selectors/datasets.js";
 export const CANVAS_GRAPHIC_ID = "canvas";
 export const PLOT_GRAPHIC_ID = "plot-main";
 
+export function findCanvasGraphic(program) {
+  const graphic = program.graphicSpec.objects[CANVAS_GRAPHIC_ID];
+  return graphic?.type === "canvas" ? graphic : undefined;
+}
+
+export function findPlotGraphic(program) {
+  const graphic = program.graphicSpec.objects[PLOT_GRAPHIC_ID];
+  return graphic?.type === "collection" ? graphic : undefined;
+}
+
 export function assertCanvasHierarchyAvailable(program) {
   const canvasByType = Object.entries(program.graphicSpec.objects).find(
     ([, graphic]) => graphic.type === "canvas"
@@ -22,8 +32,8 @@ export function assertCanvasHierarchyAvailable(program) {
 }
 
 export function resolvePlotGraphicPlacement(program, relative = {}) {
-  const canvas = program.graphicSpec.objects[CANVAS_GRAPHIC_ID];
-  const plot = program.graphicSpec.objects[PLOT_GRAPHIC_ID];
+  const canvas = findCanvasGraphic(program);
+  const plot = findPlotGraphic(program);
 
   if (canvas === undefined && plot === undefined) return relative;
   if (canvas?.type !== "canvas") {
@@ -74,15 +84,15 @@ export function resolveMarkGraphicPlacement(program, { data, markType }) {
 }
 
 export function resolveCanvasGraphicPlacement(program, relative = {}) {
-  const canvas = program.graphicSpec.objects[CANVAS_GRAPHIC_ID];
-  if (canvas?.type !== "canvas") {
+  const canvas = findCanvasGraphic(program);
+  if (canvas === undefined) {
     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(
+  const title = findCanvasGraphic(program)?.children?.find(
     id => id === "chartTitle" || id === "chartSubtitle"
   );
   const hasRelativeAnchor = relative.before !== undefined ||