ggaction 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `ggaction` are recorded in this file.
 
 ## Unreleased
 
+## [0.0.6] - 2026-07-23
+
+### Added
+
+- Added explicit edit and removal lifecycles for encodings, point appearance, selections, highlights, legends, and
+  Cartesian axis components while preserving immutable state and meaningful action traces.
+- Added revision workflows for 2D bins, interval statistics, regression, density, box plots, gradient plots, and facet
+  policies, including deterministic rematerialization after data-role and layout changes.
+
+### Changed
+
+- Expanded installed-package, Browser Canvas, Node PNG, TypeScript, action-contract, and cross-capability coverage for
+  the complete authoring lifecycle surface.
+- Improved documentation entry points, navigation, chart discovery, gallery filtering, responsive presentation, and
+  generated API routing for the completed lifecycle actions.
+
+### Fixed
+
+- Preserved unaffected shared-legend channels when selectively removing an encoding, and prevented removed resources
+  from returning after later rematerialization or facet replay.
+- Kept documentation search results under the deployed `/ggaction/` base path and improved gallery text contrast.
+- Allowed the approved Polar chart ink bounds to absorb the observed 1.5-pixel platform rasterization variance while
+  retaining exact primitive/public pixel comparisons and the existing density, color, and region checks.
+
 ## [0.0.5] - 2026-07-21
 
 ### Added
@@ -111,6 +135,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.6]: https://github.com/ggaction/ggaction/releases/tag/v0.0.6
 [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

package/README.md

@@ -142,7 +142,7 @@ All entries include TypeScript declarations. The default entry is browser-safe;
 
 ## Status and development
 
-> **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).
+> **Status:** `0.0.6` 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.5",
+  "version": "0.0.6",
   "description": "Build charts through immutable, traceable graphical actions.",
   "license": "MIT",
   "author": "Hyeon Jeon",

package/src/actions/boxPlots/edit.js

@@ -8,16 +8,27 @@ import { planDerivedDataRevision } from
   "../../materialization/dataProvenance.js";
 import { findDataset } from "../../selectors/datasets.js";
 import { findLayer } from "../../selectors/layers.js";
+import {
+  assertDistributionScaleHandoff,
+  clearCartesianPositions,
+  rebindDistributionGuides,
+  resolveDistributionScalePlan,
+  setCartesianPosition,
+  setCartesianRange
+} from "../distributions/revision.js";
 import {
   resolveBoxAppearance,
   resolveBoxMedianAppearance,
   resolveBoxOutlierAppearance,
+  resolveBoxPosition,
   resolveBoxWhisker,
   resolveBoxWidth
 } from "./options.js";
