ggaction 0.0.20 → 0.0.22

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 lt,normalizeCompositionPadding as it,validateCompositionSpacing as b}from"./composition.js";const at=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 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 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,u]of Object.entries(d))b(u,`Facet headerLayout.outer.${o}`);const g={outer:d};for(const[o,u,x,z]of[["cellRows",["top","bottom"],i,"row"],["cellColumns",["left","right"],f,"column"]]){if(o==="cellColumns"&&r[o]===void 0)continue;const v=o==="cellRows"?r[o]??{}:r[o];if(!U(v)||Object.keys(v).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 E=v[a]??Array(x).fill(0);if(!Array.isArray(E)||E.length!==x)throw new RangeError(`Facet headerLayout.${o}.${a} must match ${z} count.`);return E.forEach((m,D)=>b(m,`Facet headerLayout.${o}.${a}[${D}]`)),[a,[...E]]}))}return g}function yt({children:r,columns:i,gap:f=P.gap,align:d=P.align,padding:g=P.padding,titleHeight:o=0,sharedLegend:u=!1,sharedLegendGap:x=at,sharedLegendWidth:z=st,sharedLegendHeight:v=ct,sharedLegendPosition:a="right",headerLayout:E,spacing:m="canvas",topLane:D,plots:L}={}){if(!["canvas","plot"].includes(m))throw new Error(`Unknown facet spacing "${m}".`);const $=ot(D,m),H=new Map((L??[]).map(e=>[e.id,e])),W=r;let h=M;if(m==="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),F=ht(r??[],i),I=lt(r?.map(({value:e,row:t,column:s,...l})=>l)),c=F?.columns??mt(i,I.length),w=b(f,"Facet gap"),N=nt(d),S=it(g),p=Object.fromEntries(Object.keys(S).map(e=>[e,S[e]+h[e]])),j=b(o,"Facet title height"),Y=$===void 0?j:0;if(typeof u!="boolean")throw new TypeError("Facet sharedLegend must be a boolean.");const k=b(x,"Facet shared legend gap"),Z=b(z,"Facet shared legend width"),B=b(v,"Facet shared legend height");if(!ut.includes(a))throw new Error(`Unknown facet shared legend position "${a}".`);const O=["right","left"].includes(a),J=["left","top"].includes(a),G=u?k+(O?Z:B):0,A=F?.rows??Math.ceil(I.length/c);let n=ft(E,A,c);if(m==="plot"){let e=0;for(const[t,s]of[[n.cellRows.bottom,n.cellRows.top],[n.cellColumns?.right??[],n.cellColumns?.left??[]]])for(let l=1;l<t.length;l+=1)e=Math.max(e,t[l-1]+s[l]);if(e>w)throw rt(new Error("Plot spacing gap is too small for the facet headers."),{code:"invalid-value",optionPath:"gap",actual:w,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(c).fill(0),right:Array(c).fill(0)},C=Array(c).fill(-1/0),R=Array(A).fill(-1/0);I.forEach((e,t)=>{const s=F===void 0?t%c:r[t].column,l=F===void 0?Math.floor(t/c):r[t].row;C[s]=Math.max(C[s],e.width),R[l]=Math.max(R[l],e.height)});const X=C.map((e,t)=>p.left+n.outer.left+C.slice(0,t).reduce((s,l,_)=>s+T.left[_]+l+T.right[_],0)+w*t+T.left[t]),tt=R.map((e,t)=>Y+p.top+n.outer.top+R.slice(0,t).reduce((s,l,_)=>s+n.cellRows.top[_]+l+n.cellRows.bottom[_],0)+w*t+n.cellRows.top[t]),y=I.map((e,t)=>{const s=F===void 0?t%c:r[t].column,l=F===void 0?Math.floor(t/c):r[t].row;return{id:e.id,value:V[t],column:s,row:l,x:X[s]+(J&&O?G:0)+Q(C[s]-e.width,N),y:tt[l]+(J&&!O?G:0)+Q(R[l]-e.height,N),width:e.width,height:e.height}}),q=p.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)+w*Math.max(0,c-1)+n.outer.right+p.right,K=Y+p.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)+w*Math.max(0,A-1)+n.outer.bottom+p.bottom;if(m==="plot")for(let e=0;e<y.length;e+=1){const t=H.get(y[e].id);y[e].x-=t.x,y[e].y-=t.y,y[e].width=W[e].width,y[e].height=W[e].height}return et({...m==="plot"?{spacing:m}:{},...$===void 0?{}:{topLane:$},columns:c,rows:A,gap:w,align:N,padding:S,titleHeight:j,headerLayout:n,gridWidth:q,width:q+(O?G:0),height:K+(O?0:G),children:y,...u?{legend:{position:a,x:a==="right"?q+k:0,y:a==="bottom"?K+k:a==="top"?j:j+p.top+30,width:Z,height:B}}:{}})}export{at as DEFAULT_FACET_LEGEND_GAP,ct as DEFAULT_FACET_LEGEND_HEIGHT,st as DEFAULT_FACET_LEGEND_WIDTH,yt as resolveFacetLayout};

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/facetGuides/layout.js

@@ -1 +1 @@
-import{resolveAuthoredFacetLegendLayout as p}from"./ownerLayout.js";import{cartesianAxisOwners as B}from"../../selectors/axes.js";import{PLOT_LEGEND_POSITIONS as F}from"../../layout/legend.js";import{resolveConcreteGraphicBounds as G}from"../../grammar/schemas/graphicBounds.js";import{resolveFacetOuterSides as I}from"../../grammar/facets/guides.js";import{resolveTextBounds as P,textBoundsIntersect as C}from"../../core/textMetrics.js";import{axisGraphicIds as E}from"../guides/resources.js";import{resolveFacetHeaderItems as T}from"../facetHeaders.js";function b(o,t,e){return{left:o.left+t,right:o.right+t,top:o.top+e,bottom:o.bottom+e}}function M(o,t,e,f){const r=o.materializationConfigs.textMetrics,h=I({placements:t.children}),i=[];for(const s of t.children){const m=o.children[s.id];for(const a of B(m))for(const[g,w]of[[2,"labels"],[3,"title"]]){const n=a.config?.[w]?.position;if(o.compositionSpec.facet.guides.axes==="outer"&&!h[n]?.includes(s.id))continue;const u=E(a.channel,a.id)[g];if(m.graphicSpec.objects[u]===void 0)continue;const x=G(m.graphicSpec,u,r);x!==void 0&&i.push(b(x,s.x,s.y))}}const{items:d}=T(t,e,f);for(const s of d)s.properties.text!==""&&i.push(P(s.properties,r));return i}function O(o,t,e,f,r){const h=o.right-o.left,i=o.bottom-o.top,d=e==="right"?t.x+t.width+r:e==="left"?t.x-r-h:f==="left"?t.x:f==="right"?t.x+t.width-h:t.x+(t.width-h)/2,s=["left","right"].includes(e)?t.y:e==="top"?t.y-r-i:t.y+t.height+r;return{left:d,right:d+h,top:s,bottom:s+i}}function q(o,{layout:t,plot:e,plots:f,title:r,preparedHeaders:h,prepared:i}){if(i?.mode==="authored")return p(o,{layout:t,plot:e,title:r,prepared:i,guides:M(o,t,f,h)});if(i?.mode!=="promoted")return{layout:t,plot:e};const d=i.occupiedGroup;if(d?.placement.at!==void 0||F.includes(d?.placement.position))return{layout:t,plot:e};const s=i.reservation.position,m=i.reservation.align,a=i.kinds.map(c=>i.source.guideConfigs.legend[c]),g=i.reservation.gap,w=d===void 0?a.every(c=>c.inferredOffset===!0):d.inferredOffset===!0;let n=O(i.bounds,e,s,m,g);const u=M(o,t,f,h),x=u.map(c=>s==="right"?c.right-(e.x+e.width):s==="left"?e.x-c.left:s==="top"?e.y-c.top:c.bottom-(e.y+e.height));if(w)n=O(i.bounds,e,s,m,Math.max(g,...x.map(c=>c+g)));else if(u.some(c=>C(n,c)))throw new Error("Facet shared legend overlaps retained axes or headers.");const l=Math.max(0,t.padding.left-n.left),v=Math.max(0,r.height+t.padding.top-n.top),L=t.children.map(c=>({...c,x:c.x+l,y:c.y+v})),S={...e,x:e.x+l,y:e.y+v};return n=b(n,l,v),{plot:S,layout:{...t,children:L,width:Math.ceil(Math.max(t.width+l,n.right+t.padding.right)),height:Math.ceil(Math.max(t.height+v,n.bottom+t.padding.bottom)),legend:{position:s,x:n.left,y:n.top,width:n.right-n.left,height:n.bottom-n.top,translation:{x:n.left-i.bounds.left,y:n.top-i.bounds.top}}}}}export{q as resolvePromotedFacetLegendLayout};
+import{resolveAuthoredFacetLegendLayout as G}from"./ownerLayout.js";import{PLOT_LEGEND_POSITIONS as I}from"../../layout/legend.js";import{resolveConcreteGraphicBounds as O}from"../../grammar/schemas/graphicBounds.js";import{resolveTextBounds as P,textBoundsIntersect as y}from"../../core/textMetrics.js";import{resolveFacetHeaderItems as C,retainedFacetGuideIds as E}from"../facetHeaders.js";function w(n,t,e){return{left:n.left+t,right:n.right+t,top:n.top+e,bottom:n.bottom+e}}function M(n,t,e,f){const d=n.materializationConfigs.textMetrics,c=[];for(const r of t.children){const h=n.children[r.id];for(const m of E(n,r.id)){const g=O(h.graphicSpec,m,d);g!==void 0&&c.push(w(g,r.x,r.y))}}const{items:i}=C(t,e,f);for(const r of i)r.properties.text!==""&&c.push(P(r.properties,d));return c}function b(n,t,e,f,d){const c=n.right-n.left,i=n.bottom-n.top,r=e==="right"?t.x+t.width+d:e==="left"?t.x-d-c:f==="left"?t.x:f==="right"?t.x+t.width-c:t.x+(t.width-c)/2,h=["left","right"].includes(e)?t.y:e==="top"?t.y-d-i:t.y+t.height+d;return{left:r,right:r+c,top:h,bottom:h+i}}function k(n,{layout:t,plot:e,plots:f,title:d,preparedHeaders:c,prepared:i}){if(i?.mode==="authored")return G(n,{layout:t,plot:e,title:d,prepared:i,guides:M(n,t,f,c)});if(i?.mode!=="promoted")return{layout:t,plot:e};const r=i.occupiedGroup;if(r?.placement.at!==void 0||I.includes(r?.placement.position))return{layout:t,plot:e};const h=i.reservation.position,m=i.reservation.align,g=i.kinds.map(s=>i.source.guideConfigs.legend[s]),u=i.reservation.gap,l=r===void 0?g.every(s=>s.inferredOffset===!0):r.inferredOffset===!0;let o=b(i.bounds,e,h,m,u);const v=M(n,t,f,c),L=v.map(s=>h==="right"?s.right-(e.x+e.width):h==="left"?e.x-s.left:h==="top"?e.y-s.top:s.bottom-(e.y+e.height));if(l)o=b(i.bounds,e,h,m,Math.max(u,...L.map(s=>s+u)));else if(v.some(s=>y(o,s)))throw new Error("Facet shared legend overlaps retained axes or headers.");const a=Math.max(0,t.padding.left-o.left),x=Math.max(0,d.height+t.padding.top-o.top),B=t.children.map(s=>({...s,x:s.x+a,y:s.y+x})),F={...e,x:e.x+a,y:e.y+x};return o=w(o,a,x),{plot:F,layout:{...t,children:B,width:Math.ceil(Math.max(t.width+a,o.right+t.padding.right)),height:Math.ceil(Math.max(t.height+x,o.bottom+t.padding.bottom)),legend:{position:h,x:o.left,y:o.top,width:o.right-o.left,height:o.bottom-o.top,translation:{x:o.left-i.bounds.left,y:o.top-i.bounds.top}}}}}export{k as resolvePromotedFacetLegendLayout};

package/src/materialization/facetGuides/placement.js

@@ -145,15 +145,8 @@ function attachAuthoredParentLegend(program, prepared, layout, synchronizeColorS
     compositionSpec: { ...spec, facet: { ...spec.facet, guides: { ...spec.facet.guides, legend: prepared.intent } } } });
 }
 
