ggaction 0.0.13 → 0.0.16

package/src/materialization/facetHeaders.js

@@ -0,0 +1,347 @@
+import { isPlainObject } from "../core/immutable.js";
+import {
+  formatVisibleText,
+  measureTextWidth,
+  resolveTextBounds,
+  textBoundsIntersect
+} from "../core/textMetrics.js";
+import { resolveDisplayLabel } from "../grammar/displayLabels.js";
+import { DEFAULT_COLORS, DEFAULT_FONT_FAMILY } from "../theme/defaults.js";
+
+const SIDES = Object.freeze(["top", "right", "bottom", "left"]);
+const ZERO_SIDES = Object.freeze({ top: 0, right: 0, bottom: 0, left: 0 });
+
+export function createDefaultFacetHeaders() {
+  return {
+    mode: "legacy",
+    common: {
+      fontSize: 12,
+      fontFamily: DEFAULT_FONT_FAMILY,
+      fontWeight: 600,
+      color: DEFAULT_COLORS.strongText,
+      offset: 10,
+      align: "center"
+    },
+    row: { side: "left" },
+    column: { side: "top" }
+  };
+}
+
+export function normalizeFacetHeadersConfig(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("Facet headers config must be a plain object.");
+  }
+  if (value.common === undefined && value.mode === undefined) {
+    return {
+      ...createDefaultFacetHeaders(),
+      common: {
+        ...createDefaultFacetHeaders().common,
+        ...value
+      }
+    };
+  }
+  if (!["legacy", "roles"].includes(value.mode) ||
+      !isPlainObject(value.common) || !isPlainObject(value.row) ||
+      !isPlainObject(value.column)) {
+    throw new Error("Facet headers config must contain canonical mode and role objects.");
+  }
+  return {
+    mode: value.mode,
+    common: { ...value.common },
+    row: { ...value.row },
+    column: { ...value.column }
+  };
+}
+
+export function resolveFacetHeaderConfig(headers, role) {
+  const normalized = normalizeFacetHeadersConfig(headers);
+  return role === "all"
+    ? { ...normalized.common }
+    : { ...normalized.common, ...normalized[role] };
+}
+
+function mappedText(value, config) {
+  return resolveDisplayLabel(value, config.labelMap, formatVisibleText);
+}
+
+function gridCellById(spec) {
+  return new Map((spec.facet.grid?.cells ?? []).map(cell => [cell.id, cell]));
+}
+
+function legacyDescriptors(program, headers) {
+  const spec = program.compositionSpec;
+  const config = resolveFacetHeaderConfig(headers, "all");
+  const cells = gridCellById(spec);
+  return spec.children.map((id, index) => {
+    const cell = cells.get(id);
+    const text = cell === undefined
+      ? mappedText(spec.facet.values[index], config)
+      : `${mappedText(cell.rowValue, config)} · ${mappedText(cell.columnValue, config)}`;
+    return { topology: "legacy", role: "column", id, text, config };
+  });
+}
+
+function uniqueGridGroups(spec, role) {
+  const coordinate = role === "column" ? "column" : "row";
+  const valueKey = role === "column" ? "columnValue" : "rowValue";
+  const groups = new Map();
+  for (const cell of spec.facet.grid.cells) {
+    const existing = groups.get(cell[coordinate]);
+    if (existing === undefined) {
+      groups.set(cell[coordinate], {
+        coordinate: cell[coordinate],
+        value: cell[valueKey],
+        ids: [cell.id]
+      });
+    } else {
+      if (existing.value !== cell[valueKey]) {
+        throw new Error(`Facet ${role} header values conflict at coordinate ${cell[coordinate]}.`);
+      }
+      existing.ids.push(cell.id);
+    }
+  }
+  return [...groups.values()].sort((left, right) =>
+    left.coordinate - right.coordinate
+  );
+}
+
+function roleDescriptors(program, headers) {
+  const spec = program.compositionSpec;
+  const column = resolveFacetHeaderConfig(headers, "column");
+  if (spec.facet.grid === undefined) {
+    return spec.children.map((id, index) => ({
+      topology: "cell-column",
+      role: "column",
+      id,
+      ids: [id],
+      row: Math.floor(index / spec.columns),
+      text: mappedText(spec.facet.values[index], column),
+      config: column
+    }));
+  }
+  const row = resolveFacetHeaderConfig(headers, "row");
+  const columns = uniqueGridGroups(spec, "column").map(group => ({
+    topology: "grid-column",
+    role: "column",
+    ids: group.ids,
+    coordinate: group.coordinate,
+    text: mappedText(group.value, column),
+    config: column
+  }));
+  const rows = uniqueGridGroups(spec, "row").map(group => ({
+    topology: "grid-row",
+    role: "row",
+    ids: group.ids,
+    coordinate: group.coordinate,
+    text: mappedText(group.value, row),
+    config: row
+  }));
+  return [...columns, ...rows];
+}
+
+function laneThickness(descriptors, role, profile) {
+  const visible = descriptors.filter(item => item.role === role && item.text !== "");
+  if (visible.length === 0) return 0;
+  if (role === "column") {
+    return Math.max(...visible.map(item => item.config.fontSize + item.config.offset));
+  }
+  return Math.max(...visible.map(item => measureTextWidth(item.text, item.config, profile) +
+    item.config.offset));
+}
+
+export function prepareFacetHeaders(program, headersConfig) {
+  const headers = normalizeFacetHeadersConfig(headersConfig);
+  const descriptors = headers.mode === "legacy"
+    ? legacyDescriptors(program, headers)
+    : roleDescriptors(program, headers);
+  const rows = program.compositionSpec.facet.grid === undefined
+    ? Math.ceil(program.compositionSpec.children.length / program.compositionSpec.columns)
+    : Math.max(...program.compositionSpec.facet.grid.cells.map(cell => cell.row)) + 1;
+  const headerLayout = {
+    outer: { ...ZERO_SIDES },
+    cellRows: { top: Array(rows).fill(0), bottom: Array(rows).fill(0) }
+  };
+  if (headers.mode === "roles") {
+    const column = resolveFacetHeaderConfig(headers, "column");
+    const columnThickness = laneThickness(descriptors, "column", program.materializationConfigs.textMetrics);
+    if (program.compositionSpec.facet.grid === undefined) {
+      for (const descriptor of descriptors) {
+        if (descriptor.text !== "") {
+          headerLayout.cellRows[column.side][descriptor.row] = Math.max(
+            headerLayout.cellRows[column.side][descriptor.row],
+            descriptor.config.fontSize + descriptor.config.offset
+          );
+        }
+      }
+    } else {
+      headerLayout.outer[column.side] = columnThickness;
+      const row = resolveFacetHeaderConfig(headers, "row");
+      headerLayout.outer[row.side] = laneThickness(descriptors, "row", program.materializationConfigs.textMetrics);
+    }
+  }
+  return { headers, descriptors, headerLayout };
+}
+
+function horizontalAnchor(bounds, align) {
+  if (align === "start") return { x: bounds.left, textAlign: "left" };
+  if (align === "end") return { x: bounds.right, textAlign: "right" };
+  return { x: (bounds.left + bounds.right) / 2, textAlign: "center" };
+}
+
+function verticalAnchor(bounds, align) {
+  if (align === "start") return { y: bounds.top, textBaseline: "top" };
+  if (align === "end") return { y: bounds.bottom, textBaseline: "bottom" };
+  return { y: (bounds.top + bounds.bottom) / 2, textBaseline: "middle" };
+}
+
+function union(items) {
+  return {
+    left: Math.min(...items.map(item => item.left)),
+    right: Math.max(...items.map(item => item.right)),
+    top: Math.min(...items.map(item => item.top)),
+    bottom: Math.max(...items.map(item => item.bottom))
+  };
+}
+
+function placedPlot(cell, plot) {
+  return {
+    left: cell.x + plot.x,
+    right: cell.x + plot.x + plot.width,
+    top: cell.y + plot.y,
+    bottom: cell.y + plot.y + plot.height
+  };
+}
+
+function placedCell(cell) {
+  return {
+    left: cell.x,
+    right: cell.x + cell.width,
+    top: cell.y,
+    bottom: cell.y + cell.height
+  };
+}
+
+function roleItem(descriptor, cells, plots) {
+  const selectedCells = descriptor.ids.map(id => cells.get(id));
+  const missingCell = descriptor.ids.find((id, index) =>
+    selectedCells[index] === undefined
+  );
+  const missingPlot = descriptor.ids.find(id => plots.get(id) === undefined);
+  if (missingCell !== undefined || missingPlot !== undefined) {
+    throw new Error(
+      `Facet header requires cell and plot bounds for "${missingCell ?? missingPlot}".`
+    );
+  }
+  const selectedPlots = descriptor.ids.map((id, index) =>
+    placedPlot(selectedCells[index], plots.get(id))
+  );
+  const plot = union(selectedPlots);
+  const snapshots = union(selectedCells.map(placedCell));
+  const config = descriptor.config;
+  let anchor;
+  if (descriptor.role === "column") {
+    anchor = horizontalAnchor(plot, config.align);
+    const top = config.side === "top";
+    anchor.y = top
+      ? snapshots.top - config.offset - config.fontSize / 2
+      : snapshots.bottom + config.offset + config.fontSize / 2;
+    anchor.textBaseline = "middle";
+  } else {
+    anchor = verticalAnchor(plot, config.align);
+    const left = config.side === "left";
+    anchor.x = left
+      ? snapshots.left - config.offset
+      : snapshots.right + config.offset;
+    anchor.textAlign = left ? "right" : "left";
+  }
+  return { descriptor, snapshots, properties: anchor };
+}
+
+function legacyItem(descriptor, cell, plot) {
+  if (cell === undefined || plot === undefined) {
+    throw new Error(`Facet header requires cell and plot bounds for "${descriptor.id}".`);
+  }
+  return {
+    descriptor,
+    snapshots: placedCell(cell),
+    properties: {
+      ...horizontalAnchor(placedPlot(cell, plot), descriptor.config.align),
+      y: cell.y + descriptor.config.offset,
+      textBaseline: "middle"
+    }
+  };
+}
+
+function styledItem(item) {
+  const { config } = item.descriptor;
+  return {
+    type: "text",
+    properties: {
+      ...item.properties,
+      text: item.descriptor.text,
+      fill: config.color,
+      fontSize: config.fontSize,
+      fontFamily: config.fontFamily,
+      fontWeight: config.fontWeight
+    }
+  };
+}
+
+function assertRoleHeadersFit(records, items, layout, profile) {
+  const bounds = items.map((item, index) => records[index].descriptor.text === ""
+    ? undefined
+    : resolveTextBounds(item.properties, profile));
+  for (const [index, current] of bounds.entries()) {
+    if (current === undefined) continue;
+    if (current.left < -1e-9 || current.right > layout.width + 1e-9 ||
+        current.top < -1e-9 || current.bottom > layout.height + 1e-9 ||
+        bounds.some((other, otherIndex) => otherIndex < index &&
+          other !== undefined && textBoundsIntersect(other, current)) ||
+        layout.children.some(cell => textBoundsIntersect(current, placedCell(cell)))) {
+      throw new Error(
+        "Facet role headers require sufficient non-overlapping reserved space."
+      );
+    }
+  }
+}
+
+function assertLegacyHeadersFit(items, layout, plotById, profile) {
+  const previous = [];
+  for (let index = 0; index < items.length; index += 1) {
+    if (items[index].properties.text === "") continue;
+    const bounds = resolveTextBounds(items[index].properties, profile);
+    const cell = layout.children[index];
+    const plot = plotById.get(cell.id);
+    if (bounds.left < 0 || bounds.right > layout.width ||
+      bounds.top < 0 || bounds.bottom > layout.height ||
+      previous.some(item => textBoundsIntersect(item, bounds)) ||
+      textBoundsIntersect(bounds, placedPlot(cell, plot))) {
+      throw new Error(
+        "Facet headers require sufficient non-overlapping space above every child plot."
+      );
+    }
+    previous.push(bounds);
+  }
+}
+
+export function materializeFacetHeaders(program, layout, plots, prepared) {
+  const profile = program.materializationConfigs.textMetrics;
+  const cells = new Map(layout.children.map(cell => [cell.id, cell]));
+  const plotById = new Map(plots.map(plot => [plot.id, plot]));
+  const records = prepared.descriptors.map(descriptor => {
+    if (descriptor.topology === "legacy") {
+      return legacyItem(descriptor, cells.get(descriptor.id), plotById.get(descriptor.id));
+    }
+    return roleItem(descriptor, cells, plotById);
+  });
+  const items = records.map(styledItem);
+  if (prepared.headers.mode === "legacy") {
+    assertLegacyHeadersFit(items, layout, plotById, profile);
+  } else {
+    assertRoleHeadersFit(records, items, layout, profile);
+  }
+  const id = `${program.compositionSpec.id}-headers`;
+  return program
+    .createGraphics({ id, type: "collection", parent: "canvas" })
+    .editGraphics({ target: id, property: "items", value: items });
+}

