ggaction 0.0.21 → 0.0.23

package/src/grammar/scales/colorConsumers.js

@@ -1,63 +1 @@
-import { BAR_GRAINS, resolveBarChannels, resolveBarGrain } from "../bars/policy.js";
-import { validateAggregate, validateAggregateFieldType } from "../aggregate.js";
-import { isDiscretizedColorScaleType } from "./types.js";
-
-export function validateContinuousColorConsumer(layer, encoding, scale, {
-  inferAggregate = false,
-  channel = "color"
-} = {}) {
-  const kind = layer.mark?.type;
-  if (["log", "pow", "sqrt", "symlog"].includes(scale.type) && encoding.fieldType !== "quantitative") {
-    throw new Error(`Scale type "${scale.type}" requires quantitative color.`);
-  }
-  if (channel === "stroke") {
-    if (!["point", "line", "area", "bar", "rect", "arc", "rule", "tick"].includes(kind)) {
-      throw new Error("Continuous stroke requires a supported graphical mark consumer.");
-    }
-    if (!['quantitative', 'temporal'].includes(encoding.fieldType) ||
-      (isDiscretizedColorScaleType(scale.type) && encoding.fieldType !== "quantitative")) {
-      throw new Error(`Scale type "${scale.type}" has an incompatible stroke field type.`);
-    }
-    if (encoding.aggregate !== undefined) {
-      throw new Error("Continuous stroke does not support aggregate.");
-    }
-    if (Object.hasOwn(scale, "unknown") && kind !== "point") {
-      throw new Error("Continuous stroke scale unknown currently requires a row-owned point mark.");
-    }
-    return undefined;
-  }
-  if (!["point", "bar", "rect", "text", "area"].includes(kind)) {
-    throw new Error("Continuous color requires a Point, aggregate Bar, Rect, Text, or quantitative Area consumer.");
-  }
-  if (!["quantitative", "temporal"].includes(encoding.fieldType) ||
-    (isDiscretizedColorScaleType(scale.type) && encoding.fieldType !== "quantitative")) {
-    throw new Error(`Scale type "${scale.type}" has an incompatible color field type.`);
-  }
-  if (Object.hasOwn(scale, "unknown") && kind !== "point") {
-    throw new Error("Continuous color scale unknown currently requires a row-owned point mark.");
-  }
-  if (kind === "area" && encoding.fieldType !== "quantitative") {
-    throw new Error("Continuous area color requires a quantitative field.");
-  }
-  if (kind !== "bar") {
-    if (encoding.aggregate !== undefined) throw new Error(`${kind} continuous color does not support aggregate.`);
-    return undefined;
-  }
-  if (["nominal", "ordinal"].includes(layer.encoding?.color?.fieldType)) {
-    throw new Error("Continuous bar color cannot replace an existing nominal color layout.");
-  }
-  if (encoding.fieldType !== "quantitative") {
-    throw new Error("Aggregate bar color currently requires a quantitative field.");
-  }
-  if (resolveBarGrain(layer) !== BAR_GRAINS.aggregate) {
-    throw new Error("Continuous bar color requires a complete categorical aggregate bar.");
-  }
-  const measure = layer.encoding?.[resolveBarChannels(layer).measure];
-  const aggregate = encoding.aggregate ?? (inferAggregate && measure?.field === encoding.field ? measure.aggregate : undefined);
-  if (aggregate === undefined) {
-    throw new Error("Continuous bar color requires aggregate when its field differs from the measure field.");
-  }
-  validateAggregate(aggregate);
-  validateAggregateFieldType(aggregate, encoding.fieldType);
-  return aggregate;
-}
+import{isNominalValue as d,readNominalField as s}from"./fields.js";import{BAR_GRAINS as f,resolveBarChannels as p,resolveBarGrain as c}from"../bars/policy.js";import{validateAggregate as w,validateAggregateFieldType as g}from"../aggregate.js";import{isDiscretizedColorScaleType as l}from"./types.js";function m(o,e){if(o.mark?.type!=="tick")return;const{color:r,stroke:t}=o.encoding??{};if(r!==void 0&&t!==void 0||e==="color"&&t!==void 0||e==="stroke"&&r!==void 0)throw new Error("Tick color and stroke cannot coexist; remove the existing encoding before switching channels.");if(r!==void 0&&!["quantitative","temporal"].includes(r.fieldType))throw new Error("Tick color requires a quantitative or temporal field.")}function v(o,e,r,{inferAggregate:t=!1,channel:n="color"}={}){const i=o.mark?.type;if(m(o,n),["log","pow","sqrt","symlog"].includes(r.type)&&e.fieldType!=="quantitative")throw new Error(`Scale type "${r.type}" requires quantitative color.`);if(n==="stroke"){if(!["point","line","area","bar","rect","arc","rule","tick"].includes(i))throw new Error("Continuous stroke requires a supported graphical mark consumer.");if(!["quantitative","temporal"].includes(e.fieldType)||l(r.type)&&e.fieldType!=="quantitative")throw new Error(`Scale type "${r.type}" has an incompatible stroke field type.`);if(e.aggregate!==void 0)throw new Error("Continuous stroke does not support aggregate.");if(Object.hasOwn(r,"unknown")&&i!=="point")throw new Error("Continuous stroke scale unknown currently requires a row-owned point mark.");return}if(!["point","line","bar","rect","text","area","arc","tick"].includes(i))throw new Error("Continuous color requires a Point, Line, aggregate Bar, Rect, Text, Arc, Tick, or quantitative Area consumer.");if(!["quantitative","temporal"].includes(e.fieldType)||l(r.type)&&e.fieldType!=="quantitative")throw new Error(`Scale type "${r.type}" has an incompatible color field type.`);if(Object.hasOwn(r,"unknown")&&i!=="point")throw new Error("Continuous color scale unknown currently requires a row-owned point mark.");if(i==="area"&&e.fieldType!=="quantitative")throw new Error("Continuous area color requires a quantitative field.");if(i!=="bar"){if(e.aggregate!==void 0)throw new Error(`${i} continuous color does not support aggregate.`);return}if(["nominal","ordinal"].includes(o.encoding?.color?.fieldType))throw new Error("Continuous bar color cannot replace an existing nominal color layout.");if(e.fieldType!=="quantitative")throw new Error("Aggregate bar color currently requires a quantitative field.");if(c(o)!==f.aggregate)throw new Error("Continuous bar color requires a complete categorical aggregate bar.");const u=o.encoding?.[p(o).measure],a=e.aggregate??(t&&u?.field===e.field?u.aggregate:void 0);if(a===void 0)throw new Error("Continuous bar color requires aggregate when its field differs from the measure field.");return w(a),g(a,e.fieldType),a}function C(o,e,r,t="color"){if(!Object.hasOwn(r,"unknown")||o.mark?.type==="point")return!1;const n=o.encoding??{};if(t==="strokeDash"){if(!["line","rule"].includes(o.mark?.type)||!["nominal","ordinal"].includes(e.fieldType)||r.type!=="ordinal"||n.parallel!==void 0||n.theta!==void 0||n.radius!==void 0||[n.x,n.y,n.x2,n.y2].some(i=>i?.aggregate!==void 0||i?.bin!==void 0))throw new Error("StrokeDash unknown requires a Cartesian line or rule with categorical ordinal mapping.");return!1}if(o.mark?.type!=="line"||t!=="color"||!["nominal","ordinal"].includes(e.fieldType)||r.type!=="ordinal"||!Array.isArray(r.domain)||r.domain.length===0||n.parallel!==void 0||n.theta!==void 0||n.radius!==void 0||[n.x,n.y].some(i=>i?.aggregate!==void 0||i?.bin!==void 0))throw new Error("Categorical unknown requires a row-owned point or a Cartesian line with explicit ordinal domain.");return!0}function T(o,e){return s([],e),o.map((r,t)=>{const n=r[e];if(n==null||d(n))return n;throw new TypeError(`Field "${e}" must contain a nominal value at row ${t}.`)})}export{T as readCategoricalLineColor,C as validateCategoricalColorConsumer,v as validateContinuousColorConsumer,m as validateTickColorChannels};

