ggaction 0.0.20 → 0.0.22

package/src/actions/canvas/plotBorder.js

@@ -2,6 +2,7 @@ import { action } from "../../core/action.js";
 import { noOptions } from "../../core/validation.js";
 import { resolveGraphicBounds } from "../../layout/canvas.js";
 import { resolvePlotGraphicPlacement } from "../../materialization/graphicHierarchy.js";
+import { hasPlotUnderlays } from "../../materialization/plotDrawOrder.js";
 
 export const rematerializePlotBorder = /* @__PURE__ */ action(
   { op: "rematerializePlotBorder", description: "Materialize the optional inset plot border." },
@@ -23,6 +24,6 @@ export const rematerializePlotBorder = /* @__PURE__ */ action(
     for (const [property, value] of Object.entries(properties)) {
       next = next.editGraphics({ target: "plotBorder", property, value });
     }
-    return next;
+    return hasPlotUnderlays(next) ? next.rematerializePlotDrawOrder() : next;
   }
 );

package/src/actions/canvas/plotOrder.js

@@ -0,0 +1,14 @@
+import { action } from "../../core/action.js";
+import { noOptions } from "../../core/validation.js";
+import { resolveProgramPlotDrawOrder } from "../../materialization/plotDrawOrder.js";
+
+export const rematerializePlotDrawOrder = action({
+  op: "rematerializePlotDrawOrder", description: "Reconcile explicit guide underlays without changing graphic content."
+}, function (args = {}) {
+  noOptions(args, "rematerializePlotDrawOrder");
+  const plot = this.graphicSpec.objects["plot-main"];
+  if (this.compositionSpec !== undefined || plot === undefined) return this;
+  const children = resolveProgramPlotDrawOrder(this);
+  if (children.every((id, index) => id === plot.children[index])) return this;
+  return this.editGraphics({ target: "plot-main", property: "children", value: children });
+});

package/src/actions/charts/area.js

