@bsuite/page-builder 1.0.2 → 1.0.4

package/dist/autoHeight.d.ts

@@ -44,6 +44,40 @@ export interface ComputeAutoHeightRowsOptions {
  * time. Ceiling always over-allocates rather than under-allocates, trading
  * a few pixels of empty card padding for a guarantee that content is never
  * cut off.
+ *
+ * THE MARGIN IS *BETWEEN* ROWS, NOT INSIDE EVERY ROW. This is the correction
+ * that this file existed for a month without.
+ *
+ * react-grid-layout allocates an item of `n` rows exactly:
+ *
+ *     px(n) = n * rowHeight + (n - 1) * marginY
+ *
+ * so `n` rows are worth `n * (rowHeight + marginY) - marginY` pixels — one
+ * margin LESS than the row unit suggests. Dividing the needed height by the
+ * bare row unit therefore credits every item with `marginY` pixels it does
+ * not get, and `Math.ceil` cannot rescue that: the shortfall is inside the
+ * rounding, not beyond it.
+ *
+ * Inverting the real formula for the smallest `n` that fits:
+ *
+ *     n * rowHeight + (n - 1) * marginY  >=  needed
+ *     n                                  >= (needed + marginY) / (rowHeight + marginY)
+ *
+ * MEASURED ON PRODUCTION, 2026-08-20, crm7 /clients/create at 1366x768. The
+ * card holding the form's Create/Cancel row measured 32px tall around a 36px
+ * button, with `overflow-hidden`, so the button was cut off and a neighbouring
+ * card's helper text was painted over what remained — `elementFromPoint` at the
+ * button's centre returned a `<p>`, not the button. The form could not be
+ * submitted by a person. rowHeight 32 + marginY 6: 36px of content came to
+ * `ceil((36 + 2) / 38) = 1` row, and one row is 32 pixels.
+ *
+ * The old form clips whenever the needed height lands 1..marginY pixels above a
+ * row boundary — 6 of every 38 possible heights, about one card in six.
+ *
+ * It survived because the tests asserted the ARITHMETIC rather than the
+ * OUTCOME: they checked the division, never whether the resulting row count
+ * buys enough pixels. Three of them encoded a clipping case as the expected
+ * answer. They now assert against react-grid-layout's own formula instead.
  */
 export declare function computeAutoHeightRows({ contentPx, cardChromePx, rowHeightPx, marginYPx, minRows, }: ComputeAutoHeightRowsOptions): number;
 //# sourceMappingURL=autoHeight.d.ts.map

package/dist/autoHeight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"autoHeight.d.ts","sourceRoot":"","sources":["../src/autoHeight.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,YAAY,EACZ,WAAW,EACX,SAAS,EACT,OAAW,GACZ,EAAE,4BAA4B,GAAG,MAAM,CAKvC"}
+{"version":3,"file":"autoHeight.d.ts","sourceRoot":"","sources":["../src/autoHeight.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,YAAY,EACZ,WAAW,EACX,SAAS,EACT,OAAW,GACZ,EAAE,4BAA4B,GAAG,MAAM,CAOvC"}

package/dist/autoHeight.js

@@ -6,11 +6,47 @@
  * time. Ceiling always over-allocates rather than under-allocates, trading
  * a few pixels of empty card padding for a guarantee that content is never
  * cut off.
+ *
+ * THE MARGIN IS *BETWEEN* ROWS, NOT INSIDE EVERY ROW. This is the correction
+ * that this file existed for a month without.
+ *
+ * react-grid-layout allocates an item of `n` rows exactly:
+ *
+ *     px(n) = n * rowHeight + (n - 1) * marginY
+ *
+ * so `n` rows are worth `n * (rowHeight + marginY) - marginY` pixels — one
+ * margin LESS than the row unit suggests. Dividing the needed height by the
+ * bare row unit therefore credits every item with `marginY` pixels it does
+ * not get, and `Math.ceil` cannot rescue that: the shortfall is inside the
+ * rounding, not beyond it.
+ *
+ * Inverting the real formula for the smallest `n` that fits:
+ *
+ *     n * rowHeight + (n - 1) * marginY  >=  needed
+ *     n                                  >= (needed + marginY) / (rowHeight + marginY)
+ *
+ * MEASURED ON PRODUCTION, 2026-08-20, crm7 /clients/create at 1366x768. The
+ * card holding the form's Create/Cancel row measured 32px tall around a 36px
+ * button, with `overflow-hidden`, so the button was cut off and a neighbouring
+ * card's helper text was painted over what remained — `elementFromPoint` at the
+ * button's centre returned a `<p>`, not the button. The form could not be
+ * submitted by a person. rowHeight 32 + marginY 6: 36px of content came to
+ * `ceil((36 + 2) / 38) = 1` row, and one row is 32 pixels.
+ *
+ * The old form clips whenever the needed height lands 1..marginY pixels above a
+ * row boundary — 6 of every 38 possible heights, about one card in six.
+ *
+ * It survived because the tests asserted the ARITHMETIC rather than the
+ * OUTCOME: they checked the division, never whether the resulting row count
+ * buys enough pixels. Three of them encoded a clipping case as the expected
+ * answer. They now assert against react-grid-layout's own formula instead.
  */
 export function computeAutoHeightRows({ contentPx, cardChromePx, rowHeightPx, marginYPx, minRows = 1, }) {
     const rowUnitPx = rowHeightPx + marginYPx;
     if (rowUnitPx <= 0)
         return minRows;
-    const raw = Math.ceil((contentPx + cardChromePx) / rowUnitPx);
+    // `+ marginYPx` inverts px(n) = n*rowHeight + (n-1)*marginY. Without it every
+    // item is credited with one margin it never receives. See the docblock.
+    const raw = Math.ceil((contentPx + cardChromePx + marginYPx) / rowUnitPx);
     return Math.max(minRows, raw);
 }

package/dist/usePageGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,2IAM7B,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAiBzC,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,cAAc,EACd,WAAgB,EAChB,aAAiB,EACjB,WAAkB,EAClB,gBAA6C,EAC7C,iBAA4C,EAC5C,iBAAiB,GAClB,EAAE,wBAAwB,GAAG,uBAAuB,CAwnBpD"}
+{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAGV,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0BAA0B,2IAM7B,CAAC;AAEX;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,6BAA6B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAiBzC,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,cAAc,EACd,WAAgB,EAChB,aAAiB,EACjB,WAAkB,EAClB,gBAA6C,EAC7C,iBAA4C,EAC5C,iBAAiB,GAClB,EAAE,wBAAwB,GAAG,uBAAuB,CA4pBpD"}

package/dist/usePageGridLayout.js

@@ -184,13 +184,24 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         }
         return resolved;
     }, [rawLayouts, baseCols, layoutCols, defaultAutoHeight]);
