ggaction 0.0.21 → 0.0.22

package/src/grammar/lineSeries.js

@@ -1,376 +1 @@
-import { cloneAndFreeze } from "../core/immutable.js";
-import {
-  readNominalField,
-  readQuantitativeField,
-  readTemporalField
-} from "./scales/index.js";
-import {
-  aggregateRows,
-  isAggregate,
-  validateAggregateFieldType,
-  validateAggregateFieldValues
-} from "./aggregate.js";
-import { stableOrderPathValues } from "./pathOrder.js";
-import { finiteMidpoint } from "./numeric.js";
-import {
-  findHistogramBinIndex,
-  resolveHistogramBins
-} from "./histogram.js";
-import {
-  validatePathSeriesAppearance
-} from "./pathSeries.js";
-
-function requireLineEncoding(layer) {
-  if (layer?.mark?.type !== "line") {
-    throw new Error("Line series derivation requires a semantic line mark.");
-  }
-
-  const x = layer.encoding?.x;
-  const y = layer.encoding?.y;
-
-  if (x === undefined) {
-    throw new Error(`Line mark "${layer.id}" requires an x encoding.`);
-  }
-
-  const binnedAggregate =
-    x?.fieldType === "quantitative" &&
-    x.bin !== undefined &&
-    isAggregate(y?.aggregate);
-  const aggregateMode =
-    (["temporal", "nominal", "ordinal"].includes(x?.fieldType) && isAggregate(y?.aggregate)) ||
-    binnedAggregate;
-  const directNumericY =
-    ["quantitative", "nominal", "ordinal"].includes(x?.fieldType) &&
-    x.bin === undefined &&
-    y?.fieldType === "quantitative" &&
-    y.aggregate === undefined;
-  const directTemporal =
-    y?.aggregate === undefined &&
-    ((x?.fieldType === "temporal" && y?.fieldType === "quantitative") ||
-      (x?.fieldType === "quantitative" && y?.fieldType === "temporal"));
-  if (!aggregateMode && !directNumericY && !directTemporal) {
-    if (x?.fieldType === "temporal") {
-      throw new Error(
-        `Line mark "${layer.id}" requires a supported aggregate y encoding.`
-      );
-    }
-    throw new Error(
-      `Line mark "${layer.id}" requires categorical/temporal aggregate or compatible direct x/y encodings.`
-    );
-  }
-  if (aggregateMode) {
-    validateAggregateFieldType(y.aggregate, y.fieldType);
-  }
-  return {
-    x,
-    y,
-    isAggregate: aggregateMode,
-    binnedAggregate,
-    directRows: directTemporal || directNumericY,
-    directTemporal
-  };
-}
-
-function groupKey(values) {
-  return JSON.stringify(values);
-}
-
-function groupedSeries(groups, fields, dimensions) {
-  const id = groupKey(dimensions);
-  let series = groups.get(id);
-  if (series === undefined) {
-    series = {
-      key: Object.fromEntries(
-        fields.map((field, index) => [field, dimensions[index]])
-      ),
-      values: []
-    };
-    groups.set(id, series);
-  }
-  return series;
-}
-
-function freezeCartesianSeries(series, categoryOrder) {
-  const observedX = series.flatMap(item => item.values.map(value => value.x));
-  const observedSet = new Set(observedX);
-  if (categoryOrder !== undefined) {
-    const domain = new Set(categoryOrder);
-    if (observedX.some(value => !domain.has(value))) {
-      throw new Error("Line categorical x domain must contain every observed vertex.");
-    }
-  }
-  return cloneAndFreeze({
-    xValues: categoryOrder === undefined ? observedX : categoryOrder.filter(value => observedSet.has(value)),
-    yValues: series.flatMap(item => item.values.map(value => value.y)),
-    series
-  });
-}
-
-export function resolveLineBins(rows, layer, scale = {}) {
-  const x = layer?.encoding?.x;
-  if (
-    layer?.mark?.type !== "line" ||
-    x?.fieldType !== "quantitative" ||
-    x.bin === undefined
-  ) {
-    return undefined;
-  }
-  return resolveHistogramBins({
-    values: readQuantitativeField(rows, x.field),
-    bin: x.bin,
-    domain: scale.domain ?? "auto",
-    nice: scale.nice ?? true,
-    zero: scale.zero ?? false
-  });
-}
-
-function deriveCartesianLineSeries(rows, layer, options = {}) {
-  const { x, y, isAggregate, binnedAggregate, directRows, directTemporal } =
-    requireLineEncoding(layer);
-  if (isAggregate) {
-    validateAggregateFieldValues(rows, y.field, y.fieldType);
-  }
-  const categorical = ["nominal", "ordinal"].includes(x.fieldType);
-  const xValues = categorical ? readNominalField(rows, x.field)
-    : x.fieldType === "temporal"
-    ? readTemporalField(rows, x.field, x.temporalUnit)
-    : readQuantitativeField(rows, x.field);
-  const yValues = isAggregate
-    ? undefined
-    : y.fieldType === "temporal"
-      ? readTemporalField(rows, y.field, y.temporalUnit)
-      : readQuantitativeField(rows, y.field);
-  const categoryOrder = categorical ? options.xDomain ?? [...new Set(xValues)] : undefined;
-  const ranks = new Map(categoryOrder?.map((value, index) => [value, index]));
-  const compareX = categorical
-    ? (left, right) => ranks.get(left.x) - ranks.get(right.x)
-    : (left, right) => left.x - right.x;
-  const seriesFields = validatePathSeriesAppearance(rows, layer);
-  const binBoundaries = binnedAggregate
-    ? options.xBinBoundaries ?? resolveLineBins(rows, layer).boundaries
-    : undefined;
-
-  const pathOrder = layer.encoding?.pathOrder;
-  if (pathOrder !== undefined) {
-    if (isAggregate) {
-      throw new Error(
-        `Line mark "${layer.id}" cannot combine aggregate y and path order.`
-      );
-    }
-    const orderValues = readQuantitativeField(rows, pathOrder.field);
-    const groups = new Map();
-    for (let index = 0; index < rows.length; index += 1) {
-      const dimensions = seriesFields.map(
-        field => rows[index][field]
-      );
-      const series = groupedSeries(groups, seriesFields, dimensions);
-      series.values.push({ x: xValues[index], y: yValues[index] });
-      series.orderValues ??= [];
-      series.orderValues.push(orderValues[index]);
-    }
-    const series = [...groups.values()].flatMap(item => {
-      const values = stableOrderPathValues(
-        item.values,
-        item.orderValues,
-        pathOrder.order
-      );
-      return [{ key: item.key, values }];
-    });
-    if (series.length === 0) {
-      throw new Error(
-        `Line series on mark "${layer.id}" requires at least two ordered points.`
-      );
-    }
-    return freezeCartesianSeries(series, categoryOrder);
-  }
-
-  if (directRows) {
-    const groups = new Map();
-    for (let index = 0; index < rows.length; index += 1) {
-      const dimensions = seriesFields.map(
-        field => rows[index][field]
-      );
-      const series = groupedSeries(groups, seriesFields, dimensions);
-      series.values.push({ x: xValues[index], y: yValues[index] });
-    }
-    const orderBy = directTemporal && y.fieldType === "temporal" ? "y" : "x";
-    const series = [...groups.values()].flatMap(item => {
-      const values = item.values.sort(
-        orderBy === "x" ? compareX : (left, right) => left.y - right.y
-      );
-      return [{ key: item.key, values }];
-    });
-    if (series.length === 0) {
-      throw new Error(
-        `Line series on mark "${layer.id}" requires at least two direct points.`
-      );
-    }
-    return freezeCartesianSeries(series, categoryOrder);
-  }
-  const aggregateGroups = new Map();
-
-  for (let index = 0; index < rows.length; index += 1) {
-    const dimensions = seriesFields.map(
-      field => rows[index][field]
-    );
-    const binIndex = binnedAggregate
-      ? findHistogramBinIndex(xValues[index], binBoundaries)
-      : undefined;
-    if (binIndex === -1) continue;
-    const position = binnedAggregate
-      ? finiteMidpoint(
-          binBoundaries[binIndex],
-          binBoundaries[binIndex + 1]
-        )
-      : xValues[index];
-    const key = groupKey([binnedAggregate ? binIndex : position, ...dimensions]);
-    const group = aggregateGroups.get(key) ?? {
-      x: position,
-      dimensions,
-      rows: []
-    };
-
-    group.rows.push(rows[index]);
-    aggregateGroups.set(key, group);
-  }
-
-  if (aggregateGroups.size === 0) {
-    throw new Error(`Line mark "${layer.id}" has no values to aggregate.`);
-  }
-
-  const seriesGroups = new Map();
-
-  for (const group of aggregateGroups.values()) {
-    const value = aggregateRows(group.rows, y.field, y.aggregate);
-    if (value === undefined) continue;
-    const series = groupedSeries(
-      seriesGroups,
-      seriesFields,
-      group.dimensions
-    );
-
-    series.values.push({
-      x: group.x,
-      y: value
-    });
-  }
-
-  const series = [...seriesGroups.values()].flatMap(item => {
-    const values = item.values.sort(compareX);
-
-    if (values.length < 2) {
-      return [];
-    }
-
-    return [{ key: item.key, values }];
-  });
-
-  if (series.length === 0) {
-    throw new Error(
-      `Line series on mark "${layer.id}" requires at least two aggregate points.`
-    );
-  }
-
-  return freezeCartesianSeries(series, categoryOrder);
-}
-
-function requirePolarLineEncoding(layer) {
-  if (layer?.mark?.type !== "line") {
-    throw new Error("Polar line series derivation requires a semantic line mark.");
-  }
-  const theta = layer.encoding?.theta;
-  const radius = layer.encoding?.radius;
-  if (theta === undefined || radius === undefined) {
-    throw new Error(
-      `Polar line mark "${layer.id}" requires theta and radius encodings.`
-    );
-  }
-  if (!["quantitative", "temporal", "ordinal", "nominal"].includes(
-    theta.fieldType
-  )) {
-    throw new Error(
-      `Polar line mark "${layer.id}" has unsupported theta field type.`
-    );
-  }
-  if (radius.fieldType !== "quantitative") {
-    throw new Error(
-      `Polar line mark "${layer.id}" requires a quantitative radius encoding.`
-    );
-  }
-  return { theta, radius };
-}
-
-function readThetaValues(rows, encoding) {
-  if (["nominal", "ordinal"].includes(encoding.fieldType)) {
-    return readNominalField(rows, encoding.field);
-  }
-  return encoding.fieldType === "temporal"
-    ? readTemporalField(rows, encoding.field, encoding.temporalUnit)
-    : readQuantitativeField(rows, encoding.field);
-}
-
-function thetaOrder(values, fieldType, domain) {
-  if (!["nominal", "ordinal"].includes(fieldType)) return values;
-  const order = domain ?? [...new Set(values)];
-  const indices = new Map(order.map((value, index) => [value, index]));
-  for (const value of values) {
-    if (!indices.has(value)) {
-      throw new Error(`Polar line theta domain does not contain "${value}".`);
-    }
-  }
-  return values.map(value => indices.get(value));
-}
-
-export function derivePolarLineSeries(rows, layer, { thetaDomain } = {}) {
-  if (layer.encoding?.pathOrder !== undefined) {
-    throw new Error(
-      `Polar line mark "${layer.id}" does not support path order.`
-    );
-  }
-  const { theta, radius } = requirePolarLineEncoding(layer);
-  const thetaValues = readThetaValues(rows, theta);
-  const radiusValues = readQuantitativeField(rows, radius.field);
-  const sortValues = thetaOrder(thetaValues, theta.fieldType, thetaDomain);
-  const seriesFields = validatePathSeriesAppearance(rows, layer);
-  const groups = new Map();
-
-  for (let index = 0; index < rows.length; index += 1) {
-    const dimensions = seriesFields.map(
-      field => rows[index][field]
-    );
-    const series = groupedSeries(groups, seriesFields, dimensions);
-    series.values.push({
-      theta: thetaValues[index],
-      radius: radiusValues[index],
-      order: sortValues[index],
-      sourceIndex: index
-    });
-  }
-
-  const series = [...groups.values()].flatMap(item => {
-    const values = item.values.sort(
-      (left, right) => left.order - right.order ||
-        left.sourceIndex - right.sourceIndex
-    );
-    return values.length < 2 ? [] : [{ key: item.key, values }];
-  });
-  if (series.length === 0) {
-    throw new Error(
-      `Polar line series on mark "${layer.id}" requires at least two points.`
-    );
-  }
-  return cloneAndFreeze({
-    thetaFieldType: theta.fieldType,
-    thetaValues: series.flatMap(item => item.values.map(value => value.theta)),
-    radiusValues: series.flatMap(item => item.values.map(value => value.radius)),
-    series
-  });
-}
-
-export function deriveLineSeries(rows, layer, options) {
-  const polar = layer?.encoding?.theta !== undefined ||
-    layer?.encoding?.radius !== undefined;
-  return polar
-    ? derivePolarLineSeries(rows, layer, options)
-    : deriveCartesianLineSeries(rows, layer, options);
-}
+import{cloneAndFreeze as $}from"../core/immutable.js";import{readLinePosition as R,validateLineMissingScope as N,orderLineGapValues as X,splitLineGapValues as j}from"./lineMissing.js";import{readNominalField as U,readQuantitativeField as k,readTemporalField as P}from"./scales/index.js";import{aggregateRows as D,isAggregate as C,validateAggregateFieldType as Q,validateAggregateFieldValues as Y}from"./aggregate.js";import{stableOrderPathValues as _}from"./pathOrder.js";import{finiteMidpoint as J}from"./numeric.js";import{findHistogramBinIndex as W,resolveHistogramBins as Z}from"./histogram.js";import{validatePathSeriesAppearance as I,pathSeriesKey as H}from"./pathSeries.js";function ee(e){if(e?.mark?.type!=="line")throw new Error("Line series derivation requires a semantic line mark.");const n=e.encoding?.x,i=e.encoding?.y;if(n===void 0)throw new Error(`Line mark "${e.id}" requires an x encoding.`);const a=n?.fieldType==="quantitative"&&n.bin!==void 0&&C(i?.aggregate),r=["temporal","nominal","ordinal"].includes(n?.fieldType)&&C(i?.aggregate)||a,s=["quantitative","nominal","ordinal"].includes(n?.fieldType)&&n.bin===void 0&&i?.fieldType==="quantitative"&&i.aggregate===void 0,c=i?.aggregate===void 0&&(n?.fieldType==="temporal"&&i?.fieldType==="quantitative"||n?.fieldType==="quantitative"&&i?.fieldType==="temporal");if(!r&&!s&&!c)throw n?.fieldType==="temporal"?new Error(`Line mark "${e.id}" requires a supported aggregate y encoding.`):new Error(`Line mark "${e.id}" requires categorical/temporal aggregate or compatible direct x/y encodings.`);return r&&Q(i.aggregate,i.fieldType),{x:n,y:i,isAggregate:r,binnedAggregate:a,directRows:c||s,directTemporal:c}}function q(e,n,i){const a=H(i);let r=e.get(a);return r===void 0&&(r={key:Object.fromEntries(n.map((s,c)=>[s,i[c]])),values:[]},e.set(a,r)),r}function A(e,n){const i=e.flatMap(r=>r.values.map(s=>s.x)),a=new Set(i);if(n!==void 0){const r=new Set(n);if(i.some(s=>!r.has(s)))throw new Error("Line categorical x domain must contain every observed vertex.")}return $({xValues:n===void 0?i:n.filter(r=>a.has(r)),yValues:e.flatMap(r=>r.values.map(s=>s.y)),series:e})}function ne(e,n,i={}){const a=n?.encoding?.x;if(!(n?.mark?.type!=="line"||a?.fieldType!=="quantitative"||a.bin===void 0))return Z({values:k(e,a.field),bin:a.bin,domain:i.domain??"auto",nice:i.nice??!0,zero:i.zero??!1})}function ie(e,n,i={}){const{x:a,y:r,isAggregate:s,binnedAggregate:c,directRows:M,directTemporal:V}=ee(n);if(n.mark.missing==="break"){const t=R(e,a),d=R(e,r),f=I(e,n,i.scales),o=n.encoding?.pathOrder,g=o===void 0?V&&r.fieldType==="temporal"?d:t:k(e,o.field),m=new Map;for(let l=0;l<e.length;l+=1){const L=q(m,f,f.map(O=>e[l][O]));L.values.push({x:t[l],y:d[l],sourceIndex:l}),(L.orderValues??=[]).push(g[l])}const v=[...m.values()].flatMap(l=>{const L=X(l.values,l.orderValues,o?.order);return j(L).map(z=>({key:l.key,values:z.map(({sourceIndex:G,...K})=>K),sourceIndices:z.map(G=>G.sourceIndex)}))});return $({xValues:t.filter(l=>l!==null),yValues:d.filter(l=>l!==null),series:v})}s&&Y(e,r.field,r.fieldType);const y=["nominal","ordinal"].includes(a.fieldType),h=y?U(e,a.field):a.fieldType==="temporal"?P(e,a.field,a.temporalUnit):k(e,a.field),u=s?void 0:r.fieldType==="temporal"?P(e,r.field,r.temporalUnit):k(e,r.field),p=y?i.xDomain??[...new Set(h)]:void 0,w=new Map(p?.map((t,d)=>[t,d])),x=y?(t,d)=>w.get(t.x)-w.get(d.x):(t,d)=>t.x-d.x,T=I(e,n,i.scales),b=c?i.xBinBoundaries??ne(e,n).boundaries:void 0,S=n.encoding?.pathOrder;if(S!==void 0){if(s)throw new Error(`Line mark "${n.id}" cannot combine aggregate y and path order.`);const t=k(e,S.field),d=new Map;for(let o=0;o<e.length;o+=1){const g=T.map(v=>e[o][v]),m=q(d,T,g);m.values.push({x:h[o],y:u[o]}),m.orderValues??=[],m.orderValues.push(t[o])}const f=[...d.values()].flatMap(o=>{const g=_(o.values,o.orderValues,S.order);return[{key:o.key,values:g}]});if(f.length===0)throw new Error(`Line series on mark "${n.id}" requires at least two ordered points.`);return A(f,p)}if(M){const t=new Map;for(let o=0;o<e.length;o+=1){const g=T.map(v=>e[o][v]);q(t,T,g).values.push({x:h[o],y:u[o]})}const d=V&&r.fieldType==="temporal"?"y":"x",f=[...t.values()].flatMap(o=>{const g=o.values.sort(d==="x"?x:(m,v)=>m.y-v.y);return[{key:o.key,values:g}]});if(f.length===0)throw new Error(`Line series on mark "${n.id}" requires at least two direct points.`);return A(f,p)}const E=new Map;for(let t=0;t<e.length;t+=1){const d=T.map(v=>e[t][v]),f=c?W(h[t],b):void 0;if(f===-1)continue;const o=c?J(b[f],b[f+1]):h[t],g=H([c?f:o,...d]),m=E.get(g)??{x:o,dimensions:d,rows:[]};m.rows.push(e[t]),E.set(g,m)}if(E.size===0)throw new Error(`Line mark "${n.id}" has no values to aggregate.`);const F=new Map;for(const t of E.values()){const d=D(t.rows,r.field,r.aggregate);if(d===void 0)continue;q(F,T,t.dimensions).values.push({x:t.x,y:d})}const B=[...F.values()].flatMap(t=>{const d=t.values.sort(x);return d.length<(i.allowSingleton===!0?1:2)?[]:[{key:t.key,values:d}]});if(B.length===0)throw new Error(`Line series on mark "${n.id}" requires at least two aggregate points.`);return A(B,p)}function re(e){if(e?.mark?.type!=="line")throw new Error("Polar line series derivation requires a semantic line mark.");const n=e.encoding?.theta,i=e.encoding?.radius;if(n===void 0||i===void 0)throw new Error(`Polar line mark "${e.id}" requires theta and radius encodings.`);if(!["quantitative","temporal","ordinal","nominal"].includes(n.fieldType))throw new Error(`Polar line mark "${e.id}" has unsupported theta field type.`);if(i.fieldType!=="quantitative")throw new Error(`Polar line mark "${e.id}" requires a quantitative radius encoding.`);return{theta:n,radius:i}}function te(e,n){return["nominal","ordinal"].includes(n.fieldType)?U(e,n.field):n.fieldType==="temporal"?P(e,n.field,n.temporalUnit):k(e,n.field)}function ae(e,n,i){if(!["nominal","ordinal"].includes(n))return e;const a=i??[...new Set(e)],r=new Map(a.map((s,c)=>[s,c]));for(const s of e)if(!r.has(s))throw new Error(`Polar line theta domain does not contain "${s}".`);return e.map(s=>r.get(s))}function oe(e,n,{thetaDomain:i}={}){if(n.encoding?.pathOrder!==void 0)throw new Error(`Polar line mark "${n.id}" does not support path order.`);const{theta:a,radius:r}=re(n),s=te(e,a),c=k(e,r.field),M=ae(s,a.fieldType,i),V=I(e,n),y=new Map;for(let u=0;u<e.length;u+=1){const p=V.map(x=>e[u][x]);q(y,V,p).values.push({theta:s[u],radius:c[u],order:M[u],sourceIndex:u})}const h=[...y.values()].flatMap(u=>{const p=u.values.sort((w,x)=>w.order-x.order||w.sourceIndex-x.sourceIndex);return p.length<2?[]:[{key:u.key,values:p}]});if(h.length===0)throw new Error(`Polar line series on mark "${n.id}" requires at least two points.`);return $({thetaFieldType:a.fieldType,thetaValues:h.flatMap(u=>u.values.map(p=>p.theta)),radiusValues:h.flatMap(u=>u.values.map(p=>p.radius)),series:h})}function me(e,n,i){return N(n),n?.encoding?.theta!==void 0||n?.encoding?.radius!==void 0?oe(e,n,i):ie(e,n,i)}export{me as deriveLineSeries,oe as derivePolarLineSeries,ne as resolveLineBins};

