ggaction 0.0.17 → 0.0.18

package/src/layout/canvas.js

@@ -1,110 +1 @@
-import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import {
-  validateNonEmptyString,
-  validateNonNegativeFinite,
-  validatePositiveFinite
-} from "../core/validation.js";
-
-const MARGIN_KEYS = Object.freeze(["top", "right", "bottom", "left"]);
-
-export const DEFAULT_MARGIN = cloneAndFreeze({
-  top: 30,
-  right: 30,
-  bottom: 60,
-  left: 70
-});
-
-export const DEFAULT_CANVAS = cloneAndFreeze({
-  width: 640,
-  height: 400,
-  background: "white",
-  margin: DEFAULT_MARGIN
-});
-
-function validateMarginValue(value, key) {
-  validateNonNegativeFinite(value, `Canvas margin.${key}`);
-}
-
-export function normalizeMargin(margin, base = DEFAULT_MARGIN) {
-  if (Number.isFinite(margin)) {
-    if (margin < 0) {
-      throw new RangeError("Canvas margin must not be negative.");
-    }
-
-    return cloneAndFreeze({
-      top: margin,
-      right: margin,
-      bottom: margin,
-      left: margin
-    });
-  }
-
-  if (!isPlainObject(margin)) {
-    throw new TypeError("Canvas margin must be a number or a plain object.");
-  }
-
-  const keys = Object.keys(margin);
-
-  if (keys.length === 0) {
-    throw new TypeError("Canvas margin object must contain at least one side.");
-  }
-
-  for (const key of keys) {
-    if (!MARGIN_KEYS.includes(key)) {
-      throw new Error(`Unknown canvas margin option "${key}".`);
-    }
-
-    validateMarginValue(margin[key], key);
-  }
-
-  return cloneAndFreeze({
-    ...base,
-    ...margin
-  });
-}
-
-export function validateCanvasState({ width, height, background, margin }) {
-  validatePositiveFinite(width, "Canvas width");
-  validatePositiveFinite(height, "Canvas height");
-
-  validateNonEmptyString(background, "Canvas background");
-
-  for (const key of MARGIN_KEYS) {
-    validateMarginValue(margin[key], key);
-  }
-
-  if (margin.left + margin.right >= width) {
-    throw new RangeError("Canvas horizontal margins must be smaller than width.");
-  }
-
-  if (margin.top + margin.bottom >= height) {
-    throw new RangeError("Canvas vertical margins must be smaller than height.");
-  }
-}
-
-export function createGraphicBounds({ width, height, margin }) {
-  return cloneAndFreeze({
-    x: margin.left,
-    y: margin.top,
-    width: width - margin.left - margin.right,
-    height: height - margin.top - margin.bottom
-  });
-}
-
-export function resolveGraphicBounds(program) {
-  const canvas = program.graphicSpec.objects.canvas;
-  const margin = program.materializationConfigs.canvas?.margin;
-  if (
-    canvas?.type !== "canvas" ||
-    !Number.isFinite(canvas.properties.width) ||
-    !Number.isFinite(canvas.properties.height) ||
-    margin === undefined
-  ) {
-    throw new Error("Graphical layout requires Canvas dimensions and margin.");
-  }
-  return createGraphicBounds({
-    width: canvas.properties.width,
-    height: canvas.properties.height,
-    margin
-  });
-}
+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};

package/src/layout/facets.js

