ggaction 0.0.23 → 0.0.24

package/src/layout/composition.js

@@ -1,3 +1,4 @@
+import { validateCompositionSpacing } from "../core/facetGap.js";
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
 
 const DIRECTIONS = ["horizontal", "vertical"];
@@ -11,12 +12,7 @@ export const DEFAULT_COMPOSITION_LAYOUT = cloneAndFreeze({
   padding: { top: 0, right: 0, bottom: 0, left: 0 }
 });
 
-export function validateCompositionSpacing(value, label) {
-  if (!Number.isFinite(value) || value < 0) {
-    throw new RangeError(`${label} must be a non-negative finite number.`);
-  }
-  return value;
-}
+export { validateCompositionSpacing } from "../core/facetGap.js";
 
 function validatePaddingBase(base) {
   if (!isPlainObject(base)) {

package/src/layout/facetContentFlow.js

@@ -1,5 +1,5 @@
 import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import { validateCompositionSpacing } from "./composition.js";
+import { normalizeFacetGap, facetGapAxis, assertFacetGapFinite } from "../core/facetGap.js";
 
 /** Pack ordered full content bounds without imposing common plot origins. */
 export function resolveFacetContentFlow({ children, columns, gap = 16 } = {}) {
@@ -11,7 +11,8 @@ export function resolveFacetContentFlow({ children, columns, gap = 16 } = {}) {
     throw new RangeError("Facet content flow columns must be a positive integer.");
   }
   columns = Math.min(columns, children.length);
-  validateCompositionSpacing(gap, "Facet content flow gap");
+  gap = normalizeFacetGap(gap, "Facet content flow gap");
+  const gapX = facetGapAxis(gap, "x"), gapY = facetGapAxis(gap, "y");
   const ids = new Set();
   const rightExtents = Array(columns).fill(0);
   const bottomExtents = Array(Math.ceil(children.length / columns)).fill(0);
@@ -35,16 +36,23 @@ export function resolveFacetContentFlow({ children, columns, gap = 16 } = {}) {
   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 +
+    x = cell.column === 0 ? 0 : x + rightExtents[cell.column - 1] + gapX +
       Math.max(0, Math.ceil(-cell.bounds.left));
     if (cell.row > 0) {
-      columnOrigins[cell.column] += bottomExtents[cell.row - 1] + gap +
+      columnOrigins[cell.column] += bottomExtents[cell.row - 1] + gapY +
         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.");
+    if (typeof gap === "number") {
+      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.");
+      }
+    } else {
+      assertFacetGapFinite(gap, "x", [x, x + cell.bounds.left, x + cell.bounds.right],
+        "Facet content flow exceeds finite layout bounds.");
+      assertFacetGapFinite(gap, "y", [y, y + cell.bounds.top, y + cell.bounds.bottom],
+        "Facet content flow exceeds finite layout bounds.");
     }
     return {
       id: cell.id, column: cell.column, row: cell.row, x, y,

package/src/layout/facets.js

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

package/src/layout/title.js

@@ -21,7 +21,7 @@ export function buildTitleReadingBlock({ text, subtitle }, config, profile) {
     style: config.subtitleStyle, profile
   });
   const titleLineHeight = config.lineHeight ?? config.titleStyle.fontSize * 1.2;
-  const subtitleLineHeight = config.lineHeight ??
+  const subtitleLineHeight = config.subtitleLineHeight ?? config.lineHeight ??
     config.subtitleStyle.fontSize * 1.2;
   const titleCenters = lineCenters(
     titleLines,

package/src/materialization/guides/layout.js

@@ -1 +1 @@
-import{resetLegendClipGraphics as m,hasLegendClipGraphics as c}from"../legendClip.js";import{localLegendPosition as g}from"../legendGroups.js";import{needsLegendAxisReflow as p,needsSideLegendAxisReflow as h}from"./resources.js";import{getErrorDetails as C}from"../../core/diagnostics.js";import{planCanvasRematerialization as L}from"../layout.js";import{applyMaterializationPlan as v}from"../planner.js";import{assertGuideCollisionBlocks as G}from"../../layout/guideCollisions.js";import{resolveGuideCollisionBlocks as y}from"./resources.js";import{hasPlotUnderlays as u}from"../plotDrawOrder.js";import{resolveGuideCollisionBlocks as A}from"./resources.js";function z(i,l){if(i.context.deferGuideLayoutValidation===!0)return l(i);const a=i.materializationConfigs.canvas?.plot;let n=i.materializationConfigs.canvas?.margin,e;for(let s=0;;s+=1)try{let t=m(i)._withContext({deferGuideLayoutValidation:!0});s>0&&(t=t.editGraphics({target:"canvas",property:"width",value:a.width+n.left+n.right}).editGraphics({target:"canvas",property:"height",value:a.height+n.top+n.bottom})._withCanvasConfig({...t.materializationConfigs.canvas,margin:n}),t=v(t,L(t))),e=l(t),c(i)&&!c(e)&&Object.values(e.guideConfigs.legend??{}).some(o=>o.clipHeight!==void 0)&&(e=e.rematerializeLegend()),e.compositionSpec===void 0&&h(i,e)&&(e=e.rematerializeLegend()),e.compositionSpec===void 0&&Object.values(e.guideConfigs.legend??{}).some(o=>["left","right"].includes(o.position))&&(e=e.rematerializeSideLegendLane()),e.compositionSpec===void 0&&p(i,e)&&(e=e.rematerializeHorizontalLegendLane()),e.compositionSpec===void 0&&(Object.keys(e.guideConfigs.legendGroups??{}).length>0||Object.values(e.guideConfigs.legend??{}).some(o=>g(o)!==void 0))&&(e=e.rematerializeLegendGroups()),a!==void 0&&e.titleConfig!==void 0&&(e=e.rematerializeTitle()),(u(i)||u(e))&&(e=e.rematerializePlotDrawOrder());break}catch(t){const o=C(t)?.canvasOverflow;if(a===void 0||o===void 0||s>=16)throw t;n=Object.fromEntries(Object.keys(n).map(d=>[d,o[d]>0?Math.ceil((n[d]+o[d])*4)/4:n[d]]))}const{deferGuideLayoutValidation:w,...f}=e.context;Object.hasOwn(i.context,"deferGuideLayoutValidation")&&(f.deferGuideLayoutValidation=i.context.deferGuideLayoutValidation);const r=e._clone({context:f});return G(y(r.graphicSpec,r.guideConfigs,r.titleConfig,r.materializationConfigs.textMetrics)),r}function B(i){return function(l){return z(this,a=>i.call(a,l))}}export{A as resolveGuideCollisionBlocks,z as withGuideLayoutTransaction,B as withGuideLayoutValidation};
+import{resetLegendClipGraphics as p,hasLegendClipGraphics as u}from"../legendClip.js";import{localLegendPosition as m}from"../legendGroups.js";import{needsLegendAxisReflow as h,needsSideLegendAxisReflow as x}from"./resources.js";import{getErrorDetails as v}from"../../core/diagnostics.js";import{planCanvasRematerialization as C}from"../layout.js";import{applyMaterializationPlan as L}from"../planner.js";import{assertGuideCollisionBlocks as G}from"../../layout/guideCollisions.js";import{resolveGuideCollisionBlocks as w}from"./resources.js";import{hasPlotUnderlays as g}from"../plotDrawOrder.js";import{resolveGuideCollisionBlocks as M}from"./resources.js";function _(i,l,a){const t=a(i._withContext({pendingRelativeTitleAxis:l})),{pendingRelativeTitleAxis:e,...s}=t.context;return Object.hasOwn(i.context,"pendingRelativeTitleAxis")&&(s.pendingRelativeTitleAxis=i.context.pendingRelativeTitleAxis),t._clone({context:s})}function y(i,l){if(i.context.deferGuideLayoutValidation===!0)return l(i);const a=i.materializationConfigs.canvas?.plot;let t=i.materializationConfigs.canvas?.margin,e;for(let f=0;;f+=1)try{let n=p(i)._withContext({deferGuideLayoutValidation:!0});f>0&&(n=n.editGraphics({target:"canvas",property:"width",value:a.width+t.left+t.right}).editGraphics({target:"canvas",property:"height",value:a.height+t.top+t.bottom})._withCanvasConfig({...n.materializationConfigs.canvas,margin:t}),n=L(n,C(n))),e=l(n),u(i)&&!u(e)&&Object.values(e.guideConfigs.legend??{}).some(o=>o.clipHeight!==void 0)&&(e=e.rematerializeLegend()),e.compositionSpec===void 0&&x(i,e)&&(e=e.rematerializeLegend()),e.compositionSpec===void 0&&Object.values(e.guideConfigs.legend??{}).some(o=>["left","right"].includes(o.position))&&(e=e.rematerializeSideLegendLane()),e.compositionSpec===void 0&&h(i,e)&&(e=e.rematerializeHorizontalLegendLane()),e.compositionSpec===void 0&&(Object.keys(e.guideConfigs.legendGroups??{}).length>0||Object.values(e.guideConfigs.legend??{}).some(o=>m(o)!==void 0))&&(e=e.rematerializeLegendGroups()),a!==void 0&&e.titleConfig!==void 0&&(e=e.rematerializeTitle()),(g(i)||g(e))&&(e=e.rematerializePlotDrawOrder());break}catch(n){const o=v(n)?.canvasOverflow;if(a===void 0||o===void 0||f>=16)throw n;t=Object.fromEntries(Object.keys(t).map(d=>[d,o[d]>0?Math.ceil((t[d]+o[d])*4)/4:t[d]]))}const{deferGuideLayoutValidation:s,...c}=e.context;Object.hasOwn(i.context,"deferGuideLayoutValidation")&&(c.deferGuideLayoutValidation=i.context.deferGuideLayoutValidation);const r=e._clone({context:c});return G(w(r.graphicSpec,r.guideConfigs,r.titleConfig,r.materializationConfigs.textMetrics)),r}function k(i){return function(l){return y(this,a=>i.call(a,l))}}export{M as resolveGuideCollisionBlocks,y as withGuideLayoutTransaction,k as withGuideLayoutValidation,_ as withPendingRelativeAxisTitle};

package/src/materialization/guides/resources.js

@@ -1 +1 @@
-import{axisGraphicIds as k}from"../../selectors/axes.js";import{localLegendPosition as z,localLegendPlacement as C}from"../legendGroups.js";import{resolveConcreteGraphicBounds as B,unionConcreteGraphicBounds as x}from"../../grammar/schemas/graphicBounds.js";function T(e,i,n,s){const t=[],r=(o,a,u,l)=>{if(u===void 0)return;const b=l.filter(O=>e.objects[O]!==void 0),m=x(e,b,s);m!==void 0&&t.push({id:o,kind:a,position:u,bounds:m})};r("chart title","title",n?.position,["chartTitle","chartSubtitle"]);for(const[o,a]of Object.entries(i.axis??{})){const u=["line","ticks","labels","title"].map(b=>a[b]?.position).find(Boolean),l=["x","y"].includes(o)?o:["top","bottom"].includes(u)?"x":["left","right"].includes(u)?"y":void 0;if(l!==void 0)for(const[b,m]of["line","ticks","labels","title"].entries()){const O=k(l,o)[b],I=t.length;if(r(`${o}-axis ${m}`,"axis",a[m]?.position,[O]),t.length===I)continue;const h=t.at(-1);if(h.axisId=o,h.namedAxis=o!==l,["labels","title"].includes(m)){const G=e.objects[O];h.textBounds=G.items?.map(v=>B(e,v.id,s))??[h.bounds]}}}const c=$(),d=i.legend??{},f=c.find(o=>o.family==="categorical"&&d[o.kind]!==void 0),g=f!==void 0&&d.size!==void 0&&d[f.kind].target===d.size.target&&z(d[f.kind])===void 0&&z(d.size)===void 0&&(d.size.inheritPosition!==!1||d[f.kind].position===d.size.position),p=i.legendGroups??{};for(const[o,a]of Object.entries(p)){const u=c.filter(l=>d[l.kind]?.target===o&&z(d[l.kind])===void 0).flatMap(l=>l.graphicIds);r(`${o} legend group`,"legend",a.placement.position??"free",u)}for(const o of c){const a=d[o.kind];if(p[a?.target]!==void 0&&z(a)===void 0||a===void 0||g&&o.kind==="size")continue;const u=g&&o===f?[...o.graphicIds,...c.find(l=>l.kind==="size").graphicIds]:o.graphicIds;r(`${o.kind}${g&&o===f?"+size":""} legend`,"legend",z(a)??a.position,u)}return t}const L=Object.freeze(["Symbols","SymbolLines","SymbolPoints","SymbolSwatches","Labels","Title","Background"]),j=Object.freeze({colorSize:Object.freeze({semanticKind:"colorSize",family:"sampled",rematerializeOp:void 0,graphicIds:Object.freeze(["colorSizeLegendBackground","colorSizeLegendSymbols","colorSizeLegendLabels","colorSizeLegendTitle"])}),series:Object.freeze({semanticKind:"series",family:"categorical",rematerializeOp:void 0,graphicIds:Object.freeze(L.map(e=>`seriesLegend${e}`))}),color:Object.freeze({semanticKind:"color",family:"categorical",rematerializeOp:void 0,graphicIds:Object.freeze(L.map(e=>`colorLegend${e}`))}),stroke:Object.freeze({semanticKind:"stroke",family:"categorical",rematerializeOp:void 0,graphicIds:Object.freeze(L.map(e=>`strokeLegend${e}`))}),size:Object.freeze({semanticKind:"size",family:"size",rematerializeOp:"rematerializeSizeLegend",graphicIds:Object.freeze(["sizeLegendBackground","sizeLegendSymbols","sizeLegendLabels","sizeLegendTitle"])}),gradient:Object.freeze({semanticKind:"color",family:"continuous",rematerializeOp:"rematerializeGradientLegend",graphicIds:Object.freeze(["colorGradientBackground","colorGradientStrips","colorGradientTicks","colorGradientSymbols","colorGradientLabels","colorGradientTitle"])}),interval:Object.freeze({semanticKind:"color",family:"interval",rematerializeOp:"rematerializeIntervalLegend",graphicIds:Object.freeze(["colorLegendBackground","colorLegendSymbols","colorLegendLabels","colorLegendTitle"])}),strokeGradient:Object.freeze({semanticKind:"stroke",family:"continuous",rematerializeOp:"rematerializeStrokeGradientLegend",graphicIds:Object.freeze(["strokeGradientBackground","strokeGradientStrips","strokeGradientTicks","strokeGradientLabels","strokeGradientTitle"])}),strokeInterval:Object.freeze({semanticKind:"stroke",family:"interval",rematerializeOp:"rematerializeStrokeIntervalLegend",graphicIds:Object.freeze(["strokeIntervalBackground","strokeIntervalSymbols","strokeIntervalLabels","strokeIntervalTitle"])}),opacity:Object.freeze({semanticKind:"opacity",family:"continuous",rematerializeOp:"rematerializeOpacityLegend",graphicIds:Object.freeze(["opacityLegendBackground","opacityLegendSymbols","opacityLegendLabels","opacityLegendTitle"])}),strokeWidth:Object.freeze({semanticKind:"strokeWidth",family:"strokeWidth",rematerializeOp:"rematerializeStrokeWidthLegend",graphicIds:Object.freeze(["strokeWidthLegendBackground","strokeWidthLegendSymbols","strokeWidthLegendLabels","strokeWidthLegendTitle"])})});function K(e){return w(e).graphicIds}function w(e){const i=j[e];if(i===void 0)throw new Error(`Unknown legend graphic kind "${e}".`);return i}function $(){return Object.entries(j).map(([e,i])=>({kind:e,...i}))}function R(e){return[...new Set(e.flatMap(K))]}function y(e){const i=T(e.graphicSpec,e.guideConfigs,void 0,e.materializationConfigs.textMetrics).filter(n=>n.kind==="axis");for(const n of["theta","radius"]){if(e.guideConfigs.axis?.[n]===void 0)continue;const s=k(n).slice(2).filter(r=>e.graphicSpec.objects[r]!==void 0),t=x(e.graphicSpec,s,e.materializationConfigs.textMetrics);if(t!==void 0)for(const r of["left","right","top","bottom"])i.push({id:`${n}-axis text`,kind:"axis",position:r,bounds:t})}return i}function A(e,i,n){if(i.inferredOffset!==!0||!["top","bottom","left","right"].includes(i.position)||i.layout==="legacy-bottom")return i.offset;const s=y(e).filter(r=>r.position===i.position),t=Math.max(0,...s.map(r=>({bottom:r.bounds.bottom-n.y-n.height,top:n.y-r.bounds.top,left:n.x-r.bounds.left,right:r.bounds.right-n.x-n.width})[i.position]));return i.offset+t}function S(e,i,n){if(i!=="size"||n.inheritPosition===!1)return n;const s=["series","color","stroke"].map(t=>e.guideConfigs.legend?.[t]).find(t=>t?.target===n.target);return s===void 0?n:{...n,position:s.position,offset:s.offset,inferredOffset:s.inferredOffset}}function M(e,i){return[e,i].some(s=>Object.entries(s.guideConfigs.legend??{}).some(([t,r])=>{const c=S(s,t,r);return c.inferredOffset===!0&&["top","bottom"].includes(c.position)&&c.layout!=="legacy-bottom"})||Object.values(s.guideConfigs.legendGroups??{}).some(t=>t.inferredOffset===!0&&["top","bottom"].includes(t.placement.position)))&&[e,i].some(s=>y(s).some(t=>["top","bottom"].includes(t.position)))}function N(e,i){const n=new Set;for(const t of[e,i])for(const[r,c]of Object.entries(t.guideConfigs.legend??{})){const d=C(c),f=d===void 0?t.guideConfigs.legendGroups?.[c.target]:void 0,g=S(t,r,c),p=d??f?.placement??g;(d?.inferredOffset??f?.inferredOffset??g.inferredOffset)===!0&&p.at===void 0&&["left","right"].includes(p.position)&&g.layout!=="legacy-bottom"&&n.add(p.position)}const s=t=>JSON.stringify(y(t).filter(r=>n.has(r.position)));return n.size>0&&s(e)!==s(i)}export{R as allLegendGraphicIds,k as axisGraphicIds,S as effectiveLegendOffsetConfig,K as legendGraphicIds,$ as legendResourcePolicies,w as legendResourcePolicy,M as needsLegendAxisReflow,N as needsSideLegendAxisReflow,T as resolveGuideCollisionBlocks,A as resolveLegendAxisOffset};
+import{axisGraphicIds as k,selectCartesianAxis as v}from"../../selectors/axes.js";import{localLegendPosition as z,localLegendPlacement as T}from"../legendGroups.js";import{resolveConcreteGraphicBounds as B,unionConcreteGraphicBounds as y}from"../../grammar/schemas/graphicBounds.js";function W(e,i,n){const o=e.context.pendingMaterializationPlan;if(o===void 0)return!1;const t=`edit${i.toUpperCase()}AxisTitle`;return o.steps.slice(o.next).some(r=>r.op===t&&v(e,i,r.args).id===n)}function K(e,i,n,o){const t=[],r=(s,a,u,l)=>{if(u===void 0)return;const b=l.filter(O=>e.objects[O]!==void 0),m=y(e,b,o);m!==void 0&&t.push({id:s,kind:a,position:u,bounds:m})};r("chart title","title",n?.position,["chartTitle","chartSubtitle"]);for(const[s,a]of Object.entries(i.axis??{})){const u=["line","ticks","labels","title"].map(b=>a[b]?.position).find(Boolean),l=["x","y"].includes(s)?s:["top","bottom"].includes(u)?"x":["left","right"].includes(u)?"y":void 0;if(l!==void 0)for(const[b,m]of["line","ticks","labels","title"].entries()){const O=k(l,s)[b],I=t.length;if(r(`${s}-axis ${m}`,"axis",a[m]?.position,[O]),t.length===I)continue;const h=t.at(-1);if(h.axisId=s,h.namedAxis=s!==l,["labels","title"].includes(m)){const G=e.objects[O];h.textBounds=G.items?.map(C=>B(e,C.id,o))??[h.bounds]}}}const c=w(),d=i.legend??{},f=c.find(s=>s.family==="categorical"&&d[s.kind]!==void 0),g=f!==void 0&&d.size!==void 0&&d[f.kind].target===d.size.target&&z(d[f.kind])===void 0&&z(d.size)===void 0&&(d.size.inheritPosition!==!1||d[f.kind].position===d.size.position),p=i.legendGroups??{};for(const[s,a]of Object.entries(p)){const u=c.filter(l=>d[l.kind]?.target===s&&z(d[l.kind])===void 0).flatMap(l=>l.graphicIds);r(`${s} legend group`,"legend",a.placement.position??"free",u)}for(const s of c){const a=d[s.kind];if(p[a?.target]!==void 0&&z(a)===void 0||a===void 0||g&&s.kind==="size")continue;const u=g&&s===f?[...s.graphicIds,...c.find(l=>l.kind==="size").graphicIds]:s.graphicIds;r(`${s.kind}${g&&s===f?"+size":""} legend`,"legend",z(a)??a.position,u)}return t}const L=Object.freeze(["Symbols","SymbolLines","SymbolPoints","SymbolSwatches","Labels","Title","Background"]),j=Object.freeze({colorSize:Object.freeze({semanticKind:"colorSize",family:"sampled",rematerializeOp:void 0,graphicIds:Object.freeze(["colorSizeLegendBackground","colorSizeLegendSymbols","colorSizeLegendLabels","colorSizeLegendTitle"])}),series:Object.freeze({semanticKind:"series",family:"categorical",rematerializeOp:void 0,graphicIds:Object.freeze(L.map(e=>`seriesLegend${e}`))}),color:Object.freeze({semanticKind:"color",family:"categorical",rematerializeOp:void 0,graphicIds:Object.freeze(L.map(e=>`colorLegend${e}`))}),stroke:Object.freeze({semanticKind:"stroke",family:"categorical",rematerializeOp:void 0,graphicIds:Object.freeze(L.map(e=>`strokeLegend${e}`))}),size:Object.freeze({semanticKind:"size",family:"size",rematerializeOp:"rematerializeSizeLegend",graphicIds:Object.freeze(["sizeLegendBackground","sizeLegendSymbols","sizeLegendLabels","sizeLegendTitle"])}),gradient:Object.freeze({semanticKind:"color",family:"continuous",rematerializeOp:"rematerializeGradientLegend",graphicIds:Object.freeze(["colorGradientBackground","colorGradientStrips","colorGradientTicks","colorGradientSymbols","colorGradientLabels","colorGradientTitle"])}),interval:Object.freeze({semanticKind:"color",family:"interval",rematerializeOp:"rematerializeIntervalLegend",graphicIds:Object.freeze(["colorLegendBackground","colorLegendSymbols","colorLegendLabels","colorLegendTitle"])}),strokeGradient:Object.freeze({semanticKind:"stroke",family:"continuous",rematerializeOp:"rematerializeStrokeGradientLegend",graphicIds:Object.freeze(["strokeGradientBackground","strokeGradientStrips","strokeGradientTicks","strokeGradientLabels","strokeGradientTitle"])}),strokeInterval:Object.freeze({semanticKind:"stroke",family:"interval",rematerializeOp:"rematerializeStrokeIntervalLegend",graphicIds:Object.freeze(["strokeIntervalBackground","strokeIntervalSymbols","strokeIntervalLabels","strokeIntervalTitle"])}),opacity:Object.freeze({semanticKind:"opacity",family:"continuous",rematerializeOp:"rematerializeOpacityLegend",graphicIds:Object.freeze(["opacityLegendBackground","opacityLegendSymbols","opacityLegendLabels","opacityLegendTitle"])}),strokeWidth:Object.freeze({semanticKind:"strokeWidth",family:"strokeWidth",rematerializeOp:"rematerializeStrokeWidthLegend",graphicIds:Object.freeze(["strokeWidthLegendBackground","strokeWidthLegendSymbols","strokeWidthLegendLabels","strokeWidthLegendTitle"])})});function P(e){return $(e).graphicIds}function $(e){const i=j[e];if(i===void 0)throw new Error(`Unknown legend graphic kind "${e}".`);return i}function w(){return Object.entries(j).map(([e,i])=>({kind:e,...i}))}function M(e){return[...new Set(e.flatMap(P))]}function x(e){const i=K(e.graphicSpec,e.guideConfigs,void 0,e.materializationConfigs.textMetrics).filter(n=>n.kind==="axis");for(const n of["theta","radius"]){if(e.guideConfigs.axis?.[n]===void 0)continue;const o=k(n).slice(2).filter(r=>e.graphicSpec.objects[r]!==void 0),t=y(e.graphicSpec,o,e.materializationConfigs.textMetrics);if(t!==void 0)for(const r of["left","right","top","bottom"])i.push({id:`${n}-axis text`,kind:"axis",position:r,bounds:t})}return i}function N(e,i,n){if(i.inferredOffset!==!0||!["top","bottom","left","right"].includes(i.position)||i.layout==="legacy-bottom")return i.offset;const o=x(e).filter(r=>r.position===i.position),t=Math.max(0,...o.map(r=>({bottom:r.bounds.bottom-n.y-n.height,top:n.y-r.bounds.top,left:n.x-r.bounds.left,right:r.bounds.right-n.x-n.width})[i.position]));return i.offset+t}function S(e,i,n){if(i!=="size"||n.inheritPosition===!1)return n;const o=["series","color","stroke"].map(t=>e.guideConfigs.legend?.[t]).find(t=>t?.target===n.target);return o===void 0?n:{...n,position:o.position,offset:o.offset,inferredOffset:o.inferredOffset}}function U(e,i){return[e,i].some(o=>Object.entries(o.guideConfigs.legend??{}).some(([t,r])=>{const c=S(o,t,r);return c.inferredOffset===!0&&["top","bottom"].includes(c.position)&&c.layout!=="legacy-bottom"})||Object.values(o.guideConfigs.legendGroups??{}).some(t=>t.inferredOffset===!0&&["top","bottom"].includes(t.placement.position)))&&[e,i].some(o=>x(o).some(t=>["top","bottom"].includes(t.position)))}function _(e,i){const n=new Set;for(const t of[e,i])for(const[r,c]of Object.entries(t.guideConfigs.legend??{})){const d=T(c),f=d===void 0?t.guideConfigs.legendGroups?.[c.target]:void 0,g=S(t,r,c),p=d??f?.placement??g;(d?.inferredOffset??f?.inferredOffset??g.inferredOffset)===!0&&p.at===void 0&&["left","right"].includes(p.position)&&g.layout!=="legacy-bottom"&&n.add(p.position)}const o=t=>JSON.stringify(x(t).filter(r=>n.has(r.position)));return n.size>0&&o(e)!==o(i)}export{M as allLegendGraphicIds,k as axisGraphicIds,S as effectiveLegendOffsetConfig,W as hasPendingAxisTitleRematerialization,P as legendGraphicIds,w as legendResourcePolicies,$ as legendResourcePolicy,U as needsLegendAxisReflow,_ as needsSideLegendAxisReflow,K as resolveGuideCollisionBlocks,N as resolveLegendAxisOffset};

package/src/materialization/planner.js

@@ -1,3 +1,5 @@
+import { cloneAndFreeze } from "../core/immutable.js";
+
 const STAGES = Object.freeze([
   "scales",
   "marks",
@@ -116,16 +118,29 @@ export function buildMaterializationPlan(stages = {}) {
 
 export function applyMaterializationPlan(program, plan) {
   const steps = deduplicateSteps(normalizeSteps(plan));
+  const ownedSteps = typeof program?._withContext === "function" ? cloneAndFreeze(steps) : steps;
   let next = program;
-  for (const step of steps) {
+  for (const [index, step] of steps.entries()) {
     if (typeof next?.[step.op] !== "function") {
       throw new Error(
         `Materialization operation "${step.op}" is not available on the program.`
       );
     }
-    next = step.args === undefined
-      ? next[step.op]()
-      : next[step.op](step.args);
+    const previous = next;
+    // Only execution context exposes the remaining normalized plan. Domain
+    // owners decide which pending sibling operations affect their preflight.
+    const scoped = typeof previous._withContext === "function";
+    const current = scoped ? previous._withContext({ pendingMaterializationPlan: {
+      steps: ownedSteps, next: index + 1
+    } }) : previous;
+    next = step.args === undefined ? current[step.op]() : current[step.op](step.args);
+    if (scoped) {
+      const { pendingMaterializationPlan: _pending, ...context } = next.context;
+      if (Object.hasOwn(previous.context, "pendingMaterializationPlan")) {
+        context.pendingMaterializationPlan = previous.context.pendingMaterializationPlan;
+      }
+      next = next._clone({ context });
+    }
   }
   return next;
 }

package/src/persistence/validation.js

@@ -30,7 +30,8 @@ import { isContinuousSizeScaleType } from "../grammar/scales/size.js";
 import { validateGraphicItemLimit } from "../core/validation.js";
 import { LEGEND_TITLE_STYLE_KEYS, validateLegendTitleAlignment } from "../grammar/legendTitleStyle.js";
 import { validateGuideDash, normalizeGuideDashMap } from "../grammar/guideDash.js";
-import { validateAxisTextPlacement } from "../grammar/axisTextPlacement.js";
+import { validateAxisLabelFlushThreshold, validateAxisTextPlacement,
+  axisLabelHasText } from "../grammar/axisTextPlacement.js";
 import { validateTickSelectionRounding, axisTickSelection } from "../grammar/ticks.js";
 import { validateAreaPaintConfig } from "../grammar/areaPaint.js";
 import { validateOptionObject, validateKeys, validatePositiveFinite, validateNonNegativeFinite, validateNonEmptyString, validateGeneratedItemLimit } from "../core/validation.js";
@@ -236,6 +237,23 @@ export function validateProgramState(program, path, { allowMissingLookupSchemas
   }
   const cartesianOwners = cartesianAxisOwners(program);
   for (const [id, axis] of Object.entries(program.guideConfigs.axis ?? {})) {
+    if (isPlainObject(axis?.title?.offset)) {
+      if (!cartesianOwners.some(owner => owner.id === id)) throw invalidSnapshot("Relative title offset requires a Cartesian axis owner.", path);
+      validateAxisTextPlacement(axis.title, { title: true });
+      if (axis.title.inferredOffset === true) throw invalidSnapshot("Relative title offset cannot be inferred.", path);
+      const owner = cartesianOwners.find(owner => owner.id === id);
+      const labels = program.graphicSpec.objects[axisGraphicIds(owner.channel, id)[2]];
+      // Composition parents retain source intent, not local unit graphics.
+      // Their retained unit/children are validated through the same unit rule.
+      if (axis.labels?.position !== axis.title.position || (program.compositionSpec === undefined &&
+          !(labels?.items ?? (labels ? [labels] : [])).some(item => axisLabelHasText(item.properties)))) {
+        throw invalidSnapshot("Relative title offset requires nonempty same-side labels.", path);
+      }
+    }
+    if (axis?.labels?.flushThreshold !== undefined) {
+      if (!cartesianOwners.some(owner => owner.id === id)) throw invalidSnapshot("Label flushThreshold requires a Cartesian axis owner.", path);
+      validateAxisLabelFlushThreshold(axis.labels.flushThreshold);
+    }
     for (const config of [axis?.ticks, axis?.labels]) {
       if (config === undefined || !Object.hasOwn(config, "rounding")) continue;
       if (!cartesianOwners.some(owner => owner.id === id)) {

package/src/version.js

@@ -1,2 +1,2 @@
 // Must match package.json; enforced by the snapshot producer-version test.
-export const packageVersion = "0.0.23";
+export const packageVersion = "0.0.24";

package/types/basic.d.ts

@@ -10,11 +10,13 @@ export type {
   CartesianGuideDashMap,
   AxisTicksAndLabelsOptions,
   AxisTitleOptions,
+  AxisTitleOffset,
   DisplayLabelMap,
   DisplayLabelOptions,
   ApplyThemeOptions,
   BarWidthOptions,
   BasicSeriesLayoutOptions,
+  Bin2DAssignment,
   Bin2DDataOptions,
   CanvasOptions,
   ColorEncodingOptions,

package/types/index.d.ts

@@ -27,6 +27,7 @@ export type {
   AxisTicksAndLabelsOptions,
   AxisTickStyleOptions,
   AxisTitleOptions,
+  AxisTitleOffset,
   AxisValue,
   DisplayLabelMap,
   DisplayLabelOptions,
@@ -36,6 +37,7 @@ export type {
   BinnedHeatmapColorOptions,
   BinnedHeatmapOptions,
   BinnedHeatmapPositionChannel,
+  Bin2DAssignment,
   Bin2DCounts,
   Bin2DDataOptions,
   Bin2DExtent,
@@ -287,6 +289,7 @@ export type {
   FieldType,
   FillPaint,
   FacetCompositionSpec,
+  FacetGap,
   FacetGuideOptions,
   FacetOptions,
   FacetTopLaneMode,

package/types/program.d.ts

@@ -164,9 +164,11 @@ export interface CompositionOptions {
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
 }
+/** Facets may set independent axis gaps; concat continues to require a number. */
+export type FacetGap = number | Readonly<{ x: number; y: number }>;
 export interface EditCompositionLayoutOptions {
   columns?: number;
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   /** Interpret gap between child canvases (default), inner plots, or retained full content (wrapped facets). */
@@ -224,7 +226,7 @@ export interface FacetOptions {
   data?: string;
   values?: readonly DatasetScalar[];
   columns?: number;
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
@@ -245,7 +247,7 @@ export interface FacetGridOptions {
   rows: FacetGridRole;
   columns: FacetGridRole;
   combinations?: "observed" | "full";
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
@@ -262,7 +264,7 @@ export interface RepeatChartsOptions {
   channel: "x" | "y" | "theta" | "r" | { parallelDimension: string };
   fields: readonly [string, ...string[]];
   columns?: number;
-  gap?: number;
+  gap?: FacetGap;
   align?: CompositionAlign;
   padding?: number | CompositionPadding;
   scales?: FacetScaleResolutions;
@@ -328,7 +330,7 @@ export interface FacetCompositionSpec {
   readonly spacing?: "canvas" | "plot" | "content";
   /** Canonical opt-in intent; stacked is represented by omission. */
   readonly topLane?: "shared";
-  readonly gap: number;
+  readonly gap: FacetGap;
   readonly align: CompositionAlign;
   readonly padding: Readonly<Required<CompositionPadding>>;
   readonly facet: {
@@ -755,6 +757,7 @@ export type DatasetTimeUnitTransform = DatasetTimeUnitTransformBase & (
       readonly weekRule: "calendar" | "iso";
     }
 );
+export type Bin2DAssignment = "edges" | "step";
 export interface Bin2DCounts {
   x: number;
   y: number;
@@ -781,6 +784,7 @@ export interface DatasetBin2DOutputFields {
 }
 export interface DatasetBin2DTransform {
   readonly type: "bin2d";
+  readonly assignment?: "step";
   readonly x: string;
   readonly y: string;
   readonly bins: Readonly<Bin2DCounts>;
@@ -1469,6 +1473,8 @@ export interface CartesianAxisLabelStyleOptions extends AxisLabelStyleOptions {
   colorMap?: CartesianAxisLabelColorMap | "auto";
   /** Keep unrotated label bounds inside the mapped axis span; defaults to false. */
   flush?: boolean;
+  /** Only flush mapped ticks within this non-negative distance of a range edge. Auto restores all-label containment. */
+  flushThreshold?: number | "auto";
   /** Signed displacement from the mapped tick position, independent of outward offset. */
   alongOffset?: number;
 }
@@ -1494,6 +1500,7 @@ export interface AxisTicksAndLabelsOptions<P extends string> {
   ticks?: CartesianAxisTickStyleOptions;
   labels?: CartesianAxisLabelStyleOptions & AxisLabelLayoutOptions & DisplayLabelOptions;
 }
+export type AxisTitleOffset = number | Readonly<{ from: "labels"; gap: number }>;
 export interface AxisTitleOptions<P extends string> {
   /** Axis resource identity; omission prefers canonical, then a unique named owner. */
   target?: string;
@@ -1508,8 +1515,8 @@ export interface AxisTitleOptions<P extends string> {
   scale?: string;
   position?: P;
   at?: "start" | "center" | "end" | number;
-  /** Signed distance from the axis frame: positive outward, negative inward. */
-  offset?: number;
+  /** Signed distance from the axis frame, or a nonnegative gap outside same-owner labels. */
+  offset?: AxisTitleOffset;
   rotation?: RotationInput;
   color?: string;
   fontSize?: number;
@@ -2673,6 +2680,7 @@ export interface Bin2DDataOptions {
   y: string;
   bins?: number | Bin2DCounts;
   extent?: Bin2DExtent;
+  assignment?: "edges" | "step";
   includeEmpty?: boolean;
   members?: boolean;
   as?: Bin2DOutputFields;
@@ -2685,6 +2693,7 @@ export interface EditBin2DDataOptions {
   y?: string;
   bins?: number | Bin2DCounts;
   extent?: Bin2DExtent;
+  assignment?: "edges" | "step";
   includeEmpty?: boolean;
   members?: boolean;
   as?: DatasetBin2DOutputFields;
@@ -4043,6 +4052,7 @@ export interface BinnedHeatmapColorOptions {
 export interface HeatmapBinOptions {
   bins?: number | Bin2DCounts;
   extent?: Bin2DExtent;
+  assignment?: "edges" | "step";
   includeEmpty?: boolean;
 }
 
@@ -5193,6 +5203,8 @@ export interface TitleOptions {
   maxWidth?: number;
   wrap?: "word" | "character";
   lineHeight?: number;
+  /** Subtitle-only line spacing; overrides lineHeight without requiring maxWidth. */
+  subtitleLineHeight?: number;
   titleStyle?: TitleTextStyleOptions;
   subtitleStyle?: TitleTextStyleOptions;
 }