ggaction 0.0.23 → 0.0.26

package/src/actions/titles/resolve.js

@@ -1,3 +1,4 @@
+import { validateTextAlignment } from "../../core/validation.js";
 import { textBoundsFitCanvas } from "../../core/textMetrics.js";
 import { resolveGuideCollisionBlocks } from "../../materialization/guides/resources.js";
 import { canvasOverflowError } from "../../layout/canvas.js";
@@ -24,10 +25,10 @@ import { findCanvasGraphic } from
 
 const OPTIONS = Object.freeze([
   "text", "subtitle", "position", "align", "offset", "alongOffset", "gap", "titleStyle",
-  "subtitleStyle", "maxWidth", "wrap", "lineHeight"
+  "subtitleStyle", "maxWidth", "wrap", "lineHeight", "subtitleLineHeight"
 ]);
 const STYLE_OPTIONS = Object.freeze([
-  "color", "fontSize", "fontFamily", "fontWeight", "fontStyle"
+  "color", "fontSize", "fontFamily", "fontWeight", "fontStyle", "align"
 ]);
 const POSITIONS = Object.freeze(["top", "bottom", "left", "right"]);
 const ALIGNS = Object.freeze(["left", "center", "right"]);
@@ -69,6 +70,7 @@ function normalizeStyle(value, defaults, label) {
   }
   const style = { ...defaults, ...(value ?? {}) };
   validateKeys(style, STYLE_OPTIONS, label);
+  validateTextAlignment(style, label);
   validateTitleString(style.color, `${label} color`);
   validateTitleString(style.fontFamily, `${label} fontFamily`);
   validatePositiveFinite(style.fontSize, `${label} fontSize`);
@@ -101,6 +103,9 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
   const maxWidth = args.maxWidth ?? defaults.maxWidth;
   const wrap = args.wrap ?? defaults.wrap ?? (maxWidth === undefined ? undefined : "word");
   const lineHeight = args.lineHeight ?? defaults.lineHeight;
+  const subtitleLineHeight = args.subtitleLineHeight === undefined
+    ? defaults.subtitleLineHeight
+    : args.subtitleLineHeight;
   if (!POSITIONS.includes(position)) {
     throw new Error(`Unsupported title position "${position}".`);
   }
@@ -128,6 +133,12 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
   )) {
     throw new RangeError("Chart title lineHeight must cover every visible fontSize.");
   }