package/src/grammar/lookup.js

@@ -0,0 +1,97 @@
+import {cloneAndFreeze, isPlainObject} from "../core/immutable.js";
+import {validateUserId} from "../core/identifiers.js";
+import {
+  rejectUnknownProperties, requireStringValue, validateDataRows, validateWorkLimit
+} from "../core/validation.js";
+
+export function normalizeLookupTransform({field, lookup} = {}) {
+  if (!isPlainObject(lookup)) throw new TypeError("Lookup requires a lookup object.");
+  const definition = {
+    type: "lookup", field,
+    lookup: {
+      ...lookup,
+      fields: Array.isArray(lookup.fields) ? [...lookup.fields] : lookup.fields,
+      as: Array.isArray(lookup.as === undefined ? lookup.fields : lookup.as) ? [...(lookup.as === undefined ? lookup.fields : lookup.as)] : lookup.as
+    }
+  };
+  validateLookupTransform(definition);
+  return cloneAndFreeze(definition);
+}
+
+export function validateLookupTransform(transform) {
+  if (!isPlainObject(transform)) throw new TypeError("Lookup transform must be a plain object.");
+  rejectUnknownProperties(transform, ["type", "field", "lookup"], "lookup transform");
+  if (transform.type !== "lookup") throw new Error(`Unsupported lookup transform "${transform.type}".`);
+  requireStringValue(transform.field, "Lookup field");
+  const lookup = transform.lookup;
+  if (!isPlainObject(lookup)) throw new TypeError("Lookup requires a lookup object.");
+  rejectUnknownProperties(lookup, ["data", "key", "fields", "as"], "lookup definition");
+  validateUserId(lookup.data, "Lookup dataset id");
+  requireStringValue(lookup.key, "Lookup key");
+  if (!Array.isArray(lookup.fields) || lookup.fields.length === 0) {
+    throw new TypeError("Lookup fields must be a non-empty array.");
+  }
+  if (!Array.isArray(lookup.as) || lookup.as.length !== lookup.fields.length) {
+    throw new TypeError("Lookup as requires one alias per field.");
+  }
+  for (const key of ["fields", "as"]) {
+    for (let i = 0; i < lookup[key].length; i += 1) {
+      if (!Object.hasOwn(lookup[key], i)) throw new TypeError(`Lookup ${key} must be dense.`);
+      requireStringValue(lookup[key][i], `Lookup ${key}[${i}]`);
+    }
+    if (new Set(lookup[key]).size !== lookup[key].length) {
+      throw new Error(`Lookup ${key} must be unique.`);
+    }
+  }
+  return transform;
+}
+
+function keyValue(row, field) {
+  const key = Object.hasOwn(row, field) ? row[field] : undefined;
+  if (key === undefined || key === null) return undefined;
+  if (typeof key !== "string" && typeof key !== "boolean" && !Number.isFinite(key)) {
+    throw new TypeError(`Lookup key field "${field}" requires a string, finite number or boolean.`);
+  }
+  return key;
+}
+
+export function deriveLookupRows(rows, lookupRows, transform) {
+  validateLookupTransform(transform);
+  validateDataRows(rows, "Lookup primary data");
+  validateDataRows(lookupRows, "Lookup reference data");
+  const lookup = transform.lookup;
+  validateWorkLimit(lookupRows.length + rows.length * (lookup.fields.length + 1), "Lookup work");
+  const existing = new Set(rows.flatMap(row => Object.keys(row)));
+  for (const name of lookup.as) {
+    if (existing.has(name)) throw new Error(`Lookup output field "${name}" already exists in primary data.`);
+  }
+  const index = new Map();
+  for (const row of lookupRows) {
+    const key = keyValue(row, lookup.key);
+    if (key === undefined) continue;
+    if (index.has(key)) throw new Error(`Lookup key field "${lookup.key}" contains duplicate keys.`);
+    index.set(key, row);
+  }
+  return cloneAndFreeze(rows.map(row => {
+    const key = keyValue(row, transform.field);
+    const match = key === undefined ? undefined : index.get(key);
+    const output = {...row};
+    for (let i = 0; i < lookup.fields.length; i += 1) {
+      const field = lookup.fields[i];
+      Object.defineProperty(output, lookup.as[i], {
+        value: match !== undefined && Object.hasOwn(match, field) ? match[field] ?? null : null,
+        enumerable: true, configurable: true, writable: true
+      });
+    }
+    return output;
+  }));
+}
+
+export function sameLookupValue(left, right) {
+  if (Object.is(left, right)) return true;
+  if (left === null || right === null || typeof left !== "object" || typeof right !== "object") return false;
+  if (Array.isArray(left) !== Array.isArray(right)) return false;
+  const keys = Object.keys(left), other = Object.keys(right);
+  return keys.length === other.length && keys.every((key, index) =>
+    key === other[index] && sameLookupValue(left[key], right[key]));
+}

