@rowsncolumns/charts 28.1.2 → 28.1.4

package/dist/esm/utils/legend-layout.js

@@ -0,0 +1,299 @@
+// Legend band reservation (rowsncolumns/spreadsheet#986).
+//
+// Excel and Google Sheets never let the legend paint over the plot: for
+// every legend position the chart reserves a band of its own — legend
+// outermost, then the axis title, then the tick labels, then the plot
+// area shrinks to whatever is left. Both renderers here used to pin the
+// legend a fixed distance from the frame edge and leave the plot margin
+// constant, so a bottom legend sat on the category labels and hid the
+// horizontal axis title (and a top legend crowded the chart title).
+//
+// This module estimates the legend's rendered size from its actual items
+// (count, label widths, font size, wrapping into rows / columns) and turns
+// that into renderer geometry: the echarts `grid` + legend offsets +
+// category-axis `nameGap`, and the plotly `margin` + paper-relative legend
+// anchor. The estimate is deliberately generous — a few px of slack beats
+// a legend on top of the labels.
+/** Space kept between neighbouring bands (legend ↔ axis title ↔ labels). */
+export const BAND_GAP = 8;
+/** Inset of the outermost band from the chart frame. */
+export const EDGE_PAD = 10;
+/** echarts `legend.padding` default used by both adapters' legend boxes. */
+export const LEGEND_PADDING = 10;
+/** echarts `legend.itemGap` default. */
+export const LEGEND_ITEM_GAP = 10;
+/** Gap echarts leaves between a legend icon and its text. */
+const LEGEND_ICON_TEXT_GAP = 5;
+/** Approximate rendered width of `text` at `fontSize` (canvas when available). */
+export const measureTextWidth = (text, fontSize) => {
+    if (typeof document !== "undefined") {
+        const ctx = document.createElement("canvas").getContext("2d");
+        if (ctx) {
+            ctx.font = `${fontSize}px sans-serif`;
+            const width = ctx.measureText(text).width;
+            if (Number.isFinite(width) && width > 0)
+                return width;
+        }
+    }
+    // Headless fallback: ~0.6em per character.
+    return text.length * fontSize * 0.6;
+};
+/**
+ * Estimate the legend's rendered box from its items. Horizontal legends
+ * pack items greedily into rows no wider than the frame; vertical legends
+ * stack items and spill into a new column when taller than the frame.
+ */
+export const estimateLegendBand = ({ labels, fontSize = 12, itemWidth = 10, itemGap = LEGEND_ITEM_GAP, padding = LEGEND_PADDING, orientation, availableWidth, availableHeight, }) => {
+    if (!labels.length)
+        return { rows: 0, columns: 0, width: 0, height: 0 };
+    const lineHeight = Math.ceil(fontSize * 1.3);
+    const itemWidths = labels.map((label) => itemWidth + LEGEND_ICON_TEXT_GAP + Math.ceil(measureTextWidth(label, fontSize)));
+    if (orientation === "horizontal") {
+        const maxRowWidth = Math.max(1, availableWidth - padding * 2);
+        let rows = 1;
+        let rowWidth = 0;
+        let widestRow = 0;
+        for (const w of itemWidths) {
+            const next = rowWidth === 0 ? w : rowWidth + itemGap + w;
+            if (next > maxRowWidth && rowWidth > 0) {
+                widestRow = Math.max(widestRow, rowWidth);
+                rows += 1;
+                rowWidth = w;
+            }
+            else {
+                rowWidth = next;
+            }
+        }
+        widestRow = Math.max(widestRow, rowWidth);
+        return {
+            rows,
+            columns: 1,
+            width: padding * 2 + widestRow,
+            height: padding * 2 + rows * lineHeight + (rows - 1) * itemGap,
+        };
+    }
+    const maxColumnHeight = Math.max(1, availableHeight - padding * 2);
+    const perColumn = Math.max(1, Math.floor((maxColumnHeight + itemGap) / (lineHeight + itemGap)));
+    const columns = Math.ceil(labels.length / perColumn);
+    const rows = Math.min(labels.length, perColumn);
+    const widestItem = Math.max(...itemWidths);
+    return {
+        rows,
+        columns,
+        width: padding * 2 + columns * widestItem + (columns - 1) * itemGap,
+        height: padding * 2 + rows * lineHeight + (rows - 1) * itemGap,
+    };
+};
+/**
+ * Pull the legend entry labels out of an echarts `legend.data` (strings or
+ * `{ name }` items); falls back to the series names, which is what echarts
+ * itself lists when `data` is empty.
+ */
+export const legendLabelsFrom = (legendData, seriesNames) => {
+    const fromData = (legendData ?? [])
+        .map((d) => typeof d === "string"
+        ? d
+        : d && typeof d === "object" && typeof d.name === "string"
+            ? d.name
+            : "")
+        .filter((s) => s.length > 0);
+    if (fromData.length)
+        return fromData;
+    return seriesNames
+        .map((n) => (typeof n === "string" ? n : n === undefined || n === null ? "" : String(n)))
+        .filter((s) => s.length > 0);
+};
+/**
+ * Depth (px) of one row of echarts axis tick labels measured from the axis
+ * line: 5px tick + 8px label margin + one 12px line, rounded up. With
+ * `grid.containLabel` this is the part the grid already accounts for; the
+ * axis title sits beyond it.
+ */
+export const echartsAxisLabelDepth = (fontSize = 12) => 5 + 8 + Math.ceil(fontSize * 1.1);
+/**
+ * echarts `nameGap` for a category axis whose title sits in the middle
+ * below the tick labels: clear one row of labels plus a small gap, measured
+ * to the title's centre line.
+ */
+export const categoryAxisNameGap = (fontSize = 12) => echartsAxisLabelDepth(fontSize) + BAND_GAP / 2 + Math.ceil(fontSize / 2);
+/** Height of the echarts chart-title band (padding 10 each side + one line). */
+export const echartsTitleBand = (titleFontSize = 16) => LEGEND_PADDING * 2 + Math.ceil(titleFontSize * 1.25);
+/**
+ * Echarts cartesian geometry with a band reserved for the legend in its
+ * position, outside the axis-title band, outside the tick labels.
+ */
+export const reserveEchartsLegendBand = ({ position, visible, labels, legendFontSize = 12, legendItemWidth = 10, width, height, hasTitle, titleFontSize = 16, hasBottomAxisTitle, bottomAxisNameGap, hasLeftAxisTitle, axisFontSize = 12, }) => {
+    const pos = visible ? (position ?? "top") : "none";
+    const horizontal = pos === "top" || pos === "bottom";
+    const band = pos === "none"
+        ? { rows: 0, columns: 0, width: 0, height: 0 }
+        : estimateLegendBand({
+            labels,
+            fontSize: legendFontSize,
+            itemWidth: legendItemWidth,
+            orientation: horizontal ? "horizontal" : "vertical",
+            availableWidth: width,
+            availableHeight: height,
+        });
+    const titleBand = hasTitle ? echartsTitleBand(titleFontSize) : 0;
+    const labelDepth = echartsAxisLabelDepth(axisFontSize);
+    // The bottom axis title's centre sits `nameGap` below the axis line and
+    // its line box extends half a font below that; the contained labels
+    // already cover `labelDepth` of it.
+    const bottomTitleOverhang = hasBottomAxisTitle
+        ? Math.max(0, bottomAxisNameGap + Math.ceil(axisFontSize / 2) - labelDepth) + BAND_GAP
+        : 0;
+    // The rotated left axis title clears its labels by `fontSize + 6` (see
+    // valueAxisNameGap) and its own line box extends half a font further.
+    const leftTitleOverhang = hasLeftAxisTitle
+        ? Math.ceil(axisFontSize * 1.5) + 6 + BAND_GAP / 2
+        : 0;
+    // Half a tick label pokes past the top / right end of an axis.
+    const topHeadroom = Math.ceil(axisFontSize / 2) + 4;
+    const rightHeadroom = Math.ceil(axisFontSize / 2) + 10;
+    const legend = {};
+    let top = (hasTitle ? titleBand : EDGE_PAD) + topHeadroom;
+    let bottom = EDGE_PAD + bottomTitleOverhang;
+    let left = EDGE_PAD + leftTitleOverhang;
+    let right = rightHeadroom;
+    switch (pos) {
+        case "top": {
+            legend.top = hasTitle ? titleBand : EDGE_PAD;
+            legend.bottom = undefined;
+            top = legend.top + band.height + BAND_GAP + topHeadroom;
+            break;
+        }
+        case "bottom": {
+            legend.bottom = EDGE_PAD;
+            legend.top = undefined;
+            bottom = EDGE_PAD + band.height + BAND_GAP + bottomTitleOverhang;
+            break;
+        }
+        case "left": {
+            legend.left = EDGE_PAD;
+            legend.right = undefined;
+            left = EDGE_PAD + band.width + BAND_GAP + leftTitleOverhang;
+            break;
+        }
+        case "right": {
+            legend.right = EDGE_PAD;
+            legend.left = undefined;
+            right = EDGE_PAD + band.width + BAND_GAP;
+            break;
+        }
+        case "topRight": {
+            legend.right = EDGE_PAD;
+            legend.left = undefined;
+            legend.top = hasTitle ? titleBand : EDGE_PAD;
+            legend.bottom = undefined;
+            right = EDGE_PAD + band.width + BAND_GAP;
+            break;
+        }
+        default:
+            break;
+    }
+    return {
+        band,
+        grid: { left, right, top, bottom, containLabel: true },
+        legend,
+    };
+};
+/** Plotly text line height (its LINE_SPACING is 1.3em). */
+const plotlyLineHeight = (fontSize) => Math.ceil(fontSize * 1.3);
+/** Plotly default `legend.itemwidth`. */
+const PLOTLY_LEGEND_ITEM_WIDTH = 30;
+/**
+ * Plotly geometry with a band reserved for the legend in its position.
+ * Legend coordinates are paper-relative (fractions of the plot area), so
+ * they are derived from the margins this returns; `automargin` on the
+ * axes may still grow a margin further for unusually deep tick labels.
+ */
+export const reservePlotlyLegendBand = ({ position, visible, labels, legendFontSize = 12, width, height, hasTitle, titleFontSize = 16, hasBottomAxisTitle, hasLeftAxisTitle, leftAxisDepth, rightAxisDepth = 0, bottomAxisTitleStandoff = BAND_GAP, axisFontSize = 12, }) => {
+    const pos = visible ? (position ?? "right") : "none";
+    const horizontal = pos === "top" || pos === "bottom";
+    const band = pos === "none"
+        ? { rows: 0, columns: 0, width: 0, height: 0 }
+        : estimateLegendBand({
+            labels,
+            fontSize: legendFontSize,
+            itemWidth: PLOTLY_LEGEND_ITEM_WIDTH,
+            itemGap: 5,
+            padding: 5,
+            orientation: horizontal ? "horizontal" : "vertical",
+            availableWidth: width,
+            availableHeight: height,
+        });
+    const titleBand = hasTitle
+        ? EDGE_PAD + plotlyLineHeight(titleFontSize) + BAND_GAP
+        : 0;
+    // One row of bottom tick labels: plotly pads them ~3px off the axis.
+    const bottomLabelDepth = 3 + plotlyLineHeight(axisFontSize);
+    const bottomTitleBand = hasBottomAxisTitle
+        ? bottomAxisTitleStandoff + plotlyLineHeight(axisFontSize)
+        : 0;
+    const bottomAxisDepth = bottomLabelDepth + bottomTitleBand;
+    const topHeadroom = Math.ceil(axisFontSize / 2) + 4;
+    let t = Math.max(EDGE_PAD + topHeadroom, titleBand + topHeadroom);
+    let b = bottomAxisDepth + EDGE_PAD;
+    let l = leftAxisDepth + (hasLeftAxisTitle ? BAND_GAP : 0) + EDGE_PAD;
+    let r = Math.max(EDGE_PAD + Math.ceil(axisFontSize / 2), rightAxisDepth + EDGE_PAD);
+    let legend = null;
+    switch (pos) {
+        case "top": {
+            t = (hasTitle ? titleBand : EDGE_PAD) + band.height + BAND_GAP + topHeadroom;
+            legend = { orientation: "h", x: 0.5, xanchor: "center", y: 1, yanchor: "bottom" };
+            break;
+        }
+        case "bottom": {
+            b = bottomAxisDepth + BAND_GAP + band.height + EDGE_PAD;
+            legend = { orientation: "h", x: 0.5, xanchor: "center", y: 0, yanchor: "top" };
+            break;
+        }
+        case "left": {
+            l = leftAxisDepth + BAND_GAP + band.width + EDGE_PAD;
+            legend = { orientation: "v", x: 0, xanchor: "right", y: 0.5, yanchor: "middle" };
+            break;
+        }
+        case "right": {
+            r = rightAxisDepth + BAND_GAP + band.width + EDGE_PAD;
+            legend = { orientation: "v", x: 1, xanchor: "left", y: 0.5, yanchor: "middle" };
+            break;
+        }
+        case "topRight": {
+            r = rightAxisDepth + BAND_GAP + band.width + EDGE_PAD;
+            legend = { orientation: "v", x: 1, xanchor: "left", y: 1, yanchor: "top" };
+            break;
+        }
+        default:
+            break;
+    }
+    // Paper coordinates: offsets outside the plot area are fractions of it.
+    const plotWidth = Math.max(1, width - l - r);
+    const plotHeight = Math.max(1, height - t - b);
+    if (legend) {
+        switch (pos) {
+            case "top":
+                legend.y = 1 + (BAND_GAP + topHeadroom) / plotHeight;
+                break;
+            case "bottom":
+                legend.y = -(bottomAxisDepth + BAND_GAP) / plotHeight;
+                break;
+            case "left":
+                legend.x = -(leftAxisDepth + BAND_GAP) / plotWidth;
+                break;
+            case "right":
+            case "topRight":
+                legend.x = 1 + (rightAxisDepth + BAND_GAP) / plotWidth;
+                break;
+            default:
+                break;
+        }
+    }
+    return {
+        band,
+        margin: { l, r, t, b },
+        legend,
+        bottomAxisTitleStandoff,
+        title: { yref: "container", y: 1, yanchor: "top", pad: { t: EDGE_PAD } },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowsncolumns/charts",
-  "version": "28.1.2",
+  "version": "28.1.4",
   "author": "Vinay M",
   "license": "SEE LICENSE IN LICENSE.md",
   "main": "./dist/cjs/index.js",
@@ -67,14 +67,14 @@
   },
   "devDependencies": {
     "@rowsncolumns/calculator": ">=7.3.1",
-    "@rowsncolumns/common-types": ">=5.3.1",
+    "@rowsncolumns/common-types": ">=5.3.2",
     "@rowsncolumns/grid": ">=13.2.35",
     "@rowsncolumns/icons": ">=7.2.33",
-    "@rowsncolumns/spreadsheet": ">=10.4.2",
-    "@rowsncolumns/spreadsheet-state": ">=29.1.4",
-    "@rowsncolumns/toolkit": ">=24.5.4",
-    "@rowsncolumns/ui": ">=16.0.3",
-    "@rowsncolumns/utils": ">=9.5.1",
+    "@rowsncolumns/spreadsheet": ">=10.4.4",
+    "@rowsncolumns/spreadsheet-state": ">=29.1.6",
+    "@rowsncolumns/toolkit": ">=24.5.5",
+    "@rowsncolumns/ui": ">=16.0.4",
+    "@rowsncolumns/utils": ">=9.5.3",
     "@types/react-plotly.js": "^2.6.3",
     "echarts": "^5.6.0",
     "formik": "^2.4.6",