package/src/grammar/scales/continuous.js

@@ -5,6 +5,7 @@ import {
   cleanNumericValue,
   interpolateNumber,
   inverseLerp,
+  nearestNumericIncrement,
   niceNumericStep,
   normalizeNumericRange
 } from "../numeric.js";
@@ -76,6 +77,59 @@ export function niceLinearDomain(domain) {
   return cloneAndFreeze([lower, upper]);
 }
 
+export function normalizeScaleNice(type, value) {
+  if (typeof value === "boolean") return value;
+  if (!isPlainObject(value)) {
+    throw new TypeError("Scale nice must be a boolean or a linear count object.");
+  }
+  if (type !== "linear") {
+    throw new Error("Count-based nice requires a linear position scale.");
+  }
+  if (Reflect.ownKeys(value).length !== 1 || !Object.hasOwn(value, "count")) {
+    throw new TypeError("Count-based nice requires exactly one count property.");
+  }
+  const count = value.count;
+  if (!Number.isSafeInteger(count) || count <= 0) {
+    throw new RangeError("Nice count must be a positive safe integer.");
+  }
+  return cloneAndFreeze({ count });
+}
+
+export function niceLinearCountDomain(domain, count) {
+  const input = validatePair(domain, "Nice linear domain");
+  normalizeScaleNice("linear", { count });
+  const reversed = input[0] > input[1];
+  let lower = Math.min(...input), upper = Math.max(...input);
+  let stable = lower === upper;
+  for (let iteration = 0; iteration < 10 && lower !== upper; iteration++) {
+    let start = lower, end = upper, scale = 1;
+    let increment = nearestNumericIncrement(end - start, count);
+    if (increment === null) {
+      const normalized = normalizeNumericRange(lower, upper);
+      ({ start, end, scale } = normalized);
+      increment = nearestNumericIncrement(normalized.span, count);
+      if (increment === null) break;
+    }
+    let nextLower = (increment < 0
+      ? Math.floor(start * -increment) / -increment
+      : Math.floor(start / increment) * increment) * scale;
+    let nextUpper = (increment < 0
+      ? Math.ceil(end * -increment) / -increment
+      : Math.ceil(end / increment) * increment) * scale;
+    // At numeric limits an outward step may not be representable. Retain the
+    // observed endpoint rather than overflow, move inward, or invent a value.
+    if (!Number.isFinite(nextLower) || nextLower > lower) nextLower = lower;
+    if (!Number.isFinite(nextUpper) || nextUpper < upper) nextUpper = upper;
+    if (nextLower === lower && nextUpper === upper) { stable = true; break; }
+    lower = nextLower; upper = nextUpper;
+  }
+  // A density such as one interval across zero may have no fixed outward
+  // grid. Do not return an arbitrarily enlarged result after the loop cap.
+  if (!stable) return input;
+  const result = [lower === 0 ? 0 : lower, upper === 0 ? 0 : upper];
+  return cloneAndFreeze(reversed ? result.reverse() : result);
+}
+
 export function resolveContinuousDomain({ domain, values, type, nice, zero }) {
   const explicit = domain !== "auto";
   let resolved = resolveScaleDomain(domain, values);
@@ -86,7 +140,10 @@ export function resolveContinuousDomain({ domain, values, type, nice, zero }) {
       Math.max(0, resolved[1])
     ]);
   }