package/src/grammar/markFilter.js

@@ -1,5 +1,6 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 import { normalizeMarkSelector } from "./markSelection.js";
+import { retainLineGapBoundaries } from "./lineMissing.js";
 
 const TRANSFORM_KEYS = Object.freeze([
   "type", "target", "selector", "selectors"
@@ -50,7 +51,7 @@ export function normalizeMarkFilterTransform(target, selectors) {
   return cloneAndFreeze(transform);
 }
 
-export function deriveMarkFilteredRows(sourceRows, items, selectedKeys) {
+export function deriveMarkFilteredRows(sourceRows, items, selectedKeys, layer) {
   if (!Array.isArray(sourceRows)) {
     throw new TypeError("Mark filter source values must be an array.");
   }
@@ -60,5 +61,6 @@ export function deriveMarkFilteredRows(sourceRows, items, selectedKeys) {
       .filter(item => selected.has(item.key))
       .flatMap(item => item.members)
   );
-  return cloneAndFreeze(sourceRows.filter(row => members.has(row)));
+  const retained = retainLineGapBoundaries(sourceRows, members, layer);
+  return cloneAndFreeze(sourceRows.filter(row => retained.has(row)));
 }

package/src/grammar/markLabels.js

@@ -39,9 +39,6 @@ export function normalizeMarkLabelContent(source, { content, normalizeBy }) {
         source.encoding[`${resolveBarChannels(source).measure}2`] !== undefined) {
       throw new Error("Ranged Bar text requires an explicit field or value.");
     }
-    if (content === "category" && grain === BAR_GRAINS.histogram) {
-      throw new Error("Histogram categories are intervals; use an explicit text field or value.");
-    }
   } else if (content === "category" && source.encoding?.theta?.fieldType === "quantitative") {
     throw new Error("Category text requires categorical Arc theta.");
   }
@@ -51,6 +48,8 @@ export function normalizeMarkLabelContent(source, { content, normalizeBy }) {
 function itemValue(source, item) {
   if (source.mark.type === "bar") {
     if (resolveBarGrain(source) === BAR_GRAINS.histogram) {
+      const measure = source.encoding.y;
+      if (measure.aggregate !== "count") return aggregateRows(item.members, measure.field, measure.aggregate);
       const weight = source.encoding.x.weight;
       if (weight === undefined || item.members.length === 0) return item.members.length;
       const weighted = readStatisticalWeights(item.members, weight, "Histogram label");
@@ -77,6 +76,12 @@ function itemValue(source, item) {
 }
 
 function categoryValue(source, item) {
+  if (source.mark.type === "bar" && resolveBarGrain(source) === BAR_GRAINS.histogram) {
+    // Describe the semantic bin, independently of stacking/reversal and its
+    // concrete pixel width. Suppress binary floating-point boundary artifacts.
+    const boundary = value => String(Number(value.toPrecision(12)));
+    return `${boundary(item.channels.x)}–${boundary(item.channels.x2)}`;
+  }
   return item.channels[source.mark.type === "arc" ? "theta" : resolveBarChannels(source).category];
 }
 

package/src/grammar/numeric.js

@@ -1 +1 @@
-const q=Object.freeze([1,2,3,5]);function h(t,e){if(!Array.isArray(t)||!t.every(Number.isFinite))throw new TypeError(`${e} must contain finite numbers.`)}function p(t){return new RangeError(`${t} is outside the finite numeric range.`)}function x(t,e=1){let n=0,r=0;for(const i of t){const o=i/e,c=n+o;r+=Math.abs(n)>=Math.abs(o)?n-c+o:o-c+n,n=c}return n+r}function f(t){let e=0;for(const n of t)e=Math.max(e,Math.abs(n));return e}function y(t,e="Numeric values"){h(t,e);const n=f(t)||1;return{scale:n,total:x(t,n)}}function b(t,e="Numeric result"){if(!Number.isFinite(t))throw p(e);return t===0?0:t}function N(t,e,n="Numeric result"){if(!Number.isFinite(t)||!Number.isFinite(e)||e<0)throw p(n);return b(t*e,n)}function d(t,e,n=1){h(t,e);const r=t.reduce((o,c)=>o+c,0);if(Number.isFinite(r))return r===0?0:r/n;const i=f(t)||1;return N(x(t,i)/n,i,e)}function $(t,e="Numeric sum"){return d(t,e)}function z(t,e="Numeric sum"){const n=y(t,e);let r=0,i=0,o=0;return t.map(c=>{r+=c;const u=c/n.scale,s=i+u;return o+=Math.abs(i)>=Math.abs(u)?i-s+u:u-s+i,i=s,Number.isFinite(r)?r===0?0:r:N(i+o,n.scale,e)})}function R(t,e="Numeric mean"){if(h(t,e),t.length===0)throw new RangeError(`${e} requires at least one value.`);return d(t,e,t.length)}function P(t,e="Numeric square sum"){h(t,e);const n=t.reduce((c,u)=>c+u**2,0);if(Number.isFinite(n))return n;const r=f(t);if(r===0)return 0;const i=t.reduce((c,u)=>c+(u/r)**2,0),o=N(Math.sqrt(i),r,e);return b(o**2,e)}function A(t,{sample:e=!1,divisor:n=1,label:r="Numeric deviation"}={}){if(!Number.isFinite(n)||n<=0)throw new RangeError(`${r} divisor must be positive and finite.`);const i=t.length-(e?1:0);if(i<=0)throw new RangeError(`${r} requires more values.`);const o=R(t,`${r} mean`),c=t.map(a=>a-o),u=c.reduce((a,M)=>a+M**2,0);if(Number.isFinite(u))return{mean:o,deviation:Math.sqrt(u/i)/n,squared:u};const s=c.every(Number.isFinite),m=s?f(c):Math.max(Math.abs(o),f(t));if(m===0)return{mean:o,deviation:0};const g=t.reduce((a,M,S)=>{const w=s?c[S]/m:M/m-o/m;return a+w**2},0),l=N(Math.sqrt(g/i)/n,m,r);return{mean:o,deviation:l}}function D(t,e){const n=(t.length-1)*e,r=Math.floor(n),i=Math.ceil(n);return F(t[r],t[i],n-r)}function I(t){let e=1/0,n=-1/0;for(const r of t)e=Math.min(e,r),n=Math.max(n,r);return[e,n]}function C(t,e){const n=Math.max(Math.abs(t),Math.abs(e));if(n===0)return{scale:1,start:0,end:0,span:0};const r=10**Math.floor(Math.log10(n)),i=Number.isFinite(r)&&r>0?r:n;return t/=i,e/=i,{scale:i,start:t,end:e,span:e-t}}function O(t,e=5,n=q){if(!Number.isFinite(t)||t<=0)throw new RangeError("Nice numeric span must be positive and finite.");const r=t/Math.max(1,e),i=10**Math.floor(Math.log10(r)),o=r/i;return(n.find(u=>u>=o)??10)*i}function T(t,e,n){let r=t/e;const i=Math.round(r);return Math.abs(r-i)<=1e-10&&(r=i),(n==="floor"?Math.floor(r):Math.ceil(r))*e}function E(t,e){if(!Number.isFinite(t)||t===0)return t===0?0:t;const n=Number(t.toPrecision(15));return Number.isFinite(e)&&e>0&&Math.abs(n-t)<=e*1e-10?n:t}function j(t,e,n){if(t===e)return 0;if(t===n)return 1;const r=n-e,i=t-e;if(Number.isFinite(r)&&r!==0&&Number.isFinite(i))return i/r;const o=Math.max(Math.abs(t),Math.abs(e),Math.abs(n));return(t/o-e/o)/(n/o-e/o)}function F(t,e,n){let r=n===0?t:n===1?e:void 0;if(r===void 0){const i=e-t;if(Number.isFinite(i))r=t+n*i;else{const o=Math.max(Math.abs(t),Math.abs(e));r=o*(t/o*(1-n)+e/o*n)}}return b(r,"Numeric interpolation")}function L(t,e){const n=t+e,r=Number.isFinite(n)?n/2:t/2+e/2;return b(r,"Numeric midpoint")}function V(t,e,n,r="Numeric range"){const i=Math.abs((e-t)/(n-1)),o=[],c=Math.sign(e-t);for(let u=0;u<n;u+=1){const s=E(F(t,e,u/(n-1)),i);if(!Number.isFinite(s)||c!==0&&u>0&&c*(s-o[u-1])<=0)throw new RangeError(`${r} cannot represent ${n} distinct samples.`);o.push(s)}return o}function _(t,e){let n=t.map(e??(i=>String(+i.toPrecision(3))));const r=()=>n.every((i,o)=>o===0||t[o]===t[o-1]||i!==n[o-1]);for(let i=4;!r()&&i<=17;i+=1)n=t.map(o=>String(+o.toPrecision(i)));return r()?n:t.map(String)}function k(t,e=12){if(t===0)return 0;const n=10**-e;return Math.abs(t)<n?Number(t.toPrecision(e)):Number(t.toFixed(e))}export{q as NICE_FACTORS,T as alignNumericStep,E as cleanNumericValue,L as finiteMidpoint,_ as formatDistinctNumericSamples,F as interpolateNumber,j as inverseLerp,f as maximumMagnitude,O as niceNumericStep,C as normalizeNumericRange,y as normalizedFiniteSum,I as numericExtent,D as quantileSorted,b as requireFiniteResult,N as restoreFiniteScale,V as sampleNumericRange,k as stableDecimal,A as stableFiniteDeviation,R as stableFiniteMean,z as stableFinitePrefixSums,P as stableFiniteSquareSum,$ as stableFiniteSum};
+const q=Object.freeze([1,2,3,5]);function h(t,e){if(!Array.isArray(t)||!t.every(Number.isFinite))throw new TypeError(`${e} must contain finite numbers.`)}function p(t){return new RangeError(`${t} is outside the finite numeric range.`)}function x(t,e=1){let n=0,r=0;for(const i of t){const o=i/e,c=n+o;r+=Math.abs(n)>=Math.abs(o)?n-c+o:o-c+n,n=c}return n+r}function f(t){let e=0;for(const n of t)e=Math.max(e,Math.abs(n));return e}function y(t,e="Numeric values"){h(t,e);const n=f(t)||1;return{scale:n,total:x(t,n)}}function M(t,e="Numeric result"){if(!Number.isFinite(t))throw p(e);return t===0?0:t}function N(t,e,n="Numeric result"){if(!Number.isFinite(t)||!Number.isFinite(e)||e<0)throw p(n);return M(t*e,n)}function F(t,e,n=1){h(t,e);const r=t.reduce((o,c)=>o+c,0);if(Number.isFinite(r))return r===0?0:r/n;const i=f(t)||1;return N(x(t,i)/n,i,e)}function $(t,e="Numeric sum"){return F(t,e)}function z(t,e="Numeric sum"){const n=y(t,e);let r=0,i=0,o=0;return t.map(c=>{r+=c;const s=c/n.scale,u=i+s;return o+=Math.abs(i)>=Math.abs(s)?i-u+s:s-u+i,i=u,Number.isFinite(r)?r===0?0:r:N(i+o,n.scale,e)})}function R(t,e="Numeric mean"){if(h(t,e),t.length===0)throw new RangeError(`${e} requires at least one value.`);return F(t,e,t.length)}function P(t,e="Numeric square sum"){h(t,e);const n=t.reduce((c,s)=>c+s**2,0);if(Number.isFinite(n))return n;const r=f(t);if(r===0)return 0;const i=t.reduce((c,s)=>c+(s/r)**2,0),o=N(Math.sqrt(i),r,e);return M(o**2,e)}function A(t,{sample:e=!1,divisor:n=1,label:r="Numeric deviation"}={}){if(!Number.isFinite(n)||n<=0)throw new RangeError(`${r} divisor must be positive and finite.`);const i=t.length-(e?1:0);if(i<=0)throw new RangeError(`${r} requires more values.`);const o=R(t,`${r} mean`),c=t.map(m=>m-o),s=c.reduce((m,b)=>m+b**2,0);if(Number.isFinite(s))return{mean:o,deviation:Math.sqrt(s/i)/n,squared:s};const u=c.every(Number.isFinite),a=u?f(c):Math.max(Math.abs(o),f(t));if(a===0)return{mean:o,deviation:0};const g=t.reduce((m,b,w)=>{const S=u?c[w]/a:b/a-o/a;return m+S**2},0),l=N(Math.sqrt(g/i)/n,a,r);return{mean:o,deviation:l}}function D(t,e){const n=(t.length-1)*e,r=Math.floor(n),i=Math.ceil(n);return d(t[r],t[i],n-r)}function I(t){let e=1/0,n=-1/0;for(const r of t)e=Math.min(e,r),n=Math.max(n,r);return[e,n]}function C(t,e){const n=Math.max(Math.abs(t),Math.abs(e));if(n===0)return{scale:1,start:0,end:0,span:0};const r=10**Math.floor(Math.log10(n)),i=Number.isFinite(r)&&r>0?r:n;return t/=i,e/=i,{scale:i,start:t,end:e,span:e-t}}function O(t,e){const n=t/e,r=Math.floor(Math.log10(n)),i=10**r;if(!Number.isFinite(i)||i===0)return null;const o=n/i,c=o>=Math.sqrt(50)?10:o>=Math.sqrt(10)?5:o>=Math.sqrt(2)?2:1,s=r<0?-(10**-r)/c:c*i;return Number.isFinite(s)&&s!==0?s:null}function T(t,e=5,n=q){if(!Number.isFinite(t)||t<=0)throw new RangeError("Nice numeric span must be positive and finite.");const r=t/Math.max(1,e),i=10**Math.floor(Math.log10(r)),o=r/i;return(n.find(s=>s>=o)??10)*i}function j(t,e,n){let r=t/e;const i=Math.round(r);return Math.abs(r-i)<=1e-10&&(r=i),(n==="floor"?Math.floor(r):Math.ceil(r))*e}function E(t,e){if(!Number.isFinite(t)||t===0)return t===0?0:t;const n=Number(t.toPrecision(15));return Number.isFinite(e)&&e>0&&Math.abs(n-t)<=e*1e-10?n:t}function L(t,e,n){if(t===e)return 0;if(t===n)return 1;const r=n-e,i=t-e;if(Number.isFinite(r)&&r!==0&&Number.isFinite(i))return i/r;const o=Math.max(Math.abs(t),Math.abs(e),Math.abs(n));return(t/o-e/o)/(n/o-e/o)}function d(t,e,n){let r=n===0?t:n===1?e:void 0;if(r===void 0){const i=e-t;if(Number.isFinite(i))r=t+n*i;else{const o=Math.max(Math.abs(t),Math.abs(e));r=o*(t/o*(1-n)+e/o*n)}}return M(r,"Numeric interpolation")}function V(t,e){const n=t+e,r=Number.isFinite(n)?n/2:t/2+e/2;return M(r,"Numeric midpoint")}function _(t,e,n,r="Numeric range"){const i=Math.abs((e-t)/(n-1)),o=[],c=Math.sign(e-t);for(let s=0;s<n;s+=1){const u=E(d(t,e,s/(n-1)),i);if(!Number.isFinite(u)||c!==0&&s>0&&c*(u-o[s-1])<=0)throw new RangeError(`${r} cannot represent ${n} distinct samples.`);o.push(u)}return o}function k(t,e){let n=t.map(e??(i=>String(+i.toPrecision(3))));const r=()=>n.every((i,o)=>o===0||t[o]===t[o-1]||i!==n[o-1]);for(let i=4;!r()&&i<=17;i+=1)n=t.map(o=>String(+o.toPrecision(i)));return r()?n:t.map(String)}function B(t,e=12){if(t===0)return 0;const n=10**-e;return Math.abs(t)<n?Number(t.toPrecision(e)):Number(t.toFixed(e))}export{q as NICE_FACTORS,j as alignNumericStep,E as cleanNumericValue,V as finiteMidpoint,k as formatDistinctNumericSamples,d as interpolateNumber,L as inverseLerp,f as maximumMagnitude,O as nearestNumericIncrement,T as niceNumericStep,C as normalizeNumericRange,y as normalizedFiniteSum,I as numericExtent,D as quantileSorted,M as requireFiniteResult,N as restoreFiniteScale,_ as sampleNumericRange,B as stableDecimal,A as stableFiniteDeviation,R as stableFiniteMean,z as stableFinitePrefixSums,P as stableFiniteSquareSum,$ as stableFiniteSum};

package/src/grammar/pathCommands.js

@@ -1,7 +1,7 @@
 import { freezeOwned, isPlainObject } from "../core/immutable.js";
 import { validateGeneratedItemLimit } from "../core/validation.js";
 
-export const MAX_PATH_COMMANDS = 20_000;
+export const MAX_PATH_COMMANDS = 30_000;
 
 export function validatePathCommandCount(count, label) {
   return validateGeneratedItemLimit(count, label, MAX_PATH_COMMANDS);