ggaction 0.0.17 → 0.0.19

package/src/grammar/displayLabels.js

@@ -1,4 +1,5 @@
 import { isPlainObject } from "../core/immutable.js";
+import { validateNonEmptyString } from "../core/validation.js";
 
 const ENTRY_KEYS = Object.freeze(["value", "label"]);
 
@@ -43,6 +44,14 @@ export function normalizeDisplayLabelMap(value, label = "labelMap") {
   return Object.freeze(normalized);
 }
 
+export function normalizeNumericDisplayLabelMap(value, label = "labelMap") {
+  const map = normalizeDisplayLabelMap(value, label);
+  if (map.some(entry => typeof entry.value !== "number" || !Number.isFinite(entry.value))) {
+    throw new TypeError(`${label} values must be finite numbers.`);
+  }
+  return map;
+}
+
 export function resolveDisplayLabel(value, map, fallback) {
   if (map !== undefined) {
     for (const entry of map) {
@@ -55,3 +64,30 @@ export function resolveDisplayLabel(value, map, fallback) {
   }
   return resolved;
 }
+
+
+export function normalizeDisplayColorMap(value, label = "colorMap") {
+  if (!Array.isArray(value)) throw new TypeError(`${label} must be an array.`);
+  const normalized = [];
+  for (const [index, entry] of value.entries()) {
+    if (!isPlainObject(entry)) throw new TypeError(`${label}[${index}] must be a plain object.`);
+    if (Reflect.ownKeys(entry).length !== 2 ||
+        !Object.hasOwn(entry, "value") || !Object.hasOwn(entry, "color")) {
+      throw new Error(`${label}[${index}] must contain exactly value and color.`);
+    }
+    if (!isDisplayLabelValue(entry.value)) {
+      throw new TypeError(`${label}[${index}].value must be a string, boolean, null, or finite number.`);
+    }
+    validateNonEmptyString(entry.color, `${label}[${index}].color`);
+    if (normalized.some(previous => sameDisplayLabelValue(previous.value, entry.value))) {
+      throw new Error(`${label} contains a duplicate typed value.`);
+    }
+    normalized.push(Object.freeze({ value: entry.value, color: entry.color }));
+  }
+  return Object.freeze(normalized);
+}
+
+export function resolveDisplayLabelColor(value, map, fallback) {
+  const entry = map?.find(entry => sameDisplayLabelValue(entry.value, value));
+  return entry?.color ?? fallback;
+}

package/src/grammar/ecdf.js

@@ -1,3 +1,5 @@
+import { requireStringValue as nonEmptyString } from "../core/validation.js";
+import { isGroupValue as groupValue } from "./transformKeys.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { stableDecimal } from "./numeric.js";
 
@@ -6,11 +8,6 @@ const TRANSFORM_KEYS = Object.freeze([
 ]);
 const OUTPUT_KEYS = Object.freeze(["value", "cumulative", "probability"]);
 
-function nonEmptyString(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-}
 
 function normalizeGroupBy(groupBy) {
   const fields = groupBy === undefined
@@ -101,10 +98,6 @@ export function normalizeECDFTransform({ field, groupBy, weight, missing = "drop
   return cloneAndFreeze(transform);
 }
 
-function groupValue(value) {
-  return typeof value === "string" || typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value));
-}
 
 function rejectOrDrop(transform, index, reason) {
   if (transform.missing === "error") {

package/src/grammar/facets/dependencies.js

@@ -6,12 +6,13 @@ import { resolveRectMode } from "../rects.js";
 import { resolveRuleMode } from "../rules.js";
 
 const CARTESIAN_MARKS = new Set([
-  "point", "line", "area", "bar", "rule", "tick", "rect"
+  "point", "line", "area", "bar", "rule", "tick", "rect", "text"
 ]);
 const FACET_BAR_GRAINS = new Set([
   BAR_GRAINS.histogram,
   BAR_GRAINS.aggregate,
-  BAR_GRAINS.ranged
+  BAR_GRAINS.ranged,
+  BAR_GRAINS.centered
 ]);
 const ORDINARY_SCALE_CHANNELS = Object.freeze([
   ["x", "x"], ["y", "y"], ["xOffset", "xOffset"], ["yOffset", "yOffset"],
@@ -66,6 +67,9 @@ function classifyPrimaryLayer(semanticSpec, layer) {
       `facet requires bar mark "${layer.id}" to be a complete histogram, aggregate, or ranged bar.`
     );
   }
+  if (type === "text" && layer.encoding?.text === undefined) {
+    throw new Error(`Facet text layer "${layer.id}" requires a text encoding.`);
+  }
   const complete = (
     layer.encoding?.x?.scale !== undefined &&
     layer.encoding?.y?.scale !== undefined

package/src/grammar/facets/guides.js

@@ -3,13 +3,15 @@ import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 const LEGEND_FAMILIES = Object.freeze({
   series: "categorical",
   color: "categorical",
+  colorSize: "color-size",
   stroke: "categorical",
   gradient: "gradient",
   interval: "discretized",
   strokeGradient: "gradient",
   strokeInterval: "discretized",
   size: "size",
-  opacity: "opacity"
+  opacity: "opacity",
+  strokeWidth: "stroke-width"
 });
 
 function requirePlacements(placements) {
@@ -72,25 +74,34 @@ function translatedBounds(placement, bounds, channel) {
   };
 }
 
+export function resolveFacetOuterSides({ placements } = {}) {
+  const cells = requirePlacements(placements);
+  const edges = { top: new Map(), bottom: new Map(), left: new Map(), right: new Map() };
+  for (const cell of cells) {
+    for (const [side, key, coordinate, better] of [
+      ["top", cell.column, "row", (a, b) => a < b],
+      ["bottom", cell.column, "row", (a, b) => a > b],
+      ["left", cell.row, "column", (a, b) => a < b],
+      ["right", cell.row, "column", (a, b) => a > b]
+    ]) {
+      const previous = edges[side].get(key);
+      if (previous === undefined || better(cell[coordinate], previous[coordinate])) edges[side].set(key, cell);
+    }
+  }
+  return cloneAndFreeze(Object.fromEntries(Object.entries(edges).map(([side, owners]) => {
+    const ids = new Set([...owners.values()].map(cell => cell.id));
+    return [side, cells.filter(cell => ids.has(cell.id)).map(cell => cell.id)];
+  })));
+}
+
 export function resolveFacetOuterAxes({ placements, axisBounds = {} } = {}) {
   const cells = requirePlacements(placements);
   if (!isPlainObject(axisBounds)) {
     throw new TypeError("Facet axisBounds must be a plain object.");
   }
-  const bottomByColumn = new Map();
-  const leftByRow = new Map();
-  for (const cell of cells) {
-    const bottom = bottomByColumn.get(cell.column);
-    if (bottom === undefined || cell.row > bottom.row) {
-      bottomByColumn.set(cell.column, cell);
-    }
-    const left = leftByRow.get(cell.row);
-    if (left === undefined || cell.column < left.column) {
-      leftByRow.set(cell.row, cell);
-    }
-  }
-  const xOwners = new Set([...bottomByColumn.values()].map(cell => cell.id));
-  const yOwners = new Set([...leftByRow.values()].map(cell => cell.id));
+  const sides = resolveFacetOuterSides({ placements: cells });
+  const xOwners = new Set(sides.bottom);
+  const yOwners = new Set(sides.left);
   return cloneAndFreeze({
     x: cells.filter(cell => xOwners.has(cell.id)).map(cell => cell.id),
     y: cells.filter(cell => yOwners.has(cell.id)).map(cell => cell.id),
@@ -129,7 +140,7 @@ function comparableConfig(config) {
   return stableValue(rest);
 }
 
-function sameValue(left, right) {
+export function sameFacetGuideValue(left, right) {
   return JSON.stringify(stableValue(left)) === JSON.stringify(stableValue(right));
 }
 
@@ -152,12 +163,13 @@ function requireLegendChildren(children) {
   });
 }
 
-function scaleIds(config) {
-  const ids = config.scales ?? (config.scale === undefined ? [] : [config.scale]);
+function scaleIds(config, kind) {
+  const ids = kind === "colorSize" ? [config.colorScale, config.sizeScale]
+    : config.scales ?? (config.scale === undefined ? [] : [config.scale]);
   if (!Array.isArray(ids) || ids.length === 0 || !ids.every(id =>
     typeof id === "string" && id.length > 0
   )) {
-    throw new Error(`Shared ${config.kind} legend requires resolved scale ids.`);
+    throw new Error(`Shared ${kind} legend requires resolved scale ids.`);
   }
   return ids;
 }
@@ -165,6 +177,11 @@ function scaleIds(config) {
 export function resolveSharedFacetLegends(children) {
   const normalized = requireLegendChildren(children);
   const first = normalized[0];
+  for (const child of normalized.slice(1)) {
+    if (!sameFacetGuideValue(first.guideConfigs.legendGroups, child.guideConfigs.legendGroups)) {
+      throw new Error(`Facet child "${child.id}" has incompatible legend group placement.`);
+    }
+  }
   const kinds = Object.keys(first.legends);
   const entries = kinds.map(kind => {
     const family = LEGEND_FAMILIES[kind];
@@ -178,7 +195,7 @@ export function resolveSharedFacetLegends(children) {
     ) {
       throw new Error(`Facet child "${first.id}" has invalid ${kind} legend config.`);
     }
-    const scales = scaleIds(config);
+    const scales = scaleIds(config, kind);
     const resolvedScales = Object.fromEntries(scales.map(id => {
       const scale = first.resolvedScales[id];
       if (!isPlainObject(scale)) {
@@ -190,14 +207,14 @@ export function resolveSharedFacetLegends(children) {
       const candidate = child.legends[kind];
       if (
         !isPlainObject(candidate) ||
-        !sameValue(comparableConfig(config), comparableConfig(candidate))
+        !sameFacetGuideValue(comparableConfig(config), comparableConfig(candidate))
       ) {
         throw new Error(
           `Facet child "${child.id}" has an incompatible ${kind} legend config.`
         );
       }
       for (const id of scales) {
-        if (!sameValue(resolvedScales[id], child.resolvedScales[id])) {
+        if (!sameFacetGuideValue(resolvedScales[id], child.resolvedScales[id])) {
           throw new Error(
             `Facet child "${child.id}" has an incompatible resolved legend scale "${id}".`
           );
@@ -208,7 +225,7 @@ export function resolveSharedFacetLegends(children) {
   });
   for (const child of normalized.slice(1)) {
     const childKinds = Object.keys(child.legends);
-    if (!sameValue([...kinds].sort(), [...childKinds].sort())) {
+    if (!sameFacetGuideValue([...kinds].sort(), [...childKinds].sort())) {
       throw new Error(`Facet child "${child.id}" has incompatible legend kinds.`);
     }
   }
@@ -229,7 +246,7 @@ export function planFacetGuideOwnership({
   if (!["each", "outer"].includes(axes)) {
     throw new Error("Facet axes must be each or outer.");
   }
-  if (![false, "shared"].includes(legend)) {
+  if (![false, "shared"].includes(legend) && !isPlainObject(legend)) {
     throw new Error("Facet legend must be false or shared.");
   }
   const byId = new Map(children.map(child => [child.id, child]));
@@ -237,23 +254,34 @@ export function planFacetGuideOwnership({
     throw new Error("Facet guide child ids must match occupied placements exactly.");
   }
   const outer = resolveFacetOuterAxes({ placements: cells });
-  if (legend === "shared" && !isPlainObject(sharedLegends)) {
+  const sides = resolveFacetOuterSides({ placements: cells });
+  if (legend !== false && !isPlainObject(sharedLegends)) {
     throw new Error("Shared facet legend ownership requires a compatibility plan.");
   }
   return cloneAndFreeze({
     children: Object.fromEntries(cells.map(cell => {
       const descriptor = byId.get(cell.id);
       const presentAxes = descriptor.axes ?? [];
-      const keepAxes = axes === "each"
-        ? presentAxes
-        : presentAxes.filter(channel => outer.children[cell.id][channel]);
+      const records = descriptor.axisOwners;
+      const removed = {};
+      const keepAxes = axes === "each" ? presentAxes : records === undefined
+        ? presentAxes.filter(channel => outer.children[cell.id][channel])
+        : presentAxes.filter(id => {
+          const owner = records.find(owner => owner.id === id);
+          if (owner === undefined) throw new Error("Facet axis descriptors must identify every retained owner.");
+          const components = Object.entries(owner.components);
+          const remove = components.filter(([, side]) => !sides[side]?.includes(cell.id)).map(([component]) => component);
+          if (remove.length > 0 && remove.length < components.length) removed[id] = remove;
+          return remove.length < components.length;
+        });
       return [cell.id, {
         keepAxes,
         removeAxes: presentAxes.filter(channel => !keepAxes.includes(channel)),
-        removeLegends: legend === "shared" ? descriptor.legendKinds ?? [] : []
+        ...(records === undefined ? {} : { removeAxisComponents: removed }),
+        removeLegends: legend !== false ? descriptor.legendKinds ?? [] : []
       }];
     })),
-    parent: legend === "shared"
+    parent: legend !== false
       ? { legends: sharedLegends.entries, promoteFrom: sharedLegends.source }
       : { legends: [] }
   });

package/src/grammar/facets/index.js

@@ -6,7 +6,6 @@ import {
 } from "../../core/validation.js";
 import { planFacetDependencies, resolveFacetFamily } from "./dependencies.js";
 import { readNominalField } from "../scales/index.js";
-const MAX_FACET_CHILDREN = 100;
 
 function requireFacetField(field, label = "facet") {
   if (typeof field !== "string" || field.length === 0) {
@@ -100,8 +99,7 @@ export function resolveFacetDefinition(semanticSpec, options = {}) {
   const values = resolveValues(observed, options.values);
   validateGeneratedItemLimit(
     values.length,
-    "Facet child count",
-    MAX_FACET_CHILDREN
+    "Facet child count"
   );
   validateWorkLimit(
     dataset.values.length * values.length,
@@ -175,8 +173,7 @@ export function resolveFacetGridDefinition(semanticSpec, options = {}) {
   }
   validateGeneratedItemLimit(
     selected.length,
-    "Facet grid child count",
-    MAX_FACET_CHILDREN
+    "Facet grid child count"
   );
   validateWorkLimit(
     dataset.values.length * selected.length,

package/src/grammar/facets/legendIntent.js

@@ -0,0 +1,65 @@
+import { isPlainObject } from "../../core/immutable.js";
+import { validateOptionObject, validateNonEmptyString } from "../../core/validation.js";
+import { validateUserId } from "../../core/identifiers.js";
+import { LEGEND_CONFIG_KINDS, LEGEND_POSITIONS } from "../../core/vocabulary.js";
+import { describeLegendBlock } from "../legendBlocks.js";
+import { validateLegendGroupState } from "../legendGroups.js";
+import { resolveSharedFacetLegends, sameFacetGuideValue as same } from "./guides.js";
+
+const CONFIG_KEYS = Object.freeze([
+  "kind", "target", "channels", "scales", "scale", "field", "fieldType", "domain", "title", "titleVisible",
+  "inferredTitle", "inferredSymbol", "inferredStrokeWidth", "inferredOffset", "position", "align", "offset", "direction", "columns",
+  "titlePosition", "symbol", "labels", "titleStyle", "itemGap", "layout", "overflow", "border", "gradient",
+  "count", "sampling", "representation", "gradientDirection", "inheritAppearance", "inheritPosition", "blockOverrides",
+  "combine", "sizeAreas", "clipHeight"
+]);
+
+export function isAuthoredFacetLegend(value) {
+  return isPlainObject(value) && value.type === "authored-legend";
+}
+
+export function validateAuthoredFacetLegend(program, intent) {
+  validateOptionObject(intent, ["type", "blocks", "groups"], "Stored parent legend");
+  if (!isAuthoredFacetLegend(intent) || Object.keys(intent).length !== 3 ||
+      !isPlainObject(intent.blocks) || Object.keys(intent.blocks).length === 0 || !isPlainObject(intent.groups)) {
+    throw new Error("Stored parent legend requires its closed authored block intent.");
+  }
+  validateLegendGroupState(intent.groups);
+  const configs = {};
+  for (const [kind, block] of Object.entries(intent.blocks)) {
+    if (!LEGEND_CONFIG_KINDS.includes(kind)) throw new Error("Stored parent legend has an unknown block kind.");
+    validateOptionObject(block, ["config", "guide"], "Stored parent legend block");
+    validateOptionObject(block.config, kind === "colorSize" ? [...CONFIG_KEYS, "colorScale", "sizeScale"] : CONFIG_KEYS, "Stored parent legend config");
+    const config = block.config;
+    validateUserId(config.target, "Parent legend target");
+    if (!LEGEND_POSITIONS.includes(config.position)) throw new Error("Stored parent legend requires a native position.");
+    for (const flag of ["inferredTitle", "inferredSymbol", "inferredStrokeWidth", "inferredOffset", "titleVisible", "inheritAppearance", "inheritPosition"]) {
+      if (config[flag] !== undefined && typeof config[flag] !== "boolean") throw new Error(`Stored parent legend ${flag} must be boolean.`);
+    }
+    const descriptor = describeLegendBlock(program, kind, config);
+    if (block.guide !== undefined) {
+      validateOptionObject(block.guide, kind === "colorSize" ? ["colorScale", "sizeScale", "title"]
+        : ["scale", "scales", "channels", "title", "order"], "Stored parent legend meaning");
+      if (kind === "colorSize" && (block.guide.colorScale !== config.colorScale || block.guide.sizeScale !== config.sizeScale)) {
+        throw new Error("Stored parent color-size meaning must match both block scale bindings.");
+      }
+      if (block.guide.title !== undefined) validateNonEmptyString(block.guide.title, "Parent legend title");
+      if (block.guide.channels !== undefined && !same([...block.guide.channels].sort(), descriptor.channels)) {
+        throw new Error("Stored parent legend meaning must match its block channels.");
+      }
+      if (block.guide.scale !== undefined && block.guide.scale !== descriptor.scaleIds[0] ||
+          block.guide.scales !== undefined && !same(block.guide.scales, descriptor.scaleIds)) {
+        throw new Error("Stored parent legend meaning must match its block scale binding.");
+      }
+    }
+    if (!same(config, program.guideConfigs.legend?.[kind])) throw new Error("Parent legend materialization must match its authored owner.");
+    configs[kind] = config;
+  }
+  if (!same(Object.keys(configs).sort(), Object.keys(program.guideConfigs.legend ?? {}).sort()) ||
+      !same(intent.groups, program.guideConfigs.legendGroups ?? {})) {
+    throw new Error("Parent legend materialization must contain exactly its authored blocks and groups.");
+  }
+  resolveSharedFacetLegends(program.compositionSpec.children.map(id => ({ id,
+    guideConfigs: { legend: configs, legendGroups: intent.groups }, resolvedScales: program.children[id].resolvedScales })));
+  return intent;
+}

package/src/grammar/fold.js

@@ -1,3 +1,5 @@
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 
 const TRANSFORM_KEYS = Object.freeze(["type", "fields", "as"]);
@@ -5,19 +7,7 @@ const AS_KEYS = Object.freeze(["key", "value"]);
 const MAX_FIELDS = 64;
 const MAX_OUTPUT_ROWS = 10_000;
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown ${label} property "${unknown}".`);
-  }
-}
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function normalizeAs(value) {
   const requested = value ?? {};

package/src/grammar/gradientProfile.js

@@ -1,3 +1,4 @@
+import { requireStringValue as requireField } from "../core/validation.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import {
   deriveKernelDensity,
@@ -23,12 +24,6 @@ const TRANSFORM_KEYS = [
 ];
 const OUTPUT_KEYS = Object.keys(GRADIENT_PROFILE_FIELDS);
 
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
 
 function validatePair(value, label) {
   if (

package/src/grammar/guideDash.js

@@ -0,0 +1 @@
+import{isPlainObject as i}from"../core/immutable.js";import{validateGeneratedItemLimit as o}from"../core/validation.js";function n(e,s="Guide strokeDash"){if(!Array.isArray(e)||e.length%2!==0||!e.every(r=>Number.isFinite(r)&&r>=0))throw new TypeError(`${s} must be an even-length array of non-negative finite numbers.`);return o(e.length,s),e}function u(e,{reset:s=!0}={}){if(e==="auto"&&s)return;if(!Array.isArray(e))throw new TypeError("Guide strokeDashMap must be an array.");o(e.length,"Guide strokeDashMap count");const r=new Set,a=e.map(t=>{if(!i(t)||Reflect.ownKeys(t).length!==2||!Object.hasOwn(t,"value")||!Object.hasOwn(t,"strokeDash"))throw new TypeError("Guide strokeDashMap entries must contain exactly value and strokeDash.");if(!["string","boolean"].includes(typeof t.value)&&!Number.isFinite(t.value))throw new TypeError("Guide strokeDashMap values must be strings, booleans, or finite numbers.");if(r.has(t.value))throw new Error("Guide strokeDashMap contains a duplicate typed value.");return r.add(t.value),n(t.strokeDash),Object.freeze({value:t.value,strokeDash:Object.freeze([...t.strokeDash])})});return a.length===0?void 0:Object.freeze(a)}function d(e,s){const r={...e};if(Object.hasOwn(s,"strokeDash")&&(n(s.strokeDash),r.strokeDash=[...s.strokeDash]),Object.hasOwn(s,"strokeDashMap")){const a=u(s.strokeDashMap);a===void 0?delete r.strokeDashMap:r.strokeDashMap=a}return r}function D(e,s){const r=new Map(s.strokeDashMap?.map(a=>[a.value,a.strokeDash]));return e.map(a=>r.get(a)??s.strokeDash??[])}export{u as normalizeGuideDashMap,d as patchGuideDash,D as resolveGuideDashes,n as validateGuideDash};

package/src/grammar/impute.js

@@ -1,26 +1,16 @@
+import { normalizeSortBy, validateSortBy } from "./transformKeys.js";
+import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
+import { requireStringValue as requireField } from "../core/validation.js";
 import { IMPUTE_REQUIRED_OPTIONS } from "../core/optionRequirements.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { interpolateNumber, inverseLerp } from "./numeric.js";
+import { interpolateNumber, inverseLerp, stableFiniteMean } from "./numeric.js";
 import { normalizeTemporalValue } from "./scales/fields.js";
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "fields", "groupBy", "sortBy", "method", "value", "edges", "maxGap"
 ]);
-const SORT_KEYS = Object.freeze(["field", "order"]);
 const METHODS = Object.freeze(Object.keys(IMPUTE_REQUIRED_OPTIONS));
 
-function rejectUnknownKeys(value, supported, label) {
-  const unknown = Object.keys(value).find(key => !supported.includes(key));
-  if (unknown !== undefined) throw new Error(`Unknown ${label} property "${unknown}".`);
-}
-
-function requireField(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-  return value;
-}
-
 function validateFieldList(value, label) {
   if (!Array.isArray(value) || value.length === 0 || value.some(field =>
     typeof field !== "string" || field.length === 0
@@ -35,33 +25,6 @@ function normalizeFieldList(value, { allowEmpty = false } = {}) {
   return Array.isArray(value) ? [...value] : [value];
 }
 
-function normalizeSortBy(value) {
-  if (value === undefined) return [];
-  if (!Array.isArray(value)) return value;
-  return value.map(sort => isPlainObject(sort)
-    ? { ...sort, order: sort.order ?? "ascending" }
-    : sort
-  );
-}
-
-function validateSortBy(sortBy) {
-  if (!Array.isArray(sortBy)) throw new TypeError("Impute sortBy must be an array.");
-  const fields = [];
-  sortBy.forEach((sort, index) => {
-    if (!isPlainObject(sort)) {
-      throw new TypeError(`Impute sortBy[${index}] must be a plain object.`);
-    }
-    rejectUnknownKeys(sort, SORT_KEYS, `impute sortBy[${index}]`);
-    fields.push(requireField(sort.field, `Impute sortBy[${index}].field`));
-    if (!["ascending", "descending"].includes(sort.order)) {
-      throw new Error(`Unsupported impute sort order "${sort.order}".`);
-    }
-  });
-  if (new Set(fields).size !== fields.length) {
-    throw new Error("Impute sortBy fields must be unique.");
-  }
-}
-
 function scalarType(value, label) {
   if (value === null || value === undefined) return undefined;
   if (typeof value === "string" || typeof value === "boolean") return typeof value;
@@ -94,7 +57,7 @@ export function validateImputeTransform(transform) {
   if (new Set(transform.groupBy).size !== transform.groupBy.length) {
     throw new Error("Impute groupBy fields must be unique.");
   }
-  validateSortBy(transform.sortBy);
+  validateSortBy(transform.sortBy, "Impute");
   if (!METHODS.includes(transform.method)) {
     throw new Error(`Unsupported impute method "${transform.method}".`);
   }
@@ -107,7 +70,7 @@ export function validateImputeTransform(transform) {
     scalarType(transform.value, "Impute constant value");
   } else {
     if (hasValue) throw new Error(`Impute value is not available for ${transform.method}.`);
-    if (transform.sortBy.length === 0) {
+    if (transform.method !== "mean" && transform.sortBy.length === 0) {
       throw new Error(`Impute ${transform.method} requires non-empty sortBy.`);
     }
   }
@@ -132,7 +95,7 @@ export function normalizeImputeTransform(args = {}) {
     fields: normalizeFieldList(args.fields),
     groupBy: normalizeFieldList(args.groupBy, { allowEmpty: true }),
     sortBy: normalizeSortBy(args.sortBy),
-    method: args.method,
+    method: args.method ?? "mean",
     edges: args.edges ?? "keep"
   };
   if (Object.hasOwn(args, "value")) transform.value = args.value;
@@ -212,9 +175,9 @@ function validateFieldTypes(entries, transform) {
     if (types.size > 1) {
       throw new TypeError(`Impute field "${field}" must contain one scalar type.`);
     }
-    if (transform.method === "linear" &&
+    if (["linear", "mean"].includes(transform.method) &&
       (types.size > 0 && !types.has("number"))) {
-      throw new TypeError(`Impute linear field "${field}" must contain finite numbers.`);
+      throw new TypeError(`Impute ${transform.method} field "${field}" must contain finite numbers.`);
     }
   }
 }
@@ -278,10 +241,18 @@ function setField(row, field, value) {
   });
 }
 
-function fillRun(partition, field, run, transform, positions) {
+function fillRun(partition, field, run, transform, positions, mean) {
   const [start, end] = run;
   const length = end - start + 1;
   if (transform.maxGap !== undefined && length > transform.maxGap) return;
+  if (transform.method === "mean") {
+    if (mean === undefined) {
+      if (transform.edges === "error") throw new RangeError(`Impute mean requires an observed value in field "${field}".`);
+      return;
+    }
+    for (let index = start; index <= end; index += 1) setField(partition[index].row, field, mean);
+    return;
+  }
   if (transform.method === "constant") {
     for (let index = start; index <= end; index += 1) {
       setField(partition[index].row, field, transform.value);
@@ -332,8 +303,10 @@ export function deriveImputedRows(rows, transform) {
     partition.sort((left, right) => compareEntries(left, right, transform.sortBy));
     const positions = linearPositions(partition, transform);
     for (const field of transform.fields) {
+      const observed = transform.method === "mean" ? partition.map(entry => entry.row[field]).filter(value => value !== null && value !== undefined) : [];
+      const mean = observed.length ? stableFiniteMean(observed, "Impute group mean") : undefined;
       for (const run of missingRuns(partition, field)) {
-        fillRun(partition, field, run, transform, positions);
+        fillRun(partition, field, run, transform, positions, mean);
       }
     }
   }

package/src/grammar/interval.js

@@ -1,3 +1,5 @@
+import { requireStringValue as nonEmptyString } from "../core/validation.js";
+import { isGroupValue } from "./transformKeys.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { aggregateScalarValues } from "./aggregate.js";
 import { requireFiniteResult, stableDecimal } from "./numeric.js";
@@ -21,11 +23,6 @@ const TRANSFORM_KEYS = [
 ];
 const OUTPUT_KEYS = ["center", "lower", "upper"];
 
-function nonEmptyString(value, label) {
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError(`${label} must be a non-empty string.`);
-  }
-}
 
 function validateGrouping(groupBy) {
   if (
@@ -166,10 +163,6 @@ function isMissing(value) {
     (typeof value === "number" && Number.isNaN(value));
 }
 
-function isGroupValue(value) {
-  return typeof value === "string" || typeof value === "boolean" ||
-    (typeof value === "number" && Number.isFinite(value));
-}
 
 function deriveGroup(values, transform) {
   if (transform.center === "median") {

package/src/grammar/legendBlocks.js

@@ -0,0 +1 @@
+import{LEGEND_CHANNELS as d,LEGEND_CONFIG_KINDS as h}from"../core/vocabulary.js";import{isEnumeratedSizeScaleType as u}from"./scales/size.js";function y(e,r){if(!Array.isArray(e))throw new TypeError(`${r} channels must be an array.`);if(e.length===0)throw new Error(`${r} channels must select at least one channel.`);const s=new Set;for(const t of e){if(!d.includes(t))throw new Error(`Unsupported legend channel "${t}".`);if(s.has(t))throw new Error(`${r} channels contains duplicate "${t}".`);s.add(t)}}const o=Object.freeze(["series","color","stroke"]),a=Object.freeze({size:"size",opacity:"opacity",strokeWidth:"strokeWidth",gradient:"color",interval:"color",strokeGradient:"stroke",strokeInterval:"stroke"}),c=(e,r)=>e<r?-1:e>r?1:0;function w(e,r){const s=e==="colorSize"?["color","size"]:o.includes(e)?r?.channels:a[e]===void 0?void 0:[a[e]];if(!Array.isArray(s)||s.length===0)throw new Error(`Legend block ${e} requires at least one channel.`);return y(s,`Legend block ${e}`),Object.freeze([...s].sort(c))}function p(e){if(!Array.isArray(e)||e.length===0)throw new TypeError("Legend block key requires a non-empty channel array.");return JSON.stringify([...e].sort(c))}function b(e,r,s){if(!h.includes(r))throw new Error(`Unknown legend block kind "${r}".`);const t=w(r,s),n=r==="colorSize"?[s.colorScale,s.sizeScale]:o.includes(r)?s?.scales:[s?.scale];if(!Array.isArray(n)||n.length===0||n.some(l=>typeof l!="string"||e.resolvedScales[l]===void 0))throw new Error(`Legend block ${r} requires resolved scales.`);const i=o.includes(r)?"categorical":r==="colorSize"?"sampled":r==="size"?u(e.resolvedScales[n[0]].type)?"discrete-size":"sampled":["opacity","strokeWidth"].includes(r)||r==="gradient"&&s.representation==="symbols"?"sampled":["gradient","strokeGradient"].includes(r)?"gradient":"interval";return Object.freeze({target:s.target,kind:r,family:i,key:p(t),channels:t,scaleIds:Object.freeze([...n]),config:s})}function g(e,r){return e.symbol.layers.length===1&&(e.kind==="series"&&r==="line"||["color","stroke"].includes(e.kind)&&r==="swatch")?`${e.kind}LegendSymbols`:`${e.kind}LegendSymbol${{line:"Lines",point:"Points",swatch:"Swatches"}[r]}`}export{g as categoricalLegendSymbolId,b as describeLegendBlock,w as legendBlockChannels,p as legendBlockKey,y as validateLegendChannels};

package/src/grammar/legendBorder.js

@@ -0,0 +1,9 @@
+// Legend borders use one closed rectangular path, so odd dash duplication is not implicit.
+export function normalizeLegendBorderDash(value, label = "Legend border strokeDash") {
+  if (value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length % 2 !== 0 ||
+      ![...value].every(item => Number.isFinite(item) && item >= 0)) {
+    throw new TypeError(`${label} must be an even-length array of non-negative finite numbers.`);
+  }
+  return Object.freeze([...value]);
+}

package/src/grammar/legendClip.js

@@ -0,0 +1,19 @@
+export function normalizeLegendClipHeight(value,{edit=false}={}){
+ if(value===undefined||edit&&value==='auto')return undefined;
+ if(!Number.isFinite(value)||value<=0)throw new RangeError('Legend clipHeight must be a positive finite number.');
+ return value;
+}
+export function validateLegendClip(kind,config){
+ if(config.clipHeight===undefined)return;
+ normalizeLegendClipHeight(config.clipHeight);
+ const supported=['size','opacity','colorSize'].includes(kind)||kind==='gradient'&&config.representation==='symbols'||
+  ['series','color','stroke'].includes(kind)&&config.symbol?.layers?.some(layer=>layer.type==='point');
+ if(!supported)throw new Error('Legend clipHeight requires a point-bearing sample block.');
+}
+export function patchLegendClipHeight(config,value){
+ const {clipHeight:_old,...rest}=config,clipHeight=normalizeLegendClipHeight(value,{edit:true});
+ return clipHeight===undefined?rest:{...rest,clipHeight};
+}
+export function clippedSampleBounds(bounds,height){
+ return height===undefined?bounds:{...bounds,top:Math.max(bounds.top,-height/2),bottom:Math.min(bounds.bottom,height/2)};
+}