ggaction 0.0.21 → 0.0.23

package/src/layout/canvas.js

@@ -1 +1 @@
-import{annotateError as d}from"../core/diagnostics.js";import{cloneAndFreeze as n,isPlainObject as v}from"../core/immutable.js";import{validateNonEmptyString as h,validateNonNegativeFinite as u,validatePositiveFinite as a,validateOptionObject as l}from"../core/validation.js";const f=Object.freeze(["top","right","bottom","left"]),c=n({top:30,right:30,bottom:60,left:70}),x=n({width:640,height:400,background:"white",margin:c});function p(e,r){u(e,`Canvas margin.${r}`)}function E(e,r=c){if(Number.isFinite(e)){if(e<0)throw new RangeError("Canvas margin must not be negative.");return n({top:e,right:e,bottom:e,left:e})}if(!v(e))throw new TypeError("Canvas margin must be a number or a plain object.");const o=Object.keys(e);if(o.length===0)throw new TypeError("Canvas margin object must contain at least one side.");for(const t of o){if(!f.includes(t))throw new Error(`Unknown canvas margin option "${t}".`);p(e[t],t)}return n({...r,...e})}function O(e){if(e===!1)return!1;l(e,["color","lineWidth"],"Canvas plotBorder");const r={color:"#ddd",lineWidth:1,...e};return h(r.color,"Canvas plotBorder color"),a(r.lineWidth,"Canvas plotBorder lineWidth"),n(r)}function y({width:e,height:r,background:o,margin:t,plotBorder:i=!1}){a(e,"Canvas width"),a(r,"Canvas height"),h(o,"Canvas background");for(const s of f)p(t[s],s);if(t.left+t.right>=e)throw new RangeError("Canvas horizontal margins must be smaller than width.");if(t.top+t.bottom>=r)throw new RangeError("Canvas vertical margins must be smaller than height.");if(i!==!1&&i.lineWidth>=Math.min(e-t.left-t.right,r-t.top-t.bottom))throw new RangeError("Canvas plotBorder lineWidth must be smaller than both plot dimensions.")}function w({width:e,height:r,margin:o}){return n({x:o.left,y:o.top,width:e-o.left-o.right,height:r-o.top-o.bottom})}function j(e){const r=e.graphicSpec.objects.canvas,o=e.materializationConfigs.canvas?.margin;if(r?.type!=="canvas"||!Number.isFinite(r.properties.width)||!Number.isFinite(r.properties.height)||o===void 0)throw new Error("Graphical layout requires Canvas dimensions and margin.");return w({width:r.properties.width,height:r.properties.height,margin:o})}function b(e,r){if(!r||![r.width,r.height].every(t=>Number.isFinite(t)&&t>0)||!Array.isArray(e)||e.some(t=>!t||![t.left,t.right,t.top,t.bottom].every(Number.isFinite)||t.left>t.right||t.top>t.bottom))return;const o={top:0,right:0,bottom:0,left:0};for(const t of e)o.top=Math.max(o.top,-t.top),o.right=Math.max(o.right,t.right-r.width),o.bottom=Math.max(o.bottom,t.bottom-r.height),o.left=Math.max(o.left,-t.left);return Object.values(o).some(t=>t>1e-9)?n(o):void 0}function N(e,r,o){const t=new Error(e),i=b(r,o);return i===void 0?t:d(t,{reason:"canvas-overflow",canvasOverflow:i})}function F(e,r){const o=Object.hasOwn(e,"plot")?e.plot:r;if(!(o===void 0||o===!1)){if(l(o,["width","height"],"Canvas plot"),a(o.width,"Canvas plot width"),a(o.height,"Canvas plot height"),Object.hasOwn(e,"width")||Object.hasOwn(e,"height"))throw new Error("Canvas plot dimensions cannot be combined with fixed outer dimensions.");return n(o)}}export{x as DEFAULT_CANVAS,c as DEFAULT_MARGIN,N as canvasOverflowError,w as createGraphicBounds,E as normalizeMargin,O as normalizePlotBorder,b as resolveCanvasOverflow,F as resolveCanvasPlot,j as resolveGraphicBounds,y as validateCanvasState};
+import{annotateError as p}from"../core/diagnostics.js";import{cloneAndFreeze as n,isPlainObject as u}from"../core/immutable.js";import{validateNonEmptyString as l,validateNonNegativeFinite as v,validatePositiveFinite as a,validateOptionObject as h,validateBoolean as w}from"../core/validation.js";const f=Object.freeze(["top","right","bottom","left"]),d=n({top:30,right:30,bottom:60,left:70}),x=n({width:640,height:400,background:"white",margin:d});function c(e,r){v(e,`Canvas margin.${r}`)}function E(e,r=d){if(Number.isFinite(e)){if(e<0)throw new RangeError("Canvas margin must not be negative.");return n({top:e,right:e,bottom:e,left:e})}if(!u(e))throw new TypeError("Canvas margin must be a number or a plain object.");const o=Object.keys(e);if(o.length===0)throw new TypeError("Canvas margin object must contain at least one side.");for(const t of o){if(!f.includes(t))throw new Error(`Unknown canvas margin option "${t}".`);c(e[t],t)}return n({...r,...e})}function O(e){if(e===!1)return!1;h(e,["color","lineWidth","underlay"],"Canvas plotBorder"),e.underlay!==void 0&&w(e.underlay,"Canvas plotBorder underlay");const{underlay:r,...o}=e,t={color:"#ddd",lineWidth:1,...o,...r===!0?{underlay:!0}:{}};return l(t.color,"Canvas plotBorder color"),a(t.lineWidth,"Canvas plotBorder lineWidth"),n(t)}function j({width:e,height:r,background:o,margin:t,plotBorder:i=!1}){a(e,"Canvas width"),a(r,"Canvas height"),l(o,"Canvas background");for(const s of f)c(t[s],s);if(t.left+t.right>=e)throw new RangeError("Canvas horizontal margins must be smaller than width.");if(t.top+t.bottom>=r)throw new RangeError("Canvas vertical margins must be smaller than height.");if(i!==!1&&i.lineWidth>=Math.min(e-t.left-t.right,r-t.top-t.bottom))throw new RangeError("Canvas plotBorder lineWidth must be smaller than both plot dimensions.")}function b({width:e,height:r,margin:o}){return n({x:o.left,y:o.top,width:e-o.left-o.right,height:r-o.top-o.bottom})}function N(e){const r=e.graphicSpec.objects.canvas,o=e.materializationConfigs.canvas?.margin;if(r?.type!=="canvas"||!Number.isFinite(r.properties.width)||!Number.isFinite(r.properties.height)||o===void 0)throw new Error("Graphical layout requires Canvas dimensions and margin.");return b({width:r.properties.width,height:r.properties.height,margin:o})}function m(e,r){if(!r||![r.width,r.height].every(t=>Number.isFinite(t)&&t>0)||!Array.isArray(e)||e.some(t=>!t||![t.left,t.right,t.top,t.bottom].every(Number.isFinite)||t.left>t.right||t.top>t.bottom))return;const o={top:0,right:0,bottom:0,left:0};for(const t of e)o.top=Math.max(o.top,-t.top),o.right=Math.max(o.right,t.right-r.width),o.bottom=Math.max(o.bottom,t.bottom-r.height),o.left=Math.max(o.left,-t.left);return Object.values(o).some(t=>t>1e-9)?n(o):void 0}function F(e,r,o){const t=new Error(e),i=m(r,o);return i===void 0?t:p(t,{reason:"canvas-overflow",canvasOverflow:i})}function A(e,r){const o=Object.hasOwn(e,"plot")?e.plot:r;if(!(o===void 0||o===!1)){if(h(o,["width","height"],"Canvas plot"),a(o.width,"Canvas plot width"),a(o.height,"Canvas plot height"),Object.hasOwn(e,"width")||Object.hasOwn(e,"height"))throw new Error("Canvas plot dimensions cannot be combined with fixed outer dimensions.");return n(o)}}export{x as DEFAULT_CANVAS,d as DEFAULT_MARGIN,F as canvasOverflowError,b as createGraphicBounds,E as normalizeMargin,O as normalizePlotBorder,m as resolveCanvasOverflow,A as resolveCanvasPlot,N as resolveGraphicBounds,j as validateCanvasState};