package/src/materialization/facets.js

@@ -1,9 +1,4 @@
 import { resolveGraphicBounds } from "../layout/canvas.js";
-import {
-  formatVisibleText,
-  resolveTextBounds,
-  textBoundsIntersect
-} from "../core/textMetrics.js";
 import { resolvePlacedPlotBounds } from "../layout/composition.js";
 import {
   alignedTextAnchor,
@@ -17,6 +12,10 @@ import {
   clearCompositionChildren,
   compositionChildDescriptor
 } from "./composition.js";
+import {
+  materializeFacetHeaders,
+  prepareFacetHeaders
+} from "./facetHeaders.js";
 
 const ZERO_MARGIN = { top: 0, right: 0, bottom: 0, left: 0 };
 
@@ -50,61 +49,6 @@ function titleLayout(program) {
   return { config, block, top, height: Math.ceil(top + block.height) };
 }
 
-function collection(program, id, items) {
-  return program
-    .createGraphics({ id, type: "collection", parent: "canvas" })
-    .editGraphics({ target: id, property: "items", value: items });
-}
-
-function assertFacetHeadersFit(items, layout, plotById) {
-  const previous = [];
-  for (let index = 0; index < items.length; index += 1) {
-    const bounds = resolveTextBounds(items[index].properties);
-    const cell = layout.children[index];
-    const plot = plotById.get(cell.id);
-    if (bounds.left < 0 || bounds.right > layout.width ||
-      bounds.top < 0 || bounds.bottom > layout.height ||
-      previous.some(item => textBoundsIntersect(item, bounds)) ||
-      textBoundsIntersect(bounds, {
-        left: cell.x + plot.x,
-        right: cell.x + plot.x + plot.width,
-        top: cell.y + plot.y,
-        bottom: cell.y + plot.y + plot.height
-      })) {
-      throw new Error(
-        "Facet headers require sufficient non-overlapping space above every child plot."
-      );
-    }
-    previous.push(bounds);
-  }
-}
-
-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 {
-      type: "text",
-      properties: {
-        x: cell.x + plot.x + plot.width / 2,
-        y: cell.y + config.offset,
-        text: formatVisibleText(cell.value),
-        fill: config.color,
-        fontSize: config.fontSize,
-        fontFamily: config.fontFamily,
-        fontWeight: config.fontWeight,
-        textAlign: "center",
-        textBaseline: "middle"
-      }
-    };
-  });
-  assertFacetHeadersFit(items, layout, plotById);
-  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);
@@ -162,6 +106,10 @@ export function resolveFacetProgramLayout(program, preparedLegend) {
   }
   const title = titleLayout(program);
   const spec = program.compositionSpec;
