ggaction 0.0.2 → 0.0.4

package/src/core/validation.js

@@ -8,6 +8,22 @@ export function validateKeys(value, supported, label) {
   }
 }
 
+export function validateOptionObject(value, supported, label, {
+  allowEmpty = true,
+  plainObjectMessage = `${label} options must be a plain object.`,
+  emptyMessage = `${label} requires at least one option.`,
+  emptyError = TypeError
+} = {}) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(plainObjectMessage);
+  }
+  if (supported !== undefined) validateKeys(value, supported, label);
+  if (!allowEmpty && Object.keys(value).length === 0) {
+    throw new emptyError(emptyMessage);
+  }
+  return value;
+}
+
 export function noOptions(args, operation) {
   if (!isPlainObject(args) || Object.keys(args).length > 0) {
     throw new Error(`${operation} does not accept options.`);

package/src/core/vocabulary.js

@@ -3,15 +3,30 @@ export const MARK_TYPES = Object.freeze([
   "line",
   "bar",
   "area",
-  "rule"
+  "arc",
+  "rule",
+  "text",
+  "rect"
 ]);
 
+export const MARK_GRAPHIC_TYPES = Object.freeze({
+  point: Object.freeze(["circle", "rect", "path", "collection"]),
+  line: Object.freeze(["path"]),
+  bar: Object.freeze(["rect"]),
+  area: Object.freeze(["path"]),
+  arc: Object.freeze(["path"]),
+  rule: Object.freeze(["line"]),
+  text: Object.freeze(["text"]),
+  rect: Object.freeze(["rect"])
+});
+
 export const ENCODING_CHANNELS = Object.freeze([
   "x",
   "y",
   "x2",
   "y2",
   "xOffset",
+  "yOffset",
   "theta",
   "radius",
   "color",
@@ -19,14 +34,149 @@ export const ENCODING_CHANNELS = Object.freeze([
   "size",
   "shape",
   "group",
-  "opacity"
+  "opacity",
+  "text"
+]);
+
+const CARTESIAN_MARK_TYPES = Object.freeze([
+  "point", "line", "bar", "area", "rule", "text", "rect"
 ]);
+const POLAR_MARK_TYPES = Object.freeze(["point", "line", "arc"]);
+
+export const POSITION_CHANNEL_DEFINITIONS = Object.freeze({
+  x: Object.freeze({
+    family: "cartesian",
+    role: "primary",
+    scaleChannel: "x",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    guideChannel: "x",
+    gridDirection: "vertical",
+    markTypes: CARTESIAN_MARK_TYPES
+  }),
+  y: Object.freeze({
+    family: "cartesian",
+    role: "primary",
+    scaleChannel: "y",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    guideChannel: "y",
+    gridDirection: "horizontal",
+    markTypes: CARTESIAN_MARK_TYPES
+  }),
+  x2: Object.freeze({
+    family: "cartesian",
+    role: "secondary",
+    scaleChannel: "x",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["area", "rule", "rect"])
+  }),
+  y2: Object.freeze({
+    family: "cartesian",
+    role: "secondary",
+    scaleChannel: "y",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["area", "rule", "rect"])
+  }),
+  xOffset: Object.freeze({
+    family: "cartesian",
+    role: "offset",
+    scaleChannel: "xOffset",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["bar"])
+  }),
+  yOffset: Object.freeze({
+    family: "cartesian",
+    role: "offset",
+    scaleChannel: "yOffset",
+    coordinate: Object.freeze({ id: "main", type: "cartesian" }),
+    markTypes: Object.freeze(["bar"])
+  }),
+  theta: Object.freeze({
+    family: "polar",
+    role: "primary",
+    scaleChannel: "theta",
+    coordinate: Object.freeze({ id: "polar", type: "polar" }),
+    guideChannel: "theta",
+    gridDirection: "theta",
+    markTypes: POLAR_MARK_TYPES
+  }),
+  radius: Object.freeze({
+    family: "polar",
+    role: "primary",
+    scaleChannel: "radius",
+    coordinate: Object.freeze({ id: "polar", type: "polar" }),
+    guideChannel: "radius",
+    gridDirection: "radial",
+    markTypes: POLAR_MARK_TYPES
+  })
+});
 
 export const SCALED_ENCODING_CHANNELS = Object.freeze(
-  ENCODING_CHANNELS.filter(channel => channel !== "group")
+  ENCODING_CHANNELS.filter(channel => !["group", "text"].includes(channel))
+);
+
+export const POSITION_ENCODING_CHANNELS = Object.freeze(
+  Object.keys(POSITION_CHANNEL_DEFINITIONS)
+);
+
+export const OFFSET_POSITION_CHANNELS = Object.freeze(
+  POSITION_ENCODING_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].role === "offset"
+  )
+);
+
+export const CARTESIAN_POSITION_CHANNELS = Object.freeze(
+  POSITION_ENCODING_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].family === "cartesian" &&
+    POSITION_CHANNEL_DEFINITIONS[channel].role === "primary"
+  )
+);
+
+export const POLAR_POSITION_CHANNELS = Object.freeze(
+  POSITION_ENCODING_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].family === "polar" &&
+    POSITION_CHANNEL_DEFINITIONS[channel].role === "primary"
+  )
 );
 