package/src/layout/facetContentFlow.js

@@ -0,0 +1,101 @@
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { validateCompositionSpacing } from "./composition.js";
+
+/** Pack ordered full content bounds without imposing common plot origins. */
+export function resolveFacetContentFlow({ children, columns, gap = 16 } = {}) {
+  if (!Array.isArray(children) || children.length === 0) {
+    throw new TypeError("Facet content flow requires non-empty children.");
+  }
+  columns ??= children.length;
+  if (!Number.isInteger(columns) || columns <= 0) {
+    throw new RangeError("Facet content flow columns must be a positive integer.");
+  }
+  columns = Math.min(columns, children.length);
+  validateCompositionSpacing(gap, "Facet content flow gap");
+  const ids = new Set();
+  const rightExtents = Array(columns).fill(0);
+  const bottomExtents = Array(Math.ceil(children.length / columns)).fill(0);
+  const cells = children.map((child, index) => {
+    if (!isPlainObject(child) || typeof child.id !== "string" ||
+        child.id.length === 0 || ids.has(child.id)) {
+      throw new TypeError("Facet content flow requires unique non-empty child IDs.");
+    }
+    const bounds = child.bounds;
+    if (!isPlainObject(bounds) ||
+        !["left", "right", "top", "bottom"].every(key => Number.isFinite(bounds[key])) ||
+        bounds.left > bounds.right || bounds.top > bounds.bottom) {
+      throw new RangeError("Facet content flow requires finite ordered content bounds.");
+    }
+    ids.add(child.id);
+    const column = index % columns, row = Math.floor(index / columns);
+    rightExtents[column] = Math.max(rightExtents[column], Math.ceil(bounds.right));
+    bottomExtents[row] = Math.max(bottomExtents[row], Math.ceil(bounds.bottom));
+    return { id: child.id, column, row, bounds: { ...bounds } };
+  });
+  const columnOrigins = Array(columns).fill(0);
+  let x = 0;
+  const placed = cells.map(cell => {
+    x = cell.column === 0 ? 0 : x + rightExtents[cell.column - 1] + gap +
+      Math.max(0, Math.ceil(-cell.bounds.left));
+    if (cell.row > 0) {
+      columnOrigins[cell.column] += bottomExtents[cell.row - 1] + gap +
+        Math.max(0, Math.ceil(-cell.bounds.top));
+    }
+    const y = columnOrigins[cell.column];
+    if (![x, y, x + cell.bounds.left, x + cell.bounds.right,
+      y + cell.bounds.top, y + cell.bounds.bottom].every(Number.isFinite)) {
+      throw new RangeError("Facet content flow exceeds finite layout bounds.");
+    }
+    return {
+      id: cell.id, column: cell.column, row: cell.row, x, y,
+      bounds: {
+        left: x + cell.bounds.left, right: x + cell.bounds.right,
+        top: y + cell.bounds.top, bottom: y + cell.bounds.bottom
+      }
+    };
+  });
+  const bounds = { left: Infinity, right: -Infinity, top: Infinity, bottom: -Infinity };
+  for (const child of placed) {
+    bounds.left = Math.min(bounds.left, child.bounds.left);
+    bounds.right = Math.max(bounds.right, child.bounds.right);
+    bounds.top = Math.min(bounds.top, child.bounds.top);
+    bounds.bottom = Math.max(bounds.bottom, child.bounds.bottom);
+  }
+  return cloneAndFreeze({ columns, gap, children: placed, bounds });
+}
+
+/** Place one shared footer per occupied column beneath the complete content. */
+export function resolveFacetContentFooters({ flow, footers, offset = 0 } = {}) {
+  if (!isPlainObject(flow) || !Array.isArray(flow.children) || flow.children.length === 0 ||
+      !Number.isFinite(flow.bounds?.bottom)) {
+    throw new TypeError("Facet content footers require a resolved content flow.");
+  }
+  if (!Array.isArray(footers) || !Number.isFinite(offset)) {
+    throw new TypeError("Facet content footers require an array and finite offset.");
+  }
+  const lastByColumn = new Map(), occupied = new Set(), ownerIds = new Set();
+  for (const child of flow.children) {
+    if (!isPlainObject(child) || typeof child.id !== "string" || child.id.length === 0 || ownerIds.has(child.id) ||
+        !Number.isInteger(child.column) || child.column < 0 ||
+        !Number.isInteger(child.row) || child.row < 0 || !Number.isFinite(child.x)) {
+      throw new RangeError("Facet content footer owners require finite occupied cells.");
+    }
+    const slot = `${child.row}:${child.column}`;
+    if (occupied.has(slot)) throw new Error("Facet content footer column has duplicate cells.");
+    occupied.add(slot); ownerIds.add(child.id);
+    const previous = lastByColumn.get(child.column);
+    if (previous === undefined || child.row > previous.row) lastByColumn.set(child.column, child);
+  }
+  const columns = new Set(), ids = new Set(), y = Math.ceil(flow.bounds.bottom) + offset;
+  if (!Number.isFinite(y)) throw new RangeError("Facet content footer exceeds finite layout bounds.");
+  return cloneAndFreeze(footers.map(footer => {
+    if (!isPlainObject(footer) || typeof footer.id !== "string" || footer.id.length === 0 ||
+        ids.has(footer.id) || !Number.isInteger(footer.column) ||
+        columns.has(footer.column) || !lastByColumn.has(footer.column)) {
+      throw new Error("Facet content footer requires one unique ID and occupied column.");
+    }
+    ids.add(footer.id); columns.add(footer.column);
+    const owner = lastByColumn.get(footer.column);
+    return { id: footer.id, column: footer.column, ownerId: owner.id, x: owner.x, y };
+  }));
+}

package/src/layout/facetHeaderTitles.js

@@ -0,0 +1 @@
+import{resolveTextBounds as m}from"../core/textMetrics.js";const p=Object.freeze(["fontSize","fontFamily","fontWeight","color"]),b=Object.freeze({left:-Math.PI/2,right:Math.PI/2,top:0,bottom:0});function u(r,o,n,l){const i=m({...o,text:r,x:0,y:0,textAlign:"center",textBaseline:"middle"},l);return["left","right"].includes(n)?i.right-i.left:i.bottom-i.top}function M(r,o){const n=["left","right"].includes(o)?r.cellColumns?.[o]:r.cellRows[o];return n===void 0?0:["left","top"].includes(o)?n[0]:n.at(-1)}function T({roles:r,descriptors:o,space:n,headerLayout:l,profile:i,ids:g}){const a=[];for(const[x,f]of r){if(f.title===void 0)continue;const{side:t}=f,c=f.title,s={...Object.fromEntries(p.map(e=>[e,f[e]])),...c,side:t,align:c.align??"center",rotation:c.rotation??b[t]},d=Math.max(0,...o.filter(e=>e.config.side===t&&e.text!=="").map(e=>u(e.text,e.config,t,i)+e.config.offset+(e.clearance?.[t]??0)));s.offset=c.offset??Math.max(n[t],d)+8;const h=s.offset+u(c.text,s,t,i);l.outer[t]=Math.max(l.outer[t],h-n[t]-M(l,t),0),a.push({topology:"role-title",role:x,ids:g,text:c.text,config:s})}return a}export{T as prepareFacetHeaderTitles};

package/src/layout/facetTopLane.js