-  if (nice === true) {
+  if (nice !== undefined && typeof nice === "object") {
+    const policy = normalizeScaleNice(type, nice);
+    resolved = niceLinearCountDomain(resolved, policy.count);
+  } else if (nice === true) {
     resolved = type === "time"
       ? niceTimeDomain(resolved)
       : niceLinearDomain(resolved);

package/src/grammar/scales/definition.js

@@ -1 +1 @@
-import{validateMeasuredRadiusScale as D}from"./radial.js";import{normalizeColorInterpolationOptions as F,validateContinuousColorInterpolation as N,validateSequentialMidpoint as T}from"./color.js";import{isTransformedScaleType as k}from"./mapping.js";import{normalizeTransformParameters as q,validateTransformedDomain as A}from"./transformed.js";import{isContinuousColorScaleType as R,validateScalePropertyForType as b}from"./types.js";const p=Object.freeze(["nice","zero","clamp","reverse"]),B=Object.freeze(["base","exponent","constant"]);function f(i,l,n,e,o){return Object.hasOwn(l,e)?l[e]:!o&&Object.hasOwn(i,e)?i[e]:n[e]}function _(i,l,n,e,o){const m=Object.hasOwn(n,"padding");if(m&&(Object.hasOwn(n,"paddingInner")||Object.hasOwn(n,"paddingOuter")))throw new Error("Scale padding cannot be combined with paddingInner or paddingOuter.");if(m&&(!Number.isFinite(n.padding)||n.padding<0||n.padding>=1))throw new RangeError("Scale padding must be from 0 (inclusive) to 1 (exclusive).");const d=m?{...n,paddingInner:n.padding,paddingOuter:n.padding}:n,g=f(l,d,e,"paddingInner",o)??0,w=f(l,d,e,"paddingOuter",o)??0,c=f(l,d,e,"align",o)??.5;if(!Number.isFinite(g)||g<0||g>=1)throw new RangeError("Scale paddingInner must be from 0 (inclusive) to 1 (exclusive).");if(!Number.isFinite(w)||w<0)throw new RangeError("Scale paddingOuter must be non-negative and finite.");if(!Number.isFinite(c)||c<0||c>1)throw new RangeError("Scale align must be between 0 and 1.");Object.assign(i,{paddingInner:g,paddingOuter:w,align:c})}function $(i,l,n,e,o){const m=f(l,n,e,"padding",o)??.5,d=f(l,n,e,"align",o)??.5;if(!Number.isFinite(m)||m<0)throw new RangeError("Scale padding must be non-negative and finite.");if(!Number.isFinite(d)||d<0||d>1)throw new RangeError("Scale align must be between 0 and 1.");Object.assign(i,{padding:m,align:d})}function J({type:i,color:l=!1,previous:n={},patch:e={},defaults:o={},retainCoreOnTypeChange:m=!1,retainCompatibleOnTypeChange:d=!1,allowColorReset:g=!1,allowOrdinalBandParameters:w=!1,validateDomain:c,validateRange:I}){const s=n.type!==void 0&&n.type!==i,M=Object.hasOwn(e,"domain")?e.domain:(!s||m)&&Object.hasOwn(n,"domain")?n.domain:o.domain??"auto",x=Object.hasOwn(e,"range")?e.range:(!s||m)&&Object.hasOwn(n,"range")?n.range:o.range??"auto",r={type:i,domain:c(i,M),range:I(i,x)},u=f(n,e,o,"emptyDomain",s);if(u!==void 0){if(!["preserve","require-explicit"].includes(u))throw new Error('Scale emptyDomain must be "preserve" or "require-explicit".');r.emptyDomain=u}for(const a of p){let t=f(n,e,o,a,s);if(t===void 0&&s&&d&&Object.hasOwn(n,a))try{b(i,a),t=n[a]}catch{t=void 0}if(t!==void 0){if(typeof t!="boolean")throw new TypeError(`Scale ${a} must be a boolean.`);b(i,a),r[a]=t}}const j=Object.fromEntries(B.flatMap(a=>{const t=f(n,e,o,a,s);return t===void 0?[]:[[a,t]]}));if(k(i)){const a=q(i,j);i==="log"&&(r.base=a.base),i==="pow"&&(r.exponent=a.exponent),i==="symlog"&&(r.constant=a.constant),r.domain!=="auto"&&A(i,r.domain,j)}else for(const a of Object.keys(j))b(i,a);let O=f(n,e,o,"interpolate",s);if(i==="sequential"||l&&R(i))O===void 0&&d&&(O=n.interpolate),r.interpolate=N(O??"rgb");else if(O!==void 0)throw new Error(`Scale type "${i}" does not support interpolate.`);const z=Object.hasOwn(e,"interpolate")&&e.interpolate!==n.interpolate,S={};for(const a of["whitePoint","gamma"]){const t=Object.hasOwn(e,a)?e[a]:z?void 0:f(n,e,o,a,s&&!(d&&R(i)));t!==void 0&&!(g&&t==="auto")&&(S[a]=t)}Object.assign(r,F(r.interpolate,S));const E=T(f(n,e,o,"midpoint",s),i,r.domain);if(E!==void 0&&(r.midpoint=E),i==="band"||i==="ordinal"&&w)_(r,n,e,o,s);else if(i==="point")$(r,n,e,o,s);else for(const a of["paddingInner","paddingOuter","padding","align"])Object.hasOwn(e,a)&&b(i,a);const P=Object.hasOwn(e,"radialMapping")?e.radialMapping:n.radialMapping;return P!==void 0&&(r.radialMapping=P,D({...r,...Object.hasOwn(e,"unknown")||Object.hasOwn(n,"unknown")?{unknown:e.unknown??n.unknown}:{}},{allowAuto:!0})),r}export{J as normalizeScaleDefinition};
+import{validateMeasuredRadiusScale as D}from"./radial.js";import{normalizeScaleNice as R}from"./continuous.js";import{normalizeColorInterpolationOptions as F,validateContinuousColorInterpolation as T,validateSequentialMidpoint as k}from"./color.js";import{isTransformedScaleType as q}from"./mapping.js";import{normalizeTransformParameters as A,validateTransformedDomain as _}from"./transformed.js";import{isContinuousColorScaleType as M,validateScalePropertyForType as b}from"./types.js";const $=Object.freeze(["nice","zero","clamp","reverse"]),p=Object.freeze(["base","exponent","constant"]);function f(i,l,n,e,o){return Object.hasOwn(l,e)?l[e]:!o&&Object.hasOwn(i,e)?i[e]:n[e]}function B(i,l,n,e,o){const m=Object.hasOwn(n,"padding");if(m&&(Object.hasOwn(n,"paddingInner")||Object.hasOwn(n,"paddingOuter")))throw new Error("Scale padding cannot be combined with paddingInner or paddingOuter.");if(m&&(!Number.isFinite(n.padding)||n.padding<0||n.padding>=1))throw new RangeError("Scale padding must be from 0 (inclusive) to 1 (exclusive).");const d=m?{...n,paddingInner:n.padding,paddingOuter:n.padding}:n,c=f(l,d,e,"paddingInner",o)??0,w=f(l,d,e,"paddingOuter",o)??0,g=f(l,d,e,"align",o)??.5;if(!Number.isFinite(c)||c<0||c>=1)throw new RangeError("Scale paddingInner must be from 0 (inclusive) to 1 (exclusive).");if(!Number.isFinite(w)||w<0)throw new RangeError("Scale paddingOuter must be non-negative and finite.");if(!Number.isFinite(g)||g<0||g>1)throw new RangeError("Scale align must be between 0 and 1.");Object.assign(i,{paddingInner:c,paddingOuter:w,align:g})}function L(i,l,n,e,o){const m=f(l,n,e,"padding",o)??.5,d=f(l,n,e,"align",o)??.5;if(!Number.isFinite(m)||m<0)throw new RangeError("Scale padding must be non-negative and finite.");if(!Number.isFinite(d)||d<0||d>1)throw new RangeError("Scale align must be between 0 and 1.");Object.assign(i,{padding:m,align:d})}function K({type:i,color:l=!1,previous:n={},patch:e={},defaults:o={},retainCoreOnTypeChange:m=!1,retainCompatibleOnTypeChange:d=!1,allowColorReset:c=!1,allowOrdinalBandParameters:w=!1,validateDomain:g,validateRange:I}){const s=n.type!==void 0&&n.type!==i,x=Object.hasOwn(e,"domain")?e.domain:(!s||m)&&Object.hasOwn(n,"domain")?n.domain:o.domain??"auto",z=Object.hasOwn(e,"range")?e.range:(!s||m)&&Object.hasOwn(n,"range")?n.range:o.range??"auto",r={type:i,domain:g(i,x),range:I(i,z)},u=f(n,e,o,"emptyDomain",s);if(u!==void 0){if(!["preserve","require-explicit"].includes(u))throw new Error('Scale emptyDomain must be "preserve" or "require-explicit".');r.emptyDomain=u}for(const a of $){let t=f(n,e,o,a,s);if(t===void 0&&s&&d&&Object.hasOwn(n,a))try{b(i,a),a==="nice"&&R(i,n[a]),t=n[a]}catch{t=void 0}if(t!==void 0){if(a==="nice")t=R(i,t);else if(typeof t!="boolean")throw new TypeError(`Scale ${a} must be a boolean.`);b(i,a),r[a]=t}}const j=Object.fromEntries(p.flatMap(a=>{const t=f(n,e,o,a,s);return t===void 0?[]:[[a,t]]}));if(q(i)){const a=A(i,j);i==="log"&&(r.base=a.base),i==="pow"&&(r.exponent=a.exponent),i==="symlog"&&(r.constant=a.constant),r.domain!=="auto"&&_(i,r.domain,j)}else for(const a of Object.keys(j))b(i,a);let O=f(n,e,o,"interpolate",s);if(i==="sequential"||l&&M(i))O===void 0&&d&&(O=n.interpolate),r.interpolate=T(O??"rgb");else if(O!==void 0)throw new Error(`Scale type "${i}" does not support interpolate.`);const N=Object.hasOwn(e,"interpolate")&&e.interpolate!==n.interpolate,S={};for(const a of["whitePoint","gamma"]){const t=Object.hasOwn(e,a)?e[a]:N?void 0:f(n,e,o,a,s&&!(d&&M(i)));t!==void 0&&!(c&&t==="auto")&&(S[a]=t)}Object.assign(r,F(r.interpolate,S));const E=k(f(n,e,o,"midpoint",s),i,r.domain);if(E!==void 0&&(r.midpoint=E),i==="band"||i==="ordinal"&&w)B(r,n,e,o,s);else if(i==="point")L(r,n,e,o,s);else for(const a of["paddingInner","paddingOuter","padding","align"])Object.hasOwn(e,a)&&b(i,a);const P=Object.hasOwn(e,"radialMapping")?e.radialMapping:n.radialMapping;return P!==void 0&&(r.radialMapping=P,D({...r,...Object.hasOwn(e,"unknown")||Object.hasOwn(n,"unknown")?{unknown:e.unknown??n.unknown}:{}},{allowAuto:!0})),r}export{K as normalizeScaleDefinition};

package/src/grammar/scales/ordinal.js

@@ -1,6 +1,6 @@
-import { cloneAndFreeze } from "../../core/immutable.js";
+import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 import { isNominalValue } from "./fields.js";
-import { validateColorRange, validateStrokeDashRange } from "./appearance.js";
+import { validateColorRange, validateShapeRange, validateStrokeDashRange } from "./appearance.js";
 import { validatePair, validateScaleRange } from "./validation.js";
 import { resolveScaleRange } from "./continuous.js";
 import { interpolateNumber } from "../numeric.js";
@@ -70,6 +70,9 @@ export function validateOrdinalDomain(domain) {
 export function validateOrdinalRange(range) {
   if (range === "auto") return range;
   if (Array.isArray(range)) {
+    if (range.some(value => isPlainObject(value) && Object.hasOwn(value, "polygon"))) {
+      return validateShapeRange(range);
+    }
     if (range.length === 2 && range.every(Number.isFinite)) {
       return cloneAndFreeze(range);
     }

package/src/grammar/scales/policies.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze } from "../../core/immutable.js";
-import { POINT_SHAPES } from "../pointShapes.js";
+import { POINT_SHAPES, validatePointShape } from "../pointShapes.js";
 import { normalizeStrokeDashPattern } from "./appearance.js";
 
 export function validateScaleUnknown(channel, value) {
@@ -30,10 +30,10 @@ export function validateScaleUnknown(channel, value) {
     return value;
   }
   if (channel === "shape") {
-    if (!POINT_SHAPES.includes(value)) {
+    if (typeof value !== "object" && !POINT_SHAPES.includes(value)) {
       throw new Error(`Unsupported scale unknown shape "${value}".`);
     }
-    return value;
+    return validatePointShape(value);
   }
   if (channel === "strokeDash") {
     return cloneAndFreeze(normalizeStrokeDashPattern(value));

package/src/grammar/schemas/graphicBounds.js

@@ -3,6 +3,7 @@ import {
   resolveTextBounds
 } from "../../core/textMetrics.js";
 import { interpolateNumber } from "../numeric.js";
+import { graphicClipBounds, intersectClipBounds } from "./graphicClip.js";
 import { resolveStrokeDetails } from "../strokeStyle.js";
 import {
   findGraphic,
@@ -452,7 +453,7 @@ function canvasOffset(object, property) {
   return Number.isFinite(value) ? value : 0;
 }
 
-function ancestorOffset(graphicSpec, target) {
+export function resolveGraphicParentOffset(graphicSpec, target) {
   const offset = [0, 0];
   const visited = new Set();
   let current = target;
@@ -476,11 +477,15 @@ function intersectVisibleBounds(bounds,clip) {
   return result.right<=result.left||result.bottom<=result.top?undefined:result;
 }
 
-function clipAncestorBounds(graphicSpec,id,bounds) {
+function clipAncestorBounds(graphicSpec,id,bounds,includeOwnerClips) {
   let parent=findGraphicParent(graphicSpec,id);
   while(parent!==undefined){
+    if (includeOwnerClips && parent.object.clip !== undefined) {
+      bounds = intersectVisibleBounds(bounds, graphicClipBounds(parent.object.clip,
+        ...resolveGraphicParentOffset(graphicSpec, parent.id)));
+    }
     if(parent.object.type==="canvas"&&findGraphicParent(graphicSpec,parent.id)!==undefined){
-      const [x,y]=ancestorOffset(graphicSpec,parent.id),p=parent.object.properties;
+      const [x,y]=resolveGraphicParentOffset(graphicSpec,parent.id),p=parent.object.properties;
       bounds=intersectVisibleBounds(bounds,{left:x+(p.x??0),right:x+(p.x??0)+p.width,top:y+(p.y??0),bottom:y+(p.y??0)+p.height});
     }
     parent=findGraphicParent(graphicSpec,parent.id);
@@ -488,7 +493,27 @@ function clipAncestorBounds(graphicSpec,id,bounds) {
   return bounds;
 }
 
-function objectBounds(graphicSpec, id, object, ancestors, x, y, profile) {
+// Effective rectangular visibility, including the named owner itself. Inspection
+// can opt into the root viewport without changing geometry/selection properties.
+export function resolveGraphicClipBounds(graphicSpec, target, {rootViewport = false} = {}) {
+  const found = requireGraphic(graphicSpec, target);
+  let current = found.kind === "item" ? found.ownerId : found.id;
+  let clip;
+  while (current !== undefined) {
+    const object = graphicSpec.objects[current];
+    const offset = resolveGraphicParentOffset(graphicSpec, current);
+    const parent = findGraphicParent(graphicSpec, current);
+    const local = object.clip !== undefined ? graphicClipBounds(object.clip, ...offset)
+      : object.type === "canvas" && (parent !== undefined || rootViewport)
+        ? graphicClipBounds({...object.properties, x: parent === undefined ? 0 : object.properties.x,
+            y: parent === undefined ? 0 : object.properties.y}, ...offset) : undefined;
+    if (local !== undefined) clip = clip === undefined ? local : intersectClipBounds(clip, local);
+    current = parent?.id;
+  }
+  return clip;
+}
+
+function objectBounds(graphicSpec, id, object, ancestors, x, y, profile, includeOwnerClips) {
   if (ancestors.has(id)) {
     throw new Error(`Graphic attachment cycle includes "${id}".`);
   }
@@ -508,7 +533,7 @@ function objectBounds(graphicSpec, id, object, ancestors, x, y, profile) {
       throw new Error(`Unknown attached graphic "${childId}".`);
     }
     const bounds = objectBounds(
-      graphicSpec, childId, child.object, ancestors, childX, childY, profile
+      graphicSpec, childId, child.object, ancestors, childX, childY, profile, includeOwnerClips
     );
     if (bounds !== undefined) {
       result = includeExtent(
@@ -520,28 +545,31 @@ function objectBounds(graphicSpec, id, object, ancestors, x, y, profile) {
     result=intersectVisibleBounds(result,{left:childX,right:childX+object.properties.width,
       top:childY,bottom:childY+object.properties.height});
   }
+  if (includeOwnerClips && object.clip !== undefined) result = intersectVisibleBounds(result, graphicClipBounds(object.clip, x, y));
   ancestors.delete(id);
   return result;
 }
 
-export function resolveConcreteGraphicBounds(graphicSpec, target, profile) {
+export function resolveConcreteGraphicBounds(graphicSpec, target, profile, {includeOwnerClips = true} = {}) {
   const found = requireGraphic(graphicSpec, target);
   const anchor=found.kind==="item"?found.ownerId:found.id;
-  const [x, y] = ancestorOffset(graphicSpec, anchor);
+  const [x, y] = resolveGraphicParentOffset(graphicSpec, anchor);
   return requireFiniteBounds(clipAncestorBounds(graphicSpec,anchor,found.kind === "item"
-    ? translateBounds(
+    ? (!includeOwnerClips || found.owner.clip === undefined ? translateBounds(
       resolvePrimitiveGraphicBounds(found.object.type ?? found.owner.type, found.object.properties, profile),
       x,
       y
-    )
-    : objectBounds(graphicSpec, found.id, found.object, new Set(), x, y, profile)));
+    ) : intersectVisibleBounds(translateBounds(
+      resolvePrimitiveGraphicBounds(found.object.type ?? found.owner.type, found.object.properties, profile), x, y
+    ), graphicClipBounds(found.owner.clip, x, y)))
+    : objectBounds(graphicSpec, found.id, found.object, new Set(), x, y, profile, includeOwnerClips), includeOwnerClips));
 }
 
-export function unionConcreteGraphicBounds(graphicSpec, targets, profile) {
+export function unionConcreteGraphicBounds(graphicSpec, targets, profile, options) {
   if (!Array.isArray(targets)) {
     throw new TypeError("Graphic bounds targets must be an array.");
   }
   return unionBounds(targets.map(target =>
-    resolveConcreteGraphicBounds(graphicSpec, target, profile)
+    resolveConcreteGraphicBounds(graphicSpec, target, profile, options)
   ));
 }

package/src/grammar/schemas/graphicClip.js

@@ -0,0 +1,23 @@
+import { isPlainObject } from "../../core/immutable.js";
+
+// A named owner's rectangle uses its existing parent frame; it never rebases items.
+export function validateGraphicClip(value, type) {
+  if (type === "canvas") throw new Error("Canvas uses its existing viewport, not an owner clip.");
+  if (!isPlainObject(value) || Object.keys(value).length !== 4 ||
+      !["x", "y", "width", "height"].every(key => Object.hasOwn(value, key) && Number.isFinite(value[key])) ||
+      value.width < 0 || value.height < 0 ||
+      !Number.isFinite(value.x + value.width) || !Number.isFinite(value.y + value.height)) {
+    throw new TypeError("Graphic clip requires finite x, y and non-negative width, height.");
+  }
+  return value;
+}
+
+export function graphicClipBounds(rect, x = 0, y = 0) {
+  return {left: x + rect.x, right: x + rect.x + rect.width,
+    top: y + rect.y, bottom: y + rect.y + rect.height};
+}
+
+export function intersectClipBounds(a, b) {
+  return {left: Math.max(a.left, b.left), right: Math.min(a.right, b.right),
+    top: Math.max(a.top, b.top), bottom: Math.min(a.bottom, b.bottom)};
+}

package/src/grammar/schemas/graphicTree.js

@@ -1,4 +1,20 @@
 import { isPlainObject } from "../../core/immutable.js";
+import { isGraphicContainerType } from "./graphic.js";
+
+export function resolveGraphicChildOrder(graphicSpec, target, value) {
+  const found = requireGraphic(graphicSpec, target);
+  if (found.kind !== "object" || !isGraphicContainerType(found.object.type)) {
+    throw new Error("Graphic children order requires a named Canvas or collection.");
+  }
+  const children = found.object.children ?? [];
+  const existing = new Set(children);
+  if (!Array.isArray(value) || value.length !== children.length ||
+      new Set(value).size !== children.length ||
+      value.some(id => typeof id !== "string" || !existing.has(id))) {
+    throw new Error("Graphic children order must be an exact permutation of existing direct children.");
+  }
+  return [...value];
+}
 
 function requireGraphicSpec(graphicSpec) {
   if (

package/src/grammar/statisticalReference.js

@@ -1,12 +1,34 @@
 import { rejectUnknownProperties as rejectUnknownKeys } from "../core/validation.js";
 import { aggregateRows } from "./aggregate.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { scalarKey } from "./transformKeys.js";
 
 const STATISTIC_KEYS = Object.freeze(["op", "p"]);
 const SIMPLE_STATISTICS = new Set(["mean", "median", "min", "max"]);
 const POPULATIONS = new Set(["boundData", "visibleItems"]);
 const TRANSFORM_KEYS = Object.freeze(["type", "target"]);
 
+export function normalizeReferenceGroupBy(value) {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new TypeError("Statistical reference groupBy must be a non-empty field name.");
+  }
+  return value;
+}
+
+export function partitionReferenceRows(rows, groupBy) {
+  if (groupBy === undefined) return [{ rows }];
+  const groups = new Map();
+  for (const [index, row] of rows.entries()) {
+    if (!isPlainObject(row) || !Object.hasOwn(row, groupBy)) {
+      throw new Error(`Statistical reference groupBy field "${groupBy}" is missing at item ${index}.`);
+    }
+    const group = row[groupBy], key = scalarKey(group, "Statistical reference groupBy");
+    if (!groups.has(key)) groups.set(key, { key, group, rows: [] });
+    groups.get(key).rows.push(row);
+  }
+  return [...groups.values()];
+}
 
 export function normalizeReferenceStatistic(value, label = "Reference statistic") {
   if (!isPlainObject(value)) {

package/src/grammar/text.js

@@ -1,4 +1,8 @@
-import { cloneAndFreeze } from "../core/immutable.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { schemaField } from "./datasetSchema.js";
+import { readQuantitativeField } from "./scales/fields.js";
+import { applyItemMissingPolicy } from "./itemMissing.js";
+import { validateOptionObject } from "../core/validation.js";
 import { validateConcreteGraphicValue } from "./schemas/concreteGraphic.js";
 import {
   formatValue,
@@ -11,6 +15,66 @@ export function isSourceOwnedText(layer) {
   return layer?.mark?.type === "text" && layer.source !== undefined;
 }
 
+export function isIndependentText(layer) {
+  return layer?.mark?.type === "text" && layer.source === undefined;
+}
+
+export function validateTextOffsetEncoding(encoding, channel) {
+  if (!isPlainObject(encoding)) throw new TypeError(`Text ${channel} encoding must be an object.`);
+  const field = Object.hasOwn(encoding, "field");
+  const datum = Object.hasOwn(encoding, "datum");
+  if (field === datum) throw new Error(`Text ${channel} requires exactly one field or datum.`);
+  const allowed = field ? ["field", "fieldType"] : ["datum"];
+  if (Object.keys(encoding).some(key => !allowed.includes(key))) {
+    throw new Error(`Unsupported Text ${channel} encoding option.`);
+  }
+  if (field) {
+    if (typeof encoding.field !== "string" || encoding.field.length === 0 ||
+        encoding.fieldType !== "quantitative") {
+      throw new TypeError(`Text ${channel} requires a quantitative field.`);
+    }
+  } else if (!Number.isFinite(encoding.datum)) {
+    throw new TypeError(`Text ${channel} datum must be finite logical pixels.`);
+  }
+}
+
+export function normalizeTextOffsetAssignment(args, channel) {
+  const operation = channel === "dx" ? "encodeDx" : "encodeDy";
+  validateOptionObject(args, ["target", "field", "value"], operation);
+  const field = Object.hasOwn(args, "field");
+  if (field === Object.hasOwn(args, "value")) {
+    throw new Error(`${operation} requires exactly one of field or value.`);
+  }
+  const encoding = field ? { field: args.field, fieldType: "quantitative" } : { datum: args.value };
+  validateTextOffsetEncoding(encoding, channel);
+  return cloneAndFreeze(encoding);
+}
+
+// Resolve missing rows once for positions, content, color and both pixel offsets.
+export function resolveTextOffsetDataset(layer, sourceDataset) {
+  const channels = ["dx", "dy"].filter(channel => layer.encoding?.[channel] !== undefined);
+  if (channels.length && !isIndependentText(layer)) {
+    throw new Error("Numeric text offsets require independent Text marks.");
+  }
+  const dataset = applyItemMissingPolicy(layer, sourceDataset);
+  for (const channel of channels) {
+    const encoding = layer.encoding[channel];
+    validateTextOffsetEncoding(encoding, channel);
+    if (!Object.hasOwn(encoding, "field")) continue;
+    if (sourceDataset.values.length === 0 &&
+        schemaField(sourceDataset.schema, encoding.field)?.storageType !== "number") {
+      throw new Error(`Empty Text ${channel} data requires a known numeric field "${encoding.field}".`);
+    }
+    readQuantitativeField(dataset.values, encoding.field);
+  }
+  return dataset;
+}
+
+export function textOffsetValue(encoding, row, fallback) {
+  if (encoding === undefined) return fallback;
+  return Object.hasOwn(encoding, "field") ? row[encoding.field] : encoding.datum;
+}
+
 export const TEXT_MARK_STYLE_OPTIONS = Object.freeze([
   "fill", "opacity", "fontSize", "fontFamily", "fontWeight",
   "align", "baseline", "rotation", "dx", "dy", "inheritColor", "lineHeight", "blockAlign"

package/src/grammar/ticks.js

@@ -6,6 +6,7 @@ import {
 import {
   alignNumericStep,
   cleanNumericValue,
+  nearestNumericIncrement,
   niceNumericStep,
   normalizeNumericRange
 } from "./numeric.js";
@@ -36,12 +37,64 @@ function ticksForStep(start, end, step, low, high, scale) {
   return values;
 }
 
-export function niceTicks(domain, count) {
+export function validateTickRounding(rounding, optional = true) {
+  if ((!optional || rounding !== undefined) && !["ceiling", "nearest"].includes(rounding)) {
+    throw new TypeError('Tick rounding must be "ceiling" or "nearest".');
+  }
+}
+
+export function validateTickSelectionRounding(config, scaleType) {
+  validateTickRounding(config.rounding, !Object.hasOwn(config, "rounding"));
+  if (config.rounding !== undefined && (config.mode !== "count" || scaleType !== "linear")) {
+    throw new Error("Tick rounding requires an automatic linear Cartesian axis.");
+  }
+  if (config.rounding !== undefined) {
+    if (!Number.isInteger(config.count) || config.count <= 0) {
+      throw new RangeError("Tick rounding count must be a positive integer.");
+    }
+    validateGeneratedItemLimit(config.count, "Tick rounding count");
+  }
+}
+
+export function axisTickSelection(config) {
+  return config.mode === "values" ? { mode: "values", values: config.values } : {
+    mode: "count", count: config.count,
+    ...(config.rounding === "nearest" ? { rounding: "nearest" } : {})
+  };
+}
+
+function nearestTicks(low, high, count) {
+  let start = low, end = high, scale = 1;
+  let increment = nearestNumericIncrement(end - start, count);
+  if (increment === null) {
+    const normalized = normalizeNumericRange(low, high);
+    ({ start, end, scale } = normalized);
+    increment = nearestNumericIncrement(normalized.span, count);
+  }
+  if (increment === null) return cloneAndFreeze([low, high]);
+  const first = Math.ceil(increment < 0 ? start * -increment : start / increment);
+  const last = Math.floor(increment < 0 ? end * -increment : end / increment);
+  const length = last - first + 1;
+  if (!Number.isFinite(length) || length <= 0) return cloneAndFreeze([low, high]);
+  const size = Math.min(length, MAX_GENERATED_ITEMS), values = [];
+  for (let index = 0; index < size; index++) {
+    const offset = length === size ? index : Math.round(index * (length - 1) / (size - 1));
+    const at = first + offset;
+    const value = (increment < 0 ? at / -increment : at * increment) * scale;
+    if (Number.isFinite(value) && value >= low && value <= high &&
+        (values.length === 0 || value > values.at(-1))) values.push(value === 0 ? 0 : value);
+  }
+  return cloneAndFreeze(values.length > 0 ? values : [low, high]);
+}
+
+export function niceTicks(domain, count, rounding = "ceiling") {
+  validateTickRounding(rounding);
   if (!Number.isInteger(count) || count <= 0) throw new RangeError("Tick count must be a positive integer.");
   const effectiveCount = Math.min(count, MAX_GENERATED_ITEMS);
   const low = Math.min(...domain);
   const high = Math.max(...domain);
   if (low === high) return cloneAndFreeze([low]);
+  if (rounding === "nearest") return nearestTicks(low, high, effectiveCount);
   const directSpan = high - low;
   if (Number.isFinite(directSpan) && directSpan > 0) {
     const directStep = niceNumericStep(directSpan, effectiveCount);
@@ -254,3 +307,41 @@ export function formatTimeTicks(values, domain) {
   }
   return cloneAndFreeze(values.map(value => String(value)));
 }
+
+
+// Fixed numeric display precision belongs to one settled axis, not its dataset.
+// Sorting a copied distinct list preserves the caller's tick and painter order.
+export function formatNumericTickValues(values) {
+  if (!Array.isArray(values) || !values.every(Number.isFinite)) {
+    throw new TypeError("Numeric tick formatting requires finite tick values.");
+  }
+  const ordered = [...new Set(values)].sort((a, b) => a - b);
+  if (ordered.length === 0) return [];
+  let step = Infinity;
+  for (let index = 1; index < ordered.length; index += 1) {
+    step = Math.min(step, ordered[index] - ordered[index - 1]);
+  }
+  let precision;
+  if (ordered.length === 1) {
+    const normalized = Number(ordered[0].toPrecision(12));
+    const [coefficient, exponent = "0"] = String(normalized).split("e");
+    precision = Math.max(0, (coefficient.split(".")[1]?.length ?? 0) - Number(exponent));
+  } else {
+    const normalizedStep = Number(step.toPrecision(12));
+    precision = Math.max(0, -Math.floor(Math.log10(normalizedStep)));
+  }
+  if (precision > 12) {
+    throw new RangeError("Numeric tick format supports at most 12 decimals.");
+  }
+  const fixed = (value, digits) => {
+    const label = value.toFixed(digits);
+    return Number(label) === 0 ? (0).toFixed(digits) : label.replace(/^-/, "−");
+  };
+  for (; precision <= 12; precision += 1) {
+    const labels = ordered.map(value => fixed(value, precision));
+    if (new Set(labels).size === labels.length) {
+      return values.map(value => fixed(value, precision));
+    }
+  }
+  throw new RangeError("Numeric tick format cannot distinguish values within 12 decimals.");
+}

package/src/grammar/timeUnit.js

@@ -41,7 +41,7 @@ export const TIME_UNITS = cloneAndFreeze([
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "field", "unit", "as", "temporalUnit", "timeZone",
-  "weekStartsOn", "weekRule"
+  "weekStartsOn", "weekRule", "missing"
 ]);
 
 const CALENDAR_FORMATTERS = new Map();
@@ -93,6 +93,9 @@ export function validateTimeUnitTransform(transform) {
   if (transform.type !== "timeUnit") {
     throw new Error(`Unsupported time-unit transform "${transform.type}".`);
   }
+  if (Object.hasOwn(transform, "missing") && !["error", "null"].includes(transform.missing)) {
+    throw new Error('Time-unit missing must be "error" or "null".');
+  }
   validateTemporalUnit(transform.temporalUnit);
   const field = requireField(transform.field, "Time-unit field");
   const output = requireField(transform.as, "Time-unit output field");
@@ -127,7 +130,8 @@ export function normalizeTimeUnitTransform(args = {}) {
   const as = args.as === undefined ? `${field}_${unit}` : args.as;
   const transform = { type: "timeUnit", field, unit, as,
     ...(temporalUnit === undefined ? {} : { temporalUnit }),
-    ...(timeZone === undefined ? {} : { timeZone }) };
+    ...(timeZone === undefined ? {} : { timeZone }),
+    ...(Object.hasOwn(args, "missing") ? { missing: args.missing } : {}) };
   if (unit === "week") {
     transform.weekStartsOn = args.weekStartsOn ?? 1;
     transform.weekRule = args.weekRule ?? "calendar";
@@ -319,7 +323,8 @@ export function deriveTimeUnitRows(rows, transform) {
     throw new TypeError("Time-unit source must contain plain row objects.");
   }
   const values = rows.map((row, index) => {
-    if (!Object.hasOwn(row, transform.field)) {
+    const missing = !Object.hasOwn(row, transform.field) || row[transform.field] === null;
+    if (!Object.hasOwn(row, transform.field) && transform.missing !== "null") {
       throw new Error(
         `Time-unit source does not contain field "${transform.field}" at row ${index}.`
       );
@@ -327,6 +332,7 @@ export function deriveTimeUnitRows(rows, transform) {
     if (Object.hasOwn(row, transform.as)) {
       throw new Error(`Time-unit output field "${transform.as}" already exists.`);
     }
+    if (missing && transform.missing === "null") return { ...row, [transform.as]: null };
     const timestamp = normalizeTemporalValue(row[transform.field], transform.field, index, transform.temporalUnit);
     return {
       ...row,