ggaction 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `ggaction` are recorded in this file.
 
+## Unreleased
+
+## [0.0.3] - 2026-07-19
+
+### Added
+
+- Added complete Polar point, line/radar, arc/donut/rose/radial-bar authoring with theta/radius guides, selection,
+  highlighting, and Canvas/PNG rendering.
+- Added immutable horizontal and vertical program composition, nested child snapshots, layout editing, stable child
+  replacement, and Cartesian facets with derived-data replay, scale resolution, outer axes, and shared legends.
+- Added text and rect marks, directional offsets, horizontal grouped bars, and compatible shared temporal bar/line
+  position inference.
+
+### Changed
+
+- Nested compositions now preserve their intrinsic layout and honor outer cross-axis alignment instead of stretching
+  internal cells or leaving unequal snapshots pinned to the start edge.
+
+### Fixed
+
+- Corrected zero-baseline and signed geometry for aggregate bars, and materialized complete ranged or aggregate bars
+  with their documented default width.
+- Made horizontal error bands compose with color and explicit boundaries in the same supported cases as vertical bands.
+- Added standalone point-size legends and interval-aware temporal axis labels without duplicate automatic tick text.
+- Published the exact `createDerivedData` transform-array contract and stable `ChartProgram` state-inspection paths in
+  TypeScript and user documentation.
+
 ## [0.0.2] - 2026-07-17
 
 ### Fixed
@@ -31,5 +58,6 @@ 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.3]: https://github.com/hj-n/ggaction/releases/tag/v0.0.3
 [0.0.2]: https://github.com/hj-n/ggaction/releases/tag/v0.0.2
 [0.0.1]: https://github.com/hj-n/ggaction/releases/tag/v0.0.1

package/README.md

@@ -37,7 +37,7 @@ render(program, document.querySelector("#chart").getContext("2d"));
 The renderer reads only fully materialized, backend-neutral graphics. Semantic
 state is never automatically compiled during rendering.
 
-> **Status:** `0.0.2` is the current experimental public release. APIs may change
+> **Status:** `0.0.3` is the current experimental public release. APIs may change
 > before `1.0.0`; changes are recorded in the [changelog](./CHANGELOG.md).
 
 ## Install
