ggaction 0.0.2 → 0.0.4

package/src/materialization/rowEncoding.js

@@ -0,0 +1,33 @@
+import { POSITION_CHANNELS } from "../core/vocabulary.js";
+import {
+  mapOrdinalPositionValues,
+  readNominalField,
+  readQuantitativeField,
+  readScaleField,
+  readTemporalField
+} from "../grammar/scales/index.js";
+import { mapScaleConsumerValues } from "./scales/map.js";
+
+export function resolveRowEncodingValues(program, layer, dataset, channel) {
+  const encoding = layer.encoding?.[channel];
+  if (encoding === undefined) return undefined;
+  const scale = program.resolvedScales[encoding.scale];
+  if (scale === undefined) {
+    throw new Error(
+      `${layer.mark.type} mark "${layer.id}" requires resolved ${channel} scale "${encoding.scale}".`
+    );
+  }
+  const categorical = ["nominal", "ordinal"].includes(encoding.fieldType);
+  const values = Object.hasOwn(scale, "unknown")
+    ? readScaleField(dataset.values, encoding.field, encoding.fieldType, {
+        allowUnknown: true
+      })
+    : categorical
+      ? readNominalField(dataset.values, encoding.field)
+      : encoding.fieldType === "temporal"
+        ? readTemporalField(dataset.values, encoding.field)
+        : readQuantitativeField(dataset.values, encoding.field);
+  return categorical && POSITION_CHANNELS.includes(channel)
+    ? mapOrdinalPositionValues(values, scale)
+    : mapScaleConsumerValues(values, scale, channel);
+}

package/src/materialization/scaleGuideDependencies.js

