ggaction 0.0.23 → 0.0.26

package/src/grammar/colorSizeLegend.js

@@ -1,12 +1,15 @@
 import {sameOrderedValues,validateOptionObject,validateUnitInterval,validateNonNegativeFinite,validateNonEmptyString} from '../core/validation.js';
-import {isContinuousColorScaleType} from './scales/types.js';
+import {isContinuousColorScaleType,isDiscretizedColorScaleType} from './scales/types.js';
 import {isContinuousSizeScaleType} from './scales/size.js';
 
-export function isColorSizeChannels(channels) {
- return Array.isArray(channels)&&channels.length===2&&channels.includes('color')&&channels.includes('size');
+export function isColorSizeChannels(channels,combine='color-size') {
+ return Array.isArray(channels)&&(combine==='color-size-shape'
+  ? channels.length===3&&channels.includes('shape')&&channels.includes('size')&&['color','stroke'].some(c=>channels.includes(c))
+  : channels.length===2&&channels.includes('color')&&channels.includes('size'));
 }
 
-export function resolveColorSizeMapping({layer,scales,pointConfig,coordinate}) {
+export function resolveColorSizeMapping({layer,scales,pointConfig,coordinate,combine='color-size',channels}) {
+ if(combine==='color-size-shape')return resolveColorSizeShapeMapping({layer,scales,coordinate,channels});
  const color=layer?.encoding?.color,size=layer?.encoding?.size;
  const colorScale=scales[color?.scale],sizeScale=scales[size?.scale];
  if(layer?.mark?.type!=='point'||coordinate?.type!=='cartesian'||
@@ -26,7 +29,20 @@ export function resolveColorSizeMapping({layer,scales,pointConfig,coordinate}) {
  return {target:layer.id,field:color.field,fieldType:'quantitative',colorScale:color.scale,sizeScale:size.scale,domain};
 }
 
-export function normalizeColorSizeSymbol(value,previous) {
+export function normalizeColorSizeSymbol(value,previous,mapping) {
+ if(mapping?.combine==='color-size-shape') {
+  if(value===undefined)return {...(previous??{type:'point'})};
+  if(value==='auto')return {type:'point'};
+  validateOptionObject(value,['type','fill','stroke','strokeWidth','opacity'],'Color-size-shape symbol');
+  if(value.type!==undefined&&value.type!=='point')throw new Error('Combined symbols require type point.');
+  const symbol={type:'point',...previous,...value};
+  const mapped=mapping.colorChannel==='stroke'?'stroke':'fill';
+  if(Object.hasOwn(symbol,mapped))throw new Error(`Combined symbols cannot override mapped ${mapped}.`);
+  for(const key of ['fill','stroke'])if(symbol[key]!==undefined)validateNonEmptyString(symbol[key],`Combined symbol ${key}`);
+  if(symbol.strokeWidth!==undefined)validateNonNegativeFinite(symbol.strokeWidth,'Combined symbol strokeWidth');
+  if(symbol.opacity!==undefined)validateUnitInterval(symbol.opacity,'Combined symbol opacity');
+  return symbol;
+ }
  if(value===undefined)return {...(previous??{type:'point',strokeWidth:0,opacity:1})};
  if(value==='auto')return {type:'point',strokeWidth:0,opacity:1};
  validateOptionObject(value,['type','stroke','strokeWidth','opacity'],'Color-size symbol');
@@ -37,3 +53,38 @@ export function normalizeColorSizeSymbol(value,previous) {
  validateUnitInterval(symbol.opacity,'Color-size symbol opacity');
  return symbol;
 }
+
+function resolveColorSizeShapeMapping({layer,scales,coordinate,channels}) {
+ const hues=channels===undefined?['color','stroke'].filter(c=>layer?.encoding?.[c]?.scale!==undefined)
+  :channels.filter(c=>['color','stroke'].includes(c));
+ if(hues.length!==1)throw new Error('Color-size-shape requires one color or stroke channel; select channels explicitly.');
+ const colorChannel=hues[0],hue=layer?.encoding?.[colorChannel],size=layer?.encoding?.size,shape=layer?.encoding?.shape;
+ const colorScale=scales[hue?.scale],sizeScale=scales[size?.scale],shapeScale=scales[shape?.scale];
+ if(layer?.mark?.type!=='point'||coordinate?.type!=='cartesian'||
+   hue?.fieldType!=='quantitative'||size?.fieldType!=='quantitative'||
+   !['nominal','ordinal'].includes(shape?.fieldType)||typeof hue.field!=='string'||
+   [size,shape].some(e=>e.field!==hue.field||e.data!==hue.data||e.aggregate!==hue.aggregate)||
+   !isDiscretizedColorScaleType(colorScale?.type)||!isDiscretizedColorScaleType(sizeScale?.type)||shapeScale?.type!=='ordinal') {
+  throw new Error('Color-size-shape requires one Cartesian point owner with the same field and grain on interval hue/size and ordinal shape.');
+ }
+ if(!sameOrderedValues(colorScale.thresholds,sizeScale.thresholds))throw new Error('Combined interval scales require identical threshold boundaries.');
+ return {target:layer.id,field:hue.field,fieldType:'quantitative',colorScale:hue.scale,sizeScale:size.scale,
+  shapeScale:shape.scale,colorChannel,domain:[...colorScale.domain]};
+}
+
+export function validateColorSizeShapeSamples(sampling,scale) {
+ const cuts=scale.thresholds;
+ if(sampling.mode!=='values'||sampling.values.length!==cuts.length+1||sampling.values.some((value,index)=>
+  !Number.isFinite(value)||index>0&&value<cuts[index-1]||index<cuts.length&&value>=cuts[index])) {
+  throw new Error('Color-size-shape requires one explicit finite value in each ordered threshold interval.');
+ }
+ return [...sampling.values];
+}
+
+export function colorSizeScaleIds(config) {
+ return [config.colorScale,config.sizeScale,...(config.shapeScale===undefined?[]:[config.shapeScale])];
+}
+
+export function colorSizeChannels(config) {
+ return [config.colorChannel??'color','size',...(config.shapeScale===undefined?[]:['shape'])];
+}

package/src/grammar/displayLabels.js

@@ -91,3 +91,13 @@ export function resolveDisplayLabelColor(value, map, fallback) {
   const entry = map?.find(entry => sameDisplayLabelValue(entry.value, value));
   return entry?.color ?? fallback;
 }
+
+export function normalizeLegendDisplayLabelMap(descriptor, map, scaleType) {
+  if (["size", "colorSize"].includes(descriptor.kind) && descriptor.family === "sampled") {
+    return normalizeNumericDisplayLabelMap(map, "editLegendBlock labelMap");
+  }
+  if (descriptor.family !== "categorical" && !(descriptor.family === "discrete-size" && scaleType === "ordinal")) {
+    throw new Error("editLegendBlock labelMap requires a categorical or continuous size block.");
+  }
+  return normalizeDisplayLabelMap(map, "editLegendBlock labelMap");
+}

package/src/grammar/facetHeaders.js

@@ -1 +1 @@
-import{validateOptionObject as o,validateNonEmptyString as r,validatePositiveFinite as a,validateNonNegativeFinite as c}from"../core/validation.js";import{resolveRotation as s}from"./rotation.js";const f=Object.freeze(["text","fontSize","fontFamily","fontWeight","color","offset","align","rotation","alongOffset"]);function d(e){if(o(e,f,"Facet header title",{allowEmpty:!1}),r(e.text,"Facet header title text"),/[\r\n\u2028\u2029]/u.test(e.text))throw new TypeError("Facet header title text must be one line.");e.fontSize!==void 0&&a(e.fontSize,"Facet header title fontSize");for(const t of["fontFamily","color"])e[t]!==void 0&&r(e[t],`Facet header title ${t}`);if(e.fontWeight!==void 0&&!(typeof e.fontWeight=="string"&&e.fontWeight.length>0||Number.isFinite(e.fontWeight)))throw new TypeError("Facet header title fontWeight must be a non-empty string or finite number.");if(e.offset!==void 0&&c(e.offset,"Facet header title offset"),e.align!==void 0&&!["start","center","end"].includes(e.align))throw new TypeError("Facet header title align must be start, center, or end.");for(const t of["rotation","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Facet header title ${t} must contain finite normalized radians or coordinates.`)}function h(e,t){if(t===!1)return;o(t,f,"Facet header title",{allowEmpty:!1});for(const i of Object.keys(t))if(t[i]===void 0)throw new TypeError(`Facet header title ${i} must not be undefined.`);const n={...e,...t};return Object.hasOwn(t,"rotation")&&(n.rotation=s(t.rotation,"Facet header title rotation")),d(n),n}function w(e){for(const t of e.common===void 0?[e]:[e.common,e.row,e.column]){if(t!==void 0&&Object.hasOwn(t,"anchor")&&!["plot","content","view"].includes(t.anchor))throw new TypeError("Facet header anchor must be plot, content, or view.");if(t?.rotation!==void 0&&!Number.isFinite(t.rotation))throw new TypeError("Facet header rotation must contain finite normalized radians.");t?.title!==void 0&&d(t.title)}if(e.title!==void 0||e.common?.title!==void 0)throw new TypeError("Facet header title requires an explicit row or column role.");if(e.mode!=="roles"&&(e.row?.title!==void 0||e.column?.title!==void 0))throw new TypeError("Facet field titles require role header mode.")}export{h as normalizeFacetHeaderTitle,w as validateFacetHeaderRotations,d as validateFacetHeaderTitle};
+import{validateOptionObject as o,validateNonEmptyString as r,validatePositiveFinite as a,validateNonNegativeFinite as c}from"../core/validation.js";import{resolveRotation as s}from"./rotation.js";const f=Object.freeze(["text","fontSize","fontFamily","fontWeight","color","offset","align","rotation","alongOffset"]);function d(e){if(o(e,f,"Facet header title",{allowEmpty:!1}),r(e.text,"Facet header title text"),/[\u2028\u2029]/u.test(e.text))throw new TypeError("Facet header title line breaks must use LF, CR or CRLF.");e.fontSize!==void 0&&a(e.fontSize,"Facet header title fontSize");for(const t of["fontFamily","color"])e[t]!==void 0&&r(e[t],`Facet header title ${t}`);if(e.fontWeight!==void 0&&!(typeof e.fontWeight=="string"&&e.fontWeight.length>0||Number.isFinite(e.fontWeight)))throw new TypeError("Facet header title fontWeight must be a non-empty string or finite number.");if(e.offset!==void 0&&c(e.offset,"Facet header title offset"),e.align!==void 0&&!["start","center","end"].includes(e.align))throw new TypeError("Facet header title align must be start, center, or end.");for(const t of["rotation","alongOffset"])if(Object.hasOwn(e,t)&&!Number.isFinite(e[t]))throw new TypeError(`Facet header title ${t} must contain finite normalized radians or coordinates.`)}function h(e,t){if(t===!1)return;o(t,f,"Facet header title",{allowEmpty:!1});for(const i of Object.keys(t))if(t[i]===void 0)throw new TypeError(`Facet header title ${i} must not be undefined.`);const n={...e,...t};return Object.hasOwn(t,"rotation")&&(n.rotation=s(t.rotation,"Facet header title rotation")),d(n),n}function w(e){for(const t of e.common===void 0?[e]:[e.common,e.row,e.column]){if(t!==void 0&&Object.hasOwn(t,"anchor")&&!["plot","content","view"].includes(t.anchor))throw new TypeError("Facet header anchor must be plot, content, or view.");if(t?.rotation!==void 0&&!Number.isFinite(t.rotation))throw new TypeError("Facet header rotation must contain finite normalized radians.");t?.title!==void 0&&d(t.title)}if(e.title!==void 0||e.common?.title!==void 0)throw new TypeError("Facet header title requires an explicit row or column role.");if(e.mode!=="roles"&&(e.row?.title!==void 0||e.column?.title!==void 0))throw new TypeError("Facet field titles require role header mode.")}export{h as normalizeFacetHeaderTitle,w as validateFacetHeaderRotations,d as validateFacetHeaderTitle};

package/src/grammar/facets/dependencies.js

@@ -115,9 +115,16 @@ export function resolveFacetFamily(semanticSpec) {
       semanticSpec.layers.length === 0) {
     throw new Error("facet requires at least one materializable layer.");
   }
-  const primary = semanticSpec.layers.filter(layer =>
-    !(layer.mark?.type === "text" && layer.source !== undefined)
-  );
+  // Literal positioned notes decorate a chart rather than define its data
+  // coordinate family. Keep validating/materializing them, but do not confuse
+  // a plot-space Cartesian annotation with a second Cartesian chart in a polar
+  // or parallel facet. A text-only chart still supplies its own primary layer.
+  const annotations = semanticSpec.layers.filter(layer => layer.mark?.type === 'text' &&
+    ['x', 'y', 'text'].every(channel => Object.hasOwn(layer.encoding?.[channel] ?? {}, 'datum')));
+  const dataLayers = semanticSpec.layers.filter(layer =>
+    !(layer.mark?.type === 'text' && layer.source !== undefined) && !annotations.includes(layer));
+  const primary = dataLayers.length ? dataLayers : annotations;
+  for (const note of annotations) classifyPrimaryLayer(semanticSpec, note);
   if (primary.length === 0) {
     throw new Error("facet requires at least one primary materializable layer.");
   }

package/src/grammar/facets/guides.js

@@ -1,3 +1,4 @@
+import {colorSizeScaleIds} from "../colorSizeLegend.js";
 import { cloneAndFreeze, isPlainObject } from "../../core/immutable.js";
 
 
@@ -167,7 +168,7 @@ function requireLegendChildren(children) {
 }
 
 function scaleIds(config, kind) {
-  const ids = kind === "colorSize" ? [config.colorScale, config.sizeScale]
+  const ids = kind === "colorSize" ? colorSizeScaleIds(config)
     : config.scales ?? (config.scale === undefined ? [] : [config.scale]);
   if (!Array.isArray(ids) || ids.length === 0 || !ids.every(id =>
     typeof id === "string" && id.length > 0

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.`);
+}