+  if (subtitleLineHeight !== undefined && (
+    !Number.isFinite(subtitleLineHeight) ||
+    subtitleLineHeight < subtitleStyle.fontSize
+  )) {
+    throw new RangeError("Chart subtitleLineHeight must cover subtitleStyle.fontSize.");
+  }
   return {
     position,
     align,
@@ -136,6 +147,7 @@ function normalizeConfig(args, defaults, { hasSubtitle }) {
     gap,
     titleStyle,
     subtitleStyle,
+    ...(subtitleLineHeight === undefined ? {} : { subtitleLineHeight }),
     ...(maxWidth === undefined ? {} : { maxWidth, wrap, ...(lineHeight === undefined
       ? {}
       : { lineHeight }) })
@@ -241,11 +253,12 @@ export function resolveTitleLayout(program, config) {
       : config.position === "top"
       ? 16 + config.offset
       : plot.y + plot.height + config.offset;
-    component = (lines, centers) => ({
+    const left = x - (config.align === "right" ? block.width : config.align === "center" ? block.width / 2 : 0);
+    component = (lines, centers, style) => ({
       lines,
-      x,
+      x: style.align === undefined ? x : alignedTextAnchor(left, block.width, style.align),
       y: centers.map(value => blockTop + value),
-      textAlign: config.align,
+      textAlign: style.align ?? config.align,
       rotation: 0,
       explicitRotation: config.position !== "top" || lines.length > 1
     });
@@ -257,19 +270,19 @@ export function resolveTitleLayout(program, config) {
       ? 16 + config.offset
       : canvas.properties.width - 16 + config.offset;
     const mapX = value => config.position === "left" ? edge + value : edge - value;
-    component = (lines, centers) => ({
+    component = (lines, centers, style) => ({
       lines,
       x: centers.map(mapX),
-      y,
-      textAlign: "center",
+      y: y + Math.sin(rotation) * (style.align === "left" ? -block.width / 2 : style.align === "right" ? block.width / 2 : 0),
+      textAlign: style.align ?? "center",
       rotation,
       explicitRotation: true
     });
   }
-  const title = component(block.titleLines, block.titleCenters);
+  const title = component(block.titleLines, block.titleCenters, config.titleStyle);
   const subtitle = block.subtitleLines.length === 0
     ? undefined
-    : component(block.subtitleLines, block.subtitleCenters);
+    : component(block.subtitleLines, block.subtitleCenters, config.subtitleStyle);
   const titleBounds = unionTitleBounds([
     resolveTitleComponentBounds(title, config.titleStyle, program.materializationConfigs.textMetrics),
     ...(subtitle === undefined

package/src/core/action.js

@@ -5,6 +5,21 @@ import { cloneAndFreeze, freezeOwned, isOwned, isPlainObject } from "./immutable
 const metadataByWrappedAction = new WeakMap();
 const implementationByWrappedAction = new WeakMap();
 let actionCompletionHook;
+const targetDispatchers = new WeakMap();
+const UNSCOPED_PRIMITIVES = new Set(["createGraphics", "editGraphics", "editSemantic", "createData"]);
+export function registerActionTargetDispatcher(ProgramClass, dispatcher) {
+  targetDispatchers.set(ProgramClass, dispatcher);
+}
+function targetDispatcher(ProgramClass) {
+  for (let owner = ProgramClass; owner; owner = Object.getPrototypeOf(owner)) {
+    if (targetDispatchers.has(owner)) return targetDispatchers.get(owner);
+  }
+}
+
+
+export function supportsScopedActionTargets(ProgramClass, operation) {
+  return !UNSCOPED_PRIMITIVES.has(operation) && targetDispatcher(ProgramClass) !== undefined;
+}
 
 export function setActionCompletionHook(hook) {
   if (hook !== undefined && typeof hook !== "function") {
@@ -89,29 +104,28 @@ function childList(node) {
   return list;
 }
 
-function withChildList(node, list) {
-  let children;
-  const next = {};
-  for (const key of Object.keys(node)) {
-    if (key !== "children") Object.defineProperty(next, key, {
-      value: node[key], enumerable: true
-    });
-  }
-  Object.defineProperty(next, "children", {
-    enumerable: true,
-    get() {
-      if (children === undefined) {
-        const values = new Array(list.length);
-        let item = list.tail;
-        for (let index = list.length - 1; index >= 0; index -= 1) {
-          values[index] = item.value;
-          item = item.previous;
-        }
-        children = freezeOwned(values);
-      }
-      return children;
+function readChildren() {
+  const list = childLists.get(this);
+  if (list.children === undefined) {
+    const values = new Array(list.length);
+    let item = list.tail;
+    for (let index = list.length - 1; index >= 0; index -= 1) {
+      values[index] = item.value;
+      item = item.previous;
     }
-  });
+    list.children = freezeOwned(values);
+  }
+  return list.children;
+}
+
+function withChildList(node, list) {
+  // Keep one accessor identity across revisions. A new getter closure and
+  // nonconfigurable descriptors per append force dictionary-shaped objects;
+  // freezing those dominates long nested materialization traces in V8.
+  // Copy data properties without evaluating the lazy children array.
+  const next = Object.fromEntries(Object.keys(node)
+    .filter(key => key !== "children").map(key => [key, node[key]]));
+  Object.defineProperty(next, "children", { enumerable: true, get: readChildren });
   childLists.set(next, list);
   return freezeOwned(next);
 }
@@ -202,15 +216,17 @@ export function action(metadata, implementation) {
         throw new TypeError("Action arguments must be a plain object.");
       }
   
-      if (scope === "unit") this._assertUnitProgram(ownedMetadata.op);
-      if (scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
+      const scoped = isPlainObject(args.target) || Array.isArray(args.target);
+      const dispatch = scoped && !UNSCOPED_PRIMITIVES.has(ownedMetadata.op) ? targetDispatcher(this.constructor) : undefined;
+      if (!dispatch && scope === "unit") this._assertUnitProgram(ownedMetadata.op);
+      if (!dispatch && scope === "composition") this._assertCompositionProgram(ownedMetadata.op);
   
       const summarizedArgs = summarizeArgs(args);
       const entered = this._enterAction({
         ...ownedMetadata,
         args: summarizedArgs
       });
-      let result = implementation.call(entered, args);
+      let result = dispatch ? dispatch(entered, wrappedAction, args) : implementation.call(entered, args);
   
       if (!(result instanceof this.constructor)) {
         throw new TypeError(`${ownedMetadata.op} must return a ChartProgram.`);

package/src/core/compositionScales.js

@@ -0,0 +1,12 @@
+import { isPlainObject, cloneAndFreeze } from "./immutable.js";
+
+export const COMPOSITION_SCALE_CHANNELS = Object.freeze(["x", "y", "color", "stroke", "size", "shape", "opacity", "strokeWidth", "strokeDash"]);
+
+export function normalizeCompositionShares(value = {}) {
+  if (!isPlainObject(value)) throw new TypeError("Composition share requires a channel object.");
+  for (const [channel, shared] of Object.entries(value)) {
+    if (!COMPOSITION_SCALE_CHANNELS.includes(channel)) throw new Error(`Unknown composition share channel "${channel}".`);
+    if (typeof shared !== "boolean") throw new TypeError(`Composition share.${channel} must be boolean.`);
+  }
+  return cloneAndFreeze(value);
+}

package/src/core/compositionState.js

@@ -1,3 +1,5 @@
+import { normalizeCompositionShares } from "./compositionScales.js";
+import { normalizeFacetGap } from "./facetGap.js";
 import { normalizeFacetAxes } from "./facetAxisPolicy.js";
 import { isOwned, isPlainObject } from "./immutable.js";
 import { ownProgramState } from "./programState.js";
@@ -8,6 +10,11 @@ import {
   DEFAULT_FACET_TOP_LANE
 } from "./vocabulary.js";
 
+export function normalizeCompositionLegends(value) {
+  if (!["local", "collect"].includes(value)) throw new TypeError('Composition legends must be "local" or "collect".');
+  return value;
+}
+
 // Primitive graphics/trace edits retain both immutable owners. Validate their
 // relationship once, rather than scanning every facet cell on every primitive.
 const validatedCompositions = new WeakMap();
@@ -242,10 +249,12 @@ function validateCompositionChildren(compositionSpec, childIds, facet) {
 }
 
 function validateLayout(compositionSpec) {
-  if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
+  if (compositionSpec.type === "facet") {
+    normalizeFacetGap(compositionSpec.gap, "compositionSpec.gap");
+  } else if (!Number.isFinite(compositionSpec.gap) || compositionSpec.gap < 0) {
     throw new RangeError("compositionSpec.gap must be a non-negative finite number.");
   }
-  if (!["start", "center", "end"].includes(compositionSpec.align)) {
+  if (!(compositionSpec.type === "facet" ? ["start", "center", "end"] : ["start", "center", "end", "plot"]).includes(compositionSpec.align)) {
     throw new Error("compositionSpec.align must be start, center, or end.");
   }
   if (!isPlainObject(compositionSpec.padding)) {
@@ -281,7 +290,7 @@ export function ownCompositionSpec(compositionSpec, children) {
   }
   const allowed = [
     "id", "type", "direction", "children", "columns", "gap", "align",
-    "padding", "facet", "spacing", "topLane"
+    "padding", "facet", "spacing", "topLane", "share", "legends"
   ];
   const unknown = Object.keys(compositionSpec).find(key => !allowed.includes(key));
   if (unknown !== undefined) {
@@ -314,6 +323,14 @@ export function ownCompositionSpec(compositionSpec, children) {
   ) {
     throw new Error("Concat compositionSpec does not accept facet properties.");
   }
+  if (compositionSpec.legends !== undefined) {
+    if (facet) throw new Error("Facet uses guides.legend, not composition legends.");
+    normalizeCompositionLegends(compositionSpec.legends);
+  }
+  if (compositionSpec.share !== undefined) {
+    if (facet) throw new Error("Facet uses scales, not composition share.");
+    normalizeCompositionShares(compositionSpec.share);
+  }
   validateLayout(compositionSpec);
   const owned = ownProgramState(compositionSpec);
   if (isOwned(children)) {

package/src/core/facetGap.js

@@ -0,0 +1,44 @@
+import { cloneAndFreeze, isPlainObject } from "./immutable.js";
+import { annotateError } from "./diagnostics.js";
+export function validateCompositionSpacing(value, label) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new RangeError(`${label} must be a non-negative finite number.`);
+  }
+  return value;
+}
+
+/** Keep scalar intent intact; a facet pair always declares both axes. */
+export function normalizeFacetGap(value, label = "Facet gap") {
+  if (!isPlainObject(value)) return validateCompositionSpacing(value, label);
+  const keys = Reflect.ownKeys(value);
+  if (keys.length !== 2 || !keys.includes("x") || !keys.includes("y")) {
+    throw annotateError(new TypeError(`${label} must contain exactly x and y.`), {
+      code: "invalid-value", optionPath: "gap", actual: value
+    });
+  }
+  const result = {};
+  for (const axis of ["x", "y"]) {
+    try {
+      result[axis] = validateCompositionSpacing(value[axis], `${label}.${axis}`);
+    } catch (error) {
+      throw annotateError(error, {
+        code: "invalid-value", optionPath: `gap.${axis}`, actual: value[axis], limit: 0
+      });
+    }
+  }
+  return cloneAndFreeze(result);
+}
+
+/** Accept only a previously normalized scalar or pair. */
+export function facetGapAxis(gap, axis) {
+  return typeof gap === "number" ? gap : gap[axis];
+}
+
+/** Overflow remains axis-specific for a pair; scalar callers keep their old error. */
+export function assertFacetGapFinite(gap, axis, values, message) {
+  if (values.every(Number.isFinite)) return;
+  const error = new RangeError(message);
+  throw typeof gap === "number" ? error : annotateError(error, {
+    code: "invalid-value", optionPath: `gap.${axis}`, actual: gap[axis]
+  });
+}

package/src/core/immutable.js

@@ -46,12 +46,17 @@ export function cloneAndFreeze(value, ancestors = new WeakSet(), path = "state")
   if (Array.isArray(value)) {
     clone = value.map((item, index) => cloneAndFreeze(item, ancestors, `${path}[${index}]`));
   } else if (isPlainObject(value)) {
-    clone = Object.fromEntries(
-      Object.entries(value).map(([key, item]) => [
-        key,
-        cloneAndFreeze(item, ancestors, `${path}.${key}`)
-      ])
-    );
+    clone = {};
+    // Snapshot entries before descending, as with Object.fromEntries, but avoid
+    // allocating a second entries array and a pair for every stored property.
+    for (const [key, item] of Object.entries(value)) {
+      const child = cloneAndFreeze(item, ancestors, `${path}.${key}`);
+      if (key === "__proto__") {
+        Object.defineProperty(clone, key, {
+          value: child, enumerable: true, writable: true, configurable: true
+        });
+      } else clone[key] = child;
+    }
   } else {
     throw new TypeError("ChartProgram state only supports plain objects and arrays.");
   }

package/src/core/programState.js

@@ -48,9 +48,25 @@ export function releaseNamedResourceOwnership(program, { kind, id, dataOwner })
     materializationConfigs,
     ["regressionFits", dataOwner?.current ?? id]
   ).value;
+  materializationConfigs = removeMaterializationConfig(
+    materializationConfigs,
+    ["rowProvenance", dataOwner?.current ?? id]
+  ).value;
   const context = program.context.currentData === id
     ? freezeOwned({ ...program.context, currentData: undefined })
     : program.context;
   if (context === program.context && materializationConfigs === program.materializationConfigs) return program;
   return program._clone({ context, materializationConfigs });
 }
+
+// Scoped planners temporarily annotate context. Restore only those keys after
+// the action so genuine target/data context changes survive, and absent keys
+// remain absent in persistence rather than becoming serialized undefined tags.
+export function restoreProgramContextKeys(program, reference, keys) {
+  const context = { ...program.context };
+  for (const key of keys) {
+    if (Object.hasOwn(reference.context, key)) context[key] = reference.context[key];
+    else delete context[key];
+  }
+  return program._clone({ context: freezeOwned(context) });
+}

package/src/core/resourceReferences.js

@@ -13,7 +13,7 @@ const DATA_VALUE_KEYS = new Set([
 const DATA_SOURCE_CONFIGS = new Set([
   "boxPlot", "density", "ecdfPlot", "endpointPlot", "errorBand", "errorBar",
   "gradientPlot", "horizon", "intervalPlot", "markFilter", "raincloudPlot",
-  "regression", "violinPlot"
+  "regression", "violinPlot", "radarPlot"
 ]);
 const MARK_ID_KEYS = new Set([
   "bandId", "bodyId", "centerId", "connectorId", "intervalId", "lineId",
@@ -98,7 +98,7 @@ export function collectSemanticScaleReferences(program) {
     }
   }
   collectKnownKeys(program.semanticSpec.guides, [], (key, value, path) => {
-    if (["scale", "colorScale", "sizeScale"].includes(key)) {
+    if (["scale", "colorScale", "sizeScale", "shapeScale"].includes(key)) {
       append(references, reference(
         "scale", value, "semanticGuide", "guides", path
       ));
@@ -134,6 +134,10 @@ export function collectMarkConfigReferences(program) {
     append(references, reference(
       "mark", layer.source, "layer", layer.id, ["source"]
     ));
+    append(references, reference(
+      "mark", layer.derivedBindings?.overlay?.source, "layer", layer.id,
+      ["derivedBindings", "overlay", "source"]
+    ));
   }
   for (const [ownerId, config] of Object.entries(program.markConfigs)) {
     collectKnownKeys(config, [], (key, value, path, parentPath) => {
@@ -204,13 +208,16 @@ export function collectGuideConfigReferences(program) {
   for (const target of Object.keys(program.guideConfigs?.legendGroups ?? {})) {
     append(references, reference("mark", target, "legend", target, ["legendGroups", target]));
   }
+  for (const target of Object.keys(program.guideConfigs?.suppressedLegends ?? {})) {
+    append(references, reference("mark", target, "legend", target, ["suppressedLegends", target]));
+  }
   for (const [family, configs] of Object.entries(program.guideConfigs ?? {})) {
     collectKnownKeys(configs, [], (key, value, path, parentPath) => {
       const ownerId = parentPath.length === 0 ? family : parentPath.join(".");
       const relativePath = parentPath.length === 0
         ? path
         : path.slice(parentPath.length);
-      if (["scale", "colorScale", "sizeScale"].includes(key)) {
+      if (["scale", "colorScale", "sizeScale", "shapeScale"].includes(key)) {
         append(references, reference(
           "scale", value, family, ownerId, relativePath
         ));
@@ -240,6 +247,12 @@ export function collectSelectionReferences(program) {
     append(references, reference(
       "mark", config.target, "selection", id, ["target"]
     ));
+    append(references, reference(
+      "selection", config.sourceSelection, "selection", id, ["sourceSelection"]
+    ));
+    append(references, reference(
+      "data", config.selector?.rows?.data, "selection", id, ["selector", "rows", "data"]
+    ));
   }
   for (const [id, config] of Object.entries(
     program.materializationConfigs.highlights ?? {}
@@ -250,6 +263,9 @@ export function collectSelectionReferences(program) {
     append(references, reference(
       "selection", config.selection, "highlight", id, ["selection"]
     ));
+    append(references, reference(
+      "selection", config.groupSelection, "highlight", id, ["groupSelection"]
+    ));
   }
   return freezeOwned(references);
 }

package/src/core/validation.js

@@ -127,7 +127,14 @@ export function validateFontWeight(value, label, numberType = "number") {
   return value;
 }
 
+export function validateTextAlignment(style, label) {
+  if (Object.hasOwn(style, "align") && !["left", "center", "right"].includes(style.align)) {
+    throw new TypeError(`${label} align requires left, center or right.`);
+  }
+}
+
 export function validateTextStyle(config, label) {
+  validateTextAlignment(config, label);
   validateNonEmptyString(config.color, `${label} color`);
   validatePositiveFinite(config.fontSize, `${label} fontSize`);
   validateNonEmptyString(config.fontFamily, `${label} fontFamily`);

package/src/core/vocabulary.js

@@ -253,7 +253,7 @@ const marks = (...types) => Object.freeze(types);
 export const APPEARANCE_MARK_TYPES = Object.freeze({
   encodeColor: marks('point', 'line', 'bar', 'area', 'arc', 'rect', 'text'),
   encodeStroke: marks('point', 'line', 'area', 'bar', 'rect', 'arc', 'rule', 'tick'),
-  encodeOpacity: marks('point', 'rule', 'line', 'bar', 'rect'),
+  encodeOpacity: marks('point', 'rule', 'line', 'area', 'bar', 'rect'),
   encodeStrokeWidth: marks('rule', 'line', 'rect'),
   encodeStrokeDash: marks('line', 'rule'),
   encodeSize: marks('point'),
@@ -261,6 +261,12 @@ export const APPEARANCE_MARK_TYPES = Object.freeze({
   encodeAngle: marks('point', 'tick')
 });
 
+// Constant appearance can support more marks than field mapping. Inspection
+// and execution share this distinction instead of advertising unusable fields.
+export const FIXED_APPEARANCE_MARK_TYPES = Object.freeze({
+  encodeStrokeWidth: marks('rule', 'line', 'rect', 'point', 'bar', 'area', 'arc', 'tick')
+});
+
 // Generated default action methods: start
-export const DEFAULT_ACTION_METHODS = /* @__PURE__ */ Object.freeze(["createCanvas","editCanvas","fitCanvas","applyTextMetrics","removeTextMetrics","applyTheme","removeTheme","createData","reviseData","removeData","removeScale","removeCoordinate","bindMarkData","filterData","createSummaryData","createBinData","createLookupData","createFlattenData","createFoldData","createComputedData","createNormalizedData","createSortedData","createCompleteData","createImputedData","createStackData","createDensityData","createRegressionData","createRegressionStatisticsData","createWindowData","createTimeUnitData","createBin2DData","editBin2DData","editDerivedData","editComputedData","editFilteredData","editLookupData","editFlattenData","editFoldData","editSummaryData","editBinData","editTimeUnitData","editWindowData","editDensityData","editStackData","editRegressionData","editRegressionStatisticsData","editIntervalData","editECDFData","editNormalizedData","editSortedData","editCompleteData","editImputedData","createIntervalData","createECDFData","createPointMark","createTickMark","createStatisticalReference","createReferenceLine","createReferenceBand","createMarkLabels","editMarkLabelSelection","editMarkLabelPlacement","removeMarkLabels","createAnnotation","createTextMark","editTextMark","layoutLabels","removeLabelLayout","editPointMark","editTickMark","jitterPoints","removeJitter","packPoints","removePointPacking","removeMark","createLineMark","editLineMark","createBarMark","editBarMark","createAreaMark","createRuleMark","editRuleMark","editAreaMark","encodeX","encodeY","encodeChannels","encodeX2","encodeColor","encodeStrokeDash","encodeStroke","encodeStrokeWidth","encodeSize","encodeShape","encodeAngle","encodeOpacity","encodeRadius","encodeTheta","encodeR","encodePointRadius","removePointRadius","encodeXOffset","encodeYOffset","encodeY2","encodeYRange","encodeXRange","encodeGroup","encodePathOrder","encodeParallelCoordinates","removePathOrder","orderCategories","removeCategoryOrder","removeEncoding","encodeText","encodeDx","encodeDy","encodeHistogram","encodeDensity","editDensity","encodeHorizon","editHorizon","encodeBarWidth","createRegression","editRegression","createErrorBar","editErrorBar","createErrorBand","editErrorBand","editErrorBandBoundary","createBoxPlot","editBoxPlot","createGradientPlot","editGradientPlot","createViolinPlot","editViolinPlot","createParallelAxes","createParallelAxis","editParallelAxis","removeParallelAxis","removeParallelAxes","createAxes","createXAxis","createYAxis","createXAxisLine","createYAxisLine","editXAxisLine","editYAxisLine","createXAxisTicks","createYAxisTicks","editXAxisTicks","editYAxisTicks","createXAxisLabels","createYAxisLabels","editXAxisLabels","editYAxisLabels","createXAxisTicksAndLabels","createYAxisTicksAndLabels","editXAxisTicksAndLabels","editYAxisTicksAndLabels","createXAxisTitle","createYAxisTitle","editXAxisTitle","editYAxisTitle","editAxes","editXAxis","editYAxis","removeXAxis","removeYAxis","createGrid","createHorizontalGrid","createVerticalGrid","editHorizontalGrid","editVerticalGrid","editGrid","removeGrid","createLegend","editLegend","editLegendBlock","editLegendLayout","editLegendLabels","editLegendTitle","editLegendSymbols","editLegendBorder","createGuides","removeLegend","createTitle","editTitle","removeTitle","createCoordinate","editCoordinate","createScale","editScale","editXScale","editYScale","editXOffsetScale","editYOffsetScale","editParallelScale","editThetaScale","editRScale","editColorScale","editStrokeScale","editSizeScale","editOpacityScale","editShapeScale","editStrokeWidthScale","editStrokeDashScale","createDerivedData","createRegressionBand","editRegressionBand","createRegressionLine","editRegressionLine","filterMarks","removeMarkFilter","selectMarks","editMarkSelection","removeMarkHighlight","removeMarkSelection","highlightMarks","editSemantic","createGraphics","editGraphics","createArcMark","editArcMark","createThetaAxis","createRadialAxis","editThetaAxis","editRadialAxis","removeThetaAxis","removeRadialAxis","createThetaAxisLine","editThetaAxisLine","createRadialAxisLine","editRadialAxisLine","createThetaAxisTicks","editThetaAxisTicks","createRadialAxisTicks","editRadialAxisTicks","createThetaAxisLabels","editThetaAxisLabels","createRadialAxisLabels","editRadialAxisLabels","createThetaAxisTitle","editThetaAxisTitle","createRadialAxisTitle","editRadialAxisTitle","createThetaGrid","createRadialGrid","editThetaGrid","editRadialGrid","editCompositionLayout","replaceCompositionChild","insertCompositionChild","removeCompositionChild","reorderCompositionChildren","facet","facetGrid","repeatCharts","editFacetSource","editFacetHeaders","editFacetScales","editFacetGuides","createScatterPlot","createTextPlot","createDotPlot","createLollipopPlot","createDumbbellPlot","editEndpointPlot","createECDFPlot","editECDFPlot","createIntervalPlot","createRegressionPlot","createLinePlot","createPolarScatterPlot","createPolarLinePlot","createRadarPlot","editRadarPlot","createRugPlot","createStripPlot","createBeeswarmPlot","createRaincloudPlot","editRaincloudPlot","createBarPlot","createHistogram","createHeatmap","createParallelCoordinates","createRectMark","editRectMark","createPiePlot","createRosePlot","createRadialBarPlot","createDensityPlot","createHorizonPlot","createAreaPlot","layoutSeries"]);
+export const DEFAULT_ACTION_METHODS = /* @__PURE__ */ Object.freeze(["createCanvas","editCanvas","fitCanvas","applyTextMetrics","removeTextMetrics","applyTheme","removeTheme","createData","reviseData","removeData","removeScale","removeCoordinate","bindMarkData","filterData","createSummaryData","createBinData","createLookupData","createFlattenData","createFoldData","createComputedData","createNormalizedData","createSortedData","createCompleteData","createImputedData","createStackData","createDensityData","createRegressionData","createRegressionStatisticsData","createWindowData","createTimeUnitData","createBin2DData","editBin2DData","editDerivedData","editComputedData","editFilteredData","editLookupData","editFlattenData","editFoldData","editSummaryData","editBinData","editTimeUnitData","editWindowData","editDensityData","editStackData","editRegressionData","editRegressionStatisticsData","editIntervalData","editECDFData","editNormalizedData","editSortedData","editCompleteData","editImputedData","createIntervalData","createECDFData","createPointMark","createTickMark","createStatisticalReference","createReferenceLine","createReferenceBand","createMarkLabels","editMarkLabelSelection","editMarkLabelPlacement","removeMarkLabels","createAnnotation","createTextMark","editTextMark","layoutLabels","removeLabelLayout","editPointMark","editTickMark","jitterPoints","removeJitter","packPoints","removePointPacking","removeMark","createLineMark","editLineMark","createBarMark","editBarMark","createAreaMark","createRuleMark","editRuleMark","editAreaMark","encodeX","encodeY","encodeChannels","encodeX2","encodeColor","encodeStrokeDash","encodeStroke","encodeStrokeWidth","encodeSize","encodeShape","encodeAngle","encodeOpacity","encodeRadius","encodeTheta","encodeR","encodePointRadius","removePointRadius","encodeXOffset","encodeYOffset","encodeY2","encodeYRange","encodeXRange","encodeGroup","encodePathOrder","encodeParallelCoordinates","removePathOrder","orderCategories","removeCategoryOrder","removeEncoding","encodeText","encodeDx","encodeDy","encodeHistogram","encodeDensity","editDensity","encodeHorizon","editHorizon","encodeBarWidth","createRegression","editRegression","createErrorBar","editErrorBar","createErrorBand","editErrorBand","editErrorBandBoundary","createBoxPlot","editBoxPlot","createGradientPlot","editGradientPlot","createViolinPlot","editViolinPlot","createParallelAxes","createParallelAxis","editParallelAxis","removeParallelAxis","removeParallelAxes","createAxes","createXAxis","createYAxis","createXAxisLine","createYAxisLine","editXAxisLine","editYAxisLine","createXAxisTicks","createYAxisTicks","editXAxisTicks","editYAxisTicks","createXAxisLabels","createYAxisLabels","editXAxisLabels","editYAxisLabels","createXAxisTicksAndLabels","createYAxisTicksAndLabels","editXAxisTicksAndLabels","editYAxisTicksAndLabels","createXAxisTitle","createYAxisTitle","editXAxisTitle","editYAxisTitle","editAxes","editXAxis","editYAxis","removeXAxis","removeYAxis","createGrid","createHorizontalGrid","createVerticalGrid","editHorizontalGrid","editVerticalGrid","editGrid","removeGrid","createLegend","editLegend","editLegendBlock","editLegendLayout","editLegendLabels","editLegendTitle","editLegendSymbols","editLegendBorder","createGuides","removeLegend","createTitle","editTitle","removeTitle","createCoordinate","editCoordinate","createScale","editScale","editXScale","editYScale","editXOffsetScale","editYOffsetScale","editParallelScale","editThetaScale","editRScale","editColorScale","editStrokeScale","editSizeScale","editOpacityScale","editShapeScale","editStrokeWidthScale","editStrokeDashScale","createDerivedData","createRegressionBand","editRegressionBand","createRegressionLine","editRegressionLine","filterMarks","removeMarkFilter","selectMarks","editMarkSelection","removeMarkHighlight","removeMarkSelection","highlightMarks","editSemantic","createGraphics","editGraphics","createArcMark","editArcMark","createThetaAxis","createRadialAxis","editThetaAxis","editRadialAxis","removeThetaAxis","removeRadialAxis","createThetaAxisLine","editThetaAxisLine","createRadialAxisLine","editRadialAxisLine","createThetaAxisTicks","editThetaAxisTicks","createRadialAxisTicks","editRadialAxisTicks","createThetaAxisLabels","editThetaAxisLabels","createRadialAxisLabels","editRadialAxisLabels","createThetaAxisTitle","editThetaAxisTitle","createRadialAxisTitle","editRadialAxisTitle","createThetaGrid","createRadialGrid","editThetaGrid","editRadialGrid","editCompositionLayout","replaceCompositionChild","insertCompositionChild","removeCompositionChild","reorderCompositionChildren","facet","facetGrid","repeatCharts","editFacetSource","editFacetHeaders","editFacetScales","editFacetGuides","createScatterPlot","createTextPlot","createDotPlot","createLollipopPlot","createDumbbellPlot","editEndpointPlot","createECDFPlot","editECDFPlot","createIntervalPlot","createRegressionPlot","createLinePlot","createPolarScatterPlot","createPolarLinePlot","createRadarPlot","editRadarPlot","createRugPlot","createStripPlot","createBeeswarmPlot","createRaincloudPlot","editRaincloudPlot","createBarPlot","createHistogram","createHeatmap","createParallelCoordinates","createRectMark","editRectMark","createPiePlot","createRosePlot","createRadialBarPlot","createDensityPlot","createHorizonPlot","createAreaPlot","layoutSeries","createOverlay","editOverlay","createLayerPlot","createAdjacentPlot","editCompositionScales"]);
 // Generated default action methods: end

package/src/grammar/actionTargets.js

@@ -0,0 +1,24 @@
+import { validateOptionObject } from "../core/validation.js";
+import { validateUserId } from "../core/identifiers.js";
+
+function normalizeTarget(target) {
+  if (typeof target === "string") return { childPath: [], id: validateUserId(target, "Action target") };
+  validateOptionObject(target, ["childPath", "id", "facetSource"], "Scoped action target");
+  if (!Array.isArray(target.childPath) || target.childPath.some(id => typeof id !== "string")) {
+    throw new TypeError("Scoped action target requires a childPath array.");
+  }
+  if (target.facetSource !== undefined && target.facetSource !== true) throw new TypeError("facetSource must be true when supplied.");
+  target.childPath.forEach(id => validateUserId(id, "Target child id"));
+  return { childPath: [...target.childPath], ...(target.facetSource ? { facetSource: true } : {}), ...(target.id === undefined ? {} : { id: validateUserId(target.id, "Action target id") }) };
+}
+
+
+export function normalizeActionTargets(value) {
+  const requested = Array.isArray(value) ? value : [value];
+  if (!requested.length) throw new Error("Action target list must not be empty.");
+  const targets = requested.map(normalizeTarget);
+  if (new Set(targets.map(target => JSON.stringify(target))).size !== targets.length) {
+    throw new Error("Action targets must be unique.");
+  }
+  return targets;
+}

package/src/grammar/axisTextPlacement.js

@@ -1 +1 @@
-import{resolveTextLines as l}from"../core/textMetrics.js";function a(e,{title:i=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(i){if(Object.hasOwn(e,"overlap")&&!["error","allow"].includes(e.overlap))throw new TypeError("Axis title overlap must be error or allow.");if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");for(const t of["offset","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Axis title ${t} must be a finite number.`)}}function f(e,i){if(!/[\r\n]/u.test(e))return;const t=i.baseline??"middle",n=l(e,{fontSize:i.fontSize,align:i.align??"center",baseline:t,...t==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(t)){const o=(n.length-1)*i.fontSize*1.2;return n.map(r=>({...r,y:r.y-o}))}return n.length>1?n:void 0}function b(e){return e?.overlap==="allow"}export{b as axisTitleAllowsLabelOverlap,f as axisTitleTextLines,a as validateAxisTextPlacement};
+import{validateKeys as a,validateNonNegativeFinite as o}from"../core/validation.js";import{isPlainObject as s}from"../core/immutable.js";import{resolveTextLines as b}from"../core/textMetrics.js";function c(e,{title:t=!1}={}){if(Object.hasOwn(e,"align")&&!["left","center","right"].includes(e.align))throw new TypeError("Axis text align must be left, center, or right.");if(t){if(Object.hasOwn(e,"overlap")&&!["error","allow"].includes(e.overlap))throw new TypeError("Axis title overlap must be error or allow.");if(Object.hasOwn(e,"baseline")&&!["top","hanging","middle","alphabetic","ideographic","bottom"].includes(e.baseline))throw new TypeError("Axis title baseline must be a supported text baseline.");if(Object.hasOwn(e,"offset")&&s(e.offset)){if(a(e.offset,["from","gap"],"Axis title offset"),e.offset.from!=="labels"||!Object.hasOwn(e.offset,"gap"))throw new TypeError("Axis title offset requires from: labels and gap.");o(e.offset.gap,"Axis title label gap")}for(const i of["offset","alongOffset"])if(!(i==="offset"&&f(e.offset))&&Object.hasOwn(e,i)&&!Number.isFinite(e[i]))throw new TypeError(`Axis title ${i} must be a finite number.`)}}function f(e){return s(e)&&e.from==="labels"}function h(e){return e?.inferredOffset===!0||f(e?.offset)}function m(e){return(e?.lines??[{text:e?.text}]).some(t=>typeof t.text=="string"&&t.text.length>0)}function w(e,t){if(!/[\r\n]/u.test(e))return;const i=t.baseline??"middle",r=b(e,{fontSize:t.fontSize,align:t.align??"center",baseline:i,...i==="middle"?{blockAlign:"middle"}:{}});if(["bottom","ideographic"].includes(i)){const l=(r.length-1)*t.fontSize*1.2;return r.map(n=>({...n,y:n.y-l}))}return r.length>1?r:void 0}function u(e){return e?.overlap==="allow"}function g(e,{allowReset:t=!1}={}){e===void 0||t&&e==="auto"||o(e,"Label flushThreshold")}export{m as axisLabelHasText,u as axisTitleAllowsLabelOverlap,h as axisTitleFollowsLabels,w as axisTitleTextLines,f as isLabelRelativeTitleOffset,g as validateAxisLabelFlushThreshold,c as validateAxisTextPlacement};

package/src/grammar/bin2d.js

@@ -11,7 +11,7 @@ const MAX_CELLS = 1_000_000;
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "x", "y", "bins", "extent", "includeEmpty", "members", "as",
-  "resolved"
+  "resolved", "assignment"
 ]);
 const AXIS_KEYS = Object.freeze(["x", "y"]);
 const FIELD_KEYS = Object.freeze(["x0", "x1", "y0", "y1", "count", "members"]);
@@ -180,6 +180,11 @@ export function validateBin2DTransform(transform) {
   }
   requireField(transform.x, "2D bin x field");
   requireField(transform.y, "2D bin y field");
+  if (transform.assignment !== undefined && transform.assignment !== "step") {
+    throw new TypeError(
+      'Stored 2D bin assignment must be "step" or omitted.'
+    );
+  }
   validateBins(transform.bins);
   validateRequestedExtent(transform.extent);
   if (typeof transform.includeEmpty !== "boolean") {
@@ -201,10 +206,16 @@ export function normalizeBin2DTransform({
   y,
   bins,
   extent,
+  assignment = "edges",
   includeEmpty = false,
   members = false,
   as
 } = {}) {
+  if (assignment !== "edges" && assignment !== "step") {
+    throw new TypeError(
+      '2D bin assignment must be "edges" or "step".'
+    );
+  }
   const normalizedBins = normalizeBins(bins);
   const transform = {
     type: "bin2d",
@@ -214,7 +225,8 @@ export function normalizeBin2DTransform({
     extent: normalizeRequestedExtent(extent),
     includeEmpty,
     members,
-    as: normalizeOutputFields(id, as, members)
+    as: normalizeOutputFields(id, as, members),
+    ...(assignment === "step" ? { assignment } : {})
   };
   validateBin2DTransform(transform);
   return cloneAndFreeze(transform);
@@ -266,6 +278,20 @@ function findBinIndex(value, edges) {
   return low;
 }
 
+function findStepBinIndex(value, extent, count) {
+  if (count === 1 || value === extent[1]) return count - 1;
+  const [minimum, maximum] = extent;
+  const span = maximum - minimum;
+  const step = Number.isFinite(span)
+    ? span / count
+    : maximum / count - minimum / count;
+  const distance = value - minimum;
+  const position = Number.isFinite(distance)
+    ? distance / step
+    : value / step - minimum / step;
+  return Math.max(0, Math.min(count - 1, Math.floor(1e-14 + position)));
+}
+
 export function deriveBin2DRows(rows, transform) {
   if (!Array.isArray(rows)) {
     throw new TypeError("2D bin source rows must be an array.");
@@ -304,8 +330,12 @@ export function deriveBin2DRows(rows, transform) {
     () => []
   );
   for (const item of eligible) {
-    const xIndex = findBinIndex(item.row[transform.x], edges.x);
-    const yIndex = findBinIndex(item.row[transform.y], edges.y);
+    const xIndex = transform.assignment === "step"
+      ? findStepBinIndex(item.row[transform.x], extent.x, transform.bins.x)
+      : findBinIndex(item.row[transform.x], edges.x);
+    const yIndex = transform.assignment === "step"
+      ? findStepBinIndex(item.row[transform.y], extent.y, transform.bins.y)
+      : findBinIndex(item.row[transform.y], edges.y);
     buckets[yIndex * transform.bins.x + xIndex].push(item.index);
   }
   const values = [];
@@ -340,3 +370,10 @@ export function requestedBin2DTransform(transform) {
   const { resolved: _resolved, ...requested } = transform;
   return cloneAndFreeze(requested);
 }
+
+// Preserve caller-authored aliases; only the canonical generated count field
+// receives a human-readable title when guide creation is deferred.
+export function inferBin2DFieldTitle(transform, id, field) {
+  return transform?.type === 'bin2d' && transform.as.count === field &&
+    normalizeOutputFields(id, undefined, false).count === field ? 'Count' : field;
+}