@bsuite/page-builder 0.7.0 → 0.9.0

package/dist/usePageGridLayout.js

@@ -1,6 +1,6 @@
 import { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { verticalCompactor } from 'react-grid-layout';
-import { buildResponsiveLayouts } from './buildResponsiveLayouts.js';
+import { buildResponsiveLayouts, isCanonicalisableBreakpoint, isDerivedBreakpoint, } from './buildResponsiveLayouts.js';
 import { defaultPreferenceAdapter } from './preferences.js';
 import { rescaleLayout } from './rescaleLayout.js';
 export const DEFAULT_EDITOR_EVENT_NAMES = [
@@ -20,7 +20,43 @@ export const DEFAULT_EDITOR_EVENT_NAMES = [
  * launchers scope by page if they handle multiple grids on one screen.
  */
 export const PAGE_GRID_EDITING_EVENT = 'bsuite-page-grid-editing';
-export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, layoutVersion = 1, canEditPage = true, editorEventNames = DEFAULT_EDITOR_EVENT_NAMES, preferenceAdapter = defaultPreferenceAdapter, }) {
+/**
+ * Package-wide layout epoch, added to EVERY consumer's `layoutVersion`.
+ *
+ * When a default that governs all grids changes, a saved layout produced under
+ * the old default has to be invalidated — and there is no way to reach ~330
+ * call sites across six apps to hand-bump each one. crm7's `DraggableCardPage`
+ * already solved this locally with its own `LAYOUT_EPOCH`; this is the same
+ * lever one level down, so it also covers the raw `PageGridLayout` consumers
+ * (Dashboard, Billing, GTO, Analytics, the throughput and braden pages) that
+ * no app-level epoch can see.
+ *
+ * 0 -> 1000 (2026-08-13, D-75/D-76): two all-grids defaults changed in the same
+ * release — `autoHeight` now defaults to true for raw consumers, and md/sm no
+ * longer collapse to a full-width stack. Every stored layout predates both and
+ * was additionally polluted with frozen derived breakpoints, so all of them
+ * reset once to the corrected defaults.
+ *
+ * Per-page `layoutVersion` bumps keep working on top; this only moves the
+ * floor.
+ */
+export const PACKAGE_LAYOUT_EPOCH = 1000;
+/**
+ * Default for `GridLayoutItem.autoHeight` when an item does not state one.
+ *
+ * D-76 ("cards render half cut off on page open"). `DraggableCardPage` has
+ * defaulted this to true since the E5a flip, but a RAW `PageGridLayout`
+ * consumer builds its layout array by hand and inherits nothing — the flag had
+ * to be written on every item. Sixteen of the eighteen raw consumers across the
+ * suite never did, so their cards were fixed at whatever seed `h` the author
+ * guessed and clipped everything past it behind `overflow-auto`. That is not a
+ * per-page authoring mistake repeated sixteen times; it is a default in the
+ * wrong place. An item that genuinely owns its own scroll (a virtualized list)
+ * opts out with an explicit `autoHeight: false`.
+ */
+const DEFAULT_ITEM_AUTO_HEIGHT = true;
+export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, layoutVersion = 1, canEditPage = true, editorEventNames = DEFAULT_EDITOR_EVENT_NAMES, preferenceAdapter = defaultPreferenceAdapter, defaultAutoHeight, }) {
+    const effectiveLayoutVersion = layoutVersion + PACKAGE_LAYOUT_EPOCH;
     const containerRef = useRef(null);
     const [containerWidth, setContainerWidth] = useState(0);
     const [isEditing, setIsEditingState] = useState(false);
@@ -65,18 +101,18 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
     useEffect(() => {
         if (!prefsLoaded)
             return;
-        if ((savedLayoutVersion ?? 0) < layoutVersion) {
+        if ((savedLayoutVersion ?? 0) < effectiveLayoutVersion) {
             startTransition(() => {
                 setSavedLayout(defaultLayouts);
                 setLayoutCols(defaultCols);
                 setBaseCols(defaultCols);
-                setSavedLayoutVersion(layoutVersion);
+                setSavedLayoutVersion(effectiveLayoutVersion);
             });
         }
     }, [
         defaultCols,
         defaultLayouts,
-        layoutVersion,
+        effectiveLayoutVersion,
         prefsLoaded,
         savedLayoutVersion,
         setBaseCols,
@@ -89,7 +125,26 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
     const rawLayouts = useMemo(() => {
         if (Object.keys(savedLayout || {}).length === 0)
             return defaultLayouts;
-        const saved = savedLayout;
+        // Drop DERIVED breakpoints out of a stored layout before anything reads it.
+        //
+        // Until 0.8.0 react-grid-layout's `onLayoutChange` echo persisted md/sm/xs/
+        // xxs alongside lg. `buildResponsiveLayouts` then treated them as
+        // consumer-supplied and preserved them verbatim, so a layout derived once —
+        // at whatever column count happened to be active that day — outlived every
+        // later change to `lg` and to the columns slider (D-75). Every user who has
+        // ever dragged a card on any page has that pollution stored, so the fix has
+        // to heal on read rather than wait for a layoutVersion bump; `lg` (the only
+        // breakpoint that was ever authoritative) is preserved untouched, so nobody
+        // loses the arrangement they made.
+        const stored = savedLayout;
+        const saved = {};
+        for (const bp of Object.keys(stored)) {
+            if (isDerivedBreakpoint(bp))
+                continue;
+            saved[bp] = stored[bp];
+        }
+        if (!saved.lg)
+            saved.lg = stored.lg ?? defaultLayouts.lg ?? [];
         let changed = false;
         const merged = {};
         for (const bp of Object.keys(saved)) {
@@ -107,12 +162,28 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
                 merged[bp] = savedItems;
             }
         }
-        return changed ? merged : savedLayout;
+        // `merged` is always returned (never the raw `savedLayout`) because the
+        // derived-breakpoint filter above may have removed keys even when no
+        // default item was missing — handing back `savedLayout` would smuggle the
+        // stale derived breakpoints straight past the heal.
+        void changed;
+        return merged;
     }, [savedLayout, defaultLayouts]);
     const currentLayouts = useMemo(() => {
         const rescaled = baseCols !== layoutCols ? rescaleLayout(rawLayouts, baseCols, layoutCols) : rawLayouts;
-        return buildResponsiveLayouts(rescaled, { cols: layoutCols });
-    }, [rawLayouts, baseCols, layoutCols]);
+        const responsive = buildResponsiveLayouts(rescaled, { cols: layoutCols });
+        // Resolve the autoHeight default HERE rather than at the render layer, so
+        // `stripAutoHeightRows` (which reads this object through
+        // `currentLayoutsForStripRef`) and `PageGridLayout`'s `activeLayouts` agree
+        // on which items are auto-height. They disagreed once before and the
+        // measured height leaked into storage.
+        const resolvedAutoHeight = defaultAutoHeight ?? DEFAULT_ITEM_AUTO_HEIGHT;
+        const resolved = { lg: [] };
+        for (const bp of Object.keys(responsive)) {
+            resolved[bp] = (responsive[bp] ?? []).map((item) => item.autoHeight === undefined ? { ...item, autoHeight: resolvedAutoHeight } : item);
+        }
+        return resolved;
+    }, [rawLayouts, baseCols, layoutCols, defaultAutoHeight]);
     useEffect(() => {
         if (baseCols !== layoutCols) {
             const rescaled = rescaleLayout(rawLayouts, baseCols, layoutCols);
@@ -265,6 +336,67 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
     useEffect(() => {
         currentLayoutsForStripRef.current = currentLayouts;
     }, [currentLayouts]);
+    /**
+     * The breakpoint react-grid-layout is currently rendering, tracked so a
+     * gesture can be written back to the breakpoint that OWNS it.
+     *
+     * Seeded to `lg` and corrected by `<Responsive onBreakpointChange>`, which
+     * fires on mount once the container width is known.
+     */
+    const activeBreakpointRef = useRef('lg');
+    const handleBreakpointChange = useCallback((breakpoint) => {
+        activeBreakpointRef.current = breakpoint;
+    }, []);
+    /**
+     * Reduce react-grid-layout's all-breakpoints echo down to the ONE breakpoint
+     * that is authoritative — `lg` — or refuse the write.
+     *
+     * Two defects this closes, both reported as D-75:
+     *
+     * 1. **The derived breakpoints froze.** RGL echoes every breakpoint on every
+     *    gesture. Persisting them made them consumer-supplied, so
+     *    `buildResponsiveLayouts` stopped deriving them and the columns slider
+     *    (which rescales `lg`) could no longer reach the breakpoint actually on
+     *    screen. Below a 1200px container — i.e. most real desktop sessions once
+     *    the sidebar is subtracted — moving the slider changed nothing at all.
+     *
+     * 2. **An edit made at `md`/`sm` was invisible at `lg`.** The gesture landed
+     *    in `layouts.md`; `layouts.lg` kept its old values; the same user on a
+     *    wider monitor saw their arrangement revert. `md` and `sm` render the
+     *    same array against the same column count as `lg`, so folding the
+     *    gesture onto `lg` is lossless and makes one arrangement follow the user
+     *    across every window size.
+     *
+     * `xs`/`xxs` return `null` (no write). Those breakpoints render a full-width
+     * stack, so a gesture there carries only a vertical order; applying it to
+     * `lg` would flatten a multi-column desktop arrangement that the user cannot
+     * even see on that device. Refusing the write is the conservative half of
+     * the trade: a phone visit can no longer destroy the desktop layout, at the
+     * cost of phone-only reordering not persisting. Stated in the PR, not hidden.
+     */
+    const canonicaliseLayoutForPersist = useCallback((layouts) => {
+        const breakpoint = activeBreakpointRef.current;
+        if (!isCanonicalisableBreakpoint(breakpoint))
+            return null;
+        const items = layouts[breakpoint] ?? layouts.lg;
+        if (!items)
+            return null;
+        const next = { lg: items };
+        // Preserve any breakpoint a CONSUMER supplied deliberately (never a
+        // derived one) so an opt-out layout is not silently discarded.
+        for (const bp of Object.keys(layouts)) {
+            if (bp === 'lg' || isDerivedBreakpoint(bp))
+                continue;
+            next[bp] = layouts[bp] ?? [];
+        }
+        return next;
+    }, []);
+    const commitLayout = useCallback((layouts) => {
+        const canonical = canonicaliseLayoutForPersist(layouts);
+        if (!canonical)
+            return;
+        setSavedLayout(stripAutoHeightRows(canonical));
+    }, [canonicaliseLayoutForPersist, setSavedLayout, stripAutoHeightRows]);
     const onLayoutChange = useCallback((_layout, layouts) => {
         if (!isEditing)
             return;
@@ -272,7 +404,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         if (layoutCommitFrameRef.current !== null)
             return;
         if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function') {
-            setSavedLayout(stripAutoHeightRows(layouts));
+            commitLayout(layouts);
             return;
         }
         // Trailing rAF — lets a burst of resize ticks coalesce into one commit.
@@ -281,10 +413,10 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             const pending = pendingLayoutRef.current;
             if (pending) {
                 pendingLayoutRef.current = null;
-                setSavedLayout(stripAutoHeightRows(pending));
+                commitLayout(pending);
             }
         });
-    }, [isEditing, setSavedLayout, stripAutoHeightRows]);
+    }, [commitLayout, isEditing]);
     useEffect(() => {
         return () => {
             if (layoutCommitFrameRef.current !== null &&
@@ -300,6 +432,23 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         setLayoutCols(newCols);
         setBaseCols(newCols);
     }, [currentLayouts, layoutCols, setBaseCols, setLayoutCols, setSavedLayout]);
+    /**
+     * Build the object handed to the preference adapter from a new `lg` array.
+     *
+     * Only `lg` and consumer-supplied breakpoints are stored; md/sm/xs/xxs are
+     * re-derived on every render. Before 0.8.0 every mutator below spread
+     * `currentLayouts` (which contains the derived breakpoints) into its write,
+     * which re-froze them one gesture after `rawLayouts` had healed them.
+     */
+    const layoutsWithLg = useCallback((items) => {
+        const next = { lg: items };
+        for (const bp of Object.keys(currentLayouts)) {
+            if (bp === 'lg' || isDerivedBreakpoint(bp))
+                continue;
+            next[bp] = currentLayouts[bp] ?? [];
+        }
+        return next;
+    }, [currentLayouts]);
     const handleCompact = useCallback(() => {
         if (!currentLayouts.lg)
             return;
@@ -316,8 +465,8 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             placed.push(compacted);
             return compacted;
         });
-        startTransition(() => setSavedLayout({ ...currentLayouts, lg: result }));
-    }, [currentLayouts, setSavedLayout]);
+        startTransition(() => setSavedLayout(layoutsWithLg(result)));
+    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     const handleReset = useCallback(() => {
         startTransition(() => {
             setSavedLayout(defaultLayouts);
@@ -326,7 +475,6 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         });
     }, [defaultCols, defaultLayouts, setBaseCols, setLayoutCols, setSavedLayout]);
     const addWidget = useCallback((widgetKey, initialSize) => {
-        const bps = Object.keys(currentLayouts);
         const maxY = (currentLayouts.lg ?? []).reduce((max, item) => Math.max(max, item.y + item.h), 0);
         const newItem = {
             i: widgetKey,
@@ -337,60 +485,42 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             minW: initialSize?.minW,
             minH: initialSize?.minH,
         };
-        const updated = { lg: [] };
-        for (const bp of bps) {
-            updated[bp] = [...(currentLayouts[bp] ?? []), newItem];
-        }
-        startTransition(() => setSavedLayout(updated));
-    }, [currentLayouts, layoutCols, setSavedLayout]);
+        startTransition(() => setSavedLayout(layoutsWithLg([...(currentLayouts.lg ?? []), newItem])));
+    }, [currentLayouts, layoutCols, layoutsWithLg, setSavedLayout]);
     const moveWidget = useCallback((widgetKey, direction) => {
-        const updated = { lg: [] };
-        for (const bp of Object.keys(currentLayouts)) {
-            const items = [...(currentLayouts[bp] ?? [])];
-            const index = items.findIndex((item) => item.i === widgetKey);
-            if (index === -1) {
-                updated[bp] = items;
-                continue;
-            }
-            const targetIndex = direction === 'up' ? index - 1 : index + 1;
-            if (targetIndex < 0 || targetIndex >= items.length) {
-                updated[bp] = items;
-                continue;
-            }
-            const moved = items[index];
-            const withoutMoved = [...items.slice(0, index), ...items.slice(index + 1)];
-            const nextItems = [
-                ...withoutMoved.slice(0, targetIndex),
-                moved,
-                ...withoutMoved.slice(targetIndex),
-            ];
-            updated[bp] = nextItems;
-        }
-        startTransition(() => setSavedLayout(updated));
-    }, [currentLayouts, setSavedLayout]);
+        const items = [...(currentLayouts.lg ?? [])];
+        const index = items.findIndex((item) => item.i === widgetKey);
+        if (index === -1)
+            return;
+        const targetIndex = direction === 'up' ? index - 1 : index + 1;
+        if (targetIndex < 0 || targetIndex >= items.length)
+            return;
+        const moved = items[index];
+        const withoutMoved = [...items.slice(0, index), ...items.slice(index + 1)];
+        const nextItems = [
+            ...withoutMoved.slice(0, targetIndex),
+            moved,
+            ...withoutMoved.slice(targetIndex),
+        ];
+        startTransition(() => setSavedLayout(layoutsWithLg(nextItems)));
+    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     const setWidgetLocked = useCallback((widgetKey, locked) => {
-        const updated = { lg: [] };
-        for (const bp of Object.keys(currentLayouts)) {
-            updated[bp] = (currentLayouts[bp] ?? []).map((item) => {
-                if (item.i !== widgetKey)
-                    return item;
-                return {
-                    ...item,
-                    static: locked,
-                    isDraggable: !locked,
-                    isResizable: !locked,
-                };
-            });
-        }
-        startTransition(() => setSavedLayout(updated));
-    }, [currentLayouts, setSavedLayout]);
+        const nextItems = (currentLayouts.lg ?? []).map((item) => {
+            if (item.i !== widgetKey)
+                return item;
+            return {
+                ...item,
+                static: locked,
+                isDraggable: !locked,
+                isResizable: !locked,
+            };
+        });
+        startTransition(() => setSavedLayout(layoutsWithLg(nextItems)));
+    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     const removeWidget = useCallback((widgetKey) => {
-        const updated = { lg: [] };
-        for (const bp of Object.keys(currentLayouts)) {
-            updated[bp] = (currentLayouts[bp] ?? []).filter((item) => item.i !== widgetKey);
-        }
-        startTransition(() => setSavedLayout(updated));
-    }, [currentLayouts, setSavedLayout]);
+        const nextItems = (currentLayouts.lg ?? []).filter((item) => item.i !== widgetKey);
+        startTransition(() => setSavedLayout(layoutsWithLg(nextItems)));
+    }, [currentLayouts, layoutsWithLg, setSavedLayout]);
     /**
      * Measured auto-height overrides (widgetKey -> rows). DERIVED, in-memory-
      * only state (quality-review design ruling, 2026-07-14):
@@ -467,6 +597,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         activeCompactor,
         onLayoutChange,
         handleColumnChange,
+        handleBreakpointChange,
         handleCompact,
         handleReset,
         addWidget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -23,7 +23,11 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./styles.css": "./src/styles/react-grid-layout-overrides.css"
+    "./styles.css": "./src/styles/react-grid-layout-overrides.css",
+    "./scanner": {
+      "import": "./dist/scanner/index.js",
+      "types": "./dist/scanner/index.d.ts"
+    }
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
@@ -70,6 +74,7 @@
     "react-resizable": "^4.0.1",
     "typescript": "~6.0.3",
     "vite": "^8.0.16",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "@types/node": "^25.9.2"
   }
 }