-export const POSITION_CHANNELS = Object.freeze(["x", "y"]);
+export const POSITION_CHANNELS = Object.freeze([
+  ...CARTESIAN_POSITION_CHANNELS,
+  ...POLAR_POSITION_CHANNELS
+]);
+
+export const FACET_SCALE_CHANNELS = Object.freeze([
+  "x",
+  "y",
+  "xOffset",
+  "yOffset",
+  "color",
+  "size",
+  "shape",
+  "opacity",
+  "strokeDash"
+]);
+
+export const FACET_SCALE_RESOLUTIONS = Object.freeze([
+  "shared",
+  "independent"
+]);
+
+export function getPositionChannelDefinition(channel) {
+  return POSITION_CHANNEL_DEFINITIONS[channel];
+}
+
+export function normalizePositionScaleChannel(channel) {
+  return POSITION_CHANNEL_DEFINITIONS[channel]?.scaleChannel ?? channel;
+}
+
+export function positionChannelsForFamily(family) {
+  return POSITION_CHANNELS.filter(channel =>
+    POSITION_CHANNEL_DEFINITIONS[channel].family === family
+  );
+}
+
+export function getMarkGraphicTypes(markType) {
+  return MARK_GRAPHIC_TYPES[markType];
+}
 
 export const COLOR_LAYOUTS = Object.freeze([
   "stack",

package/src/grammar/arcs.js

@@ -0,0 +1,154 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+import {
+  mapContinuousScaleValues,
+  mapOrdinalPositionValues,
+  readNominalField,
+  readQuantitativeField
+} from "./scales/index.js";
+
+function requireArcLayer(layer) {
+  if (layer?.mark?.type !== "arc") {
+    throw new Error("Arc derivation requires a semantic arc mark.");
+  }
+  const theta = layer.encoding?.theta;
+  if (theta === undefined || !["nominal", "ordinal"].includes(theta.fieldType)) {
+    throw new Error(`Arc mark "${layer.id}" requires categorical theta.`);
+  }
+  return theta;
+}
+
+function requireBandScale(scale, label) {
+  if (
+    scale?.type !== "band" ||
+    !Array.isArray(scale.domain) ||
+    !Array.isArray(scale.range) ||
+    !Number.isFinite(scale.bandwidth) ||
+    scale.bandwidth <= 0
+  ) {
+    throw new Error(`${label} requires a resolved band scale.`);
+  }
+  return scale;
+}
+
+function colorValues(rows, encoding) {
+  return encoding === undefined
+    ? rows.map(() => undefined)
+    : readNominalField(rows, encoding.field);
+}
+
+function countSectors(rows, layer, thetaScale, frame, innerRadiusRatio) {
+  const theta = layer.encoding.theta;
+  if (theta.aggregate !== "count") {
+    throw new Error(`Arc mark "${layer.id}" requires count or radial layout.`);
+  }
+  const values = readNominalField(rows, theta.field);
+  const colors = colorValues(rows, layer.encoding?.color);
+  const groups = new Map(thetaScale.domain.map(value => [value, []]));
+  for (let index = 0; index < rows.length; index += 1) {
+    const group = groups.get(values[index]);
+    if (group === undefined) {
+      throw new Error(`Arc theta value "${values[index]}" is outside the scale domain.`);
+    }
+    group.push({ row: rows[index], color: colors[index], sourceIndex: index });
+  }
+  const total = [...groups.values()].reduce((sum, group) => sum + group.length, 0);
+  if (total === 0) throw new Error(`Arc mark "${layer.id}" has no rows to count.`);
+  const start = thetaScale.range[0];
+  const span = thetaScale.range[1] - thetaScale.range[0];
+  const innerRadius = frame.availableRadius * innerRadiusRatio;
+  let cursor = start;
+  const sectors = [];
+  for (const value of thetaScale.domain) {
+    const group = groups.get(value);
+    if (group.length === 0) continue;
+    const endTheta = cursor + group.length / total * span;
+    const distinctColors = [...new Set(group.map(item => item.color))];
+    if (distinctColors.length > 1) {
+      throw new Error(
+        `Count arc theta group "${value}" must resolve to one color value.`
+      );
+    }
+    sectors.push({
+      key: value,
+      theta: value,
+      count: group.length,
+      color: distinctColors[0],
+      startTheta: cursor,
+      endTheta,
+      innerRadius,
+      outerRadius: frame.availableRadius,
+      sourceIndices: group.map(item => item.sourceIndex)
+    });
+    cursor = endTheta;
+  }
+  return sectors;
+}
+
+function radialSectors(rows, layer, thetaScale, radiusScale) {
+  const theta = layer.encoding.theta;
+  const radius = layer.encoding?.radius;
+  if (radius?.fieldType !== "quantitative") {
+    throw new Error(`Arc mark "${layer.id}" requires quantitative radius.`);
+  }
+  const thetaValues = readNominalField(rows, theta.field);
+  const radiusValues = readQuantitativeField(rows, radius.field);
+  const colors = colorValues(rows, layer.encoding?.color);
+  const centers = mapOrdinalPositionValues(thetaValues, thetaScale);
+  const outerRadii = mapContinuousScaleValues(radiusValues, radiusScale);
+  const innerRadius = Math.min(...radiusScale.range);
+  const direction = Math.sign(thetaScale.step) || 1;
+  const halfBand = direction * thetaScale.bandwidth / 2;
+  const grouped = new Map(thetaScale.domain.map(value => [value, []]));
+  for (let index = 0; index < rows.length; index += 1) {
+    if (outerRadii[index] <= innerRadius) continue;
+    const group = grouped.get(thetaValues[index]);
+    if (group === undefined) {
+      throw new Error(
+        `Arc theta value "${thetaValues[index]}" is outside the scale domain.`
+      );
+    }
+    group.push({
+      key: `${String(thetaValues[index])}:${index}`,
+      theta: thetaValues[index],
+      radius: radiusValues[index],
+      color: colors[index],
+      startTheta: centers[index] - halfBand,
+      endTheta: centers[index] + halfBand,
+      innerRadius,
+      outerRadius: outerRadii[index],
+      sourceIndices: [index]
+    });
+  }
+  const sectors = [];
+  for (const value of thetaScale.domain) {
+    const group = grouped.get(value);
+    group.sort((left, right) =>
+      right.outerRadius - left.outerRadius ||
+      left.sourceIndices[0] - right.sourceIndices[0]
+    );
+    sectors.push(...group);
+  }
+  return sectors;
+}
+
+export function deriveArcSectors(rows, layer, {
+  thetaScale,
+  radiusScale,
+  frame,
+  innerRadiusRatio = 0
+} = {}) {
+  if (!Array.isArray(rows)) throw new TypeError("Arc derivation requires rows.");
+  const theta = requireArcLayer(layer);
+  requireBandScale(thetaScale, `Arc mark "${layer.id}" theta`);
+  if (
+    !Number.isFinite(innerRadiusRatio) ||
+    innerRadiusRatio < 0 ||
+    innerRadiusRatio >= 1
+  ) {
+    throw new RangeError("Arc innerRadius must be from 0 (inclusive) to 1 (exclusive).");
+  }
+  const sectors = theta.aggregate === "count"
+    ? countSectors(rows, layer, thetaScale, frame, innerRadiusRatio)
+    : radialSectors(rows, layer, thetaScale, radiusScale);
+  return cloneAndFreeze({ sectors });
+}

package/src/grammar/areaSeries.js

@@ -3,7 +3,7 @@ import {
   readNominalField,
   readQuantitativeField,
   readTemporalField
-} from "./scales.js";
+} from "./scales/index.js";
 import {
   layoutSeriesPartition,
   validateColorLayout

package/src/grammar/bars/aggregate.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze } from "../../core/immutable.js";
-import { readNominalField, readTemporalField } from "../scales.js";
+import { readNominalField, readTemporalField } from "../scales/index.js";
 import {
   aggregateRows,
   validateAggregateFieldType,
@@ -40,7 +40,7 @@ export function deriveBarAggregates(rows, layer) {
   let colorAggregate;
 
   if (color !== undefined) {
-    if (color.fieldType === "nominal") {
+    if (["nominal", "ordinal"].includes(color.fieldType)) {
       colorValues = readNominalField(rows, color.field);
     } else if (color.fieldType === "quantitative") {
       colorAggregate = color.aggregate;
@@ -48,7 +48,7 @@ export function deriveBarAggregates(rows, layer) {
       validateAggregateFieldValues(rows, color.field, color.fieldType);
     } else {
       throw new Error(
-        `Bar color encoding on mark "${layer.id}" must be nominal or aggregate quantitative.`
+        `Bar color encoding on mark "${layer.id}" must be categorical or aggregate quantitative.`
       );
     }
   }

package/src/grammar/bars/geometry.js

@@ -27,19 +27,19 @@ export function normalizeBarWidth(options = {}, existing) {
   return cloneAndFreeze({ pixels: options.pixels });
 }
 
-export function normalizeOffsetPadding(options = {}, existing) {
+export function normalizeOffsetPadding(options = {}, existing, channel = "xOffset") {
   const paddingInner = options.paddingInner ??
     existing?.paddingInner ?? DEFAULT_OFFSET_PADDING.paddingInner;
   const paddingOuter = options.paddingOuter ??
     existing?.paddingOuter ?? DEFAULT_OFFSET_PADDING.paddingOuter;
   if (!Number.isFinite(paddingInner) || paddingInner < 0 || paddingInner >= 1) {
     throw new RangeError(
-      "xOffset paddingInner must be from 0 (inclusive) to 1 (exclusive)."
+      `${channel} paddingInner must be from 0 (inclusive) to 1 (exclusive).`
     );
   }
   if (!Number.isFinite(paddingOuter) || paddingOuter < 0) {
     throw new RangeError(
-      "xOffset paddingOuter must be a non-negative finite number."
+      `${channel} paddingOuter must be a non-negative finite number.`
     );
   }
   return cloneAndFreeze({ paddingInner, paddingOuter });

package/src/grammar/bars/policy.js

@@ -46,6 +46,11 @@ export function resolveBarChannels(layer) {
     : { orientation, category: "y", measure: "x" };
 }
 
+export function resolveBarOffsetChannel(layer) {
+  const channels = resolveBarChannels(layer);
+  return channels === undefined ? undefined : `${channels.category}Offset`;
+}
+
 export function resolveBarGrain(layer) {
   if (layer?.mark?.type !== "bar") return undefined;
   const x = layer.encoding?.x;
@@ -84,7 +89,8 @@ export function resolveBarColorLayout(layer) {
   }
   const channels = resolveBarChannels(layer);
   if (layer?.encoding?.[channels?.measure]?.stack === "normalize") return "fill";
-  if (layer?.encoding?.xOffset !== undefined) return "group";
+  const offsetChannel = resolveBarOffsetChannel(layer);
+  if (layer?.encoding?.[offsetChannel] !== undefined) return "group";
   if (layer?.encoding?.[channels?.measure]?.stack === null) return "overlay";
   return "stack";
 }

package/src/grammar/coordinates.js

@@ -1,10 +1,6 @@
+import { getPositionChannelDefinition } from "../core/vocabulary.js";
+
 const COORDINATE_TYPES = new Set(["cartesian", "polar"]);
-const POSITION_COORDINATES = Object.freeze({
-  x: Object.freeze({ id: "main", type: "cartesian" }),
-  y: Object.freeze({ id: "main", type: "cartesian" }),
-  theta: Object.freeze({ id: "polar", type: "polar" }),
-  radius: Object.freeze({ id: "polar", type: "polar" })
-});
 
 export function validateCoordinateType(value) {
   if (!COORDINATE_TYPES.has(value)) {
@@ -15,7 +11,7 @@ export function validateCoordinateType(value) {
 }
 
 export function getPositionCoordinateDefaults(channel) {
-  const coordinate = POSITION_COORDINATES[channel];
+  const coordinate = getPositionChannelDefinition(channel)?.coordinate;
 
   if (coordinate === undefined) {
     throw new Error(`Unknown positional channel "${channel}".`);

package/src/grammar/density.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze } from "../core/immutable.js";
-import { isNominalValue } from "./scales.js";
+import { isNominalValue } from "./scales/index.js";
 
 const SQRT_TWO_PI = Math.sqrt(2 * Math.PI);
 
@@ -35,7 +35,7 @@ function requireField(value, label) {
 export function validateDensityTransform(transform) {
   const supported = [
     "type", "field", "groupBy", "bandwidth", "extent", "steps", "as",
-    "resolve", "kernel", "normalization"
+    "resolve", "kernel", "normalization", "resolved"
   ];
   const unknown = Object.keys(transform).find(key => !supported.includes(key));
   if (unknown !== undefined) {
@@ -92,6 +92,25 @@ export function validateDensityTransform(transform) {
   if (transform.resolve !== "shared") {
     throw new Error(`Unsupported density resolve "${transform.resolve}".`);
   }
+  if (transform.resolved !== undefined) {
+    const resolved = transform.resolved;
+    if (
+      resolved === null ||
+      typeof resolved !== "object" ||
+      Array.isArray(resolved) ||
+      Object.keys(resolved).some(key => !["bandwidth", "extent"].includes(key)) ||
+      !Number.isFinite(resolved.bandwidth) ||
+      resolved.bandwidth <= 0 ||
+      !Array.isArray(resolved.extent) ||
+      resolved.extent.length !== 2 ||
+      !resolved.extent.every(Number.isFinite) ||
+      resolved.extent[0] >= resolved.extent[1]
+    ) {
+      throw new TypeError(
+        "Density resolved provenance requires a positive bandwidth and ascending finite extent."
+      );
+    }
+  }
   return transform;
 }
 

package/src/grammar/facets/dependencies.js

@@ -0,0 +1,185 @@
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
+import { validateUserId } from "../../core/identifiers.js";
+
+const ROW_PRESERVING_TRANSFORMS = new Set(["filter"]);
+const STATISTICAL_TRANSFORMS = new Set([
+  "regression",
+  "density",
+  "interval",
+  "boxSummary",
+  "boxOutlier"
+]);
+
+function requireCollection(value, label) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new Error(`Facet dependency planning requires at least one ${label}.`);
+  }
+  return value;
+}
+
+function indexById(values, label) {
+  const indexed = new Map();
+  values.forEach((value, index) => {
+    if (!isPlainObject(value)) {
+      throw new TypeError(`Facet ${label} at index ${index} must be a plain object.`);
+    }
+    const id = validateUserId(value.id, `Facet ${label} id`);
+    if (indexed.has(id)) {
+      throw new Error(`Facet dependency graph contains duplicate ${label} id "${id}".`);
+    }
+    indexed.set(id, { value, index });
+  });
+  return indexed;
+}
+
+function classifyDataset(dataset) {
+  const transforms = dataset.transform;
+  if (transforms === undefined || transforms.length === 0) {
+    if (dataset.source !== undefined) {
+      throw new Error(
+        `Derived dataset "${dataset.id}" requires one supported transform.`
+      );
+    }
+    if (!Array.isArray(dataset.values)) {
+      throw new TypeError(`Source dataset "${dataset.id}" requires array values.`);
+    }
+    return "source";
+  }
+  if (!Array.isArray(transforms) || transforms.length !== 1 || !isPlainObject(transforms[0])) {
+    throw new Error(
+      `Facet replay currently requires dataset "${dataset.id}" to contain exactly one transform.`
+    );
+  }
+  if (typeof dataset.source !== "string" || dataset.source.length === 0) {
+    throw new Error(`Transformed dataset "${dataset.id}" requires a source dataset.`);
+  }
+  const type = transforms[0].type;
+  if (ROW_PRESERVING_TRANSFORMS.has(type)) return "rowPreserving";
+  if (STATISTICAL_TRANSFORMS.has(type)) return "statistical";
+  throw new Error(
+    `Facet replay does not support dataset transform "${type ?? "unknown"}" on "${dataset.id}".`
+  );
+}
+
+function tracePath(id, datasets, classifications, visiting = new Set()) {
+  const indexed = datasets.get(id);
+  if (indexed === undefined) {
+    throw new Error(`Facet dependency graph references missing dataset "${id}".`);
+  }
+  if (visiting.has(id)) {
+    throw new Error(`Facet dependency graph contains a cycle at dataset "${id}".`);
+  }
+  const dataset = indexed.value;
+  const kind = classifications.get(id);
+  if (kind === "source") return [id];
+  const nextVisiting = new Set(visiting).add(id);
+  return [
+    ...tracePath(dataset.source, datasets, classifications, nextVisiting),
+    id
+  ];
+}
+
+function eligiblePrefix(path, classifications) {
+  const statisticalIndex = path.findIndex(id => classifications.get(id) === "statistical");
+  return statisticalIndex === -1 ? path : path.slice(0, statisticalIndex);
+}
+
+function resolveAnchor(paths, datasets, classifications, requested) {
+  const eligible = paths.map(path => eligiblePrefix(path, classifications));
+  const common = eligible[0].filter(id =>
+    eligible.every(path => path.includes(id))
+  );
+  if (common.length === 0) {
+    const roots = [...new Set(paths.map(path => path[0]))];
+    throw new Error(
+      `Facet layers do not share one partition anchor; roots are ${roots.map(id => `"${id}"`).join(", ")}.`
+    );
+  }
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Facet partition dataset id");
+    if (!datasets.has(id)) {
+      throw new Error(`Facet partition dataset "${id}" does not exist.`);
+    }
+    if (!common.includes(id)) {
+      throw new Error(
+        `Facet partition dataset "${id}" is not a common row-preserving ancestor of every layer.`
+      );
+    }
+    return id;
+  }
+  return common.at(-1);
+}
+
+function requireFacetField(dataset, field) {
+  if (!Array.isArray(dataset.values)) {
+    throw new TypeError(
+      `Facet partition dataset "${dataset.id}" requires materialized array values.`
+    );
+  }
+  for (const [index, row] of dataset.values.entries()) {
+    if (!isPlainObject(row) || !Object.hasOwn(row, field)) {
+      throw new Error(
+        `Facet field "${field}" is missing from row ${index} of partition dataset "${dataset.id}".`
+      );
+    }
+  }
+}
+
+export function planFacetDependencies(semanticSpec, options = {}) {
+  if (!isPlainObject(semanticSpec)) {
+    throw new TypeError("planFacetDependencies requires a semantic spec.");
+  }
+  if (!isPlainObject(options)) {
+    throw new TypeError("Facet dependency options must be a plain object.");
+  }
+  if (typeof options.field !== "string" || options.field.length === 0) {
+    throw new TypeError("Facet field must be a non-empty string.");
+  }
+  const field = options.field;
+  const datasetValues = requireCollection(semanticSpec.datasets, "dataset");
+  const layerValues = requireCollection(semanticSpec.layers, "visible layer");
+  const datasets = indexById(datasetValues, "dataset");
+  const layers = indexById(layerValues, "layer");
+  const classifications = new Map(
+    [...datasets].map(([id, { value }]) => [id, classifyDataset(value)])
+  );
+  const layerPaths = [...layers].map(([layerId, { value: layer }]) => {
+    const data = validateUserId(layer.data, `Facet layer "${layerId}" dataset id`);
+    return { layerId, data, path: tracePath(data, datasets, classifications) };
+  });
+  const anchor = resolveAnchor(
+    layerPaths.map(entry => entry.path),
+    datasets,
+    classifications,
+    options.data
+  );
+  requireFacetField(datasets.get(anchor).value, field);
+
+  const replayIds = new Set();
+  for (const { path } of layerPaths) {
+    const anchorIndex = path.indexOf(anchor);
+    for (const id of path.slice(anchorIndex + 1)) replayIds.add(id);
+  }
+  const replay = [...replayIds]
+    .map(id => {
+      const { value: dataset, index } = datasets.get(id);
+      const depth = layerPaths.find(entry => entry.path.includes(id)).path.indexOf(id);
+      return {
+        id,
+        source: dataset.source,
+        kind: classifications.get(id),
+        transform: dataset.transform[0],
+        depth,
+        index
+      };
+    })
+    .sort((left, right) => left.depth - right.depth || left.index - right.index)
+    .map(({ depth, index, ...entry }) => entry);
+
+  return cloneAndFreeze({
+    field,
+    anchor,
+    replay,
+    layers: layerPaths.map(({ layerId, data }) => ({ id: layerId, data }))
+  });
+}