ggaction 0.0.24 → 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";
@@ -27,7 +28,7 @@ const OPTIONS = Object.freeze([
   "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`);
@@ -251,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
     });
@@ -267,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,4 @@
+import { normalizeCompositionShares } from "./compositionScales.js";
 import { normalizeFacetGap } from "./facetGap.js";
 import { normalizeFacetAxes } from "./facetAxisPolicy.js";
 import { isOwned, isPlainObject } from "./immutable.js";
@@ -9,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();
@@ -248,7 +254,7 @@ function validateLayout(compositionSpec) {
   } 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)) {
@@ -284,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) {
@@ -317,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/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/bin2d.js

@@ -370,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;
+}

package/src/grammar/colorSizeLegend.js

@@ -1,12 +1,15 @@
 import {sameOrderedValues,validateOptionObject,validateUnitInterval,validateNonNegativeFinite,validateNonEmptyString} from '../core/validation.js';
-import {isContinuousColorScaleType} from './scales/types.js';
+import {isContinuousColorScaleType,isDiscretizedColorScaleType} from './scales/types.js';
 import {isContinuousSizeScaleType} from './scales/size.js';
 
-export function isColorSizeChannels(channels) {
- return Array.isArray(channels)&&channels.length===2&&channels.includes('color')&&channels.includes('size');
+export function isColorSizeChannels(channels,combine='color-size') {
+ return Array.isArray(channels)&&(combine==='color-size-shape'
+  ? channels.length===3&&channels.includes('shape')&&channels.includes('size')&&['color','stroke'].some(c=>channels.includes(c))
+  : channels.length===2&&channels.includes('color')&&channels.includes('size'));
 }
 
-export function resolveColorSizeMapping({layer,scales,pointConfig,coordinate}) {
+export function resolveColorSizeMapping({layer,scales,pointConfig,coordinate,combine='color-size',channels}) {
+ if(combine==='color-size-shape')return resolveColorSizeShapeMapping({layer,scales,coordinate,channels});
  const color=layer?.encoding?.color,size=layer?.encoding?.size;
  const colorScale=scales[color?.scale],sizeScale=scales[size?.scale];
  if(layer?.mark?.type!=='point'||coordinate?.type!=='cartesian'||
@@ -26,7 +29,20 @@ export function resolveColorSizeMapping({layer,scales,pointConfig,coordinate}) {
  return {target:layer.id,field:color.field,fieldType:'quantitative',colorScale:color.scale,sizeScale:size.scale,domain};
 }
 
-export function normalizeColorSizeSymbol(value,previous) {
+export function normalizeColorSizeSymbol(value,previous,mapping) {
+ if(mapping?.combine==='color-size-shape') {
+  if(value===undefined)return {...(previous??{type:'point'})};
+  if(value==='auto')return {type:'point'};
+  validateOptionObject(value,['type','fill','stroke','strokeWidth','opacity'],'Color-size-shape symbol');
+  if(value.type!==undefined&&value.type!=='point')throw new Error('Combined symbols require type point.');
+  const symbol={type:'point',...previous,...value};
+  const mapped=mapping.colorChannel==='stroke'?'stroke':'fill';
+  if(Object.hasOwn(symbol,mapped))throw new Error(`Combined symbols cannot override mapped ${mapped}.`);
+  for(const key of ['fill','stroke'])if(symbol[key]!==undefined)validateNonEmptyString(symbol[key],`Combined symbol ${key}`);
+  if(symbol.strokeWidth!==undefined)validateNonNegativeFinite(symbol.strokeWidth,'Combined symbol strokeWidth');
+  if(symbol.opacity!==undefined)validateUnitInterval(symbol.opacity,'Combined symbol opacity');
+  return symbol;
+ }
  if(value===undefined)return {...(previous??{type:'point',strokeWidth:0,opacity:1})};
  if(value==='auto')return {type:'point',strokeWidth:0,opacity:1};
  validateOptionObject(value,['type','stroke','strokeWidth','opacity'],'Color-size symbol');
@@ -37,3 +53,38 @@ export function normalizeColorSizeSymbol(value,previous) {
  validateUnitInterval(symbol.opacity,'Color-size symbol opacity');
  return symbol;
 }
+
+function resolveColorSizeShapeMapping({layer,scales,coordinate,channels}) {
+ const hues=channels===undefined?['color','stroke'].filter(c=>layer?.encoding?.[c]?.scale!==undefined)
+  :channels.filter(c=>['color','stroke'].includes(c));
+ if(hues.length!==1)throw new Error('Color-size-shape requires one color or stroke channel; select channels explicitly.');
+ const colorChannel=hues[0],hue=layer?.encoding?.[colorChannel],size=layer?.encoding?.size,shape=layer?.encoding?.shape;
+ const colorScale=scales[hue?.scale],sizeScale=scales[size?.scale],shapeScale=scales[shape?.scale];
+ if(layer?.mark?.type!=='point'||coordinate?.type!=='cartesian'||
+   hue?.fieldType!=='quantitative'||size?.fieldType!=='quantitative'||
+   !['nominal','ordinal'].includes(shape?.fieldType)||typeof hue.field!=='string'||
+   [size,shape].some(e=>e.field!==hue.field||e.data!==hue.data||e.aggregate!==hue.aggregate)||
+   !isDiscretizedColorScaleType(colorScale?.type)||!isDiscretizedColorScaleType(sizeScale?.type)||shapeScale?.type!=='ordinal') {
+  throw new Error('Color-size-shape requires one Cartesian point owner with the same field and grain on interval hue/size and ordinal shape.');
+ }
+ if(!sameOrderedValues(colorScale.thresholds,sizeScale.thresholds))throw new Error('Combined interval scales require identical threshold boundaries.');
+ return {target:layer.id,field:hue.field,fieldType:'quantitative',colorScale:hue.scale,sizeScale:size.scale,
+  shapeScale:shape.scale,colorChannel,domain:[...colorScale.domain]};
+}
+
+export function validateColorSizeShapeSamples(sampling,scale) {
+ const cuts=scale.thresholds;
+ if(sampling.mode!=='values'||sampling.values.length!==cuts.length+1||sampling.values.some((value,index)=>
+  !Number.isFinite(value)||index>0&&value<cuts[index-1]||index<cuts.length&&value>=cuts[index])) {
+  throw new Error('Color-size-shape requires one explicit finite value in each ordered threshold interval.');
+ }
+ return [...sampling.values];
+}
+
+export function colorSizeScaleIds(config) {
+ return [config.colorScale,config.sizeScale,...(config.shapeScale===undefined?[]:[config.shapeScale])];
+}
+
+export function colorSizeChannels(config) {
+ return [config.colorChannel??'color','size',...(config.shapeScale===undefined?[]:['shape'])];
+}

package/src/grammar/displayLabels.js

@@ -91,3 +91,13 @@ export function resolveDisplayLabelColor(value, map, fallback) {
   const entry = map?.find(entry => sameDisplayLabelValue(entry.value, value));
   return entry?.color ?? fallback;
 }
+
+export function normalizeLegendDisplayLabelMap(descriptor, map, scaleType) {
+  if (["size", "colorSize"].includes(descriptor.kind) && descriptor.family === "sampled") {
+    return normalizeNumericDisplayLabelMap(map, "editLegendBlock labelMap");
+  }
+  if (descriptor.family !== "categorical" && !(descriptor.family === "discrete-size" && scaleType === "ordinal")) {
+    throw new Error("editLegendBlock labelMap requires a categorical or continuous size block.");
+  }
+  return normalizeDisplayLabelMap(map, "editLegendBlock labelMap");
+}

package/src/grammar/facetHeaders.js

@@ -1 +1 @@
-import{validateOptionObject as o,validateNonEmptyString as r,validatePositiveFinite as a,validateNonNegativeFinite as c}from"../core/validation.js";import{resolveRotation as s}from"./rotation.js";const f=Object.freeze(["text","fontSize","fontFamily","fontWeight","color","offset","align","rotation","alongOffset"]);function d(e){if(o(e,f,"Facet header title",{allowEmpty:!1}),r(e.text,"Facet header title text"),/[\r\n\u2028\u2029]/u.test(e.text))throw new TypeError("Facet header title text must be one line.");e.fontSize!==void 0&&a(e.fontSize,"Facet header title fontSize");for(const t of["fontFamily","color"])e[t]!==void 0&&r(e[t],`Facet header title ${t}`);if(e.fontWeight!==void 0&&!(typeof e.fontWeight=="string"&&e.fontWeight.length>0||Number.isFinite(e.fontWeight)))throw new TypeError("Facet header title fontWeight must be a non-empty string or finite number.");if(e.offset!==void 0&&c(e.offset,"Facet header title offset"),e.align!==void 0&&!["start","center","end"].includes(e.align))throw new TypeError("Facet header title align must be start, center, or end.");for(const t of["rotation","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Facet header title ${t} must contain finite normalized radians or coordinates.`)}function h(e,t){if(t===!1)return;o(t,f,"Facet header title",{allowEmpty:!1});for(const i of Object.keys(t))if(t[i]===void 0)throw new TypeError(`Facet header title ${i} must not be undefined.`);const n={...e,...t};return Object.hasOwn(t,"rotation")&&(n.rotation=s(t.rotation,"Facet header title rotation")),d(n),n}function w(e){for(const t of e.common===void 0?[e]:[e.common,e.row,e.column]){if(t!==void 0&&Object.hasOwn(t,"anchor")&&!["plot","content","view"].includes(t.anchor))throw new TypeError("Facet header anchor must be plot, content, or view.");if(t?.rotation!==void 0&&!Number.isFinite(t.rotation))throw new TypeError("Facet header rotation must contain finite normalized radians.");t?.title!==void 0&&d(t.title)}if(e.title!==void 0||e.common?.title!==void 0)throw new TypeError("Facet header title requires an explicit row or column role.");if(e.mode!=="roles"&&(e.row?.title!==void 0||e.column?.title!==void 0))throw new TypeError("Facet field titles require role header mode.")}export{h as normalizeFacetHeaderTitle,w as validateFacetHeaderRotations,d as validateFacetHeaderTitle};
+import{validateOptionObject as o,validateNonEmptyString as r,validatePositiveFinite as a,validateNonNegativeFinite as c}from"../core/validation.js";import{resolveRotation as s}from"./rotation.js";const f=Object.freeze(["text","fontSize","fontFamily","fontWeight","color","offset","align","rotation","alongOffset"]);function d(e){if(o(e,f,"Facet header title",{allowEmpty:!1}),r(e.text,"Facet header title text"),/[\u2028\u2029]/u.test(e.text))throw new TypeError("Facet header title line breaks must use LF, CR or CRLF.");e.fontSize!==void 0&&a(e.fontSize,"Facet header title fontSize");for(const t of["fontFamily","color"])e[t]!==void 0&&r(e[t],`Facet header title ${t}`);if(e.fontWeight!==void 0&&!(typeof e.fontWeight=="string"&&e.fontWeight.length>0||Number.isFinite(e.fontWeight)))throw new TypeError("Facet header title fontWeight must be a non-empty string or finite number.");if(e.offset!==void 0&&c(e.offset,"Facet header title offset"),e.align!==void 0&&!["start","center","end"].includes(e.align))throw new TypeError("Facet header title align must be start, center, or end.");for(const t of["rotation","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Facet header title ${t} must contain finite normalized radians or coordinates.`)}function h(e,t){if(t===!1)return;o(t,f,"Facet header title",{allowEmpty:!1});for(const i of Object.keys(t))if(t[i]===void 0)throw new TypeError(`Facet header title ${i} must not be undefined.`);const n={...e,...t};return Object.hasOwn(t,"rotation")&&(n.rotation=s(t.rotation,"Facet header title rotation")),d(n),n}function w(e){for(const t of e.common===void 0?[e]:[e.common,e.row,e.column]){if(t!==void 0&&Object.hasOwn(t,"anchor")&&!["plot","content","view"].includes(t.anchor))throw new TypeError("Facet header anchor must be plot, content, or view.");if(t?.rotation!==void 0&&!Number.isFinite(t.rotation))throw new TypeError("Facet header rotation must contain finite normalized radians.");t?.title!==void 0&&d(t.title)}if(e.title!==void 0||e.common?.title!==void 0)throw new TypeError("Facet header title requires an explicit row or column role.");if(e.mode!=="roles"&&(e.row?.title!==void 0||e.column?.title!==void 0))throw new TypeError("Facet field titles require role header mode.")}export{h as normalizeFacetHeaderTitle,w as validateFacetHeaderRotations,d as validateFacetHeaderTitle};

package/src/grammar/facets/dependencies.js

@@ -115,9 +115,16 @@ export function resolveFacetFamily(semanticSpec) {
       semanticSpec.layers.length === 0) {
     throw new Error("facet requires at least one materializable layer.");
   }
-  const primary = semanticSpec.layers.filter(layer =>
-    !(layer.mark?.type === "text" && layer.source !== undefined)
-  );
+  // Literal positioned notes decorate a chart rather than define its data
+  // coordinate family. Keep validating/materializing them, but do not confuse
+  // a plot-space Cartesian annotation with a second Cartesian chart in a polar
+  // or parallel facet. A text-only chart still supplies its own primary layer.
+  const annotations = semanticSpec.layers.filter(layer => layer.mark?.type === 'text' &&
+    ['x', 'y', 'text'].every(channel => Object.hasOwn(layer.encoding?.[channel] ?? {}, 'datum')));
+  const dataLayers = semanticSpec.layers.filter(layer =>
+    !(layer.mark?.type === 'text' && layer.source !== undefined) && !annotations.includes(layer));
+  const primary = dataLayers.length ? dataLayers : annotations;
+  for (const note of annotations) classifyPrimaryLayer(semanticSpec, note);
   if (primary.length === 0) {
     throw new Error("facet requires at least one primary materializable layer.");
   }

package/src/grammar/facets/guides.js

@@ -1,3 +1,4 @@
+import {colorSizeScaleIds} from "../colorSizeLegend.js";
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 
 
@@ -167,7 +168,7 @@ function requireLegendChildren(children) {
 }
 
 function scaleIds(config, kind) {
-  const ids = kind === "colorSize" ? [config.colorScale, config.sizeScale]
+  const ids = kind === "colorSize" ? colorSizeScaleIds(config)
     : config.scales ?? (config.scale === undefined ? [] : [config.scale]);
   if (!Array.isArray(ids) || ids.length === 0 || !ids.every(id =>
     typeof id === "string" && id.length > 0