@@ -33,7 +33,7 @@ export const createAreaPlot = /* @__PURE__ */ action({ op: OPERATION, descriptio
   validateAreaEndpointPair(normalizeAreaBound(lower), normalizeAreaBound(upper));
   const groupBy = args.groupBy === undefined ? undefined : normalizeGroupFields(args.groupBy);
   const area = omitUndefinedOptions(normalizeAppearance(args.area, [
-    "fill", "opacity", "stroke", "strokeWidth", "curve",
+    "clip",     "fill", "opacity", "stroke", "strokeWidth", "curve",
     ...STROKE_STYLE_PROPERTIES
   ], `${OPERATION} area`));
   const color = args.color === undefined ? undefined : normalizeCategoricalColor(args.color, `${OPERATION} color`);

package/src/actions/charts/bar.js

@@ -17,10 +17,10 @@ import {
 } from "./shared.js";
 
 const OPTIONS = Object.freeze([
-  "id", "data", "coordinate", "orientation", "x", "y", "color", "width", "bar", "guides"
+  "id", "data", "coordinate", "orientation", "x", "y", "color", "width", "bar", "missing", "guides"
 ]);
 const BAR_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
+  "clip",   "fill", "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
 ]);
 
 function normalizeBarPosition(value, label) {
@@ -40,7 +40,7 @@ function normalizeBarPosition(value, label) {
 export const createBarPlot = /* @__PURE__ */ action(
   {
     op: "createBarPlot",
-    description: "Create a Cartesian bar plot from existing chart data."
+    description: "Create a Cartesian bar plot, including interval-width X bins with Y aggregates, from existing chart data."
   },
   function (args = {}) {
     validateFacadeOptions(args, OPTIONS, "createBarPlot");
@@ -74,7 +74,7 @@ export const createBarPlot = /* @__PURE__ */ action(
     const positions = isBarCategoryEncoding(y) || orientation === "horizontal"
       ? [["encodeY", y], [xRange ? "encodeXRange" : "encodeX", x]]
       : [["encodeX", x], [yRange ? "encodeYRange" : "encodeY", y]];
-    let next = this.createBarMark({ id, data, ...bar, ...(orientation === undefined ? {} : { orientation }) });
+    let next = this.createBarMark({ id, data, ...bar, ...(args.missing === undefined ? {} : { missing: args.missing }), ...(orientation === undefined ? {} : { orientation }) });
     for (const [operation, encoding] of positions) {
       next = next[operation](positionArgs(encoding, {
         target: id, coordinate: args.coordinate

package/src/actions/charts/density.js

@@ -10,7 +10,7 @@ const OPERATION = "createDensityPlot";
 const OPTIONS = ["id", "data", "coordinate", "field", "groupBy", "bandwidth", "extent", "steps",
   "kernel", "normalization", "weight", "as", "densityChannel", "valueScale", "densityScale", "color", "area", "guides"];
 const AREA_OPTIONS = [
-  "fill", "opacity", "stroke", "strokeWidth", "curve",
+  "clip",   "fill", "opacity", "stroke", "strokeWidth", "curve",
   ...STROKE_STYLE_PROPERTIES
 ];
 

package/src/actions/charts/ecdf.js

@@ -23,7 +23,7 @@ const EDIT_OPTIONS = Object.freeze([
   "target", "data", "coordinate", "field", "groupBy", "weight", "missing", "as", "color"
 ]);
 const LINE_OPTIONS = Object.freeze([
-  "strokeWidth", "stroke", "opacity", ...STROKE_STYLE_PROPERTIES
+  "clip",   "strokeWidth", "stroke", "opacity", ...STROKE_STYLE_PROPERTIES
 ]);
 const LABEL_OPTIONS = Object.freeze([
   "field", "value", "content", "normalizeBy", "format", "layout", "fill",

package/src/actions/charts/endpoints.js

@@ -9,6 +9,7 @@ import {
   validateNonNegativeFinite,
   validateOptionObject
 } from "../../core/validation.js";
+import { retainStatisticalDependents, restoreStatisticalDependents } from "../marks/dependentReferences.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findSemanticScale } from "../../selectors/scales.js";
 import {
@@ -33,14 +34,14 @@ const DUMBBELL_OPTIONS = Object.freeze([
 const CATEGORY_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
 const VALUE_OPTIONS = Object.freeze(["field", "fieldType", "scale"]);
 const POINT_OPTIONS = Object.freeze([
-  "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
+  "clip",   "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
   ...STROKE_STYLE_PROPERTIES
 ]);
 const RULE_OPTIONS = Object.freeze([
-  "stroke", "strokeWidth", "strokeDash", "opacity", ...STROKE_STYLE_PROPERTIES
+  "clip", "stroke", "strokeWidth", "strokeDash", "opacity", ...STROKE_STYLE_PROPERTIES
 ]);
 const LABEL_OPTIONS = Object.freeze([
-  "endpoint", "field", "value", "content", "normalizeBy", "format", "layout",
+  "clip",   "endpoint", "field", "value", "content", "normalizeBy", "format", "layout",
   "fill", "opacity", "fontSize", "fontFamily", "fontWeight", "align", "baseline",
   "rotation", "dx", "dy"
 ]);
@@ -435,6 +436,49 @@ function reviseRequestedScales(program, ownerId, revised, changes) {
   return next;
 }
 
+function reviseRoleGuideSamples(program, owner, current, revised, changes) {
+  const categoryAxis = current.orientation === "vertical" ? "x" : "y";
+  const valueAxis = categoryAxis === "x" ? "y" : "x";
+  const field = value => typeof value === "string" ? value : value?.field;
+  const axes = new Set();
+  for (const key of changes) {
+    if (["data", "orientation"].includes(key) && revised[key] !== current.options[key]) {
+      axes.add("x"); axes.add("y");
+    } else if (key === "category" &&
+      (field(revised.category) !== current.roles.category.field || revised.category?.scale)) {
+      axes.add(categoryAxis);
+    } else if (["value", "start", "end"].includes(key) &&
+      (field(revised[key]) !== current.roles[key]?.field || revised[key]?.scale) ||
+      ["summary", "baseline"].includes(key) && revised[key] !== current.options[key]) {
+      axes.add(valueAxis);
+    }
+  }
+  let next = program;
+  for (const axis of axes) {
+    const saved = revised.guides?.axes?.[axis]?.ticksAndLabels;
+    if (saved?.values) {
+      const { values, ...rest } = saved;
+      revised.guides = { ...revised.guides, axes: { ...revised.guides.axes,
+        [axis]: { ...revised.guides.axes[axis], ticksAndLabels: {
+          ...rest, ...(axis === categoryAxis ? {} : { count: Math.max(2, values.length) })
+        } }
+      } };
+    }
+    const scale = owner.encoding[axis]?.scale;
+    for (const [id, config] of Object.entries(next.guideConfigs.axis ?? {})) {
+      if (config.ticks?.scale !== scale || config.ticks.mode !== "values") continue;
+      const refresh = part => {
+        if (axis === categoryAxis) return { ...part, inferredValues: true };
+        const { values, ...rest } = part;
+        return { ...rest, mode: "count", count: Math.max(2, values?.length ?? 5), inferredValues: false };
+      };
+      next = next._withGuideConfig(id, "ticks", refresh(config.ticks));
+      if (config.labels) next = next._withGuideConfig(id, "labels", refresh(config.labels));
+    }
+  }
+  return next;
+}
+
 export const editEndpointPlot = /* @__PURE__ */ action(
   { op: "editEndpointPlot", description: "Atomically revise an endpoint plot's semantic roles." },
   function (args = {}) {
@@ -452,8 +496,13 @@ export const editEndpointPlot = /* @__PURE__ */ action(
     }
     const revised = { ...current.options };
     for (const key of changes) revised[key] = args[key];
-    let next = this.removeMark({ target: owner.id });
+    const axes = { fromAxis: current.orientation === "vertical" ? "y" : "x",
+      toAxis: revised.orientation === "vertical" ? "y" : "x" };
+    const retained = retainStatisticalDependents(this, owner.id);
+    let next = reviseRoleGuideSamples(retained.program, owner, current, revised, changes);
+    next = next.removeMark({ target: owner.id });
     next = reviseRequestedScales(next, owner.id, revised, changes);
-    return next[KIND_METHOD[current.kind]](revised);
+    const rebuilt = next[KIND_METHOD[current.kind]](revised);
+    return restoreStatisticalDependents(rebuilt, retained.references, { ...axes, fallbackSource: owner.id });
   }
 );

package/src/actions/charts/heatmap.js

@@ -23,7 +23,7 @@ const OPTIONS = [
   "id", "data", "coordinate", "x", "y", "bin", "color", "rect", "guides"
 ];
 const RECT_OPTIONS = [
-  "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
+  "clip",   "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
 ];
 const BIN_OPTIONS = [
   "bins", "extent", "includeEmpty"

package/src/actions/charts/histogram.js

@@ -17,7 +17,7 @@ const OPTIONS = Object.freeze([
   "binBoundaries", "stack", "xScale", "yScale", "weight", "color", "bar", "guides"
 ]);
 const BAR_OPTIONS = Object.freeze([
-  "fill", "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
+  "clip",   "fill", "opacity", "stroke", "strokeWidth", ...RECT_STYLE_PROPERTIES
 ]);
 const HISTOGRAM_OPTIONS = Object.freeze([
   "maxBins", "binStep", "binBoundaries", "stack", "xScale", "yScale", "weight"

package/src/actions/charts/horizon.js

@@ -52,7 +52,7 @@ export const createHorizonPlot = /* @__PURE__ */ action({
   const { id: requestedId, data: requestedData, coordinate, x: requestedX, y: requestedY,
     area: requestedArea, guides: requestedGuides, ...horizon } = omitUndefinedOptions(args);
   const { opacity, ...area } = omitUndefinedOptions(normalizeAppearance(requestedArea,
-    ["opacity", "stroke", "strokeWidth", "curve", ...STROKE_STYLE_PROPERTIES],
+    ["clip", "opacity", "stroke", "strokeWidth", "curve", ...STROKE_STYLE_PROPERTIES],
     `${OPERATION} area`));
   for (const [key, value] of Object.entries({ ...horizon, ...area })) {
     if (value === null) throw new TypeError(`${OPERATION} ${key} cannot be null.`);

package/src/actions/charts/index.js

@@ -11,7 +11,7 @@ import { createPiePlot } from "./pie.js";
 import { createDensityPlot } from "./density.js";
 import { createHorizonPlot } from "./horizon.js";
 import { createPolarLinePlot, createPolarScatterPlot } from "./polar.js";
-import { createRadarPlot } from "./radar.js";
+import { createRadarPlot, editRadarPlot } from "./radar.js";
 import { createRugPlot, createStripPlot } from "./rug-strip.js";
 import { createIntervalPlot, createRegressionPlot } from "./interval-regression.js";
 import {
@@ -38,6 +38,7 @@ export function registerChartActions(ProgramClass) {
   ProgramClass.prototype.createPolarScatterPlot = createPolarScatterPlot;
   ProgramClass.prototype.createPolarLinePlot = createPolarLinePlot;
   ProgramClass.prototype.createRadarPlot = createRadarPlot;
+  ProgramClass.prototype.editRadarPlot = editRadarPlot;
   ProgramClass.prototype.createRugPlot = createRugPlot;
   ProgramClass.prototype.createStripPlot = createStripPlot;
   ProgramClass.prototype.createIntervalPlot = createIntervalPlot;

package/src/actions/charts/interval-regression.js

@@ -19,7 +19,7 @@ const INTERVAL_OPTIONS = Object.freeze([
   "color", "point", "errorBar", "guides"
 ]);
 const POINT_OPTIONS = Object.freeze([
-  "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
+  "clip",   "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
   ...STROKE_STYLE_PROPERTIES
 ]);
 const ERROR_BAR_OPTIONS = Object.freeze([

package/src/actions/charts/line.js

@@ -20,7 +20,7 @@ const OPTIONS = Object.freeze([
   "strokeDash", "line", "guides"
 ]);
 const LINE_OPTIONS = Object.freeze([
-  "strokeWidth", "curve", "tension", "stroke", "opacity", "closed",
+  "clip", "missing", "strokeWidth", "curve", "tension", "stroke", "opacity", "closed",
   ...STROKE_STYLE_PROPERTIES
 ]);
 

package/src/actions/charts/radar.js

@@ -7,6 +7,10 @@ import { normalizeGroupFields } from "../../grammar/pathSeries.js";
 import { readNominalField, readQuantitativeField } from
   "../../grammar/scales/fields.js";
 import { findDataset } from "../../selectors/datasets.js";
+import { resolveEligibleLayer } from "../../selectors/layers.js";
+import { planDerivedDataRevision } from "../../materialization/dataProvenance.js";
+import { applyLayerDataRematerialization } from "../../materialization/dependencies.js";
+import { deriveFoldRows, normalizeFoldTransform } from "../../grammar/fold.js";
 import {
   normalizeAppearance,
   normalizeEncoding,
@@ -76,13 +80,13 @@ function normalizeValue(value, operation) {
   return { ...omitUndefinedOptions(result), fieldType: "quantitative" };
 }
 
-function normalizeWide(value, id, operation) {
+function normalizeWide(value, id, operation, minimum = 3) {
   if (!isPlainObject(value)) {
     throw new TypeError(`${operation} wide must be a plain object.`);
   }
   validateOptionObject(value, WIDE_OPTIONS, `${operation} wide`);
-  if (!Array.isArray(value.fields) || value.fields.length < 3) {
-    throw new Error(`${operation} wide.fields must contain at least three fields.`);
+  if (!Array.isArray(value.fields) || value.fields.length < minimum) {
+    throw new Error(`${operation} wide.fields must contain at least ${minimum === 3 ? "three" : "two"} fields.`);
   }
   const fields = [...value.fields];
   for (const field of fields) validateNonEmptyString(field, `${operation} wide field`);
@@ -303,3 +307,59 @@ export const createRadarPlot = /* @__PURE__ */ action(
     });
   }
 );
+
+export const editRadarPlot = /* @__PURE__ */ action(
+  {
+    op: "editRadarPlot",
+    description: "Revise a wide Radar plot's dimensions and order while preserving its series and appearance."
+  },
+  function (args = {}) {
+    const operation = "editRadarPlot";
+    validateFacadeOptions(args, ["target", "wide"], operation);
+    validateOptionObject(args.wide, ["fields"], `${operation} wide`);
+    const owner = resolveEligibleLayer(this, {
+      target: args.target,
+      label: "wide Radar plot",
+      predicate: layer => this.markConfigs[layer.id]?.compositionRole === "radar" &&
+        findDataset(this, layer.data)?.transform?.[0]?.type === "fold"
+    });
+    const previous = findDataset(this, owner.data);
+    const prior = previous.transform[0];
+    const source = findDataset(this, previous.source);
+    const wide = normalizeWide({ ...args.wide, as: prior.as }, owner.id, operation, 2);
+    for (const field of wide.fields) readQuantitativeField(source.values, field);
+    const transform = normalizeFoldTransform(wide, previous.id);
+    const rows = deriveFoldRows(source.values, transform);
+    const group = owner.encoding.group;
+    const groupBy = group?.fields ?? (group?.field ? [group.field] : []);
+    validateRadarRows(rows, { category: prior.as.key, value: prior.as.value,
+      groupBy, order: wide.fields }, operation);
+    const revision = planDerivedDataRevision(this, {
+      owner: owner.id, role: "RadarData", previous: previous.id, consumers: [owner.id]
+    });
+    let next = this.createFoldData({
+      id: revision.id, source: source.id, fields: wide.fields, as: prior.as
+    }).rebindLayerData(revision.rebinds[0]);
+    const theta = owner.encoding.theta.scale;
+    const revisedValues = config => {
+      const full = config.inferredValues || !Array.isArray(config.values) ||
+        config.values.length === prior.fields.length && prior.fields.every(field => config.values.includes(field));
+      const retained = full ? wide.fields : config.values.filter(field => wide.fields.includes(field));
+      return { ...config, mode: "values", values: retained.length ? retained : wide.fields };
+    };
+    for (const [id, axis] of Object.entries(next.semanticSpec.guides.axis ?? {})) {
+      if (axis.scale !== theta) continue;
+      for (const role of ["ticks", "labels"]) {
+        const config = next.guideConfigs.axis?.[id]?.[role];
+        if (config) next = next._withGuideConfig(id, role, revisedValues(config));
+      }
+    }
+    const thetaGrid = next.guideConfigs.grid?.theta;
+    if (thetaGrid?.scale === theta) next = next._withGridConfig("theta", revisedValues(thetaGrid));
+    next = next.editThetaScale({ target: owner.id, domain: wide.fields });
+    next = applyLayerDataRematerialization(next, owner.id);
+    if (next.markConfigs[owner.id]?.closed !== true) next = next.editLineMark({ target: owner.id, closed: true });
+    return next.releaseDerivedData(revision.release)
+      ._withContext({ currentMark: owner.id, currentData: source.id });
+  }
+);

package/src/actions/charts/raincloud.js

@@ -5,6 +5,7 @@ import { validateOptionObject } from "../../core/validation.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { retainStatisticalDependents, restoreStatisticalDependents } from "../marks/dependentReferences.js";
 import { resolveViolinRoles } from "../violinPlots/create.js";
 import {
   applyFacadeGuides,
@@ -111,6 +112,13 @@ function roleScale(encoding, fallbackId, label, defaults = {}) {
 
 function normalizeColor(value, category, id) {
   if (value === undefined || value === false) return undefined;
+  if (isPlainObject(value) && Object.hasOwn(value, "value")) {
+    validateOptionObject(value, ["value"], "Raincloud fixed color");
+    if (typeof value.value !== "string" || value.value.length === 0) {
+      throw new TypeError("Raincloud fixed color requires a non-empty value.");
+    }
+    return { value: value.value };
+  }
   const color = normalizeEncoding(value, "Raincloud color");
   if (color.field !== category.field) {
     throw new Error("Raincloud color must encode its category field.");
@@ -194,6 +202,9 @@ function addSummary(program, config, positions) {
       y: positions.y,
       width: options.width ?? { band: 0.24 },
       ...options,
+      ...(config.color?.value === undefined ? {} : {
+        box: { ...(options.box ?? {}), fill: config.color.value }
+      }),
       guides: false
     });
     if (config.color !== undefined) next = next.encodeColor({ target: id, ...config.color });
@@ -238,7 +249,7 @@ function addPoints(program, config, positions) {
     coordinate: config.coordinate,
     x: positions.x,
     y: positions.y,
-    ...(config.color === undefined ? {} : { color: config.color }),
+    ...(config.color?.field === undefined ? {} : { color: config.color }),
     ...(size === undefined ? {} : { size }),
     ...(shape === undefined ? {} : { shape }),
     ...(point === undefined ? {} : { point }),
@@ -274,7 +285,7 @@ function buildRaincloud(program, config) {
       coordinate: config.coordinate,
       x: positions.x,
       y: positions.y,
-      ...(config.color === undefined ? {} : { color: config.color }),
+      ...(config.color?.field === undefined ? {} : { color: config.color }),
       density: { ...density, side: densitySide(config.orientation, config.side) },
       ...(area === undefined ? {} : { area }),
       guides: false
@@ -282,6 +293,11 @@ function buildRaincloud(program, config) {
   }
   next = addSummary(next, config, positions);
   next = addPoints(next, config, positions);
+  if (config.color?.value !== undefined) {
+    for (const id of [config.childIds.cloud, config.childIds.points]) {
+      if (findLayer(next, id) !== undefined) next = next.encodeColor({ target: id, value: config.color.value });
+    }
+  }
   const ownerId = [config.childIds.cloud, config.childIds.summary, config.childIds.points]
     .find(id => findLayer(next, id) !== undefined);
   if (ownerId === undefined) throw new Error("Raincloud requires at least one enabled component.");
@@ -395,11 +411,16 @@ export const editRaincloudPlot = /* @__PURE__ */ action(
     }
     const ownerId = raincloudOwner(this, args.target);
     const current = this.markConfigs[ownerId].raincloudPlot;
+    const category = Object.hasOwn(args, "category") ? args.category : current.category;
+    const color = Object.hasOwn(args, "color") ? args.color
+      : Object.hasOwn(args, "category") && current.color?.field === current.category.field
+        ? { ...current.color, field: normalizeEncoding(category, "Raincloud category").field }
+        : current.color;
     const candidateArgs = {
       id: current.id,
       data: Object.hasOwn(args, "data") ? args.data : current.source,
       ...(current.coordinate === undefined ? {} : { coordinate: current.coordinate }),
-      category: Object.hasOwn(args, "category") ? args.category : current.category,
+      category,
       value: Object.hasOwn(args, "value") ? args.value : current.value,
       orientation: args.orientation ?? current.orientation,
       side: args.side ?? current.side,
@@ -412,11 +433,21 @@ export const editRaincloudPlot = /* @__PURE__ */ action(
       points: Object.hasOwn(args, "points")
         ? normalizePoints(args.points, current.points)
         : current.points,
-      color: Object.hasOwn(args, "color") ? args.color : current.color,
+      color,
       guides: current.guides
     };
-    const withoutCurrent = this.removeMark({ target: ownerId });
+    const axes = { fromAxis: current.orientation === "vertical" ? "y" : "x",
+      toAxis: candidateArgs.orientation === "vertical" ? "y" : "x" };
+    const retained = retainStatisticalDependents(this, ownerId);
+    const withoutCurrent = retained.program.removeMark({ target: ownerId });
     const revised = normalizeCreate(withoutCurrent, candidateArgs, operation);
-    return buildRaincloud(alignExistingRoleScales(withoutCurrent, revised), revised);
+    const rebuilt = buildRaincloud(alignExistingRoleScales(withoutCurrent, revised), {
+      ...revised,
+      ...(!Object.hasOwn(args, "data") && current.sourceFilter !== undefined
+        ? { sourceFilter: current.sourceFilter } : {})
+    });
+    return restoreStatisticalDependents(rebuilt, retained.references, {
+      ...axes, fallbackSource: raincloudOwner(rebuilt, current.id)
+    });
   }
 );

package/src/actions/charts/rug-strip.js

@@ -21,13 +21,13 @@ import {
 const RUG_OPTIONS = Object.freeze(["id", "data", "coordinate", "x", "y", "edge", "tick", "guides"]);
 const MEASURE_OPTIONS = Object.freeze(["field", "fieldType", "temporalUnit", "scale"]);
 const TICK_OPTIONS = Object.freeze([
-  "length", "stroke", "strokeWidth", "opacity", ...STROKE_STYLE_PROPERTIES
+  "clip", "length", "stroke", "strokeWidth", "opacity", ...STROKE_STYLE_PROPERTIES
 ]);
 const STRIP_OPTIONS = Object.freeze([
   "id", "data", "coordinate", "x", "y", "color", "size", "shape", "point", "jitter", "guides"
 ]);
 const POINT_OPTIONS = Object.freeze([
-  "radius", "shape", "fill", "opacity", "stroke", "strokeWidth",
+  "clip",   "radius", "shape", "fill", "opacity", "stroke", "strokeWidth",
   ...STROKE_STYLE_PROPERTIES
 ]);
 const JITTER_OPTIONS = Object.freeze(["maxOffset", "seed", "key"]);

package/src/actions/charts/scatter.js

@@ -17,10 +17,10 @@ import {
 
 const OPTIONS = Object.freeze([
   "id", "data", "coordinate", "x", "y", "color", "stroke", "size", "shape",
-  "point", "guides"
+  "point", "missing", "guides"
 ]);
 const POINT_OPTIONS = Object.freeze([
-  "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
+  "clip",   "shape", "fill", "opacity", "stroke", "strokeWidth", "radius",
   ...STROKE_STYLE_PROPERTIES
 ]);
 
@@ -62,7 +62,7 @@ export const createScatterPlot = /* @__PURE__ */ action(
     const initialPoint = { ...point };
     if (stroke !== undefined) delete initialPoint.strokeWidth;
     let next = this
-      .createPointMark({ id, data, ...initialPoint })
+      .createPointMark({ id, data, ...initialPoint, ...(args.missing === undefined ? {} : { missing: args.missing }) })
       .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
       .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
     if (radius !== undefined) next = next.encodePointRadius({ target: id, value: radius });

package/src/actions/charts/text.js

@@ -7,7 +7,7 @@ import {
 } from "./shared.js";
 
 const OPTIONS = Object.freeze(["id", "data", "coordinate", "x", "y", "text", "color", "style", "guides"]);
-const STYLE_OPTIONS = Object.freeze(["missing", ...TEXT_MARK_STYLE_OPTIONS.filter(key => key !== "inheritColor")]);
+const STYLE_OPTIONS = Object.freeze(["clip", "missing", ...TEXT_MARK_STYLE_OPTIONS.filter(key => key !== "inheritColor")]);
 
 export const createTextPlot = /* @__PURE__ */ action({
   op: "createTextPlot", description: "Create a Cartesian text plot from existing chart data."

package/src/actions/composition/actions.js

@@ -20,7 +20,7 @@ const CONCAT_OPTIONS = Object.freeze([
   "id", "programs", "gap", "align", "padding"
 ]);
 const LAYOUT_EDIT_OPTIONS = Object.freeze([
-  "columns", "gap", "spacing", "align", "padding"
+  "columns", "gap", "spacing", "topLane", "align", "padding"
 ]);
 const REPLACEMENT_OPTIONS = Object.freeze(["target", "program"]);
 const INSERTION_OPTIONS = Object.freeze(["id", "program", "before", "after"]);
@@ -181,6 +181,9 @@ const editCompositionLayout = /* @__PURE__ */ closedAction(
       );
     }
     if (current.type !== "facet" && Object.hasOwn(args, "spacing")) throw new Error("Plot spacing requires a facet composition.");
+    if (current.type !== "facet" && Object.hasOwn(args, "topLane")) {
+      throw new Error("topLane requires a facet composition.");
+    }
     const padding = Object.hasOwn(args, "padding")
       ? normalizeCompositionPadding(args.padding, current.padding)
       : current.padding;
@@ -191,6 +194,7 @@ const editCompositionLayout = /* @__PURE__ */ closedAction(
       );
       layout = resolveFacetLayout({
         spacing: option(args, "spacing", current.spacing),
+        topLane: args.topLane === undefined ? current.topLane : args.topLane,
         plots: current.children.map(id => ({ id, ...resolveGraphicBounds(this.children[id]) })),
         children: current.children.map((id, index) => ({
           ...childDescriptor({ id, program: this.children[id] }),
@@ -218,11 +222,14 @@ const editCompositionLayout = /* @__PURE__ */ closedAction(
         padding
       });
     }
+    const { topLane: _previousTopLane, ...currentLayoutSpec } = current;
     return applyCompositionState(this, {
       children: this.children,
       compositionSpec: {
-        ...current,
-        ...(current.type === "facet" ? { columns: layout.columns, ...(layout.spacing !== undefined ? { spacing: layout.spacing } : current.spacing !== undefined ? { spacing: "canvas" } : {}) } : {}),
+        ...currentLayoutSpec,
+        ...(current.type === "facet" ? { columns: layout.columns,
+          ...(layout.spacing !== undefined ? { spacing: layout.spacing } : current.spacing !== undefined ? { spacing: "canvas" } : {}),
+          ...(layout.topLane === undefined ? {} : { topLane: layout.topLane }) } : {}),
         gap: layout.gap,
         align: layout.align,
         padding: layout.padding

package/src/actions/coordinates/actions.js

@@ -1,4 +1,5 @@
 import { action } from "../../core/action.js";
+import { validateMarkClipCoordinate } from "../../selectors/markClip.js";
 import { validateCoordinateType } from "../../grammar/coordinates.js";
 import { validateUserId } from "../../core/identifiers.js";
 import { findCoordinate } from "../../selectors/coordinates.js";
@@ -51,6 +52,7 @@ export const createCoordinate = /* @__PURE__ */ action(
 
     for (const layerId of layers) {
       const layer = findLayer(this, layerId);
+      validateMarkClipCoordinate(this, layer, this.markConfigs[layerId]?.clip, type);
 
       if (layer.coordinate !== undefined && layer.coordinate !== id) {
         throw new Error(

package/src/actions/data/basic.js

@@ -1,3 +1,5 @@
+import { createFlattenData, materializeFlattenData } from "./flatten.js";
+import {createLookupData,materializeLookupData} from "./lookup.js";
 import { createData } from "./create.js";
 import { createDerivedData } from "./derived.js";
 import { createBasicBin2DData } from "./basicBin2d.js";
@@ -5,6 +7,10 @@ import { materializeBin2DData } from "./bin2dMaterialize.js";
 
 export function registerBasicDataActions(ProgramClass) {
   ProgramClass.prototype.createData = createData;
+  ProgramClass.prototype.createFlattenData = createFlattenData;
+  ProgramClass.prototype.materializeFlattenData = materializeFlattenData;
+  ProgramClass.prototype.createLookupData=createLookupData;
+  ProgramClass.prototype.materializeLookupData=materializeLookupData;
   ProgramClass.prototype.createDerivedData = createDerivedData;
   ProgramClass.prototype.createBin2DData = createBasicBin2DData;
   ProgramClass.prototype.materializeBin2DData = materializeBin2DData;

package/src/actions/data/derived.js

@@ -1,3 +1,4 @@
+import {resolveDatasetTransformInputs} from "./shared.js";
 import { closedAction } from "../../core/action.js";
 import { validateGraphicItemLimit } from "../../core/validation.js";
 import { resolveGraphicItemCapacity } from "../../selectors/graphicCapacity.js";
@@ -49,11 +50,14 @@ export const createDerivedData = /* @__PURE__ */ closedAction(
     if (!hasDataset(this, source)) {
       throw new Error(`Unknown source dataset "${source}".`);
     }
+    const transforms=args.transform?.[0]?.type==="lookup"
+      ? [resolveDatasetTransformInputs(this,args.transform[0])]
+      : args.transform;
     const created = this
       .editSemantic({ property: `dataset[${id}].source`, value: source })
-      .editSemantic({ property: `dataset[${id}].transform`, value: args.transform });
+      .editSemantic({ property: `dataset[${id}].transform`, value: transforms });
     const input = resolveDatasetReference(created, source, "Source dataset");
-    const transform = args.transform[0];
+    const transform = transforms[0];
     assertFieldsAvailable(input.schema, transformInputFields(transform), {
       data: input.id,
       operation: "createDerivedData"