@@ -1,244 +1 @@
-import { cloneAndFreeze, isPlainObject } from "../core/immutable.js";
-import {
-  DEFAULT_COMPOSITION_LAYOUT,
-  normalizeCompositionAlign,
-  normalizeCompositionChildren,
-  normalizeCompositionPadding,
-  validateCompositionSpacing
-} from "./composition.js";
-
-export const DEFAULT_FACET_LEGEND_GAP = 18;
-export const DEFAULT_FACET_LEGEND_WIDTH = 132;
-export const DEFAULT_FACET_LEGEND_HEIGHT = 0;
-
-const FACET_LEGEND_POSITIONS = Object.freeze([
-  "right", "left", "top", "bottom"
-]);
-
-function resolveColumns(columns, count) {
-  const value = columns ?? count;
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new RangeError("Facet columns must be a positive integer.");
-  }
-  return Math.min(value, count);
-}
-
-function resolveGridCoordinates(children, columns) {
-  const requested = children.some(child => child.row !== undefined || child.column !== undefined);
-  if (!requested) return undefined;
-  if (children.some(child => !(
-    Number.isInteger(child.row) && child.row >= 0 &&
-    Number.isInteger(child.column) && child.column >= 0
-  ))) {
-    throw new RangeError("Facet grid children require non-negative integer row and column coordinates.");
-  }
-  const keys = children.map(child => `${child.row}:${child.column}`);
-  if (new Set(keys).size !== keys.length) {
-    throw new Error("Facet grid children must occupy unique row and column coordinates.");
-  }
-  const requiredColumns = Math.max(...children.map(child => child.column)) + 1;
-  if (columns !== undefined && columns !== requiredColumns) {
-    throw new RangeError("Facet grid columns must match the declared column domain.");
-  }
-  return {
-    columns: requiredColumns,
-    rows: Math.max(...children.map(child => child.row)) + 1
-  };
-}
-
-function alignedOffset(remaining, align) {
-  if (align === "start") return 0;
-  if (align === "end") return remaining;
-  return remaining / 2;
-}
-
-const ZERO_SIDES = Object.freeze({ top: 0, right: 0, bottom: 0, left: 0 });
-
-function normalizeHeaderLayout(value, rows) {
-  if (value === undefined) {
-    return {
-      outer: ZERO_SIDES,
-      cellRows: { top: Array(rows).fill(0), bottom: Array(rows).fill(0) }
-    };
-  }
-  if (!isPlainObject(value) || Object.keys(value).some(
-    key => !["outer", "cellRows"].includes(key)
-  )) {
-    throw new TypeError("Facet headerLayout must contain outer and cellRows.");
-  }
-  const outer = { ...ZERO_SIDES, ...(value.outer ?? {}) };
-  if (!isPlainObject(value.outer ?? {}) || Object.keys(outer).some(
-    key => !Object.hasOwn(ZERO_SIDES, key)
-  )) {
-    throw new TypeError("Facet headerLayout.outer must contain side reservations.");
-  }
-  for (const [side, amount] of Object.entries(outer)) {
-    validateCompositionSpacing(amount, `Facet headerLayout.outer.${side}`);
-  }
-  const sourceRows = value.cellRows ?? {};
-  if (!isPlainObject(sourceRows) || Object.keys(sourceRows).some(
-    key => !["top", "bottom"].includes(key)
-  )) {
-    throw new TypeError("Facet headerLayout.cellRows must contain top and bottom arrays.");
-  }
-  const cellRows = Object.fromEntries(["top", "bottom"].map(side => {
-    const amounts = sourceRows[side] ?? Array(rows).fill(0);
-    if (!Array.isArray(amounts) || amounts.length !== rows) {
-      throw new RangeError(`Facet headerLayout.cellRows.${side} must match row count.`);
-    }
-    amounts.forEach((amount, index) => validateCompositionSpacing(
-      amount,
-      `Facet headerLayout.cellRows.${side}[${index}]`
-    ));
-    return [side, [...amounts]];
-  }));
-  return { outer, cellRows };
-}
-
-export function resolveFacetLayout({
-  children,
-  columns,
-  gap = DEFAULT_COMPOSITION_LAYOUT.gap,
-  align = DEFAULT_COMPOSITION_LAYOUT.align,
-  padding = DEFAULT_COMPOSITION_LAYOUT.padding,
-  titleHeight = 0,
-  sharedLegend = false,
-  sharedLegendGap = DEFAULT_FACET_LEGEND_GAP,
-  sharedLegendWidth = DEFAULT_FACET_LEGEND_WIDTH,
-  sharedLegendHeight = DEFAULT_FACET_LEGEND_HEIGHT,
-  sharedLegendPosition = "right",
-  headerLayout
-} = {}) {
-  const values = children?.map(child => child?.value);
-  const coordinates = resolveGridCoordinates(children ?? [], columns);
-  const resolvedChildren = normalizeCompositionChildren(children?.map(
-    ({ value: _value, row: _row, column: _column, ...child }) => child
-  ));
-  const resolvedColumns = coordinates?.columns ??
-    resolveColumns(columns, resolvedChildren.length);
-  const resolvedGap = validateCompositionSpacing(gap, "Facet gap");
-  const resolvedAlign = normalizeCompositionAlign(align);
-  const resolvedPadding = normalizeCompositionPadding(padding);
-  const resolvedTitleHeight = validateCompositionSpacing(
-    titleHeight,
-    "Facet title height"
-  );
-  if (typeof sharedLegend !== "boolean") {
-    throw new TypeError("Facet sharedLegend must be a boolean.");
-  }
-  const legendGap = validateCompositionSpacing(
-    sharedLegendGap,
-    "Facet shared legend gap"
-  );
-  const legendWidth = validateCompositionSpacing(
-    sharedLegendWidth,
-    "Facet shared legend width"
-  );
-  const legendHeight = validateCompositionSpacing(
-    sharedLegendHeight,
-    "Facet shared legend height"
-  );
-  if (!FACET_LEGEND_POSITIONS.includes(sharedLegendPosition)) {
-    throw new Error(
-      `Unknown facet shared legend position "${sharedLegendPosition}".`
-    );
-  }
-  const sideLegend = ["right", "left"].includes(sharedLegendPosition);
-  const beforeGrid = ["left", "top"].includes(sharedLegendPosition);
-  const legendLane = sharedLegend
-    ? legendGap + (sideLegend ? legendWidth : legendHeight)
-    : 0;
-  const rowCount = coordinates?.rows ??
-    Math.ceil(resolvedChildren.length / resolvedColumns);
-  const headers = normalizeHeaderLayout(headerLayout, rowCount);
-  const columnWidths = Array(resolvedColumns).fill(-Infinity);
-  const rowHeights = Array(rowCount).fill(-Infinity);
-  resolvedChildren.forEach((child, index) => {
-    const column = coordinates === undefined
-      ? index % resolvedColumns
-      : children[index].column;
-    const row = coordinates === undefined
-      ? Math.floor(index / resolvedColumns)
-      : children[index].row;
-    columnWidths[column] = Math.max(columnWidths[column], child.width);
-    rowHeights[row] = Math.max(rowHeights[row], child.height);
-  });
-  const columnStarts = columnWidths.map((_, column) =>
-    resolvedPadding.left + headers.outer.left + columnWidths.slice(0, column)
-      .reduce((sum, width) => sum + width, 0) + resolvedGap * column
-  );
-  const rowStarts = rowHeights.map((_, row) =>
-    resolvedTitleHeight + resolvedPadding.top + headers.outer.top +
-    rowHeights.slice(0, row).reduce((sum, height, index) =>
-      sum + headers.cellRows.top[index] + height + headers.cellRows.bottom[index], 0) +
-    resolvedGap * row + headers.cellRows.top[row]
-  );
-  const placements = resolvedChildren.map((child, index) => {
-    const column = coordinates === undefined
-      ? index % resolvedColumns
-      : children[index].column;
-    const row = coordinates === undefined
-      ? Math.floor(index / resolvedColumns)
-      : children[index].row;
-    return {
-      id: child.id,
-      value: values[index],
-      column,
-      row,
-      x: columnStarts[column] + (beforeGrid && sideLegend ? legendLane : 0) +
-        alignedOffset(
-          columnWidths[column] - child.width,
-          resolvedAlign
-        ),
-      y: rowStarts[row] + (beforeGrid && !sideLegend ? legendLane : 0) +
-        alignedOffset(
-          rowHeights[row] - child.height,
-          resolvedAlign
-        ),
-      width: child.width,
-      height: child.height
-    };
-  });
-  const gridWidth = resolvedPadding.left +
-    headers.outer.left +
-    columnWidths.reduce((sum, width) => sum + width, 0) +
-    resolvedGap * Math.max(0, resolvedColumns - 1) +
-    headers.outer.right +
-    resolvedPadding.right;
-  const gridHeight = resolvedTitleHeight + resolvedPadding.top +
-    headers.outer.top +
-    rowHeights.reduce((sum, height) => sum + height, 0) +
-    headers.cellRows.top.reduce((sum, amount) => sum + amount, 0) +
-    headers.cellRows.bottom.reduce((sum, amount) => sum + amount, 0) +
-    resolvedGap * Math.max(0, rowCount - 1) +
-    headers.outer.bottom +
-    resolvedPadding.bottom;
-  return cloneAndFreeze({
-    columns: resolvedColumns,
-    rows: rowCount,
-    gap: resolvedGap,
-    align: resolvedAlign,
-    padding: resolvedPadding,
-    titleHeight: resolvedTitleHeight,
-    headerLayout: headers,
-    gridWidth,
-    width: gridWidth + (sideLegend ? legendLane : 0),
-    height: gridHeight + (sideLegend ? 0 : legendLane),
-    children: placements,
-    ...(sharedLegend ? {
-      legend: {
-        position: sharedLegendPosition,
-        x: sharedLegendPosition === "right"
-          ? gridWidth + legendGap
-          : 0,
-        y: sharedLegendPosition === "bottom"
-          ? gridHeight + legendGap
-          : sharedLegendPosition === "top"
-            ? resolvedTitleHeight
-            : resolvedTitleHeight + resolvedPadding.top + 30,
-        width: legendWidth,
-        height: legendHeight
-      }
-    } : {})
-  });
-}
+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};

