ggaction 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -4,6 +4,35 @@ All notable changes to `ggaction` are recorded in this file.
 
 ## Unreleased
 
+## [0.0.5] - 2026-07-21
+
+### Added
+
+- Added complete `createScatterPlot`, `createLinePlot`, `createBarPlot`, `createHistogram`, `createHeatmap`, and
+  `createParallelCoordinates` facades that reuse ordinary mark, encoding, scale, coordinate, and guide actions.
+- Added deterministic point jitter, ordered line paths, collision-aware text labels, field-driven rule widths, and
+  weighted Polar sectors with immutable rematerialization across data, scale, Canvas, selection, and facet changes.
+- Added window and rectangular 2D-bin data actions, binned heatmaps, categorical density and violin plots, Horizon
+  charts, Parallel Coordinates, and density-filled gradient plots with Browser Canvas and Node PNG parity.
+- Added backend-neutral item-local gradient paint, expanded public declarations and action contracts, and runnable
+  chart examples for every new capability.
+
+### Changed
+
+- Aligned Box Plot with the shared facade inference, ambiguity, public option-type, and opt-in guide contracts while
+  preserving its existing omitted-guide behavior.
+- Reorganized source, test, documentation, and internal architecture ownership around explicit policies and capability
+  registries without changing the renderer's concrete `graphicSpec` boundary.
+- Expanded public documentation with task-oriented API routing, generated split action references, improved mobile and
+  no-JavaScript navigation, complete facade discovery, and release-scoped deployment checks.
+
+### Fixed
+
+- Materialized the documented default point radius, made direct quantitative line x/y authoring order-independent, and
+  made layered datum rules resolve to the expected full-span geometry instead of an empty result.
+- Kept sticky documentation deep links below the top bar by sharing one computed fragment offset between CSS and the
+  page table of contents.
+
 ## [0.0.4] - 2026-07-19
 
 ### Changed
@@ -82,6 +111,7 @@ All notable changes to `ggaction` are recorded in this file.
 - Cartesian charts are the complete current path. Polar semantic tokens exist only where explicitly documented and do
   not imply complete polar rendering.
 
+[0.0.5]: https://github.com/ggaction/ggaction/releases/tag/v0.0.5
 [0.0.4]: https://github.com/ggaction/ggaction/releases/tag/v0.0.4
 [0.0.3]: https://github.com/ggaction/ggaction/releases/tag/v0.0.3
 [0.0.2]: https://github.com/ggaction/ggaction/releases/tag/v0.0.2

package/README.md

@@ -38,10 +38,13 @@ import { chart } from "ggaction";
 const program = chart()
   .createCanvas()
   .createData({ values: cars })
-  .createPointMark({ id: "points" })
-  .encodeX({ field: "Displacement" })
-  .encodeY({ field: "Acceleration" })
-  .encodeColor({ field: "Origin" })
+  .createScatterPlot({
+    id: "points",
+    x: "Displacement",
+    y: "Acceleration",
+    color: "Origin",
+    guides: false
+  })
   .createRegression()
   .createGuides();
 ```
@@ -74,22 +77,41 @@ const program = chart()
     margin: { top: 30, right: 130, bottom: 60, left: 70 }
   })
   .createData({ values: observations })
-  .createPointMark()
-  .encodeX({ field: "displacement" })
-  .encodeY({ field: "acceleration" })
-  .encodeColor({ field: "origin" })
-  .encodeRadius({ value: 4 })
-  .createGuides();
+  .createScatterPlot({
+    x: "displacement",
+    y: "acceleration",
+    color: "origin"
+  });
 
 const context = document.querySelector("#chart").getContext("2d");
 render(program, context);
 ```
 
