ggaction 0.0.24 → 0.0.26

package/src/grammar/facets/legendIntent.js

@@ -1,4 +1,5 @@
 import { isPlainObject } from "../../core/immutable.js";
+import { patchLegendItemsOffset } from "../legendItemsOffset.js";
 import {validateLegendSpacing} from "../legendSpacing.js";
 import { validateOptionObject, validateNonEmptyString } from "../../core/validation.js";
 import { validateUserId } from "../../core/identifiers.js";
@@ -8,12 +9,12 @@ import { validateLegendGroupState } from "../legendGroups.js";
 import { resolveSharedFacetLegends, sameFacetGuideValue as same } from "./guides.js";
 import { normalizeDisplayLabelMap } from "../displayLabels.js";
 
-const CONFIG_KEYS = Object.freeze([
+const CONFIG_KEYS = Object.freeze(["visibility",
   "kind", "target", "channels", "scales", "scale", "field", "fieldType", "domain", "title", "titleVisible",
   "inferredTitle", "inferredSymbol", "inferredStrokeWidth", "inferredOffset", "position", "align", "offset", "direction", "columns",
   "titlePosition", "symbol", "labels", "titleStyle", "itemGap", "rowPadding", "titlePadding", "layout", "overflow", "border", "gradient",
   "count", "sampling", "representation", "gradientDirection", "inheritAppearance", "inheritPosition", "blockOverrides",
-  "combine", "sizeAreas", "clipHeight", "defaultLabelMap"
+  "combine", "sizeAreas", "clipHeight", "defaultLabelMap", "itemsOffset"
 ]);
 
 export function isAuthoredFacetLegend(value) {
@@ -31,9 +32,10 @@ export function validateAuthoredFacetLegend(program, intent) {
   for (const [kind, block] of Object.entries(intent.blocks)) {
     if (!LEGEND_CONFIG_KINDS.includes(kind)) throw new Error("Stored parent legend has an unknown block kind.");
     validateOptionObject(block, ["config", "guide"], "Stored parent legend block");
-    validateOptionObject(block.config, kind === "colorSize" ? [...CONFIG_KEYS, "colorScale", "sizeScale"] : CONFIG_KEYS, "Stored parent legend config");
+    validateOptionObject(block.config, kind === "colorSize" ? [...CONFIG_KEYS, "colorScale", "sizeScale", "shapeScale", "colorChannel"] : CONFIG_KEYS, "Stored parent legend config");
     const config = block.config;
     validateLegendSpacing(kind,config);
+    if (config.itemsOffset !== undefined) patchLegendItemsOffset({}, config.itemsOffset);
     if (config.defaultLabelMap !== undefined) normalizeDisplayLabelMap(config.defaultLabelMap, "Stored inferred legend labels");
     validateUserId(config.target, "Parent legend target");
     if (!LEGEND_POSITIONS.includes(config.position)) throw new Error("Stored parent legend requires a native position.");
@@ -42,9 +44,9 @@ export function validateAuthoredFacetLegend(program, intent) {
     }
     const descriptor = describeLegendBlock(program, kind, config);
     if (block.guide !== undefined) {
-      validateOptionObject(block.guide, kind === "colorSize" ? ["colorScale", "sizeScale", "title"]
+      validateOptionObject(block.guide, kind === "colorSize" ? ["colorScale", "sizeScale", "shapeScale", "colorChannel", "title"]
         : ["scale", "scales", "channels", "title", "order"], "Stored parent legend meaning");
-      if (kind === "colorSize" && (block.guide.colorScale !== config.colorScale || block.guide.sizeScale !== config.sizeScale)) {
+      if (kind === "colorSize" && (block.guide.colorScale !== config.colorScale || block.guide.sizeScale !== config.sizeScale || block.guide.shapeScale !== config.shapeScale || block.guide.colorChannel !== config.colorChannel)) {
         throw new Error("Stored parent color-size meaning must match both block scale bindings.");
       }
       if (block.guide.title !== undefined) validateNonEmptyString(block.guide.title, "Parent legend title");

package/src/grammar/legendBlocks.js

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

package/src/grammar/legendCombinations.js

@@ -9,7 +9,7 @@ export function isSizeShapeChannels(channels) {
 }
 export function validateLegendCombine(value) {
   if(value===undefined)return;
-  if (!['separate','size-shape','color-size'].includes(value)) throw new Error('Legend combine must be separate, size-shape, or color-size.');
+  if (!['separate','size-shape','color-size','color-size-shape'].includes(value)) throw new Error('Legend combine must be separate, size-shape, color-size, or color-size-shape.');
 }
 export function validateMappedSizeShapeSymbol(symbol) {
   if(symbol===undefined||symbol==='auto')return;

package/src/grammar/legendGroups.js

@@ -1 +1 @@
-import{validateOptionObject as o,validateNonNegativeFinite as d}from"../core/validation.js";import{validateUserId as l}from"../core/identifiers.js";import{PLOT_LEGEND_POSITIONS as i,LEGEND_POSITIONS as a,LEGEND_BLOCK_LAYOUTS as f}from"../core/vocabulary.js";function c(n){o(n,void 0,"Legend groups");for(const[t,r]of Object.entries(n)){if(l(t,"Legend group target"),o(r,["placement","blockLayout","inferredOffset"],"Legend group"),!f.includes(r.blockLayout))throw new Error("Legend group blockLayout must be row, column or wrap.");if(r.inferredOffset!==void 0&&typeof r.inferredOffset!="boolean")throw new TypeError("Legend group inferredOffset must be boolean.");const e=r.placement;if(o(e,["at","position","align","offset"],"Legend group placement"),Object.hasOwn(e,"at")){if(Object.keys(e).length!==1)throw new Error("Legend group at cannot coexist with an edge anchor.");if(o(e.at,["x","y"],"Legend group at"),!Number.isFinite(e.at.x)||!Number.isFinite(e.at.y))throw new Error("Legend group at requires finite x and y.")}else{if(Object.keys(e).length!==3||!a.includes(e.position))throw new Error("Legend group requires a complete edge placement.");if(!["left","center","right"].includes(e.align))throw new Error("Unsupported legend group alignment.");if((i.includes(e.position)||["left","right"].includes(e.position))&&e.align!=="center")throw new Error("Side and in-plot legend groups require center alignment.");d(e.offset,"Legend group offset")}}return n}function s(n){const t=Object.values(n?.blockOverrides??{}).map(r=>r.position).filter(r=>r!==void 0);if(t.length>1)throw new Error("Legend family has ambiguous local positions.");if(t.length&&!a.includes(t[0]))throw new Error("Invalid local legend position.");return t[0]}function m(n){const t=s(n);if(t!==void 0)return{position:t,align:["top","bottom"].includes(t)?n.align??"center":"center",offset:i.includes(t)?8:n.offset??(n.channels===void 0?30:8),inferredOffset:n.inferredOffset??!0}}export{m as localLegendPlacement,s as localLegendPosition,c as validateLegendGroupState};
+import{validateOptionObject as o,validateNonNegativeFinite as l}from"../core/validation.js";import{validateUserId as d}from"../core/identifiers.js";import{PLOT_LEGEND_POSITIONS as i,LEGEND_POSITIONS as f,LEGEND_BLOCK_LAYOUTS as a}from"../core/vocabulary.js";function c(e){o(e,void 0,"Legend groups");for(const[r,n]of Object.entries(e)){if(d(r,"Legend group target"),o(n,["placement","blockLayout","inferredOffset"],"Legend group"),!a.includes(n.blockLayout))throw new Error("Legend group blockLayout must be row, column or wrap.");if(n.inferredOffset!==void 0&&typeof n.inferredOffset!="boolean")throw new TypeError("Legend group inferredOffset must be boolean.");const t=n.placement;if(o(t,["at","position","align","offset","alongOffset"],"Legend group placement"),Object.hasOwn(t,"at")){if(Object.keys(t).length!==1)throw new Error("Legend group at cannot coexist with an edge anchor.");if(o(t.at,["x","y"],"Legend group at"),!Number.isFinite(t.at.x)||!Number.isFinite(t.at.y))throw new Error("Legend group at requires finite x and y.")}else{if(![3,4].includes(Object.keys(t).length)||!f.includes(t.position))throw new Error("Legend group requires a complete edge placement.");if(!["left","center","right"].includes(t.align))throw new Error("Unsupported legend group alignment.");if((i.includes(t.position)||["left","right"].includes(t.position))&&t.align!=="center")throw new Error("Side and in-plot legend groups require center alignment.");if(l(t.offset,"Legend group offset"),t.alongOffset!==void 0&&!Number.isFinite(t.alongOffset))throw new TypeError("Legend alongOffset must be finite.")}}return e}function s(e){for(const n of Object.values(e?.blockOverrides??{}))if(n.alongOffset!==void 0&&!Number.isFinite(n.alongOffset))throw new TypeError("Legend alongOffset must be finite.");const r=Object.values(e?.blockOverrides??{}).map(n=>n.position??(n.alongOffset===void 0?void 0:e.position)).filter(n=>n!==void 0);if(r.length>1)throw new Error("Legend family has ambiguous local positions.");if(r.length&&!f.includes(r[0]))throw new Error("Invalid local legend position.");return r[0]}function O(e){const r=s(e);if(r===void 0)return;const n=Object.values(e.blockOverrides??{}).flatMap(t=>t.alongOffset===void 0?[]:[t.alongOffset]);if(n.length>1||n.some(t=>!Number.isFinite(t)))throw new TypeError("Legend alongOffset requires one finite block value.");return{position:r,...n.length?{alongOffset:n[0]}:{},align:["top","bottom"].includes(r)?e.align??"center":"center",offset:i.includes(r)&&r!==e.position&&e.inferredOffset===!0?8:e.offset??(i.includes(r)?8:e.channels===void 0?30:8),inferredOffset:e.inferredOffset??!0}}function m(e,r=e.position){return s(e)===r&&Object.values(e.blockOverrides??{}).some(n=>n.alongOffset!==void 0)}export{O as localLegendPlacement,s as localLegendPosition,m as retainsLegendSlot,c as validateLegendGroupState};

package/src/grammar/legendItemsOffset.js

@@ -0,0 +1,12 @@
+import { isPlainObject } from "../core/immutable.js";
+
+export function patchLegendItemsOffset(config, value) {
+  const { itemsOffset: previous, ...rest } = config;
+  if (value === "auto") return rest;
+  if (!isPlainObject(value) || !Object.keys(value).length ||
+      Object.keys(value).some(key => !["x", "y"].includes(key) ||
+        typeof value[key] !== "number" || !Number.isFinite(value[key]))) {
+    throw new TypeError('Legend itemsOffset must be a nonempty object with finite x/y coordinates, or "auto".');
+  }
+  return { ...rest, itemsOffset: { x: 0, y: 0, ...previous, ...value } };
+}

package/src/grammar/legendOverflow.js

@@ -0,0 +1,25 @@
+import { validateOptionObject } from "../core/validation.js";
+
+export function normalizeLegendOverflow(value, { summarySymbol = false } = {}) {
+  if (value === undefined || value === false) return value;
+  validateOptionObject(value, ["maxItems", "summary", "summarySymbol"], "Legend overflow");
+  if (!Number.isInteger(value.maxItems) || value.maxItems < 1) {
+    throw new RangeError("Legend overflow.maxItems must be a positive integer.");
+  }
+  if (value.summary !== undefined && value.summary !== "ellipsis-count") {
+    throw new Error("Legend overflow.summary must be ellipsis-count.");
+  }
+  if (value.summarySymbol !== undefined && (!summarySymbol || value.summarySymbol !== "first-hidden")) {
+    throw new Error("Legend overflow.summarySymbol requires first-hidden on categorical line samples.");
+  }
+  return { maxItems: value.maxItems, summary: "ellipsis-count",
+    ...(value.summarySymbol === undefined ? {} : { summarySymbol: value.summarySymbol }) };
+}
+
+export function validateLegendOverflow(kind, config) {
+  normalizeLegendOverflow(config.overflow, { summarySymbol: ["series", "color", "stroke"].includes(kind) });
+  if (config.overflow?.summarySymbol !== undefined &&
+      (!config.symbol?.layers?.length || config.symbol.layers.some(layer => layer.type !== "line"))) {
+    throw new Error("Legend overflow.summarySymbol requires a categorical line-only sample recipe.");
+  }
+}

package/src/grammar/lineSeries.js

@@ -1 +1 @@
-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};
+import{cloneAndFreeze as M}from"../core/immutable.js";import{readLinePosition as D,validateLineMissingScope as N,orderLineGapValues as X,splitLineGapValues as j}from"./lineMissing.js";import{readNominalField as H,readQuantitativeField as k,readTemporalField as P}from"./scales/index.js";import{aggregateRows as Q,isAggregate as R,validateAggregateFieldType as Y,validateAggregateFieldValues as _}from"./aggregate.js";import{stableOrderPathValues as J}from"./pathOrder.js";import{finiteMidpoint as W}from"./numeric.js";import{findHistogramBinIndex as Z,resolveHistogramBins as ee}from"./histogram.js";import{validatePathSeriesAppearance as A,pathSeriesKey as U}from"./pathSeries.js";function ne(e){return["quantitative","temporal","nominal","ordinal"].includes(e?.fieldType)}function ie(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.`);if(n.aggregate!==void 0)throw new Error("A Line requires one independent position; both axes cannot aggregate.");const o=n?.fieldType==="quantitative"&&n.bin!==void 0&&R(i?.aggregate),t=ne(n)&&R(i?.aggregate),r=["quantitative","nominal","ordinal"].includes(n?.fieldType)&&n.bin===void 0&&i?.fieldType==="quantitative"&&i.aggregate===void 0,u=i?.aggregate===void 0&&(n?.fieldType==="temporal"&&i?.fieldType==="quantitative"||n?.fieldType==="quantitative"&&i?.fieldType==="temporal");if(!t&&!r&&!u)throw n?.fieldType==="temporal"?new Error(`Line mark "${e.id}" requires a supported aggregate y encoding.`):new Error(`Line mark "${e.id}" requires an aggregate value at compatible x positions or compatible direct x/y encodings.`);return t&&Y(i.aggregate,i.fieldType),{x:n,y:i,isAggregate:t,binnedAggregate:o,directRows:u||r,directTemporal:u}}function L(e,n,i){const o=U(i);let t=e.get(o);return t===void 0&&(t={key:Object.fromEntries(n.map((r,u)=>[r,i[u]])),values:[]},e.set(o,t)),t}function B(e,n){const i=e.flatMap(t=>t.values.map(r=>r.x)),o=new Set(i);if(n!==void 0){const t=new Set(n);if(i.some(r=>!t.has(r)))throw new Error("Line categorical x domain must contain every observed vertex.")}return M({xValues:n===void 0?i:n.filter(t=>o.has(t)),yValues:e.flatMap(t=>t.values.map(r=>r.y)),series:e})}function te(e,n,i={}){const o=n?.encoding?.x;if(!(n?.mark?.type!=="line"||o?.fieldType!=="quantitative"||o.bin===void 0))return ee({values:k(e,o.field),bin:o.bin,domain:i.domain??"auto",nice:i.nice??!0,zero:i.zero??!1})}function C(e,n,i={}){const{x:o,y:t,isAggregate:r,binnedAggregate:u,directRows:v,directTemporal:q}=ie(n);if(n.mark.missing==="break"){const a=D(e,o),d=D(e,t),f=A(e,n,i.scales),s=n.encoding?.pathOrder,g=s===void 0?q&&t.fieldType==="temporal"?d:a:k(e,s.field),m=new Map;for(let c=0;c<e.length;c+=1){const b=L(m,f,f.map(z=>e[c][z]));b.values.push({x:a[c],y:d[c],sourceIndex:c}),(b.orderValues??=[]).push(g[c])}const x=[...m.values()].flatMap(c=>{const b=X(c.values,c.orderValues,s?.order);return j(b).map(O=>({key:c.key,values:O.map(({sourceIndex:G,...K})=>K),sourceIndices:O.map(G=>G.sourceIndex)}))});return M({xValues:a.filter(c=>c!==null),yValues:d.filter(c=>c!==null),series:x})}r&&_(e,t.field,t.fieldType);const w=["nominal","ordinal"].includes(o.fieldType),h=w?H(e,o.field):o.fieldType==="temporal"?P(e,o.field,o.temporalUnit):k(e,o.field),l=r?void 0:t.fieldType==="temporal"?P(e,t.field,t.temporalUnit):k(e,t.field),p=w?i.xDomain??[...new Set(h)]:void 0,T=new Map(p?.map((a,d)=>[a,d])),y=w?(a,d)=>T.get(a.x)-T.get(d.x):(a,d)=>a.x-d.x,V=A(e,n,i.scales),S=u?i.xBinBoundaries??te(e,n).boundaries:void 0,$=n.encoding?.pathOrder;if($!==void 0){if(r)throw new Error(`Line mark "${n.id}" cannot combine aggregate y and path order.`);const a=k(e,$.field),d=new Map;for(let s=0;s<e.length;s+=1){const g=V.map(x=>e[s][x]),m=L(d,V,g);m.values.push({x:h[s],y:l[s]}),m.orderValues??=[],m.orderValues.push(a[s])}const f=[...d.values()].flatMap(s=>{const g=J(s.values,s.orderValues,$.order);return[{key:s.key,values:g}]});if(f.length===0)throw new Error(`Line series on mark "${n.id}" requires at least two ordered points.`);return B(f,p)}if(v){const a=new Map;for(let s=0;s<e.length;s+=1){const g=V.map(x=>e[s][x]);L(a,V,g).values.push({x:h[s],y:l[s]})}const d=q&&t.fieldType==="temporal"?"y":"x",f=[...a.values()].flatMap(s=>{const g=s.values.sort(d==="x"?y:(m,x)=>m.y-x.y);return[{key:s.key,values:g}]});if(f.length===0)throw new Error(`Line series on mark "${n.id}" requires at least two direct points.`);return B(f,p)}const E=new Map;for(let a=0;a<e.length;a+=1){const d=V.map(x=>e[a][x]),f=u?Z(h[a],S):void 0;if(f===-1)continue;const s=u?W(S[f],S[f+1]):h[a],g=U([u?f:s,...d]),m=E.get(g)??{x:s,dimensions:d,rows:[]};m.rows.push(e[a]),E.set(g,m)}if(E.size===0)throw new Error(`Line mark "${n.id}" has no values to aggregate.`);const I=new Map;for(const a of E.values()){const d=Q(a.rows,t.field,t.aggregate);if(d===void 0)continue;L(I,V,a.dimensions).values.push({x:a.x,y:d})}const F=[...I.values()].flatMap(a=>{const d=a.values.sort(y);return d.length<(i.allowSingleton===!0?1:2)?[]:[{key:a.key,values:d}]});if(F.length===0)throw new Error(`Line series on mark "${n.id}" requires at least two aggregate points.`);return B(F,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 ae(e,n){return["nominal","ordinal"].includes(n.fieldType)?H(e,n.field):n.fieldType==="temporal"?P(e,n.field,n.temporalUnit):k(e,n.field)}function oe(e,n,i){if(!["nominal","ordinal"].includes(n))return e;const o=i??[...new Set(e)],t=new Map(o.map((r,u)=>[r,u]));for(const r of e)if(!t.has(r))throw new Error(`Polar line theta domain does not contain "${r}".`);return e.map(r=>t.get(r))}function se(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:o,radius:t}=re(n),r=ae(e,o),u=k(e,t.field),v=oe(r,o.fieldType,i),q=A(e,n),w=new Map;for(let l=0;l<e.length;l+=1){const p=q.map(y=>e[l][y]);L(w,q,p).values.push({theta:r[l],radius:u[l],order:v[l],sourceIndex:l})}const h=[...w.values()].flatMap(l=>{const p=l.values.sort((T,y)=>T.order-y.order||T.sourceIndex-y.sourceIndex);return p.length<2?[]:[{key:l.key,values:p}]});if(h.length===0)throw new Error(`Polar line series on mark "${n.id}" requires at least two points.`);return M({thetaFieldType:o.fieldType,thetaValues:h.flatMap(l=>l.values.map(p=>p.theta)),radiusValues:h.flatMap(l=>l.values.map(p=>p.radius)),series:h})}function de(e){return e?.encoding?.x?.aggregate!==void 0||e?.encoding?.x?.fieldType==="quantitative"&&["nominal","ordinal"].includes(e?.encoding?.y?.fieldType)}function xe(e,n,i={}){if(N(n),n?.encoding?.theta!==void 0||n?.encoding?.radius!==void 0)return se(e,n,i);if(!de(n))return C(e,n,i);const t={...n,encoding:{...n.encoding,x:n.encoding.y,y:n.encoding.x}},r=C(e,t,{...i,xDomain:i.yDomain,xBinBoundaries:i.yBinBoundaries});return M({...r,xValues:r.yValues,yValues:r.xValues,series:r.series.map(u=>({...u,values:u.values.map(v=>({...v,x:v.y,y:v.x}))}))})}export{xe as deriveLineSeries,se as derivePolarLineSeries,ne as isAggregateLinePosition,de as isHorizontalLine,te as resolveLineBins};

package/src/grammar/markSelection.js

@@ -43,6 +43,7 @@ const COMPARISON_OPERATORS = new Set([
 const ORDERED_COMPARISON_OPERATORS = new Set(["gt", "gte", "lt", "lte"]);
 const RANK_OPERATORS = new Set(["min", "max"]);
 const SELECTOR_KEYS = Object.freeze([
+  "rows",
   "grain",
   "field",
   "channel",
@@ -98,6 +99,16 @@ export function normalizeMarkSelector(selector) {
     throw new Error(`Unknown mark selector option "${unknown}".`);
   }
 
+  if (selector.rows !== undefined) {
+    if (Object.keys(selector).some(key => !["rows", "grain"].includes(key)) || !isPlainObject(selector.rows) ||
+        Object.keys(selector.rows).some(key => !["data", "indices"].includes(key)) ||
+        typeof selector.rows.data !== "string" || !selector.rows.data || !Array.isArray(selector.rows.indices) ||
+        !Array.from(selector.rows.indices).every(i => Number.isInteger(i) && i >= 0)) throw new TypeError("Row selection requires data and non-negative integer indices.");
+    const grain = selector.grain ?? "item";
+    if (!MARK_SELECTOR_GRAINS.includes(grain)) throw new Error(`Unknown mark selector grain "${grain}".`);
+    return cloneAndFreeze({ grain, rows: { data: selector.rows.data, indices: [...new Set(selector.rows.indices)] } });
+  }
+
   const sources = ["field", "channel", "property"].filter(key =>
     Object.hasOwn(selector, key)
   );
@@ -298,6 +309,10 @@ function rankGroup(items, selector) {
 export function selectMarkItemKeys(items, selector) {
   validateItems(items);
   const normalized = normalizeMarkSelector(selector);
+  if (normalized.rows) {
+    const indices = new Set(normalized.rows.indices);
+    return cloneAndFreeze(items.filter(item => item.rows?.some(ref => ref.data === normalized.rows.data && indices.has(ref.index))).map(item => item.key));
+  }
   if (!RANK_OPERATORS.has(normalized.op)) {
     return cloneAndFreeze(
       items
@@ -324,3 +339,11 @@ export function selectMarkItemKeys(items, selector) {
     )
   );
 }
+
+// Stored selectors and live materialization share dataset identity and bounds checks.
+export function validateRowSelectionDataset(rows, dataset) {
+  if (!dataset) throw new Error(`Unknown row dataset "${rows.data}".`);
+  if (rows.indices.some(index => index >= dataset.values.length)) {
+    throw new RangeError("Selected row index exceeds the dataset length.");
+  }
+}

package/src/grammar/overlay.js

@@ -0,0 +1,51 @@
+import { isPlainObject, cloneAndFreeze } from "../core/immutable.js";
+import { validateUserId } from "../core/identifiers.js";
+
+// Inspection and materialization share the same topology capability. A
+// categorical density is an entire silhouette, not one endpoint per category.
+export function overlaySourceReason(layer, coordinateType, density) {
+  if (coordinateType !== 'cartesian' || !['bar', 'point', 'line', 'area'].includes(layer?.mark?.type))
+    return 'Overlay source requires a Cartesian bar, point, line, or area mark.';
+  if (layer.derivedBindings?.overlay) return 'Overlay source must be an independent mark.';
+  if (['x', 'y'].some(channel => !layer.encoding?.[channel]?.scale)) return 'Overlay source requires complete x and y positions.';
+  if (density?.placement?.type === 'category') return 'Categorically placed density areas do not have a single result endpoint per category.';
+  return undefined;
+}
+
+export function normalizeOverlayBinding(input) {
+  if (!isPlainObject(input) || Object.keys(input).some(key =>
+    !["source", "basis", "mode", "series", "missing", "orderBy", "inheritColor"].includes(key))) {
+    throw new TypeError("Overlay binding requires source, basis, mode, series, missing, and optional orderBy.");
+  }
+  validateUserId(input.source, "Overlay source");
+  if (input.basis !== "visibleItems" || input.mode !== "follow") {
+    throw new Error('Overlay binding requires basis "visibleItems" and mode "follow".');
+  }
+  if (!["source", "total"].includes(input.series)) throw new Error("Overlay series must be source or total.");
+  if (!["break", "connect"].includes(input.missing)) throw new Error("Overlay missing must be break or connect.");
+  if (typeof input.inheritColor !== "boolean") throw new TypeError("Overlay inheritColor must be boolean.");
+  if (input.orderBy !== undefined && !["x", "y"].includes(input.orderBy)) {
+    throw new Error("Overlay orderBy must be x or y.");
+  }
+  return cloneAndFreeze(input);
+}
+
+export function overlayGroupFields(layer) {
+  const group = layer.encoding?.group;
+  if (group?.fields) return group.fields;
+  if (group?.field) return [group.field];
+  const color = layer.encoding?.color;
+  return ["nominal", "ordinal"].includes(color?.fieldType) &&
+    ![layer.encoding?.x?.field, layer.encoding?.y?.field].includes(color.field)
+    ? [color.field] : [];
+}
+
+export function overlayPositionEncoding(source, channel) {
+  const encoding = source.encoding[channel];
+  return encoding?.field === undefined && source.encoding[`${channel}2`]?.field !== undefined
+    ? source.encoding[`${channel}2`] : encoding;
+}
+
+export function assertIndependentOverlayGeometry(layer, operation) {
+  if (layer.derivedBindings?.overlay) throw new Error(`${operation}: overlay geometry follows its source; edit the source or detach the overlay first.`);
+}

package/src/grammar/parallelCoordinates.js

@@ -1,208 +1 @@
-import { requireStringValue as nonEmptyString } from "../core/validation.js";
-import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { validateUserId } from "../core/identifiers.js";
-import { validateOptionObject } from "../core/validation.js";
-import {
-  mapContinuousScaleValues,
-  mapOrdinalPositionValues,
-  validateSemanticFieldType
-} from "./scales/index.js";
-
-const DIMENSION_OPTIONS = Object.freeze([
-  "field", "fieldType", "title", "scale"
-]);
-const FIELD_TYPES = new Set(["quantitative", "ordinal"]);
-const MISSING_POLICIES = new Set(["break", "drop-row", "error"]);
-const DIMENSION_SCALE_OPTIONS = Object.freeze([
-  "type", "domain", "range", "nice", "zero", "clamp", "reverse",
-  "base", "exponent", "constant", "paddingInner", "paddingOuter",
-  "padding", "align", "unknown"
-]);
-
-
-export function validateParallelKeyField(value) {
-  return nonEmptyString(value, "Parallel key field");
-}
-
-function inferFieldType(rows, field) {
-  const values = rows
-    .map(row => row[field])
-    .filter(value => value !== undefined && value !== null);
-  if (values.length === 0) {
-    throw new Error(`Cannot infer Parallel field type for "${field}".`);
-  }
-  if (values.every(Number.isFinite)) return "quantitative";
-  if (values.every(value => typeof value === "string")) return "ordinal";
-  throw new Error(
-    `Parallel dimension "${field}" requires an explicit compatible fieldType.`
-  );
-}
-
-function validateScaleOptions(value, index) {
-  if (value === undefined) return {};
-  if (!isPlainObject(value)) {
-    throw new TypeError(`Parallel dimension ${index} scale must be a plain object.`);
-  }
-  validateOptionObject(
-    value,
-    DIMENSION_SCALE_OPTIONS,
-    `Parallel dimension ${index} scale`
-  );
-  return { ...value };
-}
-
-export function validateParallelMissingPolicy(value) {
-  if (!MISSING_POLICIES.has(value)) {
-    throw new Error(`Unsupported Parallel missing policy "${value}".`);
-  }
-  return value;
-}
-
-export function validateParallelDimensions(dimensions, { normalized = false } = {}) {
-  if (!Array.isArray(dimensions) || dimensions.length < 2) {
-    throw new RangeError("Parallel coordinates require at least two dimensions.");
-  }
-  const fields = new Set();
-  for (const [index, dimension] of dimensions.entries()) {
-    if (!isPlainObject(dimension)) {
-      throw new TypeError(`Parallel dimension ${index} must be an object.`);
-    }
-    const supported = normalized
-      ? ["field", "fieldType", "title", "scale"]
-      : DIMENSION_OPTIONS;
-    validateOptionObject(dimension, supported, `Parallel dimension ${index}`);
-    const field = nonEmptyString(
-      dimension.field,
-      `Parallel dimension ${index} field`
-    );
-    if (fields.has(field)) {
-      throw new Error("Parallel dimensions must use unique fields.");
-    }
-    fields.add(field);
-    validateSemanticFieldType(dimension.fieldType);
-    if (!FIELD_TYPES.has(dimension.fieldType)) {
-      throw new Error(`Unsupported Parallel field type "${dimension.fieldType}".`);
-    }
-    nonEmptyString(dimension.title, `Parallel dimension ${index} title`);
-    validateUserId(dimension.scale, `Parallel dimension ${index} scale id`);
-  }
-  return dimensions;
-}
-
-export function normalizeParallelDimensions(rows, dimensions, target) {
-  if (!Array.isArray(dimensions) || dimensions.length < 2) {
-    throw new RangeError("Parallel coordinates require at least two dimensions.");
-  }
-  const normalized = dimensions.map((input, index) => {
-    const dimension = typeof input === "string" ? { field: input } : input;
-    if (!isPlainObject(dimension)) {
-      throw new TypeError(
-        `Parallel dimension ${index} must be a field string or plain object.`
-      );
-    }
-    validateOptionObject(
-      dimension,
-      DIMENSION_OPTIONS,
-      `Parallel dimension ${index}`
-    );
-    const field = nonEmptyString(
-      dimension.field,
-      `Parallel dimension ${index} field`
-    );
-    const fieldType = dimension.fieldType ?? inferFieldType(rows, field);
-    if (!FIELD_TYPES.has(fieldType)) {
-      throw new Error(`Unsupported Parallel field type "${fieldType}".`);
-    }
-    const scale = validateScaleOptions(dimension.scale, index);
-    return {
-      field,
-      fieldType,
-      title: dimension.title ?? field,
-      scale: `${target}-parallel-${index}`,
-      scaleOptions: scale
-    };
-  });
-  const fields = normalized.map(dimension => dimension.field);
-  if (new Set(fields).size !== fields.length) {
-    throw new Error("Parallel dimensions must use unique fields.");
-  }
-  return cloneAndFreeze(normalized);
-}
-
-function validDimensionValue(value, fieldType) {
-  return fieldType === "quantitative"
-    ? Number.isFinite(value)
-    : typeof value === "string" || Number.isFinite(value);
-}
-
-function commandsFromVertices(vertices) {
-  const commands = [];
-  let fragment = [];
-  const flush = () => {
-    if (fragment.length >= 2) {
-      fragment.forEach((point, index) => commands.push({
-        op: index === 0 ? "M" : "L",
-        x: point.x,
-        y: point.y
-      }));
-    }
-    fragment = [];
-  };
-  for (const vertex of vertices) {
-    if (vertex === undefined) flush();
-    else fragment.push(vertex);
-  }
-  flush();
-  return commands;
-}
-
-export function validateParallelRows(rows, dimensions, { key, missing }) {
-  const seen = new Set();
-  rows.forEach((row, index) => {
-    if (key !== undefined) {
-      const value = row[key];
-      if (value === undefined || value === null || value === "") {
-        throw new Error(`Parallel key is missing at row ${index}.`);
-      }
-      const token = `${typeof value}:${String(value)}`;
-      if (seen.has(token)) throw new Error(`Duplicate Parallel key "${value}".`);
-      seen.add(token);
-    }
-    const incomplete = dimensions.some(dimension =>
-      !validDimensionValue(row[dimension.field], dimension.fieldType)
-    );
-    if (incomplete && missing === "error") {
-      throw new Error(`Parallel row ${index} has a missing dimension.`);
-    }
-  });
-}
-
-export function materializeParallelRows(rows, dimensions, resolvedScales, bounds, {
-  key,
-  missing
-}) {
-  validateParallelRows(rows, dimensions, { key, missing });
-  const step = bounds.width / (dimensions.length - 1);
-  const items = [];
-  rows.forEach((row, sourceRowIndex) => {
-    const vertices = dimensions.map((dimension, index) => {
-      const value = row[dimension.field];
-      if (!validDimensionValue(value, dimension.fieldType)) return undefined;
-      const scale = resolvedScales[dimension.scale];
-      const mapped = dimension.fieldType === "quantitative"
-        ? mapContinuousScaleValues([value], scale)[0]
-        : mapOrdinalPositionValues([value], scale)[0];
-      return Number.isFinite(mapped)
-        ? { x: bounds.x + step * index, y: mapped, value, dimension: dimension.field }
-        : undefined;
-    });
-    const incomplete = vertices.some(vertex => vertex === undefined);
-    if (incomplete && missing === "drop-row") return;
-    items.push({
-      key: key === undefined ? `source:${sourceRowIndex}` : row[key],
-      sourceRowIndex,
-      commands: commandsFromVertices(vertices)
-    });
-  });
-  return cloneAndFreeze(items);
-}
+import{requireStringValue as P}from"../core/validation.js";import{cloneAndFreeze as N,isOwned as E,isPlainObject as $}from"../core/immutable.js";import{validateUserId as I}from"../core/identifiers.js";import{validateOptionObject as S}from"../core/validation.js";import{mapContinuousScaleValues as A,mapOrdinalPositionValues as D,validateSemanticFieldType as M}from"./scales/index.js";const q=Object.freeze(["field","fieldType","title","scale"]),F=new Set(["quantitative","ordinal"]),k=new Set(["break","drop-row","error"]),z=new WeakMap,x=Object.freeze(["id","type","domain","range","nice","zero","clamp","reverse","base","exponent","constant","paddingInner","paddingOuter","padding","align","unknown"]);function W(e){return P(e,"Parallel key field")}function V(e,t){const i=e.map(n=>n[t]).filter(n=>n!=null);if(i.length===0)throw new Error(`Cannot infer Parallel field type for "${t}".`);if(i.every(Number.isFinite))return"quantitative";if(i.every(n=>typeof n=="string"))return"ordinal";throw new Error(`Parallel dimension "${t}" requires an explicit compatible fieldType.`)}function _(e,t){if(e===void 0)return{};if(!$(e))throw new TypeError(`Parallel dimension ${t} scale must be a plain object.`);return S(e,x,`Parallel dimension ${t} scale`),{...e}}function Y(e){if(!k.has(e))throw new Error(`Unsupported Parallel missing policy "${e}".`);return e}function B(e,{normalized:t=!1}={}){if(!Array.isArray(e)||e.length<2)throw new RangeError("Parallel coordinates require at least two dimensions.");const i=new Set;for(const[n,r]of e.entries()){if(!$(r))throw new TypeError(`Parallel dimension ${n} must be an object.`);S(r,t?["field","fieldType","title","scale"]:q,`Parallel dimension ${n}`);const o=P(r.field,`Parallel dimension ${n} field`);if(i.has(o))throw new Error("Parallel dimensions must use unique fields.");if(i.add(o),M(r.fieldType),!F.has(r.fieldType))throw new Error(`Unsupported Parallel field type "${r.fieldType}".`);P(r.title,`Parallel dimension ${n} title`),I(r.scale,`Parallel dimension ${n} scale id`)}return e}function H(e,t,i){if(!Array.isArray(t)||t.length<2)throw new RangeError("Parallel coordinates require at least two dimensions.");const n=t.map((s,o)=>{const f=typeof s=="string"?{field:s}:s;if(!$(f))throw new TypeError(`Parallel dimension ${o} must be a field string or plain object.`);S(f,q,`Parallel dimension ${o}`);const l=P(f.field,`Parallel dimension ${o} field`),a=f.fieldType??V(e,l);if(!F.has(a))throw new Error(`Unsupported Parallel field type "${a}".`);const y=_(f.scale,o);return{field:l,fieldType:a,title:f.title??l,scale:y.id===void 0?`${i}-parallel-${o}`:I(y.id,"Parallel dimension scale id"),scaleOptions:y}}),r=n.map(s=>s.field);if(new Set(r).size!==r.length)throw new Error("Parallel dimensions must use unique fields.");return N(n)}function T(e,t){return t==="quantitative"?Number.isFinite(e):typeof e=="string"||Number.isFinite(e)}function C(e){const t=[];let i=[];const n=()=>{i.length>=2&&i.forEach((r,s)=>t.push({op:s===0?"M":"L",x:r.x,y:r.y})),i=[]};for(const r of e)r===void 0?n():i.push(r);return n(),t}function L(e,t,{key:i,missing:n}){const r=new Set;e.forEach((s,o)=>{if(i!==void 0){const l=s[i];if(l==null||l==="")throw new Error(`Parallel key is missing at row ${o}.`);const a=`${typeof l}:${String(l)}`;if(r.has(a))throw new Error(`Duplicate Parallel key "${l}".`);r.add(a)}if(t.some(l=>!T(s[l.field],l.fieldType))&&n==="error")throw new Error(`Parallel row ${o} has a missing dimension.`)})}function Q(e,t,i,n,{key:r,missing:s}){const o=t.map(c=>i[c.scale]),f=E(e)&&E(t)&&o.every(E),l=f?JSON.stringify({dimensions:t,scales:o,bounds:n,key:r,missing:s}):void 0;let a=f?z.get(e):void 0;if(a?.has(l)){const c=a.get(l);return a.delete(l),a.set(l,c),c}L(e,t,{key:r,missing:s});const y=n.width/(t.length-1),j=t.map((c,u)=>{const d=[],g=[];e.forEach((m,h)=>{const b=m[c.field];T(b,c.fieldType)&&(d.push(b),g.push(h))});const p=d.length===0?[]:c.fieldType==="quantitative"?A(d,o[u]):D(d,o[u]),w=new Array(e.length);return g.forEach((m,h)=>{w[m]=p[h]}),w}),O=[];e.forEach((c,u)=>{const d=t.map((p,w)=>{const m=c[p.field];if(!T(m,p.fieldType))return;const h=j[w][u];return Number.isFinite(h)?{x:n.x+y*w,y:h,value:m,dimension:p.field}:void 0});d.some(p=>p===void 0)&&s==="drop-row"||O.push({key:r===void 0?`source:${u}`:c[r],sourceRowIndex:u,commands:C(d)})});const v=N(O);return f&&(a||z.set(e,a=new Map),a.set(l,v),a.size>4&&a.delete(a.keys().next().value)),v}export{Q as materializeParallelRows,H as normalizeParallelDimensions,B as validateParallelDimensions,W as validateParallelKeyField,Y as validateParallelMissingPolicy,L as validateParallelRows};

package/src/grammar/pathCommands.js

@@ -1,4 +1,4 @@
-import { freezeOwned, isPlainObject } from "../core/immutable.js";
+import { freezeOwned, isOwned, isPlainObject } from "../core/immutable.js";
 import { validateGeneratedItemLimit } from "../core/validation.js";
 
 export const MAX_PATH_COMMANDS = 30_000;
@@ -13,6 +13,7 @@ const COMMAND_KEYS = Object.freeze({
   C: Object.freeze(["op", "x1", "y1", "x2", "y2", "x", "y"]),
   Z: Object.freeze(["op"])
 });
+const validatedCommands = new WeakSet();
 
 function validateCommand(command, index) {
   if (!isPlainObject(command) || !Object.hasOwn(COMMAND_KEYS, command.op)) {
@@ -41,6 +42,7 @@ function validateCommand(command, index) {
 }
 
 export function validatePathCommands(commands) {
+  if (validatedCommands.has(commands)) return commands;
   if (!Array.isArray(commands) || commands.length < 1) {
     throw new TypeError("path.commands must contain at least one command.");
   }
@@ -49,7 +51,10 @@ export function validatePathCommands(commands) {
   if (commands[0].op !== "M") {
     throw new Error("path.commands must start with M.");
   }
-  if (commands.length === 1) return commands;
+  if (commands.length === 1) {
+    if (isOwned(commands)) validatedCommands.add(commands);
+    return commands;
+  }
   if (commands.slice(1).some(command => command.op === "M")) {
     throw new Error("path.commands supports one subpath and only one initial M.");
   }
@@ -60,6 +65,7 @@ export function validatePathCommands(commands) {
   if (closeIndex !== -1 && closeIndex !== commands.length - 1) {
     throw new Error("path.commands Z must be the final command.");
   }
+  if (isOwned(commands)) validatedCommands.add(commands);
   return commands;
 }
 

package/src/grammar/pathSeries.js

@@ -1 +1 @@
-import{validateNonEmptyString as S}from"../core/validation.js";import{readCategoricalLineColor as p,validateCategoricalColorConsumer as y}from"./scales/colorConsumers.js";import{readNominalField as f,readQuantitativeField as O,readScaleField as x}from"./scales/fields.js";function m(n){const e=Array.isArray(n)?[...n]:[n];for(const i of e)S(i,"Path group field");if(e.length===0||new Set(e).size!==e.length)throw new Error("Path group fields must be non-empty and unique.");return e}function E(n){const e=n.encoding?.group;if(e!==void 0){if(e.fieldType!=="nominal")throw new Error(`Path group on mark "${n.id}" must be nominal.`);if(Object.hasOwn(e,"field")&&Object.hasOwn(e,"fields"))throw new Error("Path group requires exactly one of field or fields.");return m(e.fields??e.field)}if(n.mark?.type!=="line")return[];const i=["nominal","ordinal"].includes(n.encoding?.color?.fieldType)?n.encoding.color.field:void 0,o=n.encoding?.strokeDash?.field;if(i!==void 0&&o!==void 0&&i!==o)throw new Error("Line color field must match strokeDash field unless encodeGroup defines the series.");return i===void 0&&o===void 0?[]:[i??o]}function h(n){return JSON.stringify(n.map(e=>e===void 0?{}:e))}function g(n,e){const i=n.encoding?.color,o=Array.isArray(e)?e.find(t=>t.id===i?.scale):e?.[i?.scale];return o!==void 0&&y(n,i,o)?o:void 0}function P(n,e,i){const o=E(e),t=g(e,i);for(const r of o)t&&e.encoding?.group===void 0&&r===e.encoding.color.field?p(n,r):f(n,r);return o}function k(n,e,i,o,t={},r){const l=o==="strokeWidth"||o==="opacity",d=o==="color"&&r!==void 0?p(n,i):o==="stroke"||o==="color"&&["quantitative","temporal"].includes(t.fieldType)?x(n,i,t.fieldType??"nominal",{temporalUnit:t.temporalUnit}):l?O(n,i):f(n,i),a=new Map;return n.forEach((c,v)=>{const s=h(e.map(w=>c[w])),u=d[v];if(o==="strokeWidth"&&u<0)throw new RangeError(`Line strokeWidth field "${i}" cannot contain negative values.`);if(a.has(s)&&a.get(s)!==u)throw new Error(`Path ${o} field "${i}" must have one value within each series.`);a.set(s,u)}),a}function F(n,e,i,o,t,r){if(e.length===0)return[];const l=Object.keys(e[0]?.key??{}),d=k(n,l,i,o,t,Object.hasOwn(r??{},"unknown")?r:void 0);return e.map(a=>d.get(h(Object.values(a.key))))}function j(n,e,i,o){if(!["line","area"].includes(e.mark?.type)||e.encoding?.parallel!==void 0)return;const t=o??P(n,e,i);if(o!==void 0)for(const d of t)f(n,d);const r=g(e,i),l=e.mark.type==="line"?["color","stroke","strokeDash","strokeWidth","opacity"]:["color","stroke"];for(const d of l){const a=e.encoding?.[d];if(a?.field===void 0)continue;if(!(["color","stroke"].includes(d)?d==="color"?e.mark.type==="area"?["nominal","ordinal","quantitative"]:["nominal","ordinal","quantitative","temporal"]:["nominal","ordinal","quantitative","temporal"]:d==="strokeDash"?["nominal","ordinal"]:["quantitative"]).includes(a.fieldType))throw new Error(`Path ${d} encoding has an unsupported field type.`);k(n,t,a.field,d,a,d==="color"?r:void 0)}return t}function A(n,e){const i=e.encoding?.group,o=i===void 0?[]:m(i.fields??i.field);for(const r of o)f(n,r);const t=n.map(r=>o.length===0?void 0:o.length===1?r[o[0]]:JSON.stringify(o.map(l=>r[l])));return{fields:o,values:t,domain:[...new Set(t)]}}export{F as derivePathSeriesFieldValues,m as normalizeGroupFields,E as pathGroupFields,h as pathSeriesKey,P as readPathSeriesFields,A as readSeriesIdentity,j as validatePathSeriesAppearance};
+import{validateNonEmptyString as y}from"../core/validation.js";import{readCategoricalLineColor as p,validateCategoricalColorConsumer as S}from"./scales/colorConsumers.js";import{readNominalField as f,readQuantitativeField as O,readScaleField as x}from"./scales/fields.js";function m(n){const e=Array.isArray(n)?[...n]:[n];for(const i of e)y(i,"Path group field");if(e.length===0||new Set(e).size!==e.length)throw new Error("Path group fields must be non-empty and unique.");return e}function E(n){const e=n.encoding?.group;if(e!==void 0){if(e.fieldType!=="nominal")throw new Error(`Path group on mark "${n.id}" must be nominal.`);if(Object.hasOwn(e,"field")&&Object.hasOwn(e,"fields"))throw new Error("Path group requires exactly one of field or fields.");return m(e.fields??e.field)}if(n.mark?.type!=="line")return[];const i=["nominal","ordinal"].includes(n.encoding?.color?.fieldType)?n.encoding.color.field:void 0,o=n.encoding?.strokeDash?.field;if(i!==void 0&&o!==void 0&&i!==o)throw new Error("Line color field must match strokeDash field unless encodeGroup defines the series.");return i===void 0&&o===void 0?[]:[i??o]}function h(n){return JSON.stringify(n.map(e=>e===void 0?{}:e))}function g(n,e){const i=n.encoding?.color,o=Array.isArray(e)?e.find(t=>t.id===i?.scale):e?.[i?.scale];return o!==void 0&&S(n,i,o)?o:void 0}function P(n,e,i){const o=E(e),t=g(e,i);for(const r of o)t&&e.encoding?.group===void 0&&r===e.encoding.color.field?p(n,r):f(n,r);return o}function k(n,e,i,o,t={},r){const l=o==="strokeWidth"||o==="opacity",d=o==="color"&&r!==void 0?p(n,i):o==="stroke"||o==="color"&&["quantitative","temporal"].includes(t.fieldType)?x(n,i,t.fieldType??"nominal",{temporalUnit:t.temporalUnit}):l?O(n,i):f(n,i),a=new Map;return n.forEach((u,v)=>{const c=h(e.map(w=>u[w])),s=d[v];if(o==="strokeWidth"&&s<0)throw new RangeError(`Line strokeWidth field "${i}" cannot contain negative values.`);if(a.has(c)&&a.get(c)!==s)throw new Error(`Path ${o} field "${i}" must have one value within each series.`);a.set(c,s)}),a}function F(n,e,i,o,t,r){if(e.length===0)return[];const l=Object.keys(e[0]?.key??{}),d=k(n,l,i,o,t,Object.hasOwn(r??{},"unknown")?r:void 0);return e.map(a=>d.get(h(Object.values(a.key))))}function j(n,e,i,o){if(!["line","area"].includes(e.mark?.type)||e.encoding?.parallel!==void 0)return;const t=o??P(n,e,i);if(o!==void 0)for(const d of t)f(n,d);const r=g(e,i),l=e.mark.type==="line"?["color","stroke","strokeDash","strokeWidth","opacity"]:["color","stroke","opacity"];for(const d of l){const a=e.encoding?.[d];if(a?.field===void 0)continue;if(!(["color","stroke"].includes(d)?d==="color"?e.mark.type==="area"?["nominal","ordinal","quantitative"]:["nominal","ordinal","quantitative","temporal"]:["nominal","ordinal","quantitative","temporal"]:d==="strokeDash"?["nominal","ordinal"]:["quantitative"]).includes(a.fieldType))throw new Error(`Path ${d} encoding has an unsupported field type.`);k(n,t,a.field,d,a,d==="color"?r:void 0)}return t}function A(n,e){const i=e.encoding?.group,o=i===void 0?[]:m(i.fields??i.field);for(const r of o)f(n,r);const t=n.map(r=>o.length===0?void 0:o.length===1?r[o[0]]:JSON.stringify(o.map(l=>r[l])));return{fields:o,values:t,domain:[...new Set(t)]}}export{F as derivePathSeriesFieldValues,m as normalizeGroupFields,E as pathGroupFields,h as pathSeriesKey,P as readPathSeriesFields,A as readSeriesIdentity,j as validatePathSeriesAppearance};