ggaction 0.0.20 → 0.0.22

package/src/grammar/horizon.js

@@ -1,494 +1 @@
-import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import {
-  validateGeneratedItemLimit,
-  validateNonEmptyString as requireField
-} from "../core/validation.js";
-import { normalizePalette } from "./palettes.js";
-import { interpolateNumber, inverseLerp } from "./numeric.js";
-import { requireFiniteResult } from "./numeric.js";
-import {
-  isNominalValue,
-  normalizeTemporalValue,
-  resolveTemporalUnit
-} from "./scales/index.js";
-
-export const HORIZON_RESOLUTIONS = Object.freeze(["shared", "independent"]);
-export const HORIZON_MISSING_POLICIES = Object.freeze(["break", "error"]);
-export const HORIZON_OVERFLOW_POLICIES = Object.freeze(["clip", "error"]);
-
-const ENCODING_PROPERTIES = Object.freeze(["field", "fieldType", "temporalUnit"]);
-const OUTPUT_PROPERTIES = Object.freeze([
-  "x", "lower", "upper", "group", "color", "sign", "band", "segment"
-]);
-
-function validateEncoding(value, role) {
-  if (!isPlainObject(value)) {
-    throw new TypeError(`Horizon ${role} encoding must be a plain object.`);
-  }
-  const unknown = Object.keys(value).find(
-    property => !ENCODING_PROPERTIES.includes(property)
-  );
-  if (unknown !== undefined) {
-    throw new Error(`Unknown Horizon ${role} encoding property "${unknown}".`);
-  }
-  const field = requireField(value.field, `Horizon ${role} field`);
-  const fieldType = value.fieldType ?? "quantitative";
-  const supportsTemporal = role === "x";
-  if (
-    fieldType !== "quantitative" &&
-    (!supportsTemporal || fieldType !== "temporal")
-  ) {
-    throw new Error(
-      `Horizon ${role} fieldType must be quantitative${supportsTemporal ? " or temporal" : ""}.`
-    );
-  }
-  const temporalUnit = resolveTemporalUnit(value, fieldType);
-  return { field, fieldType, ...(temporalUnit === undefined ? {} : { temporalUnit }) };
-}
-
-function validateOutputFields(value) {
-  if (!isPlainObject(value)) {
-    throw new TypeError("Horizon as must be a plain object.");
-  }
-  const unknown = Object.keys(value).find(
-    property => !OUTPUT_PROPERTIES.includes(property)
-  );
-  if (unknown !== undefined) {
-    throw new Error(`Unknown Horizon output field "${unknown}".`);
-  }
-  const output = Object.fromEntries(OUTPUT_PROPERTIES.map(property => [
-    property,
-    requireField(value[property], `Horizon ${property} output field`)
-  ]));
-  if (new Set(Object.values(output)).size !== OUTPUT_PROPERTIES.length) {
-    throw new Error("Horizon output fields must be distinct.");
-  }
-  return output;
-}
-
-function validatePalette(value = {}) {
-  if (!isPlainObject(value)) {
-    throw new TypeError("Horizon palette must be a plain object.");
-  }
-  const unknown = Object.keys(value).find(
-    property => !["positive", "negative"].includes(property)
-  );
-  if (unknown !== undefined) {
-    throw new Error(`Unknown Horizon palette property "${unknown}".`);
-  }
-  return {
-    positive: normalizePalette(value.positive ?? "blues"),
-    negative: normalizePalette(value.negative ?? "reds")
-  };
-}
-
-function validateResolved(value) {
-  if (!isPlainObject(value) || Object.keys(value).some(key => key !== "extents")) {
-    throw new TypeError("Horizon resolved provenance must contain only extents.");
-  }
-  if (!Array.isArray(value.extents) || value.extents.length === 0) {
-    throw new TypeError("Horizon resolved extents must be a non-empty array.");
-  }
-  for (const [index, entry] of value.extents.entries()) {
-    if (
-      !isPlainObject(entry) ||
-      Object.keys(entry).some(key => !["group", "extent", "bandHeight"].includes(key)) ||
-      !Number.isFinite(entry.extent) ||
-      entry.extent < 0 ||
-      !Number.isFinite(entry.bandHeight) ||
-      entry.bandHeight < 0
-    ) {
-      throw new TypeError(`Horizon resolved extent ${index} is invalid.`);
-    }
-    if (Object.hasOwn(entry, "group") && !isNominalValue(entry.group)) {
-      throw new TypeError(`Horizon resolved group ${index} must be nominal.`);
-    }
-  }
-  return value;
-}
-
-export function requestedHorizonTransform(transform) {
-  const { resolved: _resolved, ...requested } = transform;
-  void _resolved;
-  return requested;
-}
-
-export function validateHorizonTransform(transform) {
-  if (!isPlainObject(transform)) {
-    throw new TypeError("Horizon transform must be a plain object.");
-  }
-  const supported = [
-    "type", "x", "y", "groupBy", "bands", "baseline", "extent",
-    "resolve", "missing", "overflow", "palette", "as", "resolved"
-  ];
-  const unknown = Object.keys(transform).find(key => !supported.includes(key));
-  if (unknown !== undefined) {
-    throw new Error(`Unknown Horizon transform property "${unknown}".`);
-  }
-  if (transform.type !== "horizon") {
-    throw new Error(`Unsupported Horizon transform "${transform.type}".`);
-  }
-  const x = validateEncoding(transform.x, "x");
-  const y = validateEncoding(transform.y, "y");
-  if (x.field === y.field) {
-    throw new Error("Horizon x and y fields must differ.");
-  }
-  if (transform.groupBy !== undefined) {
-    requireField(transform.groupBy, "Horizon groupBy");
-    if ([x.field, y.field].includes(transform.groupBy)) {
-      throw new Error("Horizon groupBy must differ from x and y fields.");
-    }
-  }
-  if (!Number.isInteger(transform.bands) || transform.bands <= 0) {
-    throw new RangeError("Horizon bands must be a positive integer.");
-  }
-  validateGeneratedItemLimit(transform.bands, "Horizon bands");
-  if (!Number.isFinite(transform.baseline)) {
-    throw new TypeError("Horizon baseline must be finite.");
-  }
-  if (
-    transform.extent !== "auto" &&
-    (!Number.isFinite(transform.extent) || transform.extent <= 0)
-  ) {
-    throw new RangeError('Horizon extent must be "auto" or a positive number.');
-  }
-  if (!HORIZON_RESOLUTIONS.includes(transform.resolve)) {
-    throw new Error(`Unknown Horizon resolve "${transform.resolve}".`);
-  }
-  if (!HORIZON_MISSING_POLICIES.includes(transform.missing)) {
-    throw new Error(`Unknown Horizon missing policy "${transform.missing}".`);
-  }
-  if (!HORIZON_OVERFLOW_POLICIES.includes(transform.overflow)) {
-    throw new Error(`Unknown Horizon overflow policy "${transform.overflow}".`);
-  }
-  const palette = validatePalette(transform.palette);
-  for (const [sign, value] of Object.entries(palette)) {
-    if (value.count !== undefined && value.count !== transform.bands) {
-      throw new Error(
-        `Horizon ${sign} palette count must equal bands (${transform.bands}).`
-      );
-    }
-  }
-  const as = validateOutputFields(transform.as);
-  if (transform.groupBy !== undefined && Object.values(as).includes(transform.groupBy)) {
-    throw new Error("Horizon output fields must not collide with groupBy.");
-  }
-  if (transform.resolved !== undefined) validateResolved(transform.resolved);
-  return cloneAndFreeze({
-    ...transform,
-    x,
-    y,
-    palette,
-    as
-  });
-}
-
-function orderedX(value, encoding, rowIndex) {
-  if (encoding.fieldType === "temporal") {
-    return normalizeTemporalValue(value, encoding.field, rowIndex, encoding.temporalUnit);
-  }
-  if (!Number.isFinite(value)) {
-    throw new TypeError(
-      `Horizon x field "${encoding.field}" must contain finite numbers at row ${rowIndex}.`
-    );
-  }
-  return value;
-}
-
-function groupRows(rows, transform) {
-  const groups = [];
-  const indexed = new Map();
-  for (const [sourceRowIndex, row] of rows.entries()) {
-    if (!isPlainObject(row)) {
-      throw new TypeError(`Horizon row ${sourceRowIndex} must be a plain object.`);
-    }
-    const group = transform.groupBy === undefined ? undefined : row[transform.groupBy];
-    if (transform.groupBy !== undefined && !isNominalValue(group)) {
-      throw new TypeError(
-        `Horizon groupBy field "${transform.groupBy}" must contain nominal values at row ${sourceRowIndex}.`
-      );
-    }
-    const key = transform.groupBy === undefined
-      ? "__horizon_ungrouped__"
-      : `${typeof group}:${String(group)}`;
-    if (!indexed.has(key)) {
-      const entry = { group, groupIndex: groups.length, rows: [] };
-      indexed.set(key, entry);
-      groups.push(entry);
-    }
-    const y = row[transform.y.field];
-    const missing = !Number.isFinite(y);
-    if (missing && transform.missing === "error") {
-      throw new Error(
-        `Horizon y field "${transform.y.field}" is missing at source row ${sourceRowIndex}.`
-      );
-    }
-    indexed.get(key).rows.push({
-      sourceRowIndex,
-      x: orderedX(row[transform.x.field], transform.x, sourceRowIndex),
-      y,
-      missing
-    });
-  }
-  for (const entry of groups) {
-    entry.rows.sort((left, right) =>
-      left.x - right.x || left.sourceRowIndex - right.sourceRowIndex
-    );
-    for (let index = 1; index < entry.rows.length; index += 1) {
-      if (entry.rows[index - 1].x === entry.rows[index].x) {
-        throw new Error(
-          `Horizon group ${JSON.stringify(entry.group ?? null)} has duplicate x value ${entry.rows[index].x}.`
-        );
-      }
-    }
-  }
-  return groups;
-}
-
-function splitSegments(rows, baseline) {
-  const segments = [];
-  let current = [];
-  const flush = () => {
-    if (current.length > 0) segments.push(current);
-    current = [];
-  };
-  for (const row of rows) {
-    if (row.missing) {
-      flush();
-      continue;
-    }
-    current.push({
-      ...row,
-      signed: requireFiniteResult(
-        row.y - baseline,
-        "Horizon signed deviation"
-      ),
-      interpolated: false
-    });
-  }
-  flush();
-  return segments;
-}
-
-function insertCrossings(points, baseline) {
-  if (points.length < 2) return points.map(point => ({ ...point }));
-  const output = [{ ...points[0] }];
-  for (let index = 1; index < points.length; index += 1) {
-    const left = points[index - 1];
-    const right = points[index];
-    if (left.signed * right.signed < 0) {
-      const fraction = inverseLerp(baseline, left.y, right.y);
-      output.push({
-        sourceRowIndex: undefined,
-        x: interpolateNumber(left.x, right.x, fraction),
-        y: baseline,
-        missing: false,
-        signed: 0,
-        interpolated: true,
-        leftSourceRowIndex: left.sourceRowIndex,
-        rightSourceRowIndex: right.sourceRowIndex,
-        fraction
-      });
-    }
-    output.push({ ...right });
-  }
-  return output;
-}
-
-function pointSign(value) {
-  return value > 0 ? "positive" : value < 0 ? "negative" : "zero";
-}
-
-function runsForSign(points, desired) {
-  const runs = [];
-  let current = [];
-  let pendingZeros = [];
-  const flush = () => {
-    if (current.some(point => pointSign(point.signed) === desired)) {
-      runs.push(current);
-    }
-    current = [];
-  };
-  for (const point of points) {
-    const sign = pointSign(point.signed);
-    if (sign === desired) {
-      if (current.length === 0 && pendingZeros.length > 0) {
-        current.push(...pendingZeros);
-      }
-      current.push(point);
-      pendingZeros = [];
-    } else if (sign === "zero") {
-      if (current.length > 0) {
-        current.push(point);
-        flush();
-      }
-      pendingZeros = [point];
-    } else {
-      flush();
-      pendingZeros = [];
-    }
-  }
-  flush();
-  return runs;
-}
-
-function maximumMagnitude(group) {
-  let maximum = 0;
-  for (const segment of group.segments ?? [group]) {
-    for (const point of segment) {
-      maximum = Math.max(maximum, Math.abs(point.signed));
-    }
-  }
-  return maximum;
-}
-
-function resolvedExtents(groups, transform) {
-  if (transform.extent !== "auto") return groups.map(() => transform.extent);
-  if (transform.resolve === "shared") {
-    let shared = 0;
-    for (const group of groups) shared = Math.max(shared, maximumMagnitude(group));
-    return groups.map(() => shared);
-  }
-  return groups.map(maximumMagnitude);
-}
-
-function validateOutputBudget(groups, extents, transform) {
-  let count = 0;
-  for (const [groupIndex, group] of groups.entries()) {
-    const extent = extents[groupIndex];
-    if (extent === 0) continue;
-    const bandHeight = extent / transform.bands;
-    if (!(bandHeight > 0) || !Number.isFinite(bandHeight)) {
-      throw new RangeError(
-        "Horizon band height is outside the positive finite numeric range."
-      );
-    }
-    for (const sign of ["negative", "positive"]) {
-      for (const segment of group.segments) {
-        for (const run of runsForSign(segment, sign)) {
-          const magnitude = maximumMagnitude(run);
-          count += Math.min(
-            transform.bands,
-            Math.ceil(Math.min(magnitude, extent) / bandHeight)
-          ) * run.length;
-          validateGeneratedItemLimit(count, "Horizon generated row count");
-        }
-      }
-    }
-  }
-}
-
-function seriesForGroup(group, extent, transform) {
-  if (extent === 0) return [];
-  const bandHeight = extent / transform.bands;
-  const output = [];
-  for (const sign of ["negative", "positive"]) {
-    const runs = [];
-    let segmentIndex = 0;
-    for (const source of group.segments) {
-      for (const points of runsForSign(source, sign)) {
-        runs.push({ points, segmentIndex });
-        segmentIndex += 1;
-      }
-    }
-    for (let bandIndex = 0; bandIndex < transform.bands; bandIndex += 1) {
-      for (const run of runs) {
-        const points = run.points.map(point => {
-          const rawMagnitude = Math.abs(point.signed);
-          if (rawMagnitude > extent && transform.overflow === "error") {
-            throw new RangeError(
-              `Horizon magnitude ${rawMagnitude} exceeds extent ${extent}.`
-            );
-          }
-          const magnitude = Math.min(rawMagnitude, extent);
-          const amplitude = Math.min(
-            bandHeight,
-            Math.max(0, magnitude - bandIndex * bandHeight)
-          );
-          return {
-            ...point,
-            magnitude,
-            rawMagnitude,
-            amplitude,
-            fraction: amplitude / bandHeight,
-            overflowed: rawMagnitude > extent
-          };
-        });
-        if (points.some(point => point.amplitude > 0)) {
-          const groupIdentity = transform.groupBy === undefined
-            ? null
-            : group.group;
-          output.push({
-            group: group.group,
-            groupIndex: group.groupIndex,
-            sign,
-            bandIndex,
-            segmentIndex: run.segmentIndex,
-            seriesKey: JSON.stringify([
-              groupIdentity,
-              sign,
-              bandIndex,
-              run.segmentIndex
-            ]),
-            colorKey: `${sign}:${bandIndex}`,
-            bandHeight,
-            points
-          });
-        }
-      }
-    }
-  }
-  return output;
-}
-
-function generatedRows(series, transform) {
-  return series.flatMap(item => item.points.map(point => ({
-    ...(transform.groupBy === undefined
-      ? {}
-      : { [transform.groupBy]: item.group }),
-    [transform.as.x]: point.x,
-    [transform.as.lower]: 0,
-    [transform.as.upper]: point.fraction,
-    [transform.as.group]: item.seriesKey,
-    [transform.as.color]: item.colorKey,
-    [transform.as.sign]: item.sign,
-    [transform.as.band]: item.bandIndex,
-    [transform.as.segment]: item.segmentIndex
-  })));
-}
-
-export function deriveHorizon(rows, requested) {
-  if (!Array.isArray(rows)) {
-    throw new TypeError("Horizon values must be an array.");
-  }
-  if (rows.length === 0) {
-    throw new Error("Horizon requires at least one source row.");
-  }
-  const transform = validateHorizonTransform(requested);
-  const grouped = groupRows(rows, transform).map(group => ({
-    ...group,
-    segments: splitSegments(group.rows, transform.baseline).map(segment =>
-      insertCrossings(segment, transform.baseline)
-    )
-  }));
-  if (!grouped.some(group => group.rows.some(row => !row.missing))) {
-    throw new Error("Horizon requires at least one finite y value.");
-  }
-  const extents = resolvedExtents(grouped, transform);
-  validateOutputBudget(grouped, extents, transform);
-  const groups = grouped.map((group, index) => ({
-    ...(transform.groupBy === undefined ? {} : { group: group.group }),
-    extent: extents[index],
-    bandHeight: extents[index] / transform.bands
-  }));
-  const series = grouped.flatMap((group, index) =>
-    seriesForGroup(group, extents[index], transform)
-  );
-  return cloneAndFreeze({
-    transform: requestedHorizonTransform(transform),
-    resolved: { extents: groups },
-    groups,
-    series,
-    values: generatedRows(series, transform)
-  });
-}
+import{cloneAndFreeze as x,isPlainObject as a}from"../core/immutable.js";import{validateGeneratedItemLimit as m,validateNonEmptyString as g}from"../core/validation.js";import{normalizePalette as z}from"./palettes.js";import{interpolateNumber as O,inverseLerp as I}from"./numeric.js";import{requireFiniteResult as T}from"./numeric.js";import{isNominalValue as v,normalizeTemporalValue as R,resolveTemporalUnit as j}from"./scales/index.js";const B=Object.freeze(["shared","independent"]),N=Object.freeze(["break","error"]),S=Object.freeze(["clip","error"]),k=Object.freeze(["field","fieldType","temporalUnit"]),w=Object.freeze(["x","lower","upper","group","color","sign","band","segment"]);function H(e,o){if(!a(e))throw new TypeError(`Horizon ${o} encoding must be a plain object.`);const n=Object.keys(e).find(u=>!k.includes(u));if(n!==void 0)throw new Error(`Unknown Horizon ${o} encoding property "${n}".`);const t=g(e.field,`Horizon ${o} field`),r=e.fieldType??"quantitative",i=o==="x";if(r!=="quantitative"&&(!i||r!=="temporal"))throw new Error(`Horizon ${o} fieldType must be quantitative${i?" or temporal":""}.`);const s=j(e,r);return{field:t,fieldType:r,...s===void 0?{}:{temporalUnit:s}}}function M(e){if(!a(e))throw new TypeError("Horizon as must be a plain object.");const o=Object.keys(e).find(t=>!w.includes(t));if(o!==void 0)throw new Error(`Unknown Horizon output field "${o}".`);const n=Object.fromEntries(w.map(t=>[t,g(e[t],`Horizon ${t} output field`)]));if(new Set(Object.values(n)).size!==w.length)throw new Error("Horizon output fields must be distinct.");return n}function U(e={}){if(!a(e))throw new TypeError("Horizon palette must be a plain object.");const o=Object.keys(e).find(n=>!["positive","negative"].includes(n));if(o!==void 0)throw new Error(`Unknown Horizon palette property "${o}".`);return{positive:z(e.positive??"blues"),negative:z(e.negative??"reds")}}function F(e){if(!a(e)||Object.keys(e).some(o=>o!=="extents"))throw new TypeError("Horizon resolved provenance must contain only extents.");if(!Array.isArray(e.extents)||e.extents.length===0)throw new TypeError("Horizon resolved extents must be a non-empty array.");for(const[o,n]of e.extents.entries()){if(!a(n)||Object.keys(n).some(t=>!["group","extent","bandHeight"].includes(t))||!Number.isFinite(n.extent)||n.extent<0||!Number.isFinite(n.bandHeight)||n.bandHeight<0)throw new TypeError(`Horizon resolved extent ${o} is invalid.`);if(Object.hasOwn(n,"group")&&!v(n.group))throw new TypeError(`Horizon resolved group ${o} must be nominal.`)}return e}function _(e){const{resolved:o,...n}=e;return n}function P(e){if(!a(e))throw new TypeError("Horizon transform must be a plain object.");const o=["type","x","y","groupBy","bands","baseline","extent","resolve","missing","overflow","palette","as","resolved"],n=Object.keys(e).find(u=>!o.includes(u));if(n!==void 0)throw new Error(`Unknown Horizon transform property "${n}".`);if(e.type!=="horizon")throw new Error(`Unsupported Horizon transform "${e.type}".`);const t=H(e.x,"x"),r=H(e.y,"y");if(t.field===r.field)throw new Error("Horizon x and y fields must differ.");if(e.groupBy!==void 0&&(g(e.groupBy,"Horizon groupBy"),[t.field,r.field].includes(e.groupBy)))throw new Error("Horizon groupBy must differ from x and y fields.");if(!Number.isInteger(e.bands)||e.bands<=0)throw new RangeError("Horizon bands must be a positive integer.");if(m(e.bands,"Horizon bands"),!Number.isFinite(e.baseline))throw new TypeError("Horizon baseline must be finite.");if(e.extent!=="auto"&&(!Number.isFinite(e.extent)||e.extent<=0))throw new RangeError('Horizon extent must be "auto" or a positive number.');if(!B.includes(e.resolve))throw new Error(`Unknown Horizon resolve "${e.resolve}".`);if(!N.includes(e.missing))throw new Error(`Unknown Horizon missing policy "${e.missing}".`);if(!S.includes(e.overflow))throw new Error(`Unknown Horizon overflow policy "${e.overflow}".`);const i=U(e.palette);for(const[u,d]of Object.entries(i))if(d.count!==void 0&&d.count!==e.bands)throw new Error(`Horizon ${u} palette count must equal bands (${e.bands}).`);const s=M(e.as);if(e.groupBy!==void 0&&Object.values(s).includes(e.groupBy))throw new Error("Horizon output fields must not collide with groupBy.");return e.resolved!==void 0&&F(e.resolved),x({...e,x:t,y:r,palette:i,as:s})}function q(e,o,n){if(o.fieldType==="temporal")return R(e,o.field,n,o.temporalUnit);if(!Number.isFinite(e))throw new TypeError(`Horizon x field "${o.field}" must contain finite numbers at row ${n}.`);return e}function L(e,o){const n=[],t=new Map;for(const[r,i]of e.entries()){if(!a(i))throw new TypeError(`Horizon row ${r} must be a plain object.`);const s=o.groupBy===void 0?void 0:i[o.groupBy];if(o.groupBy!==void 0&&!v(s))throw new TypeError(`Horizon groupBy field "${o.groupBy}" must contain nominal values at row ${r}.`);const u=o.groupBy===void 0?"__horizon_ungrouped__":`${typeof s}:${String(s)}`;if(!t.has(u)){const l={group:s,groupIndex:n.length,rows:[]};t.set(u,l),n.push(l)}const d=i[o.y.field],p=!Number.isFinite(d);if(p&&o.missing==="error")throw new Error(`Horizon y field "${o.y.field}" is missing at source row ${r}.`);t.get(u).rows.push({sourceRowIndex:r,x:q(i[o.x.field],o.x,r),y:d,missing:p})}for(const r of n){r.rows.sort((i,s)=>i.x-s.x||i.sourceRowIndex-s.sourceRowIndex);for(let i=1;i<r.rows.length;i+=1)if(r.rows[i-1].x===r.rows[i].x)throw new Error(`Horizon group ${JSON.stringify(r.group??null)} has duplicate x value ${r.rows[i].x}.`)}return n}function A(e,o){const n=[];let t=[];const r=()=>{t.length>0&&n.push(t),t=[]};for(const i of e){if(i.missing){r();continue}t.push({...i,signed:T(i.y-o,"Horizon signed deviation"),interpolated:!1})}return r(),n}function C(e,o){if(e.length<2)return e.map(t=>({...t}));const n=[{...e[0]}];for(let t=1;t<e.length;t+=1){const r=e[t-1],i=e[t];if(r.signed*i.signed<0){const s=I(o,r.y,i.y);n.push({sourceRowIndex:void 0,x:O(r.x,i.x,s),y:o,missing:!1,signed:0,interpolated:!0,leftSourceRowIndex:r.sourceRowIndex,rightSourceRowIndex:i.sourceRowIndex,fraction:s})}n.push({...i})}return n}function E(e){return e>0?"positive":e<0?"negative":"zero"}function $(e,o){const n=[];let t=[],r=[];const i=()=>{t.some(s=>E(s.signed)===o)&&n.push(t),t=[]};for(const s of e){const u=E(s.signed);u===o?(t.length===0&&r.length>0&&t.push(...r),t.push(s),r=[]):u==="zero"?(t.length>0&&(t.push(s),i()),r=[s]):(i(),r=[])}return i(),n}function h(e){let o=0;for(const n of e.segments??[e])for(const t of n)o=Math.max(o,Math.abs(t.signed));return o}function G(e,o){if(o.extent!=="auto")return e.map(()=>o.extent);if(o.resolve==="shared"){let n=0;for(const t of e)n=Math.max(n,h(t));return e.map(()=>n)}return e.map(h)}function K(e,o,n){let t=0;for(const[r,i]of e.entries()){const s=o[r];if(s===0)continue;const u=s/n.bands;if(!(u>0)||!Number.isFinite(u))throw new RangeError("Horizon band height is outside the positive finite numeric range.");for(const d of["negative","positive"])for(const p of i.segments)for(const l of $(p,d)){const c=h(l);t+=Math.min(n.bands,Math.ceil(Math.min(c,s)/u))*l.length,m(t,"Horizon generated row count")}}}function Z(e,o,n){if(o===0)return[];const t=o/n.bands,r=[];for(const i of["negative","positive"]){const s=[];let u=0;for(const d of e.segments)for(const p of $(d,i))s.push({points:p,segmentIndex:u}),u+=1;for(let d=0;d<n.bands;d+=1)for(const p of s){const l=p.points.map(c=>{const f=Math.abs(c.signed);if(f>o&&n.overflow==="error")throw new RangeError(`Horizon magnitude ${f} exceeds extent ${o}.`);const b=Math.min(f,o),y=Math.min(t,Math.max(0,b-d*t));return{...c,magnitude:b,rawMagnitude:f,amplitude:y,fraction:y/t,overflowed:f>o}});if(l.some(c=>c.amplitude>0)){const c=n.groupBy===void 0?null:e.group;r.push({group:e.group,groupIndex:e.groupIndex,sign:i,bandIndex:d,segmentIndex:p.segmentIndex,seriesKey:JSON.stringify([c,i,d,p.segmentIndex]),colorKey:`${i}:${d}`,bandHeight:t,points:l})}}}return r}function V(e,o){return e.flatMap(n=>n.points.map(t=>({...o.groupBy===void 0?{}:{[o.groupBy]:n.group},[o.as.x]:t.x,[o.as.lower]:0,[o.as.upper]:t.fraction,[o.as.group]:n.seriesKey,[o.as.color]:n.colorKey,[o.as.sign]:n.sign,[o.as.band]:n.bandIndex,[o.as.segment]:n.segmentIndex})))}function ee(e,o){if(!Array.isArray(e))throw new TypeError("Horizon values must be an array.");if(e.length===0)throw new Error("Horizon requires at least one source row.");const n=P(o),t=L(e,n).map(u=>({...u,segments:A(u.rows,n.baseline).map(d=>C(d,n.baseline))}));if(!t.some(u=>u.rows.some(d=>!d.missing)))throw new Error("Horizon requires at least one finite y value.");const r=G(t,n);K(t,r,n);const i=t.map((u,d)=>({...n.groupBy===void 0?{}:{group:u.group},extent:r[d],bandHeight:r[d]/n.bands})),s=t.flatMap((u,d)=>Z(u,r[d],n));return x({transform:_(n),resolved:{extents:i},groups:i,series:s,values:V(s,n)})}function ne(e){if(e?.type!=="horizon")return;const o=[...new Set((e.resolved?.extents??[]).map(i=>i.bandHeight))],n=o.length===1?o[0]:void 0,t=i=>String(Number(i.toPrecision(3))),r=[];for(const i of["negative","positive"])for(let s=0;s<e.bands;s+=1){const u=i==="negative"?e.baseline-(s+1)*n:e.baseline+s*n,d=i==="negative"?e.baseline-s*n:e.baseline+(s+1)*n;r.push({value:`${i}:${s}`,label:n===void 0?`${i==="negative"?"Below":"Above"} baseline \xB7 band ${s+1}/${e.bands}`:`${t(u)} \u2013 ${t(d)}`})}return{title:e.y.field,labelMap:r}}export{N as HORIZON_MISSING_POLICIES,S as HORIZON_OVERFLOW_POLICIES,B as HORIZON_RESOLUTIONS,ee as deriveHorizon,ne as horizonLegendPresentation,_ as requestedHorizonTransform,P as validateHorizonTransform};