-    useEffect(() => {
-        if (baseCols !== layoutCols) {
-            const rescaled = rescaleLayout(rawLayouts, baseCols, layoutCols);
-            setSavedLayout(rescaled);
-            setBaseCols(layoutCols);
-        }
-    }, [baseCols, layoutCols, rawLayouts, setBaseCols, setSavedLayout]);
+    /*
+     * THERE IS DELIBERATELY NO EFFECT HERE.
+     *
+     * This used to rescale the stored layout to the new column count and write it
+     * back, which made a column change DESTRUCTIVE and unrecoverable. Measured on
+     * `rescaleLayout` directly: an 11 -> 2 -> 11 round trip takes
+     *
+     *   a(w4 @x0) b(w3 @x4) c(w4 @x7) / d(w6 @x0) e(w5 @x6)
+     *
+     * to five items of w6 stacked one per row at x0. Everything narrows to the
+     * one-column minimum on the way down, the row-packer puts one item per row,
+     * and coming back up cannot recover an arrangement that no longer exists.
+     * That is what flattened the operator's dashboard.
+     *
+     * `currentLayouts` above already derives the DISPLAY at `layoutCols` from the
+     * authored layout at `baseCols`. Leaving storage alone makes the column
+     * control a view, and the round trip exact.
+     */
     const activeCols = useMemo(() => ({ lg: layoutCols, md: layoutCols, sm: layoutCols, xs: layoutCols, xxs: layoutCols }), [layoutCols]);
     /**
      * The compactor handed to react-grid-layout — the SAME one in edit mode and
@@ -413,12 +424,22 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         }
         return next;
     }, []);
+    /**
+     * Persist a layout the USER authored, and re-base the column count to the one
+     * they authored it at.
+     *
+     * Re-basing belongs here and ONLY here. A column-count change is a view
+     * operation and must not touch storage — see `handleColumnChange`. An edit is
+     * the one moment the stored arrangement and the stored column count are known
+     * to agree, so it is the one moment `baseCols` may move.
+     */
     const commitLayout = useCallback((layouts) => {
         const canonical = canonicaliseLayoutForPersist(layouts);
         if (!canonical)
             return;
         setSavedLayout(stripAutoHeightRows(canonical));
-    }, [canonicaliseLayoutForPersist, setSavedLayout, stripAutoHeightRows]);
+        setBaseCols(layoutCols);
+    }, [canonicaliseLayoutForPersist, layoutCols, setBaseCols, setSavedLayout, stripAutoHeightRows]);
     const onLayoutChange = useCallback((_layout, layouts) => {
         if (!isEditing)
             return;
@@ -448,12 +469,18 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             }
         };
     }, []);