@@ -0,0 +1,29 @@
+import { DEFAULT_FACET_TOP_LANE, FACET_TOP_LANE_MODES } from "../core/vocabulary.js";
+import { textBoundsFitCanvas, textBoundsIntersect } from "../core/textMetrics.js";
+
+export function normalizeFacetTopLane(value, spacing) {
+  const mode = value === undefined ? DEFAULT_FACET_TOP_LANE : value;
+  if (!FACET_TOP_LANE_MODES.includes(mode)) {
+    throw new Error('Facet topLane must be "stacked" or "shared".');
+  }
+  if (mode !== DEFAULT_FACET_TOP_LANE && spacing !== "plot") {
+    throw new Error('Shared facet topLane requires spacing "plot".');
+  }
+  return mode === DEFAULT_FACET_TOP_LANE ? undefined : mode;
+}
+
+export function assertFacetTopLaneBounds({ canvas, titles, headers, retained, plots }) {
+  const owned = [...titles, ...headers];
+  if (owned.some(bounds => !textBoundsFitCanvas(bounds, canvas))) {
+    throw new Error("Shared facet top lane text does not fit the final Canvas.");
+  }
+  if (titles.some(title => headers.some(header => textBoundsIntersect(title, header)))) {
+    throw new Error("Shared facet top lane title overlaps a facet header.");
+  }
+  if (owned.some(bounds => plots.some(plot => textBoundsIntersect(bounds, plot)))) {
+    throw new Error("Shared facet top lane text overlaps a child plot.");
+  }
+  if (owned.some(bounds => retained.some(other => textBoundsIntersect(bounds, other)))) {
+    throw new Error("Shared facet top lane text overlaps retained chart text.");
+  }
+}

package/src/layout/facets.js