@@ -0,0 +1,94 @@
+import { POSITION_ENCODING_CHANNELS } from "../core/vocabulary.js";
+import { materializedLegendUsesScale } from "./legends.js";
+import { buildMaterializationPlan } from "./planner.js";
+
+const CARTESIAN_AXES = Object.freeze([
+  Object.freeze({ channel: "x", prefix: "X", lineObject: "xAxisLine" }),
+  Object.freeze({ channel: "y", prefix: "Y", lineObject: "yAxisLine" })
+]);
+const POLAR_AXES = Object.freeze([
+  Object.freeze({ channel: "theta", prefix: "Theta" }),
+  Object.freeze({ channel: "radius", prefix: "Radial" })
+]);
+const GRIDS = Object.freeze([
+  Object.freeze({ role: "horizontal", op: "rematerializeHorizontalGrid" }),
+  Object.freeze({ role: "vertical", op: "rematerializeVerticalGrid" }),
+  Object.freeze({ role: "theta", op: "rematerializeThetaGrid" }),
+  Object.freeze({ role: "radial", op: "rematerializeRadialGrid" })
+]);
+
+function usesPositionalScale(program, id) {
+  return program.semanticSpec.layers.some(layer =>
+    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 semanticGuideUsesScale(program, id) {
+  return [
+    ...CARTESIAN_AXES.map(({ channel }) =>
+      program.semanticSpec.guides.axis?.[channel]
+    ),
+    ...POLAR_AXES.map(({ channel }) =>
+      program.semanticSpec.guides.axis?.[channel]
+    ),
+    ...GRIDS.map(({ role }) => program.semanticSpec.guides.grid?.[role])
+  ].some(guide => guide?.scale === id);
+}
+
+export function needsCanvasScaleRematerialization(program, scale) {
+  return (
+    (scale.range === "auto" ||
+      usesRadialScale(program, scale.id) ||
+      semanticGuideUsesScale(program, scale.id)) &&
+    program.resolvedScales[scale.id] !== undefined &&
+    usesPositionalScale(program, scale.id)
+  );
+}
+
+function componentEditOperation(prefix, component) {
+  const suffix = component[0].toUpperCase() + component.slice(1);
+  return `edit${prefix}Axis${suffix}`;
+}
+
+export function planScaleGuideRematerialization(program, id) {
+  const guides = [];
+  const objects = program.graphicSpec?.objects ?? {};
+  const guideConfigs = program.guideConfigs ?? {};
+  for (const axis of CARTESIAN_AXES) {
+    if (
+      objects[axis.lineObject] &&
+      program.semanticSpec.guides.axis?.[axis.channel]?.scale === id
+    ) {
+      guides.push({ op: componentEditOperation(axis.prefix, "line") });
+    }
+    for (const component of ["ticks", "labels", "title"]) {
+      if (guideConfigs.axis?.[axis.channel]?.[component]?.scale === id) {
+        guides.push({ op: componentEditOperation(axis.prefix, component) });
+      }
+    }
+  }
+  for (const axis of POLAR_AXES) {
+    for (const component of ["line", "ticks", "labels", "title"]) {
+      if (guideConfigs.axis?.[axis.channel]?.[component]?.scale === id) {
+        guides.push({ op: componentEditOperation(axis.prefix, component) });
+      }
+    }
+  }
+  for (const grid of GRIDS) {
+    if (guideConfigs.grid?.[grid.role]?.scale === id) {
+      guides.push({ op: grid.op });
+    }
+  }
+  if (materializedLegendUsesScale(program, id)) {
+    guides.push({ op: "rematerializeLegend" });
+  }
+  return buildMaterializationPlan({ guides });
+}

package/src/materialization/scales/map.js

@@ -0,0 +1,40 @@
+import {
+  isContinuousColorScaleType,
+  isDiscretizedColorScaleType,
+  isOrdinalScaleType,
+  mapContinuousScaleValues,
+  mapDiscretizedColors,
+  mapOrdinalValues,
+  mapSequentialColors
+} from "../../grammar/scales/index.js";
+
+export function mapScaleConsumerValues(values, resolvedScale, channel) {
+  if (channel === "color" && isDiscretizedColorScaleType(resolvedScale.type)) {
+    return mapDiscretizedColors(values, resolvedScale);
+  }
+  if (channel === "color" && isContinuousColorScaleType(resolvedScale.type)) {
+    return mapSequentialColors(
+      values,
+      resolvedScale.domain,
+      resolvedScale.range,
+      {
+        interpolation: resolvedScale.interpolate,
+        clamp: resolvedScale.clamp ?? false,
+        ...(Object.hasOwn(resolvedScale, "unknown")
+          ? { unknown: resolvedScale.unknown }
+          : {})
+      }
+    );
+  }
+  if (
+    ["color", "strokeDash", "shape"].includes(channel) &&
+    isOrdinalScaleType(resolvedScale.type)
+  ) {
+    return mapOrdinalValues(values, resolvedScale.domain, resolvedScale.range, {
+      ...(Object.hasOwn(resolvedScale, "unknown")
+        ? { unknown: resolvedScale.unknown }
+        : {})
+    });
+  }
+  return mapContinuousScaleValues(values, resolvedScale);
+}

package/src/materialization/scales/policies/arc.js

@@ -0,0 +1,37 @@
+export function resolveArcAutoPositionRange({
+  consumers,
+  scale,
+  channel,
+  domain,
+  range,
+  markConfigs
+}) {
+  if (
+    (scale.range !== "auto" && scale.range !== undefined) ||
+    consumers.length === 0 ||
+    !consumers.every(consumer => consumer.layer.mark?.type === "arc")
+  ) {
+    return range;
+  }
+  if (channel === "radius") {
+    const ratios = consumers.map(
+      consumer => markConfigs[consumer.layer.id]?.innerRadius ?? 0
+    );
+    if (new Set(ratios).size !== 1) {
+      throw new Error(
+        `Shared arc radius scale "${scale.id}" requires one innerRadius policy.`
+      );
+    }
+    const outer = Math.max(...range);
+    return [outer * ratios[0], outer];
+  }
+  if (
+    channel === "theta" &&
+    scale.type === "band" &&
+    consumers.every(consumer => consumer.encoding.aggregate === undefined)
+  ) {
+    const step = (range[1] - range[0]) / domain.length;
+    return [range[0] - step / 2, range[1] - step / 2];
+  }
+  return range;
+}

package/src/materialization/scales/policies/bar.js

@@ -0,0 +1,132 @@
+import { normalizeOffsetPadding } from "../../../grammar/bars/geometry.js";
+import {
+  BAR_GRAINS,
+  resolveBarChannels,
+  resolveBarGrain
+} from "../../../grammar/bars/policy.js";
+import { resolveHistogramBins } from "../../../grammar/histogram.js";
+
+export function resolveBinnedBarDomain({
+  valuesByConsumer,
+  channel,
+  scale,
+  id,
+  allValues
+}) {
+  const binnedBars = valuesByConsumer.filter(
+    ({ consumer }) =>
+      consumer.layer.mark?.type === "bar" &&
+      consumer.encoding.bin !== undefined
+  );
+  if (binnedBars.length === 0) return undefined;
+  if (channel !== "x" || binnedBars.length !== valuesByConsumer.length) {
+    throw new Error(
+      `Binned scale "${id}" cannot be shared with an unbinned consumer.`
+    );
+  }
+  const binDefinitions = new Set(
+    binnedBars.map(({ consumer }) => JSON.stringify(consumer.encoding.bin))
+  );
+  if (binDefinitions.size !== 1) {
+    throw new Error(`Binned scale "${id}" requires one shared bin definition.`);
+  }
+  return resolveHistogramBins({
+    values: allValues,
+    bin: binnedBars[0].consumer.encoding.bin,
+    domain: scale.domain,
+    nice: scale.nice ?? true,
+    zero: scale.zero ?? false
+  }).domain;
+}
+
+export function resolveOffsetScalePolicy({
+  consumers,
+  resolvedScales,
+  markConfigs,
+  id,
+  channel
+}) {
+  const parentChannel = channel === "xOffset" ? "x" : "y";
+  const bandwidths = consumers.map(consumer => {
+    if (parentChannel === "x" && consumer.layer.encoding?.x?.bin !== undefined) {
+      return 1;
+    }
+    const parentScaleId = consumer.layer.encoding?.[parentChannel]?.scale;
+    return resolvedScales[parentScaleId]?.bandwidth;
+  });
+  if (
+    bandwidths.some(value => !Number.isFinite(value)) ||
+    new Set(bandwidths).size !== 1
+  ) {
+    throw new Error(
+      `${channel} scale "${id}" requires one shared resolved ${parentChannel} bandwidth.`
+    );
+  }
+  const paddings = consumers.map(consumer => normalizeOffsetPadding(
+    markConfigs[consumer.layer.id]?.[channel],
+    undefined,
+    channel
+  ));
+  const signatures = new Set(
+    paddings.map(padding => JSON.stringify(padding))
+  );
+  if (signatures.size !== 1) {
+    throw new Error(
+      `${channel} scale "${id}" requires one shared padding policy.`
+    );
+  }
+  return {
+    parentBandwidth: bandwidths[0],
+    ...paddings[0]
+  };
+}
+
+export function resolveTemporalBarBand(consumers, domain, range, values) {
+  const temporalBars = consumers.filter(consumer => {
+    const channels = resolveBarChannels(consumer.layer);
+    return resolveBarGrain(consumer.layer) === BAR_GRAINS.aggregate &&
+      channels?.category === consumer.channel &&
+      consumer.encoding.fieldType === "temporal";
+  });
+  if (temporalBars.length === 0) return undefined;
+  const temporalFields = new Set(
+    temporalBars.map(consumer => consumer.encoding.field)
+  );
+  const compatibleLines = consumers.filter(consumer =>
+    consumer.layer.mark?.type === "line" &&
+    consumer.encoding.fieldType === "temporal" &&
+    temporalFields.has(consumer.encoding.field)
+  );
+  if (temporalBars.length + compatibleLines.length !== consumers.length) {
+    throw new Error(
+      "A temporal bar position scale requires compatible bar or line consumers of one field."
+    );
+  }
+  const ordered = [...new Set(values)].sort((left, right) => left - right);
+  if (ordered.length < 2) {
+    throw new Error("Temporal bar position requires at least two distinct values.");
+  }
+  const minimumGap = Math.min(
+    ...ordered.slice(1).map((value, index) => value - ordered[index])
+  );
+  const domainSpan = Math.abs(domain[1] - domain[0]);
+  if (!(minimumGap > 0) || !(domainSpan > 0)) {
+    throw new Error("Temporal bar position requires an increasing time domain.");
+  }
+  const direction = Math.sign(range[1] - range[0]) || 1;
+  const estimatedBandwidth = Math.abs(range[1] - range[0]) * minimumGap /
+    (domainSpan + minimumGap);
+  const resolvedRange = [
+    range[0] + direction * estimatedBandwidth / 2,
+    range[1] - direction * estimatedBandwidth / 2
+  ];
+  const positions = ordered.map(value =>
+    resolvedRange[0] +
+      (value - domain[0]) / (domain[1] - domain[0]) *
+      (resolvedRange[1] - resolvedRange[0])
+  );
+  const bandwidth = Math.min(
+    ...positions.slice(1).map((value, index) => Math.abs(value - positions[index]))
+  );
+  return { bandwidth, range: resolvedRange };
+}

package/src/materialization/scales/policies/series.js

@@ -0,0 +1,76 @@
+import {
+  isTransformedScaleType,
+  resolveContinuousDomain,
+  resolveTransformedDomain
+} from "../../../grammar/scales/index.js";
+
+export function resolveSeriesLayoutDomain({
+  id,
+  scale,
+  valuesByConsumer,
+  seriesLayouts
+}) {
+  if (!seriesLayouts.some(Boolean)) return undefined;
+  const activeLayouts = seriesLayouts.filter(Boolean);
+  const layouts = new Set(activeLayouts.map(item => item.layout));
+  if (layouts.size !== 1) {
+    throw new Error(`Series layout scale "${id}" requires one layout policy.`);
+  }
+  const layoutConsumers = valuesByConsumer.filter(
+    (_, index) => seriesLayouts[index] !== undefined
+  );
+  const directConsumers = valuesByConsumer.filter(
+    (_, index) => seriesLayouts[index] === undefined
+  );
+  const compatibleDirect = directConsumers.every(({ consumer }) =>
+    layoutConsumers.every(({ consumer: layoutConsumer }) => {
+      const aggregate = layoutConsumer.encoding.aggregate;
+      return aggregate !== "count" &&
+        consumer.encoding.fieldType === "quantitative" &&
+        consumer.encoding.field === layoutConsumer.encoding.field;
+    })
+  );
+  if (!compatibleDirect) {
+    throw new Error(
+      `Series layout scale "${id}" cannot be shared with another policy.`
+    );
+  }
+  const layout = activeLayouts[0].layout;
+  const values = [
+    ...activeLayouts.flatMap(item => item.values),
+    ...directConsumers.flatMap(item => item.values)
+  ];
+  if (
+    ["group", "overlay"].includes(layout) &&
+    scale.domain !== "auto" &&
+    (Math.min(...scale.domain) > 0 || Math.max(...scale.domain) < 0)
+  ) {
+    throw new Error(
+      `Series layout scale "${id}" requires an explicit domain containing zero.`
+    );
+  }
+  const nice = layout === "fill" && scale.domain === "auto"
+    ? false
+    : scale.nice;
+  const zero = layout === "fill" && scale.domain === "auto"
+    ? false
+    : scale.zero;
+  return isTransformedScaleType(scale.type)
+    ? resolveTransformedDomain({
+        type: scale.type,
+        domain: scale.domain,
+        values,
+        nice: nice ?? false,
+        zero: zero ?? false,
+        ...(scale.base === undefined ? {} : { base: scale.base }),
+        ...(scale.exponent === undefined ? {} : { exponent: scale.exponent }),
+        ...(scale.constant === undefined ? {} : { constant: scale.constant })
+      })
+    : resolveContinuousDomain({
+        domain: scale.domain,
+        values,
+        type: scale.type,
+        nice,
+        zero
+      });
+}