+    /**
+     * Change how many columns the canvas is DISPLAYED at.
+     *
+     * This writes nothing to storage. `currentLayouts` rescales the authored
+     * layout for display on every render, so switching 11 -> 2 -> 11 returns the
+     * user to exactly what they authored. The previous version persisted the
+     * rescale, which destroyed the arrangement at the narrow end and offered no
+     * undo. Storage moves only when the user actually edits — see `commitLayout`.
+     */
     const handleColumnChange = useCallback((newCols) => {
-        const rescaled = rescaleLayout(currentLayouts, layoutCols, newCols);
-        setSavedLayout(rescaled);
         setLayoutCols(newCols);
-        setBaseCols(newCols);
-    }, [currentLayouts, layoutCols, setBaseCols, setLayoutCols, setSavedLayout]);
+    }, [setLayoutCols]);
     /**
      * Build the object handed to the preference adapter from a new `lg` array.
      *
@@ -471,6 +498,11 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         }
         return next;
     }, [currentLayouts]);
+    /** Persist a bare `lg` item list from a mutator, re-basing the same way. */
+    const commitItems = useCallback((items) => {
+        setSavedLayout(layoutsWithLg(items));
+        setBaseCols(layoutCols);
+    }, [layoutCols, layoutsWithLg, setBaseCols, setSavedLayout]);
     const handleCompact = useCallback(() => {
         if (!currentLayouts.lg)
             return;
@@ -487,8 +519,8 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             placed.push(compacted);
             return compacted;
         });
-        startTransition(() => setSavedLayout(layoutsWithLg(result)));
-    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
+        startTransition(() => commitItems(result));
+    }, [currentLayouts, commitItems]);
     const handleReset = useCallback(() => {
         startTransition(() => {
             setSavedLayout(defaultLayouts);
@@ -507,7 +539,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             minW: initialSize?.minW,
             minH: initialSize?.minH,
         };
-        startTransition(() => setSavedLayout(layoutsWithLg([...(currentLayouts.lg ?? []), newItem])));
+        startTransition(() => commitItems([...(currentLayouts.lg ?? []), newItem]));
     }, [currentLayouts, layoutCols, layoutsWithLg, setSavedLayout]);
     const moveWidget = useCallback((widgetKey, direction) => {
         const items = [...(currentLayouts.lg ?? [])];
@@ -524,7 +556,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             moved,
             ...withoutMoved.slice(targetIndex),
         ];
-        startTransition(() => setSavedLayout(layoutsWithLg(nextItems)));
+        startTransition(() => commitItems(nextItems));
     }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     const setWidgetLocked = useCallback((widgetKey, locked) => {
         const nextItems = (currentLayouts.lg ?? []).map((item) => {
@@ -537,11 +569,11 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
                 isResizable: !locked,
             };
         });
-        startTransition(() => setSavedLayout(layoutsWithLg(nextItems)));
+        startTransition(() => commitItems(nextItems));
     }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     const removeWidget = useCallback((widgetKey) => {
         const nextItems = (currentLayouts.lg ?? []).filter((item) => item.i !== widgetKey);
-        startTransition(() => setSavedLayout(layoutsWithLg(nextItems)));
+        startTransition(() => commitItems(nextItems));
     }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     /**
      * Measured auto-height overrides (widgetKey -> rows). DERIVED, in-memory-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",