-For the advanced version, follow the [regression recipe](https://ggaction.github.io/ggaction/recipes/regression-scatterplot/) or open the [runnable example](./examples/cars-regression-scatterplot/).
+Use `createLinePlot`, `createBarPlot`, `createHistogram`, and `createHeatmap` for
+the other basic Cartesian charts. Each facade records the regular mark,
+encoding, and guide actions as trace children, and the same resource-specific
+actions remain available for later edits. See the
+[Basic Charts API](https://ggaction.github.io/ggaction/api/basic-charts/).
+
+Use `createParallelCoordinates({ dimensions })` to connect each source row
+across ordered, dimension-local scales and axes. See the
+[Parallel Coordinates API](https://ggaction.github.io/ggaction/api/parallel-coordinates/)
+or the [runnable Cars example](./examples/cars-parallel-coordinates/).
+
+For an advanced layered example, follow the [regression recipe](https://ggaction.github.io/ggaction/recipes/regression-scatterplot/)
+or open the [runnable regression example](./examples/cars-regression-scatterplot/).
+To compare category distributions with density-filled strips, read the
+[gradient-plot guide](https://ggaction.github.io/ggaction/api/gradient-plots/)
+or open the [runnable example](./examples/cars-gradient-plot/).
+For symmetric or split density shapes centered on categories, use the
+[violin-plot API](https://ggaction.github.io/ggaction/api/violin-plots/) or the
+[runnable Cars example](./examples/cars-acceleration-violins/).
+For compact signed time-series bands, use `encodeHorizon` on an area mark and
+open the [runnable Gapminder example](./examples/gapminder-horizon/).
 
 ## What it supports
 
-- Cartesian and polar charts
+- Cartesian, Polar, and Parallel-coordinate charts
 - Statistical layers and intervals
 - Faceting and program composition
 - Mark selection and coordinated highlighting
@@ -120,7 +142,7 @@ All entries include TypeScript declarations. The default entry is browser-safe;
 
 ## Status and development
 
-> **Status:** `0.0.4` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
+> **Status:** `0.0.5` is the current experimental public release. APIs may change before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
 
 ```bash
 npm install

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ggaction",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "description": "Build charts through immutable, traceable graphical actions.",
   "license": "MIT",
   "author": "Hyeon Jeon",
@@ -22,7 +22,7 @@
   "type": "module",
   "files": [
     "src/",
-    "!src/AGENTS.md",
+    "!src/**/AGENTS.md",
     "types/",
     "README.md",
     "CHANGELOG.md",
@@ -54,19 +54,29 @@
     "test:docs:built": "node scripts/check-built-docs.js _site",
     "test:docs:browser": "node scripts/test-built-docs.js _site",
     "test:coverage": "node scripts/run-tests.js coverage",
-    "test:render": "node test/support/artifacts.js && node scripts/run-tests.js render && node scripts/generate-roadmap-gallery.js && node scripts/test-roadmap-gallery.js",
+    "test:render": "node scripts/run-render-tests.js",
     "assets:readme": "node scripts/generate-readme-demo.js",
-    "artifacts:gallery": "node scripts/generate-roadmap-gallery.js",
-    "artifacts:gallery:test": "node scripts/test-roadmap-gallery.js",
+    "artifacts:clean": "node test/support/artifacts.js",
+    "artifacts:gallery": "node scripts/generate-artifact-gallery.js",
+    "artifacts:gallery:test": "node scripts/test-artifact-gallery.js",
     "docs:images": "node scripts/generate-doc-images.js",
     "docs:llms": "node scripts/generate-llm-docs.js",
     "docs:capabilities": "node scripts/generate-doc-capabilities.js",
     "docs:capabilities:check": "node scripts/generate-doc-capabilities.js --check",
+    "docs:actions": "node scripts/generate-doc-action-metadata.js",
+    "docs:actions:check": "node scripts/generate-doc-action-metadata.js --check",
+    "docs:search": "node scripts/generate-doc-search-index.js",
+    "docs:search:check": "node scripts/generate-doc-search-index.js --check",
+    "docs:reference": "node scripts/generate-doc-action-reference.js",
+    "docs:reference:check": "node scripts/generate-doc-action-reference.js --check",
+    "docs:metadata": "node scripts/generate-doc-page-metadata.js",
+    "docs:metadata:check": "node scripts/generate-doc-page-metadata.js --check",
+    "docs:preflight": "node scripts/check-docs-environment.js",
     "docs:signatures": "node scripts/generate-doc-signatures.js",
     "docs:signatures:check": "node scripts/generate-doc-signatures.js --check",
-    "docs:generate": "npm run docs:signatures && npm run docs:capabilities && npm run docs:images && npm run docs:llms",
+    "docs:generate": "npm run docs:signatures && npm run docs:capabilities && npm run docs:actions && npm run docs:reference && npm run docs:metadata && npm run docs:search && npm run docs:images && npm run docs:llms",
     "docs:build": "bundle exec jekyll build --source docs --destination _site --baseurl /ggaction",
-    "docs:verify": "npm run docs:generate && npm run test:docs && npm run docs:build && npm run test:docs:built && npm run test:docs:browser",
+    "docs:verify": "npm run docs:preflight && npm run docs:generate && npm run test:docs && npm run docs:build && npm run test:docs:built && npm run test:docs:browser",
     "contracts:catalog": "node scripts/generate-action-catalog.js",
     "contracts:catalog:check": "node scripts/generate-action-catalog.js --check",
     "package:check": "node scripts/package-artifact.js --check",
@@ -86,6 +96,7 @@
     "@napi-rs/canvas": "^1.0.2"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
     "es-module-lexer": "^1.7.0",
     "gifenc": "^1.0.3",
     "playwright": "^1.61.1",

package/src/actions/boxPlots/create.js

@@ -1,7 +1,7 @@
 import { action } from "../../core/action.js";
 import { validateKeys } from "../../core/validation.js";
-import { findDataset } from "../../selectors/datasets.js";
 import { findSemanticScale } from "../../selectors/scales.js";
+import { resolveFacadeData } from "../charts/shared.js";
 import {
   BOX_PLOT_OPTIONS,
   boxEncodingArgs,
@@ -9,6 +9,7 @@ import {
   resolveBoxMedianAppearance,
   resolveBoxOutlierAppearance,
   resolveBoxPosition,
+  resolveBoxGuides,
   resolveBoxWhisker,
   resolveBoxWidth
 } from "./options.js";
@@ -26,11 +27,14 @@ export const createBoxPlot = action(
   function (args = {}) {
     validateKeys(args, BOX_PLOT_OPTIONS, "createBoxPlot");
     const id = resolveBoxPlotId(this, args.id);
-    const source = resolveBoxSourceLayer(this, args.target);
-    const data = args.data ?? source?.data ?? this.context.currentData;
-    if (findDataset(this, data) === undefined) {
-      throw new Error("createBoxPlot requires data or one inferable dataset.");
-    }
+    const source = resolveBoxSourceLayer(this, args.target, {
+      requiresInference: args.x === undefined || args.y === undefined
+    });
+    const data = resolveFacadeData(
+      this,
+      args.data ?? source?.data,
+      "createBoxPlot"
+    );
     const x = resolveBoxPosition(args.x, "x") ?? source?.encoding?.x;
     const y = resolveBoxPosition(args.y, "y") ?? source?.encoding?.y;
     const whisker = resolveBoxWhisker(args.whisker);
@@ -41,6 +45,7 @@ export const createBoxPlot = action(
     const box = resolveBoxAppearance(args.box);
     const median = resolveBoxMedianAppearance(args.median);
     const outlier = resolveBoxOutlierAppearance(args.outlier);
+    const guides = resolveBoxGuides(args.guides);
     if (x !== undefined && y !== undefined && resolveBoxOrientation(x, y) === undefined) {
       throw new Error(
         "createBoxPlot requires one categorical axis and one quantitative axis."
@@ -62,7 +67,8 @@ export const createBoxPlot = action(
         outliers: args.outliers ?? true,
         box,
         median,
-        outlier
+        outlier,
+        guides
       }
     });
     if (x !== undefined) {

package/src/actions/boxPlots/edit.js

@@ -4,7 +4,8 @@ import { validateUserId } from "../../core/identifiers.js";
 import { validateKeys } from "../../core/validation.js";
 import { BOX_FIELDS, deriveBoxData, normalizeBoxTransform } from
   "../../grammar/boxPlot.js";
-import { hasDataset } from "../../selectors/index.js";
+import { planDerivedDataRevision } from
+  "../../materialization/dataProvenance.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
 import {
@@ -61,14 +62,6 @@ function resolveEditedWhisker(current, value) {
   return resolveBoxWhisker(candidate, "editBoxPlot");
 }
 
-function nextRevisionId(program, ownerId, kind) {
-  let revision = 1;
-  while (hasDataset(program, `${ownerId}${kind}Revision${revision}`)) {
-    revision += 1;
-  }
-  return `${ownerId}${kind}Revision${revision}`;
-}
-
 function removeOwnedMark(program, id) {
   return program
     .editSemantic({ property: `layer[${id}]`, remove: true })
@@ -76,10 +69,6 @@ function removeOwnedMark(program, id) {
     ._withoutMaterializationConfig(["marks", id]);
 }
 
-function rebindRuleData(program, id, data) {
-  return program.editSemantic({ property: `layer[${id}].data`, value: data });
-}
-
 export const editBoxPlot = action(
   {
     op: "editBoxPlot",
@@ -156,7 +145,18 @@ export const editBoxPlot = action(
       derived.outliers.length > 0;
 
     if (revisesData) {
-      summaryId = nextRevisionId(this, owner.id, "SummaryData");
+      const whiskerConfig = next.markConfigs[current.whiskerId];
+      const capIds = [
+        whiskerConfig.errorBar.lowerCapId,
+        whiskerConfig.errorBar.upperCapId
+      ].filter(id => id !== undefined);
+      const summaryRevision = planDerivedDataRevision(this, {
+        owner: owner.id,
+        role: "SummaryData",
+        previous: current.summaryId,
+        consumers: [owner.id, current.whiskerId, ...capIds, current.medianId]
+      });
+      summaryId = summaryRevision.id;
       next = next.createBoxSummaryData({
         id: summaryId,
         source: current.source,
@@ -166,7 +166,16 @@ export const editBoxPlot = action(
         ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
       });
       if (hasOutliers) {
-        outlierDataId = nextRevisionId(this, owner.id, "OutlierData");
+        const hadOutlierLayer = findLayer(next, current.outlierId) !== undefined;
+        const outlierRevision = planDerivedDataRevision(this, {
+          owner: owner.id,
+          role: "OutlierData",
+          ...(current.outlierDataId === undefined
+            ? {}
+            : { previous: current.outlierDataId }),
+          consumers: hadOutlierLayer ? [current.outlierId] : []
+        });
+        outlierDataId = outlierRevision.id;
         next = next.createBoxOutlierData({
           id: outlierDataId,
           source: current.source,
@@ -175,37 +184,24 @@ export const editBoxPlot = action(
           whisker: whisker.type,
           factor: whisker.factor
         });
+        for (const rebind of outlierRevision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
       } else {
         outlierDataId = undefined;
       }
 
-      next = next.editSemantic({
-        property: `layer[${owner.id}].data`,
-        value: summaryId
-      });
-      const whiskerConfig = next.markConfigs[current.whiskerId];
-      const capIds = [
-        whiskerConfig.errorBar.lowerCapId,
-        whiskerConfig.errorBar.upperCapId
-      ].filter(id => id !== undefined);
-      next = rebindRuleData(next, current.whiskerId, summaryId)
-        ._withMarkConfig(current.whiskerId, {
+      for (const rebind of summaryRevision.rebinds) {
+        next = next.rebindLayerData(rebind);
+      }
+      next = next._withMarkConfig(current.whiskerId, {
           ...whiskerConfig,
           errorBar: { ...whiskerConfig.errorBar, data: summaryId }
         });
-      for (const capId of capIds) {
-        next = rebindRuleData(next, capId, summaryId);
-      }
-      next = rebindRuleData(next, current.medianId, summaryId);
 
       const hadOutlierLayer = findLayer(next, current.outlierId) !== undefined;
       if (hadOutlierLayer && !hasOutliers) {
         next = removeOwnedMark(next, current.outlierId);
-      } else if (hadOutlierLayer && hasOutliers) {
-        next = next.editSemantic({
-          property: `layer[${current.outlierId}].data`,
-          value: outlierDataId
-        });
       } else if (!hadOutlierLayer && hasOutliers) {
         next = next.createBoxOutliers({
           id: current.outlierId,

package/src/actions/boxPlots/materialize.js

@@ -189,6 +189,9 @@ export const materializeBoxPlot = action(
         outlierDataId: hasOutliers ? outlierDataId : undefined
       }
     });
+    if (config.guides !== false) {
+      next = next.createGuides(config.guides);
+    }
     return next._withContext({ currentMark: ownerId, currentData: source });
   }
 );

package/src/actions/boxPlots/options.js

@@ -8,10 +8,11 @@ import {
 } from "../../core/validation.js";
 import { validatePointShape } from "../../grammar/pointShapes.js";
 import { DEFAULT_COLORS } from "../../theme/defaults.js";
+import { normalizeGuides } from "../charts/shared.js";
 
 export const BOX_PLOT_OPTIONS = Object.freeze([
   "id", "target", "data", "x", "y", "coordinate", "whisker",
-  "width", "outliers", "box", "median", "outlier"
+  "width", "outliers", "box", "median", "outlier", "guides"
 ]);
 
 const DEFAULT_BOX = Object.freeze({
@@ -52,6 +53,12 @@ export function boxEncodingArgs(value) {
   };
 }
 
+export function resolveBoxGuides(value) {
+  return value === undefined
+    ? false
+    : normalizeGuides(value, "createBoxPlot");
+}
+
 export function resolveBoxWhisker(value, operation = "createBoxPlot") {
   if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
   if (!isPlainObject(value)) {

package/src/actions/boxPlots/resolve.js

@@ -11,7 +11,9 @@ export function resolveBoxOrientation(x, y) {
   return undefined;
 }
 
-export function resolveBoxSourceLayer(program, target) {
+export function resolveBoxSourceLayer(program, target, {
+  requiresInference = true
+} = {}) {
   if (target !== undefined) {
     const layer = findLayer(program, validateUserId(target, "Box source layer id"));
     if (layer === undefined) throw new Error(`Unknown box source layer "${target}".`);
@@ -24,7 +26,13 @@ export function resolveBoxSourceLayer(program, target) {
   const eligible = program.semanticSpec.layers.filter(
     layer => layer.encoding?.x !== undefined && layer.encoding?.y !== undefined
   );
-  return eligible.length === 1 ? eligible[0] : undefined;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length > 1 && requiresInference) {
+    throw new Error(
+      "createBoxPlot target is ambiguous; provide target or explicit x and y."
+    );
+  }
+  return undefined;
 }
 
 export function resolveBoxPlotId(program, requested) {

package/src/actions/charts/bar.js

@@ -0,0 +1,50 @@
+import { action } from "../../core/action.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeEncoding,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  normalizeTargetOptions,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "color", "width", "bar", "guides"
+]);
+const BAR_OPTIONS = Object.freeze([
+  "fill", "opacity", "stroke", "strokeWidth"
+]);
+
+export const createBarPlot = action(
+  {
+    op: "createBarPlot",
+    description: "Create a Cartesian bar plot from existing chart data."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createBarPlot");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "barPlot",
+      operation: "createBarPlot"
+    });
+    const data = resolveFacadeData(this, args.data, "createBarPlot");
+    const bar = normalizeAppearance(args.bar, BAR_OPTIONS, "createBarPlot bar");
+    const x = normalizeFieldEncoding(args.x, "createBarPlot x");
+    const y = normalizeFieldEncoding(args.y, "createBarPlot y");
+    const color = normalizeEncoding(args.color, "createBarPlot color");
+    const width = normalizeTargetOptions(args.width, "createBarPlot width");
+    const guides = normalizeGuides(args.guides, "createBarPlot");
+
+    let next = this
+      .createBarMark({ id, data, ...bar })
+      .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+      .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }));
+    if (color !== undefined) next = next.encodeColor(targetArgs(color, id));
+    if (width !== undefined) next = next.encodeBarWidth(targetArgs(width, id));
+    return applyFacadeGuides(next, guides);
+  }
+);

package/src/actions/charts/heatmap.js

@@ -0,0 +1,205 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+import {
+  validateNonEmptyString,
+  validateOptionObject
+} from "../../core/validation.js";
+import { requireDataset } from "../../selectors/datasets.js";
+import {
+  applyFacadeGuides,
+  normalizeAppearance,
+  normalizeFieldEncoding,
+  normalizeGuides,
+  positionArgs,
+  resolveFacadeData,
+  resolveFacadeId,
+  targetArgs,
+  validateFacadeOptions
+} from "./shared.js";
+
+const OPTIONS = Object.freeze([
+  "id", "data", "coordinate", "x", "y", "bin", "color", "rect", "guides"
+]);
+const RECT_OPTIONS = Object.freeze([
+  "opacity", "stroke", "strokeWidth"
+]);
+const BIN_OPTIONS = Object.freeze([
+  "bins", "extent", "includeEmpty"
+]);
+const BINNED_POSITION_OPTIONS = Object.freeze([
+  "field", "fieldType", "scale"
+]);
+const BINNED_COLOR_OPTIONS = Object.freeze([
+  "scale", "palette"
+]);
+
+function normalizeBin(value) {
+  if (!isPlainObject(value)) {
+    throw new TypeError("createHeatmap bin must be a plain object.");
+  }
+  validateOptionObject(value, BIN_OPTIONS, "createHeatmap bin");
+  return {
+    ...value,
+    includeEmpty: value.includeEmpty ?? true
+  };
+}
+
+function normalizeBinnedPosition(value, channel) {
+  const label = `createHeatmap ${channel}`;
+  const encoding = normalizeFieldEncoding(value, label);
+  validateOptionObject(encoding, BINNED_POSITION_OPTIONS, label);
+  const field = validateNonEmptyString(encoding.field, `${label} field`);
+  const fieldType = encoding.fieldType ?? "quantitative";
+  if (fieldType !== "quantitative") {
+    throw new Error(`${label} requires a quantitative field.`);
+  }
+  if (encoding.scale !== undefined && !isPlainObject(encoding.scale)) {
+    throw new TypeError(`${label} scale must be a plain object.`);
+  }
+  return { ...encoding, field, fieldType };
+}
+
+function normalizeBinnedColor(value) {
+  if (value === undefined) return {};
+  if (!isPlainObject(value)) {
+    throw new TypeError("createHeatmap binned color must be a plain object.");
+  }
+  validateOptionObject(value, BINNED_COLOR_OPTIONS, "createHeatmap binned color");
+  return { ...value };
+}
+
+function resolvedPosition(encoding, field, extent) {
+  const scale = encoding.scale ?? {};
+  return {
+    field,
+    fieldType: "quantitative",
+    scale: {
+      type: "linear",
+      nice: false,
+      zero: false,
+      ...scale,
+      domain: scale.domain === undefined || scale.domain === "auto"
+        ? extent
+        : scale.domain
+    }
+  };
+}
+
+function axisWithTitle(value, text) {
+  if (value === false) return false;
+  if (value !== undefined && !isPlainObject(value)) {
+    throw new TypeError("createHeatmap binned axis must be false or a plain object.");
+  }
+  if (value?.title !== undefined && !isPlainObject(value.title)) {
+    throw new TypeError("createHeatmap binned axis title must be a plain object.");
+  }
+  return {
+    ...value,
+    title: {
+      text,
+      ...value?.title
+    }
+  };
+}
+
+function binnedGuides(guides, xTitle, yTitle) {
+  if (guides === false) return false;
+  for (const key of ["axes", "legend"]) {
+    if (
+      guides[key] !== undefined &&
+      guides[key] !== false &&
+      !isPlainObject(guides[key])
+    ) {
+      throw new TypeError(
+        `createHeatmap guides ${key} must be false or a plain object.`
+      );
+    }
+  }
+  const axes = guides.axes === false
+    ? false
+    : {
+        ...guides.axes,
+        x: axisWithTitle(guides.axes?.x, xTitle),
+        y: axisWithTitle(guides.axes?.y, yTitle)
+      };
+  const legend = guides.legend === false
+    ? false
+    : { title: "Count", ...guides.legend };
+  return {
+    ...guides,
+    axes,
+    grid: guides.grid ?? false,
+    legend
+  };
+}
+
+function createPreGriddedHeatmap(program, args, { id, data, rect, guides }) {
+  const x = normalizeFieldEncoding(args.x, "createHeatmap x");
+  const y = normalizeFieldEncoding(args.y, "createHeatmap y");
+  const color = normalizeFieldEncoding(args.color, "createHeatmap color");
+  const next = program
+    .createRectMark({ id, data, ...rect })
+    .encodeX(positionArgs(x, { target: id, coordinate: args.coordinate }))
+    .encodeY(positionArgs(y, { target: id, coordinate: args.coordinate }))
+    .encodeColor(targetArgs(color, id));
+  return applyFacadeGuides(next, guides);
+}
+
+function createBinnedHeatmap(program, args, { id, data, rect, guides }) {
+  const x = normalizeBinnedPosition(args.x, "x");
+  const y = normalizeBinnedPosition(args.y, "y");
+  const bin = normalizeBin(args.bin);
+  const color = normalizeBinnedColor(args.color);
+  const resolvedGuides = binnedGuides(guides, x.field, y.field);
+  const generatedData = `${id}Bin2DData`;
+  const binned = program.createBin2DData({
+    id: generatedData,
+    source: data,
+    x: x.field,
+    y: y.field,
+    ...bin
+  });
+  const dataset = requireDataset(binned, generatedData);
+  const transform = dataset.transform[0];
+  const resolved = transform.resolved;
+  const xEncoding = resolvedPosition(x, transform.as.x0, resolved.extent.x);
+  const yEncoding = resolvedPosition(y, transform.as.y0, resolved.extent.y);
+
+  const next = binned
+    .createRectMark({ id, data: generatedData, ...rect })
+    .encodeX(positionArgs(xEncoding, { target: id, coordinate: args.coordinate }))
+    .encodeX2({ target: id, field: transform.as.x1, fieldType: "quantitative" })
+    .encodeY(positionArgs(yEncoding, { target: id, coordinate: args.coordinate }))
+    .encodeY2({ target: id, field: transform.as.y1, fieldType: "quantitative" })
+    .encodeColor({
+      target: id,
+      field: transform.as.count,
+      fieldType: "quantitative",
+      ...color
+    });
+  return applyFacadeGuides(
+    next,
+    resolvedGuides
+  );
+}
+
+export const createHeatmap = action(
+  {
+    op: "createHeatmap",
+    description: "Create a pre-gridded or rectangularly binned heatmap."
+  },
+  function (args = {}) {
+    validateFacadeOptions(args, OPTIONS, "createHeatmap");
+    const id = resolveFacadeId(this, args.id, {
+      defaultId: "heatmap",
+      operation: "createHeatmap"
+    });
+    const data = resolveFacadeData(this, args.data, "createHeatmap");
+    const rect = normalizeAppearance(args.rect, RECT_OPTIONS, "createHeatmap rect");
+    const guides = normalizeGuides(args.guides, "createHeatmap");
+    const shared = { id, data, rect, guides };
+    return args.bin === undefined
+      ? createPreGriddedHeatmap(this, args, shared)
+      : createBinnedHeatmap(this, args, shared);
+  }
+);