package/src/layout/labels.js

@@ -507,6 +507,7 @@ function textBounds(item, offset = { x: 0, y: 0 }, profile) {
     x: item.x + offset.x,
     y: item.y + offset.y,
     text: item.text,
+    lines: item.lines,
     fontSize: item.fontSize,
     fontFamily: item.fontFamily,
     fontWeight: item.fontWeight,

package/src/layout/legend.js

@@ -1,3 +1,4 @@
+import { PLOT_LEGEND_POSITIONS } from "../core/vocabulary.js";
 import {
   formatVisibleText,
   measureTextWidth
@@ -7,6 +8,11 @@ export function measureLegendTextWidth(value, style = { fontSize: 12 }, profile)
   return measureTextWidth(formatVisibleText(value), style, profile);
 }
 
+// A conservative line-height reserve, not a font-specific glyph measurement.
+export function legendLabelLineHeight(fontSize) {
+  return fontSize * 1.2;
+}
+
 export function resolveLegendGrid(config, width, count, symbolHeight, profile) {
   const labels = config.domain.map(formatVisibleText);
   const itemWidths = labels.map(
@@ -43,3 +49,10 @@ export function alignLegendStart(bounds, width, align) {
   if (align === "right") return bounds.x + bounds.width - width;
   return bounds.x + (bounds.width - width) / 2;
 }
+
+
+export { PLOT_LEGEND_POSITIONS } from "../core/vocabulary.js";
+
+export function isPlotLegend(config) {
+  return PLOT_LEGEND_POSITIONS.includes(config.position);
+}

package/src/layout/legendGroup.js

@@ -0,0 +1 @@
+import{PLOT_LEGEND_POSITIONS as I}from"./legend.js";import{SIDE_LEGEND_BLOCK_GAP as M,HORIZONTAL_LEGEND_BLOCK_GAP as N}from"./legendLane.js";function H({blocks:g,group:O,plot:e,canvas:L,allowOverflow:l=!1}){if(g.length===0)return[];const{placement:t,blockLayout:f}=O,u=I.includes(t.position),c=["left","right"].includes(t.position),x=f==="column"||f==="wrap"&&c,y=u||c||t.at!==void 0?M:N,_=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>_&&!l)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 G={id:i.id,x:h,y:p,width:o,height:E};return x?p+=E+y:(h+=o+y,w=Math.max(w,E)),G}),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(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{H as resolveLegendGroupPlacement};

package/src/layout/legendItems.js

@@ -1,5 +1,6 @@
 import { measureTextWidth, resolveTextBounds } from "../core/textMetrics.js";
-import { alignLegendStart, resolveLegendGrid } from "./legend.js";
+import { alignLegendStart, resolveLegendGrid, isPlotLegend, legendLabelLineHeight } from "./legend.js";
+import { alignLegendTitle, resolveLegendTitleText } from "./legendText.js";
 
 // Measure item content before choosing its edge. Family owners supply the
 // sample dimensions and formatted labels; this module does not inspect scales.
@@ -17,13 +18,13 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
   const sampleWidth = sampleRight - sampleLeft;
   const sampleHeight = Math.max(symbol.height,
     ...sampleBounds.map(bounds => 2 * Math.max(-bounds.top, bounds.bottom)));
-  const side = ["left", "right"].includes(config.position);
+  const inside = isPlotLegend(config);
+  const side = inside || ["left", "right"].includes(config.position);
   const titleVisible = config.titleVisible !== false;
-  const titleWidth = titleVisible ? measureTextWidth(config.title, config.titleStyle, profile) : 0;
-  const titleHeight = titleVisible ? config.titleStyle.fontSize : 0;
-  const itemWidth = sampleWidth + config.labels.offset + Math.max(...labels.map(
-    text => measureTextWidth(text, config.labels, profile)
-  ));
+  const titleText = titleVisible ? resolveLegendTitleText(config.title, config.titleStyle, profile)
+    : { width: 0, height: 0 };
+  const titleWidth = titleVisible ? titleText.width : 0;
+  const titleHeight = titleVisible ? titleText.height : 0;
   let symbolX;
   let labelX;
   let itemY;
@@ -42,16 +43,36 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
     itemY = labels.map(() => canvas.height - 28);
     title = { x: x + width / 2, y: canvas.height - 52, align: "center" };
   } else if (side) {
-    const width = Math.max(itemWidth, titleWidth);
+    const grid = resolveLegendGrid({
+      ...config, columns: config.columns ?? 1, domain: labels
+    }, sampleWidth, labels.length, sampleHeight, profile);
+    const width = Math.max(grid.gridWidth, titleWidth);
     const x = config.position === "right" ? plot.x + plot.width + config.offset
       : plot.x - config.offset - width;
-    const itemHeight = Math.max(sampleHeight, config.labels.fontSize);
+    const itemHeight = Math.max(sampleHeight, legendLabelLineHeight(config.labels.fontSize));
     const pitch = Math.max(config.itemGap, itemHeight);
-    symbolX = labels.map(() => x - sampleLeft);
-    labelX = labels.map(() => x + sampleWidth + config.labels.offset);
-    const firstY = Math.max(plot.y + 52, titleVisible
+    let cursor = x;
+    const columnStarts = grid.columnWidths.map(columnWidth => {
+      const start = cursor;
+      cursor += columnWidth + config.itemGap;
+      return start;
+    });
+    symbolX = grid.cells.map(cell => columnStarts[cell.column] - sampleLeft);
+    labelX = grid.cells.map(cell => columnStarts[cell.column] + sampleWidth + config.labels.offset);
+    let firstY = Math.max(plot.y + 52, titleVisible
       ? plot.y + 20 + titleHeight / 2 + 12 + itemHeight / 2 : plot.y + 52);
-    itemY = labels.map((_, index) => firstY + index * pitch);
+    if ((inside || config.groupCorner === true) && titleVisible) {
+      const titleBounds = resolveTextBounds({ x: x, y: plot.y + 20,
+        text: config.title, ...config.titleStyle, lines: titleText.lines,
+        textAlign: "left", textBaseline: "middle" }, profile);
+      const labelTops = labels.map(text => resolveTextBounds({
+        x: 0, y: 0, text, ...config.labels,
+        textAlign: "left", textBaseline: "middle"
+      }, profile).top);
+      const itemTop = Math.min(...sampleBounds.map(bounds => bounds.top), ...labelTops);
+      firstY = titleBounds.bottom + 12 - itemTop;
+    }
+    itemY = grid.cells.map(cell => firstY + cell.row * pitch);
     title = { x, y: plot.y + 20, align: "left" };
   } else {
     const grid = resolveLegendGrid({ ...config, domain: labels }, sampleWidth, labels.length, sampleHeight, profile);
@@ -80,8 +101,7 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
   const textBounds = (x, y, text, style, align = "left") => resolveTextBounds({
     x, y, text, ...style, textAlign: align, textBaseline: "middle"
   }, profile);
-  const bounds = [
-    ...(titleVisible ? [textBounds(title.x, title.y, config.title, config.titleStyle, title.align)] : []),
+  const bodyBounds = [
     ...labels.map((label, index) => textBounds(labelX[index], itemY[index], label, config.labels)),
     ...symbolX.map((x, index) => {
       const local = sampleBounds[index];
@@ -89,6 +109,13 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
         top: itemY[index] + local.top, bottom: itemY[index] + local.bottom };
     })
   ];
+  if (titleVisible) title = alignLegendTitle(title, config.title, config.titleStyle, bodyBounds, profile);
+  const bounds = [
+    ...(titleVisible ? [resolveTextBounds({ x: title.x, y: title.y,
+      text: config.title, ...config.titleStyle, lines: titleText.lines,
+      textAlign: title.align, textBaseline: "middle" }, profile)] : []),
+    ...bodyBounds
+  ];
   if (config.layout === "legacy-bottom") {
     const itemBounds = titleVisible ? bounds.slice(1) : bounds;
     if (titleVisible && itemBounds.some(bound => bound.top < bounds[0].bottom)) {
@@ -98,5 +125,22 @@ export function resolveLegendItemLayout(plot, config, labels, symbol, canvas, pr
       throw new Error("Legacy bottom legend requires more bottom-margin space.");
     }
   }
+  if (inside) {
+    const left = Math.min(...bounds.map(b => b.left));
+    const right = Math.max(...bounds.map(b => b.right));
+    const top = Math.min(...bounds.map(b => b.top));
+    const bottom = Math.max(...bounds.map(b => b.bottom));
+    const inset = config.offset + (config.border === false ? 0 : config.border.padding + config.border.lineWidth / 2);
+    if (right - left + 2 * inset > plot.width || bottom - top + 2 * inset > plot.height) {
+      throw new Error("In-plot legend does not fit the plot; reduce its content or dimensions.");
+    }
+    const dx = config.position.endsWith("left") ? plot.x + inset - left
+      : plot.x + plot.width - inset - right;
+    const dy = config.position.startsWith("top") ? plot.y + inset - top
+      : plot.y + plot.height - inset - bottom;
+    return { symbolX: symbolX.map(x => x + dx), labelX: labelX.map(x => x + dx),
+      itemY: itemY.map(y => y + dy), title: { ...title, x: title.x + dx, y: title.y + dy },
+      bounds: bounds.map(b => ({ left: b.left + dx, right: b.right + dx, top: b.top + dy, bottom: b.bottom + dy })) };
+  }
   return { symbolX, labelX, itemY, title, bounds };
 }