@@ -1 +1 @@
-import{cloneAndFreeze as V,isPlainObject as k}from"../core/immutable.js";import{DEFAULT_COMPOSITION_LAYOUT as q,normalizeCompositionAlign as X,normalizeCompositionChildren as tt,normalizeCompositionPadding as et,validateCompositionSpacing as y}from"./composition.js";const ot=18,rt=132,nt=0,lt=Object.freeze(["right","left","top","bottom"]);function it(r,i){const f=r??i;if(!Number.isInteger(f)||f<=0)throw new RangeError("Facet columns must be a positive integer.");return Math.min(f,i)}function at(r,i){if(!r.some(o=>o.row!==void 0||o.column!==void 0))return;if(r.some(o=>!(Number.isInteger(o.row)&&o.row>=0&&Number.isInteger(o.column)&&o.column>=0)))throw new RangeError("Facet grid children require non-negative integer row and column coordinates.");const d=r.map(o=>`${o.row}:${o.column}`);if(new Set(d).size!==d.length)throw new Error("Facet grid children must occupy unique row and column coordinates.");const g=Math.max(...r.map(o=>o.column))+1;if(i!==void 0&&i!==g)throw new RangeError("Facet grid columns must match the declared column domain.");return{columns:g,rows:Math.max(...r.map(o=>o.row))+1}}function B(r,i){return i==="start"?0:i==="end"?r:r/2}const $=Object.freeze({top:0,right:0,bottom:0,left:0});function st(r,i,f){if(r===void 0)return{outer:$,cellRows:{top:Array(i).fill(0),bottom:Array(i).fill(0)}};if(!k(r)||Object.keys(r).some(o=>!["outer","cellRows","cellColumns"].includes(o)))throw new TypeError("Facet headerLayout must contain outer and cellRows.");const d={...$,...r.outer??{}};if(!k(r.outer??{})||Object.keys(d).some(o=>!Object.hasOwn($,o)))throw new TypeError("Facet headerLayout.outer must contain side reservations.");for(const[o,u]of Object.entries(d))y(u,`Facet headerLayout.outer.${o}`);const g={outer:d};for(const[o,u,I,D]of[["cellRows",["top","bottom"],i,"row"],["cellColumns",["left","right"],f,"column"]]){if(o==="cellColumns"&&r[o]===void 0)continue;const _=o==="cellRows"?r[o]??{}:r[o];if(!k(_)||Object.keys(_).some(a=>!u.includes(a)))throw new TypeError(`Facet headerLayout.${o} must contain ${u[0]} and ${u[1]} arrays.`);g[o]=Object.fromEntries(u.map(a=>{const b=_[a]??Array(I).fill(0);if(!Array.isArray(b)||b.length!==I)throw new RangeError(`Facet headerLayout.${o}.${a} must match ${D} count.`);return b.forEach((m,E)=>y(m,`Facet headerLayout.${o}.${a}[${E}]`)),[a,[...b]]}))}return g}function ht({children:r,columns:i,gap:f=q.gap,align:d=q.align,padding:g=q.padding,titleHeight:o=0,sharedLegend:u=!1,sharedLegendGap:I=ot,sharedLegendWidth:D=rt,sharedLegendHeight:_=nt,sharedLegendPosition:a="right",headerLayout:b,spacing:m="canvas",plots:E}={}){if(!["canvas","plot"].includes(m))throw new Error(`Unknown facet spacing "${m}".`);const G=new Map((E??[]).map(e=>[e.id,e])),U=r;let h=$;if(m==="plot"){if(!Array.isArray(E)||E.length!==r?.length||G.size!==E.length)throw new Error("Plot spacing requires one plot bounds record per child.");h={...$},r=r.map(e=>{const t=G.get(e.id);if(!t||![t.x,t.y,t.width,t.height].every(Number.isFinite)||t.x<0||t.y<0||t.width<=0||t.height<=0||t.x+t.width>e.width+1e-9||t.y+t.height>e.height+1e-9)throw new Error("Plot spacing requires valid contained child plot bounds.");return h.left=Math.max(h.left,t.x),h.top=Math.max(h.top,t.y),h.right=Math.max(h.right,e.width-t.x-t.width),h.bottom=Math.max(h.bottom,e.height-t.y-t.height),{...e,width:t.width,height:t.height}})}const J=r?.map(e=>e?.value),F=at(r??[],i),L=tt(r?.map(({value:e,row:t,column:l,...s})=>s)),c=F?.columns??it(i,L.length),A=y(f,"Facet gap"),H=X(d),N=et(g),w=Object.fromEntries(Object.keys(N).map(e=>[e,N[e]+h[e]])),T=y(o,"Facet title height");if(typeof u!="boolean")throw new TypeError("Facet sharedLegend must be a boolean.");const z=y(I,"Facet shared legend gap"),W=y(D,"Facet shared legend width"),P=y(_,"Facet shared legend height");if(!lt.includes(a))throw new Error(`Unknown facet shared legend position "${a}".`);const M=["right","left"].includes(a),Y=["left","top"].includes(a),j=u?z+(M?W:P):0,C=F?.rows??Math.ceil(L.length/c);let n=st(b,C,c);if(m==="plot"){for(const[e,t]of[[n.cellRows.bottom,n.cellRows.top],[n.cellColumns?.right??[],n.cellColumns?.left??[]]])for(let l=1;l<e.length;l+=1)if(e[l-1]+t[l]>A)throw new Error("Plot spacing gap is too small for the facet headers.");n={outer:{top:n.outer.top+n.cellRows.top[0],bottom:n.outer.bottom+n.cellRows.bottom.at(-1),left:n.outer.left+(n.cellColumns?.left[0]??0),right:n.outer.right+(n.cellColumns?.right.at(-1)??0)},cellRows:{top:Array(C).fill(0),bottom:Array(C).fill(0)}}}const v=n.cellColumns??{left:Array(c).fill(0),right:Array(c).fill(0)},O=Array(c).fill(-1/0),R=Array(C).fill(-1/0);L.forEach((e,t)=>{const l=F===void 0?t%c:r[t].column,s=F===void 0?Math.floor(t/c):r[t].row;O[l]=Math.max(O[l],e.width),R[s]=Math.max(R[s],e.height)});const K=O.map((e,t)=>w.left+n.outer.left+O.slice(0,t).reduce((l,s,x)=>l+v.left[x]+s+v.right[x],0)+A*t+v.left[t]),Q=R.map((e,t)=>T+w.top+n.outer.top+R.slice(0,t).reduce((l,s,x)=>l+n.cellRows.top[x]+s+n.cellRows.bottom[x],0)+A*t+n.cellRows.top[t]),p=L.map((e,t)=>{const l=F===void 0?t%c:r[t].column,s=F===void 0?Math.floor(t/c):r[t].row;return{id:e.id,value:J[t],column:l,row:s,x:K[l]+(Y&&M?j:0)+B(O[l]-e.width,H),y:Q[s]+(Y&&!M?j:0)+B(R[s]-e.height,H),width:e.width,height:e.height}}),S=w.left+n.outer.left+O.reduce((e,t)=>e+t,0)+v.left.reduce((e,t)=>e+t,0)+v.right.reduce((e,t)=>e+t,0)+A*Math.max(0,c-1)+n.outer.right+w.right,Z=T+w.top+n.outer.top+R.reduce((e,t)=>e+t,0)+n.cellRows.top.reduce((e,t)=>e+t,0)+n.cellRows.bottom.reduce((e,t)=>e+t,0)+A*Math.max(0,C-1)+n.outer.bottom+w.bottom;if(m==="plot")for(let e=0;e<p.length;e+=1){const t=G.get(p[e].id);p[e].x-=t.x,p[e].y-=t.y,p[e].width=U[e].width,p[e].height=U[e].height}return V({...m==="plot"?{spacing:m}:{},columns:c,rows:C,gap:A,align:H,padding:N,titleHeight:T,headerLayout:n,gridWidth:S,width:S+(M?j:0),height:Z+(M?0:j),children:p,...u?{legend:{position:a,x:a==="right"?S+z:0,y:a==="bottom"?Z+z:a==="top"?T:T+w.top+30,width:W,height:P}}:{}})}export{ot as DEFAULT_FACET_LEGEND_GAP,nt as DEFAULT_FACET_LEGEND_HEIGHT,rt as DEFAULT_FACET_LEGEND_WIDTH,ht as resolveFacetLayout};
+import{cloneAndFreeze as et,isPlainObject as U}from"../core/immutable.js";import{normalizeFacetTopLane as ot}from"./facetTopLane.js";import{annotateError as rt}from"../core/diagnostics.js";import{DEFAULT_COMPOSITION_LAYOUT as P,normalizeCompositionAlign as nt,normalizeCompositionChildren as at,normalizeCompositionPadding as it,validateCompositionSpacing as E}from"./composition.js";const lt=18,st=132,ct=0,ut=Object.freeze(["right","left","top","bottom"]);function mt(r,i){const f=r??i;if(!Number.isInteger(f)||f<=0)throw new RangeError("Facet columns must be a positive integer.");return Math.min(f,i)}function ht(r,i){if(!r.some(o=>o.row!==void 0||o.column!==void 0))return;if(r.some(o=>!(Number.isInteger(o.row)&&o.row>=0&&Number.isInteger(o.column)&&o.column>=0)))throw new RangeError("Facet grid children require non-negative integer row and column coordinates.");const d=r.map(o=>`${o.row}:${o.column}`);if(new Set(d).size!==d.length)throw new Error("Facet grid children must occupy unique row and column coordinates.");const w=Math.max(...r.map(o=>o.column))+1;if(i!==void 0&&i!==w)throw new RangeError("Facet grid columns must match the declared column domain.");return{columns:w,rows:Math.max(...r.map(o=>o.row))+1}}function Q(r,i){return i==="start"?0:i==="end"?r:r/2}const M=Object.freeze({top:0,right:0,bottom:0,left:0});function ft(r,i,f){if(r===void 0)return{outer:M,cellRows:{top:Array(i).fill(0),bottom:Array(i).fill(0)}};if(!U(r)||Object.keys(r).some(o=>!["outer","cellRows","cellColumns"].includes(o)))throw new TypeError("Facet headerLayout must contain outer and cellRows.");const d={...M,...r.outer??{}};if(!U(r.outer??{})||Object.keys(d).some(o=>!Object.hasOwn(M,o)))throw new TypeError("Facet headerLayout.outer must contain side reservations.");for(const[o,m]of Object.entries(d))E(m,`Facet headerLayout.outer.${o}`);const w={outer:d};for(const[o,m,x,z]of[["cellRows",["top","bottom"],i,"row"],["cellColumns",["left","right"],f,"column"]]){if(o==="cellColumns"&&r[o]===void 0)continue;const R=o==="cellRows"?r[o]??{}:r[o];if(!U(R)||Object.keys(R).some(l=>!m.includes(l)))throw new TypeError(`Facet headerLayout.${o} must contain ${m[0]} and ${m[1]} arrays.`);w[o]=Object.fromEntries(m.map(l=>{const F=R[l]??Array(x).fill(0);if(!Array.isArray(F)||F.length!==x)throw new RangeError(`Facet headerLayout.${o}.${l} must match ${z} count.`);return F.forEach((c,D)=>E(c,`Facet headerLayout.${o}.${l}[${D}]`)),[l,[...F]]}))}return w}function yt({children:r,columns:i,gap:f=P.gap,align:d=P.align,padding:w=P.padding,titleHeight:o=0,sharedLegend:m=!1,sharedLegendGap:x=lt,sharedLegendWidth:z=st,sharedLegendHeight:R=ct,sharedLegendPosition:l="right",headerLayout:F,spacing:c="canvas",topLane:D,plots:L}={}){if(!["canvas","plot","content"].includes(c))throw new Error(`Unknown facet spacing "${c}".`);const $=ot(D,c),H=new Map((L??[]).map(e=>[e.id,e])),W=r;let h=M;if(c==="plot"){if(!Array.isArray(L)||L.length!==r?.length||H.size!==L.length)throw new Error("Plot spacing requires one plot bounds record per child.");h={...M},r=r.map(e=>{const t=H.get(e.id);if(!t||![t.x,t.y,t.width,t.height].every(Number.isFinite)||t.x<0||t.y<0||t.width<=0||t.height<=0||t.x+t.width>e.width+1e-9||t.y+t.height>e.height+1e-9)throw new Error("Plot spacing requires valid contained child plot bounds.");return h.left=Math.max(h.left,t.x),h.top=Math.max(h.top,t.y),h.right=Math.max(h.right,e.width-t.x-t.width),h.bottom=Math.max(h.bottom,e.height-t.y-t.height),{...e,width:t.width,height:t.height}})}const V=r?.map(e=>e?.value),g=ht(r??[],i);if(c==="content"&&g!==void 0)throw new Error("Content flow requires a wrapped facet, not a keyed facet grid.");const I=at(r?.map(({value:e,row:t,column:s,...a})=>a)),u=g?.columns??mt(i,I.length),p=E(f,"Facet gap"),N=nt(d),k=it(w),y=Object.fromEntries(Object.keys(k).map(e=>[e,k[e]+h[e]])),j=E(o,"Facet title height"),Y=$===void 0?j:0;if(typeof m!="boolean")throw new TypeError("Facet sharedLegend must be a boolean.");const q=E(x,"Facet shared legend gap"),Z=E(z,"Facet shared legend width"),B=E(R,"Facet shared legend height");if(!ut.includes(l))throw new Error(`Unknown facet shared legend position "${l}".`);const O=["right","left"].includes(l),J=["left","top"].includes(l),G=m?q+(O?Z:B):0,A=g?.rows??Math.ceil(I.length/u);let n=ft(F,A,u);if(c==="plot"){let e=0;for(const[t,s]of[[n.cellRows.bottom,n.cellRows.top],[n.cellColumns?.right??[],n.cellColumns?.left??[]]])for(let a=1;a<t.length;a+=1)e=Math.max(e,t[a-1]+s[a]);if(e>p)throw rt(new Error("Plot spacing gap is too small for the facet headers."),{code:"invalid-value",optionPath:"gap",actual:p,limit:e});n={outer:{top:n.outer.top+n.cellRows.top[0],bottom:n.outer.bottom+n.cellRows.bottom.at(-1),left:n.outer.left+(n.cellColumns?.left[0]??0),right:n.outer.right+(n.cellColumns?.right.at(-1)??0)},cellRows:{top:Array(A).fill(0),bottom:Array(A).fill(0)}},$!==void 0&&(n.outer.top=0)}const T=n.cellColumns??{left:Array(u).fill(0),right:Array(u).fill(0)},C=Array(u).fill(-1/0),v=Array(A).fill(-1/0);I.forEach((e,t)=>{const s=g===void 0?t%u:r[t].column,a=g===void 0?Math.floor(t/u):r[t].row;C[s]=Math.max(C[s],e.width),v[a]=Math.max(v[a],e.height)});const X=C.map((e,t)=>y.left+n.outer.left+C.slice(0,t).reduce((s,a,_)=>s+T.left[_]+a+T.right[_],0)+p*t+T.left[t]),tt=v.map((e,t)=>Y+y.top+n.outer.top+v.slice(0,t).reduce((s,a,_)=>s+n.cellRows.top[_]+a+n.cellRows.bottom[_],0)+p*t+n.cellRows.top[t]),b=I.map((e,t)=>{const s=g===void 0?t%u:r[t].column,a=g===void 0?Math.floor(t/u):r[t].row;return{id:e.id,value:V[t],column:s,row:a,x:X[s]+(J&&O?G:0)+Q(C[s]-e.width,N),y:tt[a]+(J&&!O?G:0)+Q(v[a]-e.height,N),width:e.width,height:e.height}}),S=y.left+n.outer.left+C.reduce((e,t)=>e+t,0)+T.left.reduce((e,t)=>e+t,0)+T.right.reduce((e,t)=>e+t,0)+p*Math.max(0,u-1)+n.outer.right+y.right,K=Y+y.top+n.outer.top+v.reduce((e,t)=>e+t,0)+n.cellRows.top.reduce((e,t)=>e+t,0)+n.cellRows.bottom.reduce((e,t)=>e+t,0)+p*Math.max(0,A-1)+n.outer.bottom+y.bottom;if(c==="plot")for(let e=0;e<b.length;e+=1){const t=H.get(b[e].id);b[e].x-=t.x,b[e].y-=t.y,b[e].width=W[e].width,b[e].height=W[e].height}return et({...c!=="canvas"?{spacing:c}:{},...$===void 0?{}:{topLane:$},columns:u,rows:A,gap:p,align:N,padding:k,titleHeight:j,headerLayout:n,gridWidth:S,width:S+(O?G:0),height:K+(O?0:G),children:b,...m?{legend:{position:l,x:l==="right"?S+q:0,y:l==="bottom"?K+q:l==="top"?j:j+y.top+30,width:Z,height:B}}:{}})}export{lt as DEFAULT_FACET_LEGEND_GAP,ct as DEFAULT_FACET_LEGEND_HEIGHT,st as DEFAULT_FACET_LEGEND_WIDTH,yt as resolveFacetLayout};