+  const preparedHeaders = prepareFacetHeaders(
+    program,
+    facetConfig(program).headers
+  );
   const gridCells = new Map(
     (spec.facet.grid?.cells ?? []).map(cell => [cell.id, cell])
   );
@@ -179,6 +127,7 @@ export function resolveFacetProgramLayout(program, preparedLegend) {
     align: spec.align,
     padding: spec.padding,
     titleHeight: title.height,
+    headerLayout: preparedHeaders.headerLayout,
     sharedLegend: spec.facet.guides.legend === "shared",
     ...(preparedLegend === undefined ? {} : {
       sharedLegendGap: preparedLegend.reservation.gap,
@@ -195,16 +144,17 @@ export function resolveFacetProgramLayout(program, preparedLegend) {
     placements: layout.children,
     plots
   });
-  return { layout, title, plot, plots };
+  return { layout, title, plot, plots, preparedHeaders };
 }
 
 export function materializeFacetGraphics(program) {
   const preparedLegend = prepareSharedFacetLegend(program);
-  const { layout, title, plot, plots } = resolveFacetProgramLayout(
+  const { layout, title, plot, plots, preparedHeaders } = resolveFacetProgramLayout(
     program,
     preparedLegend
   );
-  const config = facetConfig(program);
+  const background = program.graphicSpec.objects.canvas?.properties
+    ?.background ?? "white";
   let next = clearCompositionChildren(program);
   if (next.graphicSpec.objects.canvas === undefined) {
     next = next.createGraphics({ id: "canvas", type: "canvas" });
@@ -212,7 +162,7 @@ export function materializeFacetGraphics(program) {
   for (const [property, value] of Object.entries({
     width: layout.width,
     height: layout.height,
-    background: "white"
+    background
   })) {
     next = next.editGraphics({ target: "canvas", property, value });
   }
@@ -225,7 +175,7 @@ export function materializeFacetGraphics(program) {
     });
     next = attachSnapshotObject(next, snapshot, snapshot.order[0], "canvas");
   }
-  next = materializeHeaders(next, layout, plots, config.headers);
+  next = materializeFacetHeaders(next, layout, plots, preparedHeaders);
   next = next.composeFacetGuides({ layout, plot });
   if (title.height > 0) next = materializeTitle(next, plot, title);
   return next._withCanvasConfig({

package/src/materialization/guides/layout.js

@@ -4,12 +4,12 @@ import { axisGraphicIds, legendResourcePolicies } from "./resources.js";
 
 // Only domain-owned guides participate. Extension primitives may deliberately
 // overlap, and a combined categorical/size legend is one occupied group.
-export function resolveGuideCollisionBlocks(graphicSpec, guideConfigs, titleConfig) {
+export function resolveGuideCollisionBlocks(graphicSpec, guideConfigs, titleConfig, profile) {
   const blocks = [];
   const append = (id, kind, position, ids) => {
     if (position === undefined) return;
     const existing = ids.filter(id => graphicSpec.objects[id] !== undefined);
-    const bounds = unionConcreteGraphicBounds(graphicSpec, existing);
+    const bounds = unionConcreteGraphicBounds(graphicSpec, existing, profile);
     if (bounds !== undefined) blocks.push({ id, kind, position, bounds });
   };
   append("chart title", "title", titleConfig?.position, ["chartTitle", "chartSubtitle"]);
@@ -46,7 +46,7 @@ export function withGuideLayoutTransaction(program, apply) {
     context.deferGuideLayoutValidation = program.context.deferGuideLayoutValidation;
   }
   const next = result._clone({ context });
-  assertGuideCollisionBlocks(resolveGuideCollisionBlocks(next.graphicSpec, next.guideConfigs, next.titleConfig));
+  assertGuideCollisionBlocks(resolveGuideCollisionBlocks(next.graphicSpec, next.guideConfigs, next.titleConfig, next.materializationConfigs.textMetrics));
   return next;
 }
 

package/src/materialization/guides/resources.js

@@ -22,6 +22,14 @@ const LEGEND_RESOURCE_POLICIES = Object.freeze({
       component => `colorLegend${component}`
     ))
   }),
+  stroke: Object.freeze({
+    semanticKind: "stroke",
+    family: "categorical",
+    rematerializeOp: undefined,
+    graphicIds: Object.freeze(CATEGORICAL_COMPONENTS.map(
+      component => `strokeLegend${component}`
+    ))
+  }),
   size: Object.freeze({
     semanticKind: "size",
     family: "size",
@@ -48,6 +56,24 @@ const LEGEND_RESOURCE_POLICIES = Object.freeze({
       "colorLegendTitle"
     ])
   }),
+  strokeGradient: Object.freeze({
+    semanticKind: "stroke",
+    family: "continuous",
+    rematerializeOp: "rematerializeStrokeGradientLegend",
+    graphicIds: Object.freeze([
+      "strokeGradientBackground", "strokeGradientStrips", "strokeGradientTicks",
+      "strokeGradientLabels", "strokeGradientTitle"
+    ])
+  }),
+  strokeInterval: Object.freeze({
+    semanticKind: "stroke",
+    family: "interval",
+    rematerializeOp: "rematerializeStrokeIntervalLegend",
+    graphicIds: Object.freeze([
+      "strokeIntervalBackground", "strokeIntervalSymbols",
+      "strokeIntervalLabels", "strokeIntervalTitle"
+    ])
+  }),
   opacity: Object.freeze({
     semanticKind: "opacity",
     family: "continuous",

package/src/materialization/legends.js

@@ -10,7 +10,7 @@ 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") {
+    if (["series", "color", "stroke"].includes(kind)) {
       return program.semanticSpec.guides.legend?.[kind] !== undefined;
     }
     return true;

package/src/materialization/marks/index.js

@@ -36,6 +36,9 @@ export function getScaleConsumerMarkSteps(program, scaleIds) {
 }
 
 export function getMarkRematerializationStep(program, layer) {
+  if (program.markConfigs?.[layer.id]?.statisticalReference !== undefined) {
+    return { op: "rematerializeStatisticalReference", args: { id: layer.id } };
+  }
   if (program.markConfigs?.[layer.id]?.markFilter?.empty === true) {
     return { op: "materializeEmptyMark", args: { id: layer.id } };
   }
@@ -54,15 +57,18 @@ export function getMarkMaterializationStep(program, layer) {
 }
 
 export function getSourceDependentMarkSteps(program, sourceId) {
-  return (program.semanticSpec.layers ?? []).flatMap(layer =>
-    layer.source === sourceId &&
-    getMarkMaterializationPolicy(layer)?.sourceDependent === true
+  return (program.semanticSpec.layers ?? []).flatMap(layer => {
+    const sourceOwned = layer.source === sourceId &&
+      getMarkMaterializationPolicy(layer)?.sourceDependent === true;
+    const statistical = program.markConfigs?.[layer.id]
+      ?.statisticalReference?.source === sourceId;
+    return sourceOwned || statistical
       ? [getMarkMaterializationStep(program, layer) ??
           getExistingMarkRematerializationStep(program, layer)].filter(
           step => step !== undefined
         )
-      : []
-  );
+      : [];
+  });
 }
 
 export function getPositionEncodingMaterializationSteps(program, layer, scaleId) {

package/src/materialization/marks/policies.js

@@ -50,7 +50,7 @@ const MARK_MATERIALIZATION_POLICIES = Object.freeze({
     op: "rematerializeAreaMark",
     positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: true }),
     encoding: Object.freeze({
-      sharedChannels: Object.freeze(["color"]),
+      sharedChannels: Object.freeze(["color", "stroke"]),
       skipRematerialization: isIntentionallyEmptyArea
     }),
     scaleApplication: Object.freeze({ default: "defer" })
@@ -58,6 +58,7 @@ const MARK_MATERIALIZATION_POLICIES = Object.freeze({
   arc: Object.freeze({
     canMaterialize: canMaterializeArc,
     op: "rematerializeArcMark",
+    acceptsResolvedScales: true,
     positionEncoding: Object.freeze({ incomplete: "scale", scaleFirst: false }),
     encoding: Object.freeze({ completeOnly: true }),
     scaleApplication: Object.freeze({ default: "defer" })