@@ -96,6 +96,17 @@ Tukey/min–max ranges, configurable factor and component appearance, and
 optional outlier rendering from categorical and quantitative field pairs.
 The [mark-selection example](https://github.com/hj-n/ggaction/tree/main/examples/mark-selection/) compares grouped point,
 complete stacked-bar, and line-series highlighting through one selector grammar.
+The [program-composition example](https://github.com/hj-n/ggaction/tree/main/examples/program-composition/) combines
+complete child programs, edits their inferred layout, and replaces one stable slot.
+The [facet example](https://github.com/hj-n/ggaction/tree/main/examples/cars-origin-scatterplot-facet/)
+repeats one chart with `.facet({ field: "Origin" })`, channel-level shared or
+independent scales, per-cell or occupied-outer axes, and an optional compatible
+parent-owned legend. Regression, density, interval, and box-derived data are
+recomputed independently inside each cell.
+Complete Cartesian and Polar programs can be nested with `hconcat` and
+`vconcat`; the [cross-feature dashboard](https://github.com/hj-n/ggaction/tree/main/examples/cross-feature-dashboard/)
+shows a Polar child replacement beside a Cartesian facet. Polar sources cannot
+currently be faceted and fail before partial child state is created.
 Completed programs can also be exported through
 [`ggaction/png`](https://hyeonword.com/ggaction/api/rendering/#png-output).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ggaction",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "Build charts through immutable, traceable graphical actions.",
   "license": "MIT",
   "author": "Hyeon Jeon",
@@ -59,6 +59,11 @@
     "artifacts:gallery:test": "node scripts/test-roadmap-gallery.js",
     "docs:images": "node scripts/generate-doc-images.js",
     "docs:llms": "node scripts/generate-llm-docs.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: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",
     "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",

package/src/actions/boxPlots/components.js

@@ -64,7 +64,8 @@ export const createBoxOutliers = action(
     let next = this.createPointMark({
       id: args.id,
       data: args.data,
-      shape: args.shape
+      shape: args.shape,
+      fill: "#111111"
     });
     next = next[categoryAction]({
       target: args.id,
@@ -82,7 +83,6 @@ export const createBoxOutliers = action(
     });
     return next
       .encodeRadius({ target: args.id, value: args.radius })
-      .encodeOpacity({ target: args.id, value: args.opacity })
-      .editGraphics({ target: args.id, property: "fill", value: "#111111" });
+      .encodeOpacity({ target: args.id, value: args.opacity });
   }
 );

package/src/actions/boxPlots/edit.js

@@ -0,0 +1,277 @@
+import { action } from "../../core/action.js";
+import { isPlainObject } from "../../core/immutable.js";
+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 { findDataset } from "../../selectors/datasets.js";
+import { findLayer } from "../../selectors/layers.js";
+import {
+  resolveBoxAppearance,
+  resolveBoxMedianAppearance,
+  resolveBoxOutlierAppearance,
+  resolveBoxWhisker,
+  resolveBoxWidth
+} from "./options.js";
+
+const OPTIONS = Object.freeze([
+  "target", "whisker", "width", "outliers", "box", "median", "outlier"
+]);
+
+function resolveBoxOwner(program, requested) {
+  const eligible = program.semanticSpec.layers.filter(
+    layer => program.markConfigs[layer.id]?.boxPlot?.materialized === true
+  );
+  if (requested !== undefined) {
+    const id = validateUserId(requested, "Box-plot owner id");
+    const layer = findLayer(program, id);
+    if (layer === undefined || !eligible.includes(layer)) {
+      throw new Error(`Unknown box-plot owner "${id}".`);
+    }
+    return layer;
+  }
+  const current = findLayer(program, program.context.currentMark);
+  if (current !== undefined && eligible.includes(current)) return current;
+  if (eligible.length === 1) return eligible[0];
+  if (eligible.length === 0) throw new Error("No box-plot owner is available.");
+  throw new Error("Box-plot owner is ambiguous; provide target.");
+}
+
+function requirePatch(value, label) {
+  if (!isPlainObject(value)) {
+    throw new TypeError(`editBoxPlot ${label} must be a plain object.`);
+  }
+  return value;
+}
+
+function resolveEditedWhisker(current, value) {
+  if (value === undefined) return current;
+  const patch = requirePatch(value, "whisker");
+  validateKeys(patch, ["type", "factor"], "editBoxPlot whisker");
+  const type = patch.type ?? current.type;
+  const candidate = type === "minmax"
+    ? { type, ...(Object.hasOwn(patch, "factor") ? { factor: patch.factor } : {}) }
+    : {
+        type,
+        factor: Object.hasOwn(patch, "factor")
+          ? patch.factor
+          : current.type === "tukey" ? current.factor : 1.5
+      };
+  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 })
+    .editGraphics({ target: id, remove: true })
+    ._withoutMaterializationConfig(["marks", id]);
+}
+
+function rebindRuleData(program, id, data) {
+  return program.editSemantic({ property: `layer[${id}].data`, value: data });
+}
+
+export const editBoxPlot = action(
+  {
+    op: "editBoxPlot",
+    description: "Revise one box plot and its owned components."
+  },
+  function (args = {}) {
+    validateKeys(args, OPTIONS, "editBoxPlot");
+    if (!OPTIONS.slice(1).some(key => Object.hasOwn(args, key))) {
+      throw new Error("editBoxPlot requires at least one box-plot option.");
+    }
+    const owner = resolveBoxOwner(this, args.target);
+    const current = this.markConfigs[owner.id].boxPlot;
+    const whisker = resolveEditedWhisker(current.whisker, args.whisker);
+    const width = Object.hasOwn(args, "width")
+      ? resolveBoxWidth(args.width, "editBoxPlot")
+      : current.width;
+    if (Object.hasOwn(args, "outliers") && typeof args.outliers !== "boolean") {
+      throw new TypeError("editBoxPlot outliers must be a boolean.");
+    }
+    const outliers = args.outliers ?? current.outliers;
+    const boxPatch = Object.hasOwn(args, "box")
+      ? requirePatch(args.box, "box")
+      : {};
+    const medianPatch = Object.hasOwn(args, "median")
+      ? requirePatch(args.median, "median")
+      : {};
+    const outlierPatch = Object.hasOwn(args, "outlier")
+      ? requirePatch(args.outlier, "outlier")
+      : {};
+    const box = resolveBoxAppearance(
+      { ...current.box, ...boxPatch },
+      "editBoxPlot"
+    );
+    const median = resolveBoxMedianAppearance(
+      { ...current.median, ...medianPatch },
+      "editBoxPlot"
+    );
+    const outlier = resolveBoxOutlierAppearance(
+      { ...current.outlier, ...outlierPatch },
+      "editBoxPlot"
+    );
+    if (Object.hasOwn(boxPatch, "fill") && owner.encoding?.color !== undefined) {
+      throw new Error(
+        "editBoxPlot box.fill cannot be combined with a color encoding."
+      );
+    }
+
+    const revisesData = JSON.stringify(whisker) !== JSON.stringify(current.whisker) ||
+      outliers !== current.outliers;
+    const changesBox = Object.hasOwn(args, "box") ||
+      Object.hasOwn(args, "width") || revisesData;
+    const changesMedian = Object.hasOwn(args, "median") ||
+      Object.hasOwn(args, "width") || revisesData;
+    const changesOutlier = Object.hasOwn(args, "outlier") || revisesData;
+    const categoryEncoding = current.orientation === "vertical"
+      ? owner.encoding.x
+      : owner.encoding.y;
+    const measureEncoding = current.orientation === "vertical"
+      ? owner.encoding.y
+      : owner.encoding.x;
+    let summaryId = current.summaryId;
+    let outlierDataId = current.outlierDataId;
+    let next = this;
+
+    const sourceRows = findDataset(this, current.source).values;
+    const derived = deriveBoxData(sourceRows, normalizeBoxTransform({
+      type: "boxSummary",
+      category: current.category,
+      field: current.measure,
+      whisker: whisker.type,
+      ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
+    }));
+    const hasOutliers = outliers && whisker.type === "tukey" &&
+      derived.outliers.length > 0;
+
+    if (revisesData) {
+      summaryId = nextRevisionId(this, owner.id, "SummaryData");
+      next = next.createBoxSummaryData({
+        id: summaryId,
+        source: current.source,
+        category: current.category,
+        field: current.measure,
+        whisker: whisker.type,
+        ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
+      });
+      if (hasOutliers) {
+        outlierDataId = nextRevisionId(this, owner.id, "OutlierData");
+        next = next.createBoxOutlierData({
+          id: outlierDataId,
+          source: current.source,
+          category: current.category,
+          field: current.measure,
+          whisker: whisker.type,
+          factor: whisker.factor
+        });
+      } 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, {
+          ...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,
+          data: outlierDataId,
+          category: current.category,
+          categoryType: categoryEncoding.fieldType,
+          measure: current.measure,
+          orientation: current.orientation,
+          coordinate: owner.coordinate,
+          categoryScale: categoryEncoding.scale,
+          measureScale: measureEncoding.scale,
+          shape: outlier.shape,
+          radius: outlier.radius,
+          opacity: outlier.opacity
+        });
+      }
+    }
+
+    next = next._withMarkConfig(owner.id, {
+      ...next.markConfigs[owner.id],
+      boxPlot: {
+        ...current,
+        whisker,
+        width,
+        outliers,
+        box,
+        median,
+        outlier,
+        summaryId,
+        outlierDataId
+      },
+      barWidth: { band: width },
+      fill: box.fill,
+      opacity: box.opacity,
+      stroke: box.stroke,
+      strokeWidth: box.strokeWidth
+    });
+
+    if (changesBox) next = next.rematerializeBarMark({ id: owner.id });
+    if (revisesData) {
+      next = next.rematerializeErrorBar({ id: current.whiskerId });
+    }
+    if (changesMedian) {
+      next = next
+        .encodeStroke({ target: current.medianId, value: median.stroke })
+        .encodeStrokeWidth({
+          target: current.medianId,
+          value: median.strokeWidth
+        });
+    }
+    if (findLayer(next, current.outlierId) !== undefined && changesOutlier) {
+      next = next
+        .editPointMark({
+          target: current.outlierId,
+          shape: outlier.shape,
+          opacity: outlier.opacity
+        })
+        .encodeRadius({ target: current.outlierId, value: outlier.radius });
+    }
+
+    if (revisesData) {
+      next = next.releaseDerivedData({ id: current.summaryId });
+      if (current.outlierDataId !== undefined) {
+        next = next.releaseDerivedData({ id: current.outlierDataId });
+      }
+    }
+    return next._withContext({ currentMark: owner.id, currentData: current.source });
+  }
+);

package/src/actions/boxPlots/index.js

@@ -1,9 +1,11 @@
 import { createBoxMedian, createBoxOutliers } from "./components.js";
 import { createBoxPlot } from "./create.js";
+import { editBoxPlot } from "./edit.js";
 import { materializeBoxPlot } from "./materialize.js";
 
 export function registerBoxPlotActions(ProgramClass) {
   ProgramClass.prototype.createBoxPlot = createBoxPlot;
+  ProgramClass.prototype.editBoxPlot = editBoxPlot;
   ProgramClass.prototype.materializeBoxPlot = materializeBoxPlot;
   ProgramClass.prototype.createBoxMedian = createBoxMedian;
   ProgramClass.prototype.createBoxOutliers = createBoxOutliers;

package/src/actions/boxPlots/materialize.js

@@ -50,7 +50,11 @@ export const materializeBoxPlot = action(
         source,
         orientation,
         category: category.field,
-        measure: measure.field
+        measure: measure.field,
+        summaryId,
+        whiskerId,
+        medianId,
+        outlierId
       },
       barWidth: { band: config.width },
       fill: config.box.fill,
@@ -178,6 +182,13 @@ export const materializeBoxPlot = action(
         opacity: config.outlier.opacity
       });
     }