package/src/layout/guideCollisions.js

@@ -1,3 +1,10 @@
+function intersects(a, b) {
+  const tolerance = Number.EPSILON * 16 * Math.max(1,
+    ...Object.values(a).map(Math.abs), ...Object.values(b).map(Math.abs));
+  return Math.min(a.right, b.right) - Math.max(a.left, b.left) > tolerance &&
+    Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top) > tolerance;
+}
+
 export function assertGuideCollisionBlocks(blocks) {
   for (let index = 0; index < blocks.length; index += 1) {
     const a = blocks[index];
@@ -5,14 +12,13 @@ export function assertGuideCollisionBlocks(blocks) {
       if (a.kind === "axis" && b.kind === "axis") {
         if (!(a.namedAxis || b.namedAxis) || a.axisId === b.axisId || !a.textBounds || !b.textBounds) continue;
         if (a.textBounds.some(left => left && b.textBounds.some(right => right &&
-            left.left < right.right && left.right > right.left && left.top < right.bottom && left.bottom > right.top))) {
+            intersects(left, right)))) {
           throw new Error(`The ${a.id} and ${b.id} text overlap; independent axes require separate text bounds.`);
         }
         continue;
       }
       if (a.position !== b.position) continue;
-      if (a.bounds.left < b.bounds.right && a.bounds.right > b.bounds.left &&
-        a.bounds.top < b.bounds.bottom && a.bounds.bottom > b.bounds.top) {
+      if (intersects(a.bounds, b.bounds)) {
         throw new Error(`The ${a.position} ${a.id} and ${b.id} overlap; guides require more margin space or different offsets.`);
       }
     }

package/src/layout/legendGroup.js

@@ -1 +1 @@
-import{PLOT_LEGEND_POSITIONS as M}from"./legend.js";import{SIDE_LEGEND_BLOCK_GAP as N,HORIZONTAL_LEGEND_BLOCK_GAP as P}from"./legendLane.js";function A({blocks:g,group:l,plot:e,canvas:L,allowOverflow:O=!1,deferCanvasFit:G=!1}){if(g.length===0)return[];const{placement:t,blockLayout:f}=l,u=M.includes(t.position),c=["left","right"].includes(t.position),x=f==="column"||f==="wrap"&&c,y=u||c||t.at!==void 0?N:P,_=e.width-(u?t.offset*2:0);let h=0,p=0,w=0;const d=g.map(i=>{const o=i.bounds.right-i.bounds.left,E=i.bounds.bottom-i.bounds.top;if(f==="wrap"&&!x&&!u&&o>_&&!O)throw new Error("Horizontal legend block requires more plot width.");!x&&f==="wrap"&&h>0&&h+o>_&&(h=0,p+=w+y,w=0);const I={id:i.id,x:h,y:p,width:o,height:E};return x?p+=E+y:(h+=o+y,w=Math.max(w,E)),I}),r=Math.max(...d.map(i=>i.x+i.width)),a=Math.max(...d.map(i=>i.y+i.height));if(f==="wrap"&&t.position==="top"){const i=new Map;for(const o of d)i.set(o.y,Math.max(i.get(o.y)??0,o.height));for(const o of d)o.y=a-o.y-i.get(o.y)}let n,s;if(t.at!==void 0)n=e.x+t.at.x,s=e.y+t.at.y;else if(u){if(r+2*t.offset>e.width||a+2*t.offset>e.height)throw new Error("In-plot legend group does not fit the plot inset.");n=t.position.endsWith("left")?e.x+t.offset:e.x+e.width-t.offset-r,s=t.position.startsWith("top")?e.y+t.offset:e.y+e.height-t.offset-a}else c?(n=t.position==="right"?e.x+e.width+t.offset:e.x-t.offset-r,s=e.y):(n=t.align==="left"?e.x:t.align==="right"?e.x+e.width-r:e.x+(e.width-r)/2,s=t.position==="top"?e.y-t.offset-a:e.y+e.height+t.offset);const m={left:n,top:s,right:n+r,bottom:s+a};if(!G&&(m.left<0||m.top<0||m.right>L.width||m.bottom>L.height))throw new Error("Legend group requires more Canvas space.");return d.map((i,o)=>({id:i.id,dx:n+i.x-g[o].bounds.left,dy:s+i.y-g[o].bounds.top}))}export{A as resolveLegendGroupPlacement};
+import{canvasOverflowError as M}from"./canvas.js";import{PLOT_LEGEND_POSITIONS as N}from"./legend.js";import{SIDE_LEGEND_BLOCK_GAP as P,HORIZONTAL_LEGEND_BLOCK_GAP as C}from"./legendLane.js";function v({blocks:u,group:O,plot:e,canvas:c,allowOverflow:_=!1,deferCanvasFit:G=!1}){if(u.length===0)return[];const{placement:t,blockLayout:f}=O,w=N.includes(t.position),p=["left","right"].includes(t.position),x=f==="column"||f==="wrap"&&p,y=w||p||t.at!==void 0?P:C,l=e.width-(w?t.offset*2:0);let h=0,E=0,m=0;const d=u.map(i=>{const o=i.bounds.right-i.bounds.left,L=i.bounds.bottom-i.bounds.top;if(f==="wrap"&&!x&&!w&&o>l&&!_)throw new Error("Horizontal legend block requires more plot width.");!x&&f==="wrap"&&h>0&&h+o>l&&(h=0,E+=m+y,m=0);const I={id:i.id,x:h,y:E,width:o,height:L};return x?E+=L+y:(h+=o+y,m=Math.max(m,L)),I}),s=Math.max(...d.map(i=>i.x+i.width)),a=Math.max(...d.map(i=>i.y+i.height));if(f==="wrap"&&t.position==="top"){const i=new Map;for(const o of d)i.set(o.y,Math.max(i.get(o.y)??0,o.height));for(const o of d)o.y=a-o.y-i.get(o.y)}let n,r;if(t.at!==void 0)n=e.x+t.at.x,r=e.y+t.at.y;else if(w){if(s+2*t.offset>e.width||a+2*t.offset>e.height)throw new Error("In-plot legend group does not fit the plot inset.");n=t.position.endsWith("left")?e.x+t.offset:e.x+e.width-t.offset-s,r=t.position.startsWith("top")?e.y+t.offset:e.y+e.height-t.offset-a}else p?(n=t.position==="right"?e.x+e.width+t.offset:e.x-t.offset-s,r=e.y):(n=t.align==="left"?e.x:t.align==="right"?e.x+e.width-s:e.x+(e.width-s)/2,r=t.position==="top"?e.y-t.offset-a:e.y+e.height+t.offset);const g={left:n,top:r,right:n+s,bottom:r+a};if(!G&&(g.left<0||g.top<0||g.right>c.width||g.bottom>c.height))throw t.at!==void 0||O.inferredOffset!==!0?new Error("Legend group requires more Canvas space."):M("Legend group requires more Canvas space.",[g],c);return d.map((i,o)=>({id:i.id,dx:n+i.x-u[o].bounds.left,dy:r+i.y-u[o].bounds.top}))}export{v as resolveLegendGroupPlacement};

package/src/layout/legendItems.js

@@ -1,6 +1,7 @@
 import { measureTextWidth, resolveTextBounds } from "../core/textMetrics.js";
 import { alignLegendStart, resolveLegendGrid, isPlotLegend, legendLabelLineHeight } from "./legend.js";
 import { alignLegendTitle, resolveLegendTitleText } from "./legendText.js";
+import {resolveLegendContentSpacing} from "./legendSpacing.js";
 
 // Measure item content before choosing its edge. Family owners supply the
 // sample dimensions and formatted labels; this module does not inspect scales.
@@ -28,6 +29,7 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
   let symbolX;
   let labelX;
   let itemY;
+  let itemRows;
   let title;
   if (config.layout === "legacy-bottom") {
     const widths = labels.map(text => sampleWidth + config.labels.offset + measureTextWidth(text, config.labels, profile));
@@ -41,6 +43,7 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
     });
     labelX = symbolX.map(value => value + sampleRight + config.labels.offset);
     itemY = labels.map(() => canvas.height - 28);