package/src/grammar/interval.js

@@ -251,15 +251,16 @@ export function deriveInterval(rows, transform) {
   }
   const bootstrapSampler = bootstrapMethod === undefined ? undefined : createBootstrapMeanSampler(bootstrapMethod);
 
+  const outputValue = bootstrapSampler === undefined ? stableDecimal : requireFiniteResult;
   const output = [];
   for (const group of groups.values()) {
     const result = deriveGroup(group.values, transform, bootstrapSampler);
     if (result === undefined) continue;
     output.push({
       ...group.fields,
-      [transform.as.center]: stableDecimal(result.center),
-      [transform.as.lower]: stableDecimal(result.lower),
-      [transform.as.upper]: stableDecimal(result.upper)
+      [transform.as.center]: outputValue(result.center),
+      [transform.as.lower]: outputValue(result.lower),
+      [transform.as.upper]: outputValue(result.upper)
     });
   }
   if (transform.missing === undefined) return cloneAndFreeze(output);

package/src/grammar/jitter.js

@@ -45,8 +45,8 @@ export function normalizePointJitterPolicy(options = {}) {
   if (!isPlainObject(options)) {
     throw new TypeError("Point jitter options must be a plain object.");
   }
-  if (!["x", "y"].includes(options.channel)) {
-    throw new Error('Point jitter channel must be "x" or "y".');
+  if (!["x", "y", "both"].includes(options.channel)) {
+    throw new Error('Point jitter channel must be "x", "y", or "both".');
   }
   const maxOffset = options.maxOffset;
   if (!isPlainObject(maxOffset)) {

package/src/grammar/legendSpacing.js

@@ -0,0 +1,45 @@
+import {validateNonNegativeFinite} from "../core/validation.js";
+
+export const LEGEND_SPACING_KEYS = Object.freeze(["rowPadding", "titlePadding"]);
+
+export function normalizeLegendSpacing(options) {
+  const result = {};
+  for (const key of LEGEND_SPACING_KEYS) {
+    if (options[key] === undefined) continue;
+    validateNonNegativeFinite(options[key], `Legend ${key}`);
+    result[key] = options[key];
+  }
+  return result;
+}
+
+// Reset removes an intent; an omitted/undefined edit preserves it. Normalizers
+// consume only numeric stored values, never the authoring-only reset token.
+export function patchLegendSpacing(config, options) {
+  const result = {...config};
+  for (const key of LEGEND_SPACING_KEYS) {
+    if (options[key] === undefined) continue;
+    if (options[key] === "auto") delete result[key];
+    else {
+      validateNonNegativeFinite(options[key], `Legend ${key}`);
+      result[key] = options[key];
+    }
+  }
+  return result;
+}
+
+export function prepareLegendSpacingEdit(config, options) {
+  const args = {...options};
+  for (const key of LEGEND_SPACING_KEYS) delete args[key];
+  return {previous:patchLegendSpacing(config, options), args};
+}
+
+export function validateLegendSpacing(kind, config) {
+  normalizeLegendSpacing(config);
+  if (LEGEND_SPACING_KEYS.some(key => config[key] !== undefined) && config.layout === "legacy-bottom") {
+    throw new Error('Legend rowPadding and titlePadding require layout "edge".');
+  }
+  if (config.rowPadding !== undefined && ["gradient", "strokeGradient"].includes(kind) &&
+      config.representation !== "symbols") {
+    throw new Error("Legend rowPadding requires an item-based legend.");
+  }
+}

package/src/grammar/lineMissing.js

@@ -0,0 +1,90 @@
+import { validateNonEmptyString } from "../core/validation.js";
+import { normalizeTemporalValue } from "./scales/fields.js";
+import { pathGroupFields, pathSeriesKey } from "./pathSeries.js";
+import { stableOrderPathValues } from "./pathOrder.js";
+
+export function validateLineMissing(value = "error") {
+  if (!["error", "break"].includes(value)) {
+    throw new Error('Line missing must be "error" or "break".');
+  }
+  return value;
+}
+
+export function validateLineMissingScope(layer) {
+  if (validateLineMissing(layer.mark?.missing) !== "break") return;
+  const encoding = layer.encoding ?? {};
+  if (encoding.parallel !== undefined || encoding.theta !== undefined ||
+      encoding.radius !== undefined || [encoding.x, encoding.y].some(position =>
+        position !== undefined && (position.aggregate !== undefined ||
+          position.bin !== undefined || !["quantitative", "temporal"].includes(position.fieldType)))) {
+    throw new Error("Line missing:break requires direct Cartesian quantitative/temporal positions.");
+  }
+}
+
+// Keep positional nulls as topology boundaries, not scale values or coerced zeros.
+export function readLinePosition(rows, encoding) {
+  const { field, fieldType, temporalUnit } = encoding;
+  validateNonEmptyString(field, "Line position field");
+  if (!["quantitative", "temporal"].includes(fieldType)) {
+    throw new Error("Line missing:break requires quantitative/temporal positions.");
+  }
+  if (!rows.some(row => Object.hasOwn(row, field))) {
+    throw new Error(`Line position field "${field}" does not exist.`);
+  }
+  const values = rows.map((row, index) => {
+    const value = row[field];
+    if (value == null) return null;
+    if (fieldType === "temporal") return normalizeTemporalValue(value, field, index, temporalUnit);
+    if (!Number.isFinite(value)) {
+      throw new TypeError(`Field "${field}" must contain a finite number at row ${index}.`);
+    }
+    return value;
+  });
+  if (!values.some(value => value !== null)) {
+    throw new Error(`Line position field "${field}" requires at least one nonmissing value.`);
+  }
+  return values;
+}
+
+// An unknown order coordinate has no sortable position: preserve it as a boundary.
+export function orderLineGapValues(values, orderValues, direction = "ascending") {
+  const result = [], run = [];
+  const flush = () => {
+    const ordered = stableOrderPathValues(run.map(item => item.value),
+      run.map(item => item.order), direction);
+    for (const value of ordered) result.push(value);
+    run.length = 0;
+  };
+  values.forEach((value, index) => {
+    if (orderValues[index] === null) {
+      flush(); result.push(value);
+    } else run.push({ value, order: orderValues[index] });
+  });
+  flush();
+  return result;
+}
+
+export function splitLineGapValues(values) {
+  const segments = [], run = [];
+  const flush = () => { if (run.length) segments.push(run.splice(0)); };
+  for (const value of values) {
+    if (value.x === null || value.y === null) flush();
+    else run.push(value);
+  }
+  flush();
+  return segments;
+}
+
+// Filtering painted runs must not delete the invisible separators and bridge them.
+export function retainLineGapBoundaries(rows, members, layer) {
+  if (layer?.mark?.type !== "line" || layer.mark.missing !== "break") return members;
+  const fields = pathGroupFields(layer);
+  const key = row => pathSeriesKey(fields.map(field => row[field]));
+  const selectedSeries = new Set([...members].map(key));
+  const result = new Set(members);
+  for (const row of rows) {
+    if ((row[layer.encoding.x.field] == null || row[layer.encoding.y.field] == null) &&
+        selectedSeries.has(key(row))) result.add(row);
+  }
+  return result;
+}