+    next = next._withMarkConfig(ownerId, {
+      ...next.markConfigs[ownerId],
+      boxPlot: {
+        ...next.markConfigs[ownerId].boxPlot,
+        outlierDataId: hasOutliers ? outlierDataId : undefined
+      }
+    });
     return next._withContext({ currentMark: ownerId, currentData: source });
   }
 );

package/src/actions/boxPlots/options.js

@@ -27,12 +27,12 @@ const DEFAULT_OUTLIER = Object.freeze({
   opacity: 0.75
 });
 
-function plainOptions(value, keys, label) {
+function plainOptions(value, keys, label, operation = "createBoxPlot") {
   if (value === undefined) return {};
   if (!isPlainObject(value)) {
-    throw new TypeError(`createBoxPlot ${label} must be a plain object.`);
+    throw new TypeError(`${operation} ${label} must be a plain object.`);
   }
-  validateKeys(value, keys, `createBoxPlot ${label}`);
+  validateKeys(value, keys, `${operation} ${label}`);
   return value;
 }
 
@@ -52,12 +52,12 @@ export function boxEncodingArgs(value) {
   };
 }
 
-export function resolveBoxWhisker(value) {
+export function resolveBoxWhisker(value, operation = "createBoxPlot") {
   if (value === undefined) return Object.freeze({ type: "tukey", factor: 1.5 });
   if (!isPlainObject(value)) {
-    throw new TypeError("createBoxPlot whisker must be a plain object.");
+    throw new TypeError(`${operation} whisker must be a plain object.`);
   }
-  validateKeys(value, ["type", "factor"], "createBoxPlot whisker");
+  validateKeys(value, ["type", "factor"], `${operation} whisker`);
   const type = value.type ?? "tukey";
   if (!["tukey", "minmax"].includes(type)) {
     throw new Error(`Unsupported createBoxPlot whisker type "${type}".`);
@@ -77,8 +77,8 @@ export function resolveBoxWhisker(value) {
   return Object.freeze({ type, factor });
 }
 
-export function resolveBoxWidth(value) {
-  const options = plainOptions(value, ["band"], "width");
+export function resolveBoxWidth(value, operation = "createBoxPlot") {
+  const options = plainOptions(value, ["band"], "width", operation);
   const band = options.band ?? 0.7;
   if (!Number.isFinite(band) || band <= 0 || band >= 1) {
     throw new RangeError(
@@ -88,11 +88,12 @@ export function resolveBoxWidth(value) {
   return band;
 }
 
-export function resolveBoxAppearance(value) {
+export function resolveBoxAppearance(value, operation = "createBoxPlot") {
   const options = plainOptions(
     value,
     ["fill", "opacity", "stroke", "strokeWidth"],
-    "box"
+    "box",
+    operation
   );
   return Object.freeze({
     fill: options.fill === undefined
@@ -113,8 +114,13 @@ export function resolveBoxAppearance(value) {
   });
 }
 
-export function resolveBoxMedianAppearance(value) {
-  const options = plainOptions(value, ["stroke", "strokeWidth"], "median");
+export function resolveBoxMedianAppearance(value, operation = "createBoxPlot") {
+  const options = plainOptions(
+    value,
+    ["stroke", "strokeWidth"],
+    "median",
+    operation
+  );
   return Object.freeze({
     stroke: options.stroke === undefined
       ? DEFAULT_MEDIAN.stroke
@@ -128,8 +134,13 @@ export function resolveBoxMedianAppearance(value) {
   });
 }
 
-export function resolveBoxOutlierAppearance(value) {
-  const options = plainOptions(value, ["shape", "radius", "opacity"], "outlier");
+export function resolveBoxOutlierAppearance(value, operation = "createBoxPlot") {
+  const options = plainOptions(
+    value,
+    ["shape", "radius", "opacity"],
+    "outlier",
+    operation
+  );
   return Object.freeze({
     shape: options.shape === undefined
       ? DEFAULT_OUTLIER.shape

package/src/actions/canvas/actions.js

@@ -6,6 +6,7 @@ import {
   validateCanvasState
 } from "../../layout/canvas.js";
 import { cloneAndFreeze } from "../../core/immutable.js";
+import { validateOptionObject } from "../../core/validation.js";
 import {
   applyMaterializationPlan,
   planCanvasRematerialization
@@ -13,6 +14,7 @@ import {
 import {
   assertCanvasHierarchyAvailable,
   CANVAS_GRAPHIC_ID,
+  findCanvasGraphic,
   PLOT_GRAPHIC_ID
 } from "../../materialization/graphicHierarchy.js";
 
@@ -24,21 +26,11 @@ const CANVAS_OPTIONS = Object.freeze([
 ]);
 
 function validateOptions(args, operation, { allowEmpty = false } = {}) {
-  const keys = Object.keys(args);
-
-  if (!allowEmpty && keys.length === 0) {
-    throw new TypeError(`${operation} requires at least one option.`);
-  }
-
-  for (const key of keys) {
-    if (!CANVAS_OPTIONS.includes(key)) {
-      throw new Error(`Unknown ${operation} option "${key}".`);
-    }
-  }
+  validateOptionObject(args, CANVAS_OPTIONS, operation, { allowEmpty });
 }
 
 function requireCanvas(program) {
-  const canvas = program.graphicSpec.objects.canvas;
+  const canvas = findCanvasGraphic(program);
 
   if (canvas?.type !== "canvas") {
     throw new Error("editCanvas requires an existing canvas.");
@@ -49,8 +41,9 @@ function requireCanvas(program) {
 
 function resolveCanvasState(program, args) {
   const canvas = requireCanvas(program);
-  const baseMargin =
-    program.materializationConfigs.canvas?.margin ?? DEFAULT_MARGIN;
+  const canvasConfig = program.materializationConfigs.canvas;
+  const baseMargin = canvasConfig?.margin ?? DEFAULT_MARGIN;
+  const baseSize = canvasConfig?.size ?? { width: "explicit", height: "explicit" };
   const state = {
     width: Object.hasOwn(args, "width")
       ? args.width
@@ -63,7 +56,11 @@ function resolveCanvasState(program, args) {
       : canvas.properties.background,
     margin: Object.hasOwn(args, "margin")
       ? normalizeMargin(args.margin, baseMargin)
-      : baseMargin
+      : baseMargin,
+    size: {
+      width: Object.hasOwn(args, "width") ? "explicit" : baseSize.width,
+      height: Object.hasOwn(args, "height") ? "explicit" : baseSize.height
+    }
   };
 
   validateCanvasState(state);
@@ -90,7 +87,7 @@ export const editCanvas = action(
       }
     }
 
-    next = next._withCanvasConfig({ margin: state.margin });
+    next = next._withCanvasConfig({ margin: state.margin, size: state.size });
 
     if (
       Object.hasOwn(args, "width") ||
@@ -132,7 +129,7 @@ export const createCanvas = action(
         : DEFAULT_CANVAS.margin
     };
 
-    return this
+    const next = this
       .createGraphics({ id: CANVAS_GRAPHIC_ID, type: "canvas" })
       .createGraphics({
         id: PLOT_GRAPHIC_ID,
@@ -140,5 +137,12 @@ export const createCanvas = action(
         parent: CANVAS_GRAPHIC_ID
       })
       .editCanvas(options);
+    return next._withCanvasConfig({
+      ...next.materializationConfigs.canvas,
+      size: {
+        width: Object.hasOwn(args, "width") ? "explicit" : "auto",
+        height: Object.hasOwn(args, "height") ? "explicit" : "auto"
+      }
+    });
   }
 );