+    itemRows = labels.map(() => 0);
     title = { x: x + width / 2, y: canvas.height - 52, align: "center" };
   } else if (side) {
     const grid = resolveLegendGrid({
@@ -73,6 +76,7 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
       firstY = titleBounds.bottom + 12 - itemTop;
     }
     itemY = grid.cells.map(cell => firstY + cell.row * pitch);
+    itemRows = grid.cells.map(cell => cell.row);
     title = { x, y: plot.y + 20, align: "left" };
   } else {
     const grid = resolveLegendGrid({ ...config, domain: labels }, sampleWidth, labels.length, sampleHeight, profile);
@@ -95,27 +99,39 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
     symbolX = grid.cells.map(cell => gridX + columns[cell.column] - sampleLeft);
     labelX = symbolX.map(value => value + sampleRight + config.labels.offset);
     itemY = grid.cells.map(cell => gridY + grid.rowHeight / 2 + cell.row * (grid.rowHeight + config.itemGap));
+    itemRows = grid.cells.map(cell => cell.row);
     title = inline ? { x, y: y + height / 2, align: "left" }
       : { x: x + width / 2, y: y + titleHeight / 2, align: "center" };
   }
   const textBounds = (x, y, text, style, align = "left") => resolveTextBounds({
     x, y, text, ...style, textAlign: align, textBaseline: "middle"
   }, profile);
-  const bodyBounds = [
-    ...labels.map((label, index) => textBounds(labelX[index], itemY[index], label, config.labels)),
-    ...symbolX.map((x, index) => {
+  const labelBounds = labels.map((label,index) => textBounds(labelX[index],itemY[index],label,config.labels));
+  const symbolItemBounds = symbolX.map((x, index) => {
       const local = sampleBounds[index];
       return { left: x + local.left, right: x + local.right,
         top: itemY[index] + local.top, bottom: itemY[index] + local.bottom };
-    })
-  ];
+    });
+  const spacingItems = config.rowPadding === undefined && config.titlePadding === undefined ? undefined
+    : labels.map((label,index) => ({row:itemRows[index],x:symbolX[index],y:itemY[index],bounds:[
+    ...(label === "" ? [] : [labelBounds[index]]),
+    ...(symbol.itemBounds !== undefined && index >= symbol.itemBounds.length ? [] : [symbolItemBounds[index]])
+  ]}));
+  const bodyBounds = spacingItems === undefined
+    ? [...labelBounds,...symbolItemBounds] : spacingItems.flatMap(item => item.bounds);
   if (titleVisible) title = alignLegendTitle(title, config.title, config.titleStyle, bodyBounds, profile);
-  const bounds = [
-    ...(titleVisible ? [resolveTextBounds({ x: title.x, y: title.y,
+  const titleBounds = titleVisible ? resolveTextBounds({ x: title.x, y: title.y,
       text: config.title, ...config.titleStyle, lines: titleText.lines,
-      textAlign: title.align, textBaseline: "middle" }, profile)] : []),
-    ...bodyBounds
-  ];
+      textAlign: title.align, textBaseline: "middle" }, profile) : undefined;
+  let bounds = [...(titleVisible ? [titleBounds] : []),...bodyBounds];
+  const spacing = spacingItems === undefined ? undefined : resolveLegendContentSpacing(config,spacingItems,titleBounds);
+  if (spacing !== undefined) {
+    symbolX = symbolX.map((x,index) => x+spacing.offsets[index].dx);
+    labelX = labelX.map((x,index) => x+spacing.offsets[index].dx);
+    itemY = itemY.map((y,index) => y+spacing.offsets[index].dy);
+    title = {...title,x:title.x+spacing.titleOffset.dx,y:title.y+spacing.titleOffset.dy};
+    bounds = spacing.bounds;
+  }
   if (config.layout === "legacy-bottom") {
     const itemBounds = titleVisible ? bounds.slice(1) : bounds;
     if (titleVisible && itemBounds.some(bound => bound.top < bounds[0].bottom)) {

package/src/layout/legendSpacing.js

@@ -0,0 +1,66 @@
+const shift = (bounds, {dx, dy}) => ({
+  left:bounds.left + dx, right:bounds.right + dx,
+  top:bounds.top + dy, bottom:bounds.bottom + dy
+});
+const union = bounds => ({
+  left:Math.min(...bounds.map(b => b.left)), right:Math.max(...bounds.map(b => b.right)),
+  top:Math.min(...bounds.map(b => b.top)), bottom:Math.max(...bounds.map(b => b.bottom))
+});
+
+// Family owners supply existing concrete text/sample bounds and logical row
+// identities. This pure function neither reads scales nor changes a recipe.
+export function resolveLegendContentSpacing(config, items, titleBounds) {
+  if (config.rowPadding === undefined && config.titlePadding === undefined) return undefined;
+  if (items.length === 0) throw new Error("Legend content spacing requires a body item.");
+  const offsets = items.map(() => ({dx:0,dy:0}));
+  const titleOffset = {dx:0,dy:0};
+  const boundsFor = (item, index) => item.bounds.length > 0 ? item.bounds
+    : [{left:item.x,right:item.x,top:item.y,bottom:item.y}];
+  const originalBody = items.flatMap(boundsFor);
+  const original = union([...originalBody, ...(titleBounds === undefined ? [] : [titleBounds])]);
+  if (config.rowPadding !== undefined) {
+    const rows = new Map();
+    items.forEach((item,index) => {
+      const row = rows.get(item.row) ?? {indices:[],bounds:[]};
+      row.indices.push(index);row.bounds.push(...boundsFor(item,index));rows.set(item.row,row);
+    });
+    let previousBottom;
+    for (const [,row] of [...rows.entries()].sort(([a],[b]) => a-b)) {
+      const occupied = union(row.bounds);
+      const dy = previousBottom === undefined ? 0 : previousBottom + config.rowPadding - occupied.top;
+      for (const index of row.indices) offsets[index].dy = dy;
+      previousBottom = occupied.bottom + dy;
+    }
+  }
+  const body = () => items.flatMap((item,index) => boundsFor(item,index).map(b => shift(b,offsets[index])));
+  if (titleBounds !== undefined && config.titlePadding !== undefined) {
+    const occupied = union(body());
+    if (config.titlePosition === "left") {
+      const dx = titleBounds.right + config.titlePadding - occupied.left;
+      for (const offset of offsets) offset.dx += dx;
+    } else if (config.titlePosition === "bottom") {
+      titleOffset.dy = occupied.bottom + config.titlePadding - titleBounds.top;
+    } else {
+      const dy = titleBounds.bottom + config.titlePadding - occupied.top;
+      for (const offset of offsets) offset.dy += dy;
+    }
+  }
+  const occupied = [...body(), ...(titleBounds === undefined ? [] : [shift(titleBounds,titleOffset)])];
+  if (occupied.some(bounds => Object.values(bounds).some(value => !Number.isFinite(value)))) {
+    throw new RangeError("Legend content spacing requires finite occupied bounds.");
+  }
+  const beforeAnchor = union(occupied);
+  const right = config.position === "left" || config.position?.endsWith("right");
+  const horizontal = ["top","bottom"].includes(config.position);
+  const align = horizontal ? config.align ?? "center" : right ? "right" : "left";
+  const coordinate = (bounds, side) => side === "center" ? (bounds.left+bounds.right)/2 : bounds[side];
+  const dx = coordinate(original,align) - coordinate(beforeAnchor,align);
+  const bottom = config.position === "top" || config.position?.startsWith("bottom-");
+  const dy = bottom ? original.bottom - beforeAnchor.bottom : original.top - beforeAnchor.top;
+  for (const offset of offsets) {offset.dx += dx;offset.dy += dy;}
+  titleOffset.dx += dx;titleOffset.dy += dy;
+  if ([...offsets,titleOffset].some(offset => !Number.isFinite(offset.dx) || !Number.isFinite(offset.dy))) {
+    throw new RangeError("Legend content spacing requires finite offsets.");
+  }
+  return {offsets,titleOffset,bounds:[...body(),...(titleBounds === undefined ? [] : [shift(titleBounds,titleOffset)])]};
+}

package/src/layout/plotDrawOrder.js

@@ -0,0 +1,17 @@
+export function resolvePlotDrawOrder({ children, grids, border, axes }) {
+  const present = new Set(children);
+  const gridOrder = grids.filter(grid => present.has(grid.id)).sort((a, b) =>
+    (a.zIndex ?? 0) - (b.zIndex ?? 0) || a.index - b.index);
+  const axisOrder = axes.map(axis => ({ ...axis, ids: children.filter(id => axis.ids.includes(id)) }));
+  const borderId = present.has(border?.id) ? [border.id] : [];
+  const owned = new Set([...gridOrder.map(grid => grid.id), ...borderId, ...axisOrder.flatMap(axis => axis.ids)]);
+  return [
+    ...gridOrder.filter(grid => (grid.zIndex ?? 0) <= 0).map(grid => grid.id),
+    ...(border?.underlay ? borderId : []),
+    ...axisOrder.filter(axis => axis.underlay).flatMap(axis => axis.ids),
+    ...children.filter(id => !owned.has(id)),
+    ...gridOrder.filter(grid => (grid.zIndex ?? 0) > 0).map(grid => grid.id),
+    ...(border?.underlay ? [] : borderId),
+    ...axisOrder.filter(axis => !axis.underlay).flatMap(axis => axis.ids)
+  ];
+}

package/src/materialization/bars/histogram.js

@@ -1,3 +1,4 @@
+import { aggregateRows } from "../../grammar/aggregate.js";
 import { resolveBarCellOpacities } from "./resolve.js";
 import { readSeriesIdentity } from "../../grammar/pathSeries.js";
 import {
@@ -25,7 +26,7 @@ import {
   validateWeightedNumericFields
 } from "../../grammar/weightedStatistics.js";
 
-export function resolveHistogramInput(dataset, xEncoding) {
+export function resolveHistogramInput(dataset, xEncoding, yEncoding) {
   const allValues = readQuantitativeField(dataset.values, xEncoding.field);
   if (xEncoding.weight === undefined) {
     return {
@@ -33,6 +34,11 @@ export function resolveHistogramInput(dataset, xEncoding) {
       values: allValues,
       entries: dataset.values.map((row, index) => ({ row, index })),
       mass(entries) {
+        if (yEncoding?.aggregate !== undefined && yEncoding.aggregate !== "count") {
+          // Empty/insufficient samples have no visible segment, just like zero
+          // count bins. Use the same native aggregate owner as category bars.
+          return aggregateRows(entries.map(entry => entry.row), yEncoding.field, yEncoding.aggregate) ?? 0;
+        }
         return entries.length;
       }
     };
@@ -65,7 +71,7 @@ export function deriveHistogramSegments({
   xScale,
   resolvedScales
 }) {
-  const input = resolveHistogramInput(dataset, xEncoding);
+  const input = resolveHistogramInput(dataset, xEncoding, layer.encoding.y);
   const { rows, values: xValues, entries } = input;
   const bins = resolveHistogramBins({
     values: xValues,

package/src/materialization/bars/resolve.js

@@ -82,7 +82,7 @@ export function requireCompleteBar(program, id) {
     grain === undefined
   ) {
     throw new Error(
-      `Bar mark "${id}" requires binned x/count y or ordinal x/aggregate y encodings.`
+      `Bar mark "${id}" requires binned x/aggregate y or ordinal x/aggregate y encodings.`
     );
   }
   const xScale = findSemanticScale(program, xEncoding.scale);

package/src/materialization/composition.js

@@ -103,6 +103,7 @@ export function attachSnapshotObject(program, snapshot, id, parent) {
       value: itemDefinitions(object)
     });
   }
+  if (object.clip !== undefined) next = next.editGraphics({target: id, property: "clip", value: object.clip});
   for (const childId of object.children ?? []) {
     next = attachSnapshotObject(next, snapshot, childId, id);
   }

package/src/materialization/compositionSnapshot.js

@@ -1,4 +1,4 @@
-import { cloneAndFreeze, freezeOwned, isPlainObject } from "../core/immutable.js";
+import { cloneAndFreeze, freezeOwned, isOwned, isPlainObject } from "../core/immutable.js";
 import { namespaceGraphicId } from "../selectors/graphicCapacity.js";
 export { namespaceGraphicId } from "../selectors/graphicCapacity.js";
 import {
@@ -6,6 +6,17 @@ import {
   walkGraphicTreeEvents
 } from "../grammar/schemas/graphicTree.js";
 
+const snapshots = new WeakMap();
+
+function placeSnapshot(snapshot, placement) {
+  const root = snapshot.order[0], canvas = snapshot.objects[root];
+  if (canvas.properties.x === placement.x && canvas.properties.y === placement.y) return snapshot;
+  return freezeOwned({ order: snapshot.order, objects: freezeOwned({
+    ...snapshot.objects,
+    [root]: freezeOwned({ ...canvas, properties: freezeOwned({ ...canvas.properties, ...placement }) })
+  }) });
+}
+
 function validateNamespace(namespace) {
   if (typeof namespace !== "string" || namespace.length === 0) {
     throw new TypeError("Graphic snapshot namespace must be a non-empty string.");
@@ -84,6 +95,8 @@ export function namespaceGraphicSnapshot(
   ) {
     throw new TypeError("Graphic snapshot requires objects and order.");
   }
+  const cached = snapshots.get(graphicSpec)?.get(resolvedNamespace);
+  if (cached) return placeSnapshot(cached, placement);
   walkGraphicTreeEvents(graphicSpec, {});
   const { id: canvasId, object: canvas } =
     requireSingleOrderedGraphicByType(graphicSpec, "canvas");
@@ -102,8 +115,15 @@ export function namespaceGraphicSnapshot(
     ]
   ));
   const rootId = namespaceGraphicId(resolvedNamespace, canvasId);
-  return freezeOwned({
+  const snapshot = freezeOwned({
     objects: freezeOwned(objects),
     order: freezeOwned([rootId])
   });
+  if (isOwned(graphicSpec)) {
+    if (!snapshots.has(graphicSpec)) snapshots.set(graphicSpec, new Map());
+    const cache = snapshots.get(graphicSpec);
+    cache.set(resolvedNamespace, snapshot);
+    if (cache.size > 16) cache.delete(cache.keys().next().value);
+  }
+  return snapshot;
 }

package/src/materialization/dataProvenance.js

@@ -59,7 +59,7 @@ export function findUpstreamTransform(program, dataset, type) {
     visited.add(current.id);
     if (current.transform?.length !== 1) return undefined;
     const transform = current.transform[0];
-    if (transform.type === type) return transform;
+    if (Array.isArray(type) ? type.includes(transform.type) : transform.type === type) return transform;
     if (findTransformTopology(transform.type)?.provenanceTransparent !== true) {
       return undefined;
     }

package/src/materialization/facetContentBounds.js

@@ -0,0 +1,96 @@
+import { cartesianAxisOwners } from "../selectors/axes.js";
+import { facetAxisMode } from "../core/facetAxisPolicy.js";
+import { resolvePrimitiveGraphicBounds, resolveGraphicParentOffset, resolveGraphicClipBounds } from "../grammar/schemas/graphicBounds.js";
+import { intersectClipBounds } from "../grammar/schemas/graphicClip.js";
+import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
+import { walkGraphicTreeEvents } from "../grammar/schemas/graphicTree.js";
+import { resolveTextBounds, requireFiniteBounds } from "../core/textMetrics.js";
+import { axisGraphicIds, allLegendGraphicIds } from "./guides/resources.js";
+import { resolveGraphicBounds } from "../layout/canvas.js";
+import { prepareSharedFacetLegend } from "./facetGuides/index.js";
+import { prepareFacetGuideOwnership } from "./facetGuides/placement.js";
+
+function includeBounds(union, bounds) {
+  if (bounds === undefined) return union;
+  if (union === undefined) return { ...bounds };
+  return { left: Math.min(union.left, bounds.left), right: Math.max(union.right, bounds.right),
+    top: Math.min(union.top, bounds.top), bottom: Math.max(union.bottom, bounds.bottom) };
+}
+
+// Header entries are concrete child-local text, never caller-supplied bounds.
+export function measureFacetContentChildren(program, { headerItems = [] } = {}) {
+  if (program?.compositionSpec?.type !== "facet") {
+    throw new Error("Facet content measurement requires a facet composition.");
+  }
+  const spec = program.compositionSpec, grid = new Map((spec.facet.grid?.cells ?? []).map(cell => [cell.id, cell]));
+  const placements = spec.children.map((id, index) => ({ id,
+    row: grid.get(id)?.row ?? Math.floor(index / spec.columns),
+    column: grid.get(id)?.column ?? index % spec.columns }));
+  const prepared = prepareSharedFacetLegend(program);
+  const ownership = prepareFacetGuideOwnership(program, placements, prepared);
+  const childIds = new Set(spec.children), headersByOwner = new Map();
+  if (!Array.isArray(headerItems) || headerItems.some(item =>
+    !childIds.has(item?.ownerId) || item.type !== "text" || !isPlainObject(item.properties))) {
+    throw new TypeError("Facet content headers require concrete text with one observed child owner.");
+  }
+  for (const header of headerItems) {
+    if (!headersByOwner.has(header.ownerId)) headersByOwner.set(header.ownerId, []);
+    headersByOwner.get(header.ownerId).push(header);
+  }
+  const components = ["line", "ticks", "labels", "title"];
+  return cloneAndFreeze(placements.map(cell => {
+    const child = program.children[cell.id], graphic = child.graphicSpec;
+    const profile = child.materializationConfigs.textMetrics;
+    const plot = resolveGraphicBounds(child);
+    const plan = ownership.children[cell.id], roles = new Map();
+    for (const owner of cartesianAxisOwners(child)) {
+      const roots = axisGraphicIds(owner.channel, owner.id);
+      for (const [index, component] of components.entries()) {
+        const removed = plan.removeAxes.includes(owner.id) || plan.removeAxisComponents?.[owner.id]?.includes(component);
+        if (removed) roles.set(roots[index], "removed");
+        else if (facetAxisMode(spec.facet.guides.axes, owner.channel) === "outer" && owner.channel === "x" && owner.config?.[component]?.position === "bottom") {
+          roles.set(roots[index], "footer");
+        }
+      }
+    }
+    for (const id of allLegendGraphicIds(plan.removeLegends)) roles.set(id, "removed");
+    const groups = new Map(), stack = [], frames = new Map();
+    const include = entry => {
+      const role = stack.at(-1);
+      if (role === "removed") return;
+      const type = entry.object.type ?? entry.owner?.type, p = entry.object.properties;
+      if (!p || type === "canvas" || p.opacity === 0 || type === "text" && (p.text === "" || p.fill === "none" || p.fill === "transparent")) return;
+      const ownerId = entry.ownerId ?? entry.id;
+      if (!frames.has(ownerId)) frames.set(ownerId, {
+        offset: resolveGraphicParentOffset(graphic, ownerId),
+        clip: resolveGraphicClipBounds(graphic, ownerId, { rootViewport: true })
+      });
+      const { offset: [x, y], clip } = frames.get(ownerId);
+      let bounds = resolvePrimitiveGraphicBounds(type, p, profile);
+      if (bounds === undefined) return;
+      bounds = requireFiniteBounds({ left: bounds.left + x, right: bounds.right + x,
+        top: bounds.top + y, bottom: bounds.bottom + y });
+      if (clip !== undefined) bounds = intersectClipBounds(bounds, clip);
+      if (bounds.left > bounds.right || bounds.top > bounds.bottom) return;
+      const key = role ?? "body";
+      groups.set(key, includeBounds(groups.get(key), bounds));
+    };
+    walkGraphicTreeEvents(graphic, {
+      enter(entry) {
+        stack.push(stack.at(-1) === "removed" ? "removed" : roles.get(entry.id) ?? stack.at(-1));
+        if (entry.object.items === undefined && !(entry.object.children?.length)) include(entry);
+      },
+      item: include,
+      exit() { stack.pop(); }
+    });
+    let body = includeBounds({ left: plot.x, right: plot.x + plot.width, top: plot.y, bottom: plot.y + plot.height }, groups.get("body"));
+    for (const header of headersByOwner.get(cell.id) ?? []) {
+      const p = header.properties;
+      if (p.text !== "" && p.opacity !== 0 && p.fill !== "none" && p.fill !== "transparent") body = includeBounds(body, resolveTextBounds(p, profile));
+    }
+    const relative = bounds => bounds === undefined ? undefined : ({ left: bounds.left - plot.x, right: bounds.right - plot.x,
+      top: bounds.top - plot.y, bottom: bounds.bottom - plot.y });
+    return { ...cell, plot, bounds: relative(body),
+      ...(groups.has("footer") ? { footerBounds: relative(groups.get("footer")) } : {}) };
+  }));
+}