+import { resolveBoxOrientation } from "./resolve.js";
 
 const OPTIONS = Object.freeze([
-  "target", "whisker", "width", "outliers", "box", "median", "outlier"
+  "target", "data", "x", "y", "whisker", "width", "outliers", "box",
+  "median", "outlier"
 ]);
 
 function resolveBoxOwner(program, requested) {
@@ -63,10 +74,287 @@ function resolveEditedWhisker(current, value) {
 }
 
 function removeOwnedMark(program, id) {
-  return program
+  const selections = Object.entries(
+    program.materializationConfigs.selections ?? {}
+  ).filter(([, config]) => config.target === id).map(([selection]) => selection);
+  let next = program;
+  for (const [highlight, config] of Object.entries(
+    program.materializationConfigs.highlights ?? {}
+  )) {
+    if (config.target === id || selections.includes(config.selection)) {
+      next = next._withoutMaterializationConfig(["highlights", highlight]);
+    }
+  }
+  for (const selection of selections) {
+    next = next._withoutMaterializationConfig(["selections", selection]);
+  }
+  return next
     .editSemantic({ property: `layer[${id}]`, remove: true })
     .editGraphics({ target: id, remove: true })
-    ._withoutMaterializationConfig(["marks", id]);
+    ._withoutMaterializationConfig(["marks", id])
+    ._withContext({
+      ...(program.context.currentMark === id ? { currentMark: undefined } : {}),
+      ...(selections.includes(program.context.currentSelection)
+        ? { currentSelection: undefined }
+        : {})
+    });
+}
+
+function currentBoxPositions(owner, current) {
+  const categoryChannel = current.orientation === "vertical" ? "x" : "y";
+  const measureChannel = current.orientation === "vertical" ? "y" : "x";
+  const categoryEncoding = owner.encoding[categoryChannel];
+  const measureEncoding = owner.encoding[measureChannel];
+  return {
+    x: current.orientation === "vertical"
+      ? {
+          field: current.category,
+          fieldType: categoryEncoding.fieldType,
+          scale: categoryEncoding.scale
+        }
+      : {
+          field: current.measure,
+          fieldType: "quantitative",
+          scale: measureEncoding.scale
+        },
+    y: current.orientation === "vertical"
+      ? {
+          field: current.measure,
+          fieldType: "quantitative",
+          scale: measureEncoding.scale
+        }
+      : {
+          field: current.category,
+          fieldType: categoryEncoding.fieldType,
+          scale: categoryEncoding.scale
+        },
+    categoryScale: categoryEncoding.scale,
+    measureScale: measureEncoding.scale
+  };
+}
+
+function requirePositionField(position, label) {
+  if (typeof position.field !== "string" || position.field.length === 0) {
+    throw new TypeError(`${label} field must be a non-empty string.`);
+  }
+  return { fieldType: position.fieldType ?? "quantitative", ...position };
+}
+
+function roleCandidate(program, owner, current, args) {
+  const previous = currentBoxPositions(owner, current);
+  const x = requirePositionField(
+    Object.hasOwn(args, "x")
+      ? resolveBoxPosition(args.x, "x", "editBoxPlot")
+      : previous.x,
+    "editBoxPlot x"
+  );
+  const y = requirePositionField(
+    Object.hasOwn(args, "y")
+      ? resolveBoxPosition(args.y, "y", "editBoxPlot")
+      : previous.y,
+    "editBoxPlot y"
+  );
+  const orientation = resolveBoxOrientation(x, y);
+  if (orientation === undefined) {
+    throw new Error(
+      "editBoxPlot requires one categorical axis and one quantitative axis."
+    );
+  }
+  const xRoleScale = orientation === "vertical"
+    ? previous.categoryScale
+    : previous.measureScale;
+  const yRoleScale = orientation === "vertical"
+    ? previous.measureScale
+    : previous.categoryScale;
+  const xScale = resolveDistributionScalePlan(program, {
+    channel: "x",
+    fieldType: x.fieldType,
+    requested: x.scale,
+    fallback: xRoleScale,
+    defaults: ["ordinal", "nominal"].includes(x.fieldType)
+      ? { discreteType: "band" }
+      : { nice: true, zero: false }
+  });
+  const yScale = resolveDistributionScalePlan(program, {
+    channel: "y",
+    fieldType: y.fieldType,
+    requested: y.scale,
+    fallback: yRoleScale,
+    defaults: ["ordinal", "nominal"].includes(y.fieldType)
+      ? { discreteType: "band" }
+      : { nice: true, zero: false }
+  });
+  return {
+    source: Object.hasOwn(args, "data")
+      ? validateUserId(args.data, "Box-plot data id")
+      : current.source,
+    orientation,
+    x: { ...x, scale: xScale.id },
+    y: { ...y, scale: yScale.id },
+    xScale,
+    yScale,
+    category: orientation === "vertical" ? x.field : y.field,
+    categoryType: orientation === "vertical" ? x.fieldType : y.fieldType,
+    measure: orientation === "vertical" ? y.field : x.field,
+    previous
+  };
+}
+
+function sameRoleCandidate(current, candidate) {
+  return candidate.source === current.source &&
+    candidate.orientation === current.orientation &&
+    candidate.category === current.category &&
+    candidate.measure === current.measure &&
+    candidate.x.fieldType === candidate.previous.x.fieldType &&
+    candidate.y.fieldType === candidate.previous.y.fieldType &&
+    candidate.xScale.id === candidate.previous.x.scale &&
+    candidate.yScale.id === candidate.previous.y.scale &&
+    candidate.xScale.edit === undefined &&
+    candidate.yScale.edit === undefined;
+}
+
+function updateBoxPositions(program, owner, current, candidate, {
+  hasOutliers
+}) {
+  const whiskerConfig = program.markConfigs[current.whiskerId];
+  const capIds = [
+    whiskerConfig.errorBar.lowerCapId,
+    whiskerConfig.errorBar.upperCapId
+  ].filter(Boolean);
+  const owned = [owner.id, current.whiskerId, ...capIds, current.medianId,
+    ...(findLayer(program, current.outlierId) ? [current.outlierId] : [])];
+  assertDistributionScaleHandoff(program, {
+    owned,
+    oldXScale: candidate.previous.x.scale,
+    oldYScale: candidate.previous.y.scale,
+    newXScale: candidate.xScale.id,
+    newYScale: candidate.yScale.id
+  });
+  let next = program;
+  for (const id of owned) next = clearCartesianPositions(next, id);
+  for (const scale of [candidate.xScale, candidate.yScale]) {
+    if (scale.create) next = next.createScale(scale.definition);
+  }
+  const category = candidate.orientation === "vertical" ? candidate.x : candidate.y;
+  const measure = candidate.orientation === "vertical" ? candidate.y : candidate.x;
+  const categoryChannel = candidate.orientation === "vertical" ? "x" : "y";
+  const measureChannel = candidate.orientation === "vertical" ? "y" : "x";
+  next = setCartesianPosition(next, owner.id, categoryChannel, {
+    field: category.field,
+    fieldType: category.fieldType,
+    scale: category.scale
+  });
+  next = setCartesianRange(
+    next,
+    owner.id,
+    measureChannel,
+    BOX_FIELDS.q1,
+    BOX_FIELDS.q3,
+    measure.scale,
+    candidate.measure
+  );
+  next = next._withMarkConfig(current.whiskerId, {
+    ...whiskerConfig,
+    errorBar: {
+      ...whiskerConfig.errorBar,
+      data: findLayer(next, current.whiskerId).data,
+      orientation: candidate.orientation,
+      positionField: candidate.category,
+      positionFieldType: candidate.categoryType,
+      coordinate: owner.coordinate,
+      positionScale: category.scale,
+      intervalScale: measure.scale
+    }
+  });
+  next = setCartesianPosition(next, current.whiskerId, categoryChannel, {
+    field: category.field,
+    fieldType: category.fieldType,
+    scale: category.scale
+  });
+  next = setCartesianRange(
+    next,
+    current.whiskerId,
+    measureChannel,
+    BOX_FIELDS.lowerWhisker,
+    BOX_FIELDS.upperWhisker,
+    measure.scale,
+    candidate.measure
+  );
+  for (const [index, capId] of capIds.entries()) {
+    const field = index === 0 ? BOX_FIELDS.lowerWhisker : BOX_FIELDS.upperWhisker;
+    next = setCartesianPosition(next, capId, categoryChannel, {
+      field: category.field,
+      fieldType: category.fieldType,
+      scale: category.scale
+    });
+    next = setCartesianPosition(next, capId, measureChannel, {
+      field,
+      fieldType: "quantitative",
+      scale: measure.scale
+    })._withMarkConfig(capId, {
+      ...next.markConfigs[capId],
+      fixedSpan: {
+        ...next.markConfigs[capId].fixedSpan,
+        orientation: candidate.orientation === "vertical"
+          ? "horizontal"
+          : "vertical"
+      }
+    });
+  }
+  next = setCartesianPosition(next, current.medianId, categoryChannel, {
+    field: category.field,
+    fieldType: category.fieldType,
+    scale: category.scale
+  });
+  next = setCartesianPosition(next, current.medianId, measureChannel, {
+    field: BOX_FIELDS.median,
+    fieldType: "quantitative",
+    scale: measure.scale
+  });
+  if (hasOutliers && findLayer(next, current.outlierId) !== undefined) {
+    next = setCartesianPosition(next, current.outlierId, categoryChannel, {
+      field: category.field,
+      fieldType: category.fieldType,
+      scale: category.scale
+    });
+    next = setCartesianPosition(next, current.outlierId, measureChannel, {
+      field: candidate.measure,
+      fieldType: "quantitative",
+      scale: measure.scale
+    });
+  }
+  for (const id of new Set([candidate.xScale.id, candidate.yScale.id])) {
+    next = next.rematerializeScale({ id, marks: false, guides: false });
+  }
+  next = rebindDistributionGuides(next, {
+    oldXScale: candidate.previous.x.scale,
+    oldYScale: candidate.previous.y.scale,
+    newXScale: candidate.xScale.id,
+    newYScale: candidate.yScale.id,
+    oldXTitle: candidate.previous.x.field,
+    oldYTitle: candidate.previous.y.field,
+    newXTitle: candidate.x.field,
+    newYTitle: candidate.y.field,
+    oldMeasureChannel: current.orientation === "vertical" ? "y" : "x",
+    newMeasureChannel: candidate.orientation === "vertical" ? "y" : "x"
+  });
+  for (const scale of [candidate.xScale, candidate.yScale]) {
+    if (scale.edit !== undefined) next = next.editScale(scale.edit);
+  }
+  next = next.rematerializeBarMark({ id: owner.id })
+    .rematerializeErrorBar({ id: current.whiskerId });
+  for (const capId of capIds) {
+    next = next.materializeRuleSpan({
+      id: capId,
+      orientation: candidate.orientation === "vertical" ? "horizontal" : "vertical",
+      size: whiskerConfig.errorBar.capSize
+    });
+  }
+  next = next.rematerializeRuleMark({ id: current.medianId });
+  if (hasOutliers && findLayer(next, current.outlierId) !== undefined) {
+    next = next.rematerializePointMark({ id: current.outlierId });
+  }
+  return next;
 }
 
 export const editBoxPlot = action(
@@ -116,6 +404,170 @@ export const editBoxPlot = action(
       );
     }
 
+    const candidate = roleCandidate(this, owner, current, args);
+    const sourceDataset = findDataset(this, candidate.source);
+    if (sourceDataset === undefined) {
+      throw new Error(`Unknown box-plot data "${candidate.source}".`);
+    }
+    const roleRequested = ["data", "x", "y"].some(
+      key => Object.hasOwn(args, key)
+    );
+    const changesRoles = !sameRoleCandidate(current, candidate);
+    if (changesRoles) {
+      const derived = deriveBoxData(
+        sourceDataset.values,
+        normalizeBoxTransform({
+          type: "boxSummary",
+          category: candidate.category,
+          field: candidate.measure,
+          whisker: whisker.type,
+          ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
+        })
+      );
+      const hasOutliers = outliers && whisker.type === "tukey" &&
+        derived.outliers.length > 0;
+      const whiskerConfig = this.markConfigs[current.whiskerId];
+      const capIds = [
+        whiskerConfig.errorBar.lowerCapId,
+        whiskerConfig.errorBar.upperCapId
+      ].filter(Boolean);
+      const summaryRevision = planDerivedDataRevision(this, {
+        owner: owner.id,
+        role: "SummaryData",
+        previous: current.summaryId,
+        consumers: [owner.id, current.whiskerId, ...capIds, current.medianId]
+      });
+      const hadOutlierLayer = findLayer(this, current.outlierId) !== undefined;
+      const outlierRevision = hasOutliers
+        ? planDerivedDataRevision(this, {
+            owner: owner.id,
+            role: "OutlierData",
+            ...(current.outlierDataId === undefined
+              ? {}
+              : { previous: current.outlierDataId }),
+            consumers: hadOutlierLayer ? [current.outlierId] : []
+          })
+        : undefined;
+      const applyEdit = program => {
+        let next = program.createBoxSummaryData({
+          id: summaryRevision.id,
+          source: candidate.source,
+          category: candidate.category,
+          field: candidate.measure,
+          whisker: whisker.type,
+          ...(whisker.factor === undefined ? {} : { factor: whisker.factor })
+        });
+        if (outlierRevision !== undefined) {
+          next = next.createBoxOutlierData({
+            id: outlierRevision.id,
+            source: candidate.source,
+            category: candidate.category,
+            field: candidate.measure,
+            whisker: whisker.type,
+            factor: whisker.factor
+          });
+          for (const rebind of outlierRevision.rebinds) {
+            next = next.rebindLayerData(rebind);
+          }
+        }
+        for (const rebind of summaryRevision.rebinds) {
+          next = next.rebindLayerData(rebind);
+        }
+        next = next._withMarkConfig(current.whiskerId, {
+          ...next.markConfigs[current.whiskerId],
+          errorBar: {
+            ...next.markConfigs[current.whiskerId].errorBar,
+            data: summaryRevision.id
+          }
+        });
+        if (hadOutlierLayer && !hasOutliers) {
+          next = removeOwnedMark(next, current.outlierId);
+        }
+        next = next._withMarkConfig(owner.id, {
+          ...next.markConfigs[owner.id],
+          boxPlot: {
+            ...current,
+            whisker,
+            width,
+            outliers,
+            box,
+            median,
+            outlier,
+            source: candidate.source,
+            orientation: candidate.orientation,
+            category: candidate.category,
+            measure: candidate.measure,
+            summaryId: summaryRevision.id,
+            outlierDataId: outlierRevision?.id
+          },
+          barWidth: { band: width },
+          fill: box.fill,
+          opacity: box.opacity,
+          stroke: box.stroke,
+          strokeWidth: box.strokeWidth
+        });
+        next = updateBoxPositions(next, owner, current, candidate, {
+          outlierDataId: outlierRevision?.id,
+          hasOutliers
+        });
+        if (!hadOutlierLayer && hasOutliers) {
+          const category = candidate.orientation === "vertical"
+            ? candidate.x
+            : candidate.y;
+          const measure = candidate.orientation === "vertical"
+            ? candidate.y
+            : candidate.x;
+          next = next.createBoxOutliers({
+            id: current.outlierId,
+            data: outlierRevision.id,
+            category: candidate.category,
+            categoryType: candidate.categoryType,
+            measure: candidate.measure,
+            orientation: candidate.orientation,
+            coordinate: owner.coordinate,
+            categoryScale: category.scale,
+            measureScale: measure.scale,
+            shape: outlier.shape,
+            radius: outlier.radius,
+            opacity: outlier.opacity
+          });
+        }
+        next = next
+          .encodeStroke({ target: current.medianId, value: median.stroke })
+          .encodeStrokeWidth({
+            target: current.medianId,
+            value: median.strokeWidth
+          });
+        if (findLayer(next, current.outlierId) !== undefined) {
+          next = next
+            .editPointMark({
+              target: current.outlierId,
+              shape: outlier.shape,
+              opacity: outlier.opacity
+            })
+            .encodeRadius({ target: current.outlierId, value: outlier.radius });
+        }
+        next = next.releaseDerivedData(summaryRevision.release);
+        if (current.outlierDataId !== undefined) {
+          next = next.releaseDerivedData({ id: current.outlierDataId });
+        }
+        return next._withContext({
+          currentMark: owner.id,
+          currentData: candidate.source
+        });
+      };
+      applyEdit(this);
+      return applyEdit(this);
+    }
+    if (roleRequested && !OPTIONS.slice(4).some(
+      key => Object.hasOwn(args, key)
+    )) {
+      return this._withContext({
+        currentMark: owner.id,
+        currentData: current.source
+      });
+    }
+
     const revisesData = JSON.stringify(whisker) !== JSON.stringify(current.whisker) ||
       outliers !== current.outliers;
     const changesBox = Object.hasOwn(args, "box") ||

package/src/actions/boxPlots/options.js

@@ -37,12 +37,12 @@ function plainOptions(value, keys, label, operation = "createBoxPlot") {
   return value;
 }
 
-export function resolveBoxPosition(value, label) {
+export function resolveBoxPosition(value, label, operation = "createBoxPlot") {
   if (value === undefined) return undefined;
   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, ["field", "fieldType", "scale"], `createBoxPlot ${label}`);
+  validateKeys(value, ["field", "fieldType", "scale"], `${operation} ${label}`);
   return value;
 }
 

package/src/actions/composition/actions.js

@@ -16,7 +16,9 @@ import { materializeFacetGraphics } from "../../materialization/facets.js";
 const CONCAT_OPTIONS = Object.freeze([
   "id", "programs", "gap", "align", "padding"
 ]);
-const LAYOUT_EDIT_OPTIONS = Object.freeze(["gap", "align", "padding"]);
+const LAYOUT_EDIT_OPTIONS = Object.freeze([
+  "columns", "gap", "align", "padding"
+]);
 const REPLACEMENT_OPTIONS = Object.freeze(["target", "program"]);
 
 function normalizeChildEntry(entry, index) {
@@ -149,7 +151,7 @@ export const vconcatAction = concatAction("vertical", "vconcat");
 const editCompositionLayout = action(
   {
     op: "editCompositionLayout",
-    description: "Edit composition spacing and alignment.",
+    description: "Edit composition layout.",
     scope: "composition"
   },
   function (args = {}) {
@@ -164,7 +166,9 @@ const editCompositionLayout = action(
           ...childDescriptor({ id, program: this.children[id] }),
           value: current.facet.values[index]
         })),
-        columns: current.columns,
+        columns: Object.hasOwn(args, "columns")
+          ? args.columns
+          : current.columns,
         gap: Object.hasOwn(args, "gap") ? args.gap : current.gap,
         align: Object.hasOwn(args, "align") ? args.align : current.align,
         padding: Object.hasOwn(args, "padding")
@@ -176,12 +180,18 @@ const editCompositionLayout = action(
         children: this.children,
         compositionSpec: {
           ...current,
+          columns: layout.columns,
           gap: layout.gap,
           align: layout.align,
           padding: layout.padding
         }
       }).materializeComposition();
     }
+    if (Object.hasOwn(args, "columns")) {
+      throw new Error(
+        "editCompositionLayout columns is available only on a facet composition."
+      );
+    }
     const padding = Object.hasOwn(args, "padding")
       ? normalizeCompositionPadding(args.padding, current.padding)
       : current.padding;