-export function applyFacetGuideComposition(program, { layout, plot, synchronizeColorSizeMeaning } = {}) {
-  if (!isPlainObject(layout) || !Array.isArray(layout.children)) {
-    throw new TypeError("Facet guide composition requires a resolved layout.");
-  }
-  if (!isPlainObject(plot)) {
-    throw new TypeError("Facet guide composition requires resolved plot bounds.");
-  }
-  const prepared = prepareSharedFacetLegend(program);
-  const children = layout.children.map(cell => {
+export function prepareFacetGuideOwnership(program, placements, prepared) {
+  const children = placements.map(cell => {
     const child = program.children[cell.id];
     return {
       id: cell.id,
@@ -164,17 +157,36 @@ export function applyFacetGuideComposition(program, { layout, plot, synchronizeC
       legendKinds: legendKinds(child)
     };
   });
-  const ownership = planFacetGuideOwnership({
-    placements: layout.children,
+  return planFacetGuideOwnership({
+    placements,
     children,
     axes: program.compositionSpec.facet.guides.axes,
     legend: program.compositionSpec.facet.guides.legend,
     ...(prepared === undefined ? {} : { sharedLegends: prepared.compatibility })
   });
+}
+
+export function applyFacetGuideComposition(program, { layout, plot, synchronizeColorSizeMeaning } = {}) {
+  if (!isPlainObject(layout) || !Array.isArray(layout.children)) {
+    throw new TypeError("Facet guide composition requires a resolved layout.");
+  }
+  if (!isPlainObject(plot)) {
+    throw new TypeError("Facet guide composition requires resolved plot bounds.");
+  }
+  const prepared = prepareSharedFacetLegend(program);
+  const ownership = prepareFacetGuideOwnership(program, layout.children, prepared);
   let next = program;
   for (const cell of layout.children) {
     const namespace = `${program.compositionSpec.id}-${cell.id}`;
     const childPlan = ownership.children[cell.id];
+    // Density guides belong to the gradient owner rather than a color channel.
+    // Facets currently support no shared density guide; the parent's legend
+    // policy still removes each local copy while retaining hue legends.
+    for (const [owner, config] of Object.entries(program.children[cell.id].markConfigs)) {
+      if (!config.gradientPlot) continue;
+      next = removeNamespacedGraphics(next, namespace,
+        ["DensityLegend", "DensityLegendLabels", "DensityLegendTitle"].map(suffix => `${owner}${suffix}`));
+    }
     const axisOwners = cartesianAxisOwners(program.children[cell.id]);
     for (const axisId of childPlan.removeAxes) {
       const owner = axisOwners.find(owner => owner.id === axisId);