@bsuite/page-builder 0.4.3 → 0.5.1

package/README.md

@@ -7,7 +7,44 @@ Exports:
 - `PageGridLayout`
 - `usePageGridLayout`
 - `rescaleLayout`
+- `computeAutoHeightRows`
 - `GridLayouts`, `GridLayoutItem`, `WidgetMeta`, and related types
 
 Consumer apps must depend on the published npm package, not `workspace:*` or
 `file:` links, because each app deploys independently.
+
+## Measured auto-height (`autoHeight`, 0.5.0+)
+
+Opt a widget into content-driven height by setting `autoHeight: true` on its
+`GridLayoutItem`:
+
+```ts
+const defaultLayouts: GridLayouts = {
+  lg: [
+    // Fixed card — user resizes it manually, height persists.
+    { i: 'summary', x: 0, y: 0, w: 6, h: 8 },
+    // Measured card — height tracks rendered content; `h` is only the
+    // initial seed used until the first measurement lands.
+    { i: 'details', x: 6, y: 0, w: 6, h: 20, autoHeight: true },
+  ],
+};
+```
+
+Behaviour and guarantees:
+
+- A `ResizeObserver` on an unconstrained measure wrapper reads the content's
+  intrinsic height; `computeAutoHeightRows` converts px → rows using the
+  same `rowHeight`/`margin` the grid renders with, so the loop converges to
+  a fixed point instead of oscillating.
+- Auto-height items render with `isResizable: false` automatically — do not
+  also wire a manual resize path for them.
+- Measured rows are **derived, in-memory-only state**: merged over the saved
+  layout at render time for every viewer, and **never persisted**. A
+  read-only viewer switching tabs inside a card produces zero preference
+  writes. User-driven `x`/`y`/`w` (and `h` for non-autoHeight items)
+  persistence is unchanged.
+- Updates are rAF-batched (all cards settling in a frame apply as one state
+  update) and suppressed mid-drag/mid-resize, then flushed on gesture end.
+
+When adding `autoHeight` to an existing page's layout, bump that page's
+`layoutVersion` so stale persisted layouts (without the flag) are reset.

package/dist/PageGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AACA,OAAO,KAAgE,MAAM,OAAO,CAAC;AAGrF,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAIxC,OAAO,KAAK,EAAe,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA+KnE,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,UAAU,EACV,SAAS,EAMT,WAAkB,EAClB,aAAsC,EACtC,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,GACvB,EAAE,mBAAmB,qBA+iBrB"}
+{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AACA,OAAO,KAA6E,MAAM,OAAO,CAAC;AAGlG,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAKxC,OAAO,KAAK,EAAe,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA0QnE,wBAAgB,cAAc,CAAC,EAC7B,OAAO,EACP,cAAc,EACd,WAAW,EACX,aAAa,EACb,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,OAAO,EACP,UAAU,EACV,SAAS,EAMT,WAAkB,EAClB,aAAsC,EACtC,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,GACvB,EAAE,mBAAmB,qBAooBrB"}

package/dist/PageGridLayout.js

@@ -1,13 +1,32 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ArrowDown, ArrowUp, ChevronDown, ChevronUp, Eye, EyeOff, Layers, LayoutGrid, Lock, Plus, RotateCcw, Save, Settings2, Unlock } from 'lucide-react';
-import React, { startTransition, useEffect, useMemo, useRef, useState } from 'react';
+import React, { startTransition, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { Responsive } from 'react-grid-layout';
 import { gridBounds, minMaxSize, minSize } from 'react-grid-layout/core';
 import 'react-grid-layout/css/styles.css';
 import 'react-resizable/css/styles.css';
+import { computeAutoHeightRows } from './autoHeight.js';
 import { defaultPreferenceAdapter } from './preferences.js';
 import { usePageGridLayout } from './usePageGridLayout.js';
 import { cn } from './utils.js';
+/**
+ * Single source of truth for the grid's pixel geometry — read by both the
+ * `<Responsive>` props below AND `GridItem`'s auto-height measurement
+ * (blueprint amendment A1). Previously these were separate inline literals
+ * (`rowHeight={32}`, `margin={[6, 6]}`) with no shared reference, which is
+ * exactly the kind of drift the auto-height px→row conversion cannot
+ * tolerate — `computeAutoHeightRows` must use the *same* rowHeight/margin
+ * the grid itself renders with, or the computed row count would target the
+ * wrong pixel size.
+ */
+const DEFAULT_ROW_HEIGHT = 32;
+const DEFAULT_MARGIN = [6, 6];
+/**
+ * Fixed non-content chrome added before converting measured content px to
+ * rows — currently just the unconditional `border border-border` (1px top
+ * + 1px bottom) added to every card surface (blueprint item 1).
+ */
+const DEFAULT_CARD_CHROME_PX = 2;
 /**
  * Default resize bounds applied as a *global* constraint to ALL grid items.
  *
@@ -55,7 +74,60 @@ const DEFAULT_ADD_ENTITY_WIDGET_EVENT_NAMES = ['bsu-add-entity-widget', 'crm7-ad
 const RGLResizeHandle = React.forwardRef(function RGLResizeHandle({ axis = 'se', className: injectedClassName, ...rest }, ref) {
     return (_jsx("span", { ref: ref, "data-no-drag": true, className: `react-resizable-handle react-resizable-handle-${axis}${injectedClassName ? ' ' + injectedClassName : ''}`, ...rest }));
 });
-const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, isEditing, label, onHide, children: injectedChildren, className: injectedClassName, style: injectedStyle, ...rest }, ref) {
+const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, isEditing, label, onHide, autoHeight, onAutoHeightChange, children: injectedChildren, className: injectedClassName, style: injectedStyle, ...rest }, ref) {
+    // Auto-height measurement (blueprint amendment A1). `measureRef` wraps
+    // `content` with NO height constraint of its own — its parent has
+    // `overflow-hidden` + `flex-1 min-h-0` (clips *painting* to the current
+    // grid cell height, per MDN's overflow semantics), but that never
+    // shrinks this child's own computed box height. So
+    // `entry.contentRect.height` here is always the content's true
+    // intrinsic size, independent of however many rows the item currently
+    // occupies — the property that makes the auto-height loop converge to
+    // a fixed point instead of oscillating (see autoHeight.ts).
+    const measureRef = useRef(null);
+    const lastReportedRowsRef = useRef(null);
+    const measureRafRef = useRef(null);
+    useEffect(() => {
+        if (!autoHeight || !onAutoHeightChange)
+            return;
+        const el = measureRef.current;
+        if (!el || typeof ResizeObserver === 'undefined')
+            return;
+        const ro = new ResizeObserver((entries) => {
+            const entry = entries[0];
+            if (!entry)
+                return;
+            const contentPx = entry.contentRect.height;
+            if (measureRafRef.current !== null)
+                return;
+            const schedule = typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function'
+                ? window.requestAnimationFrame.bind(window)
+                : (cb) => setTimeout(cb, 0);
+            measureRafRef.current = schedule(() => {
+                measureRafRef.current = null;
+                const rows = computeAutoHeightRows({
+                    contentPx,
+                    cardChromePx: DEFAULT_CARD_CHROME_PX,
+                    rowHeightPx: DEFAULT_ROW_HEIGHT,
+                    marginYPx: DEFAULT_MARGIN[1],
+                });
+                if (rows !== lastReportedRowsRef.current) {
+                    lastReportedRowsRef.current = rows;
+                    onAutoHeightChange(id, rows);
+                }
+            });
+        });
+        ro.observe(el);
+        return () => {
+            ro.disconnect();
+            if (measureRafRef.current !== null &&
+                typeof window !== 'undefined' &&
+                typeof window.cancelAnimationFrame === 'function') {
+                window.cancelAnimationFrame(measureRafRef.current);
+            }
+            measureRafRef.current = null;
+        };
+    }, [autoHeight, id, onAutoHeightChange]);
     // DnD root-cause fix (2026-05-07): react-draggable@4 (used internally by
     // react-grid-layout@2) checks the drag handle via
     // `matchesSelectorAndParentsTo(target, handle, baseNode)` — it walks UP
@@ -73,7 +145,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     return (_jsxs("div", { ref: ref, className: outerClass, style: injectedStyle, ...rest, children: [_jsxs("div", { className: "h-full w-full relative", children: [isEditing && (_jsx("div", { className: "absolute inset-0 z-10 pointer-events-none rounded-3xl border-2 border-transparent group-hover:border-primary/50 transition-colors bg-black/5" })), isEditing && (_jsx("div", { className: "absolute top-2 left-2 z-30 flex items-center gap-1 pointer-events-none", children: _jsx("span", { className: "text-[10px] px-1.5 py-0.5 rounded-md opacity-80 font-medium bg-muted text-muted-foreground", children: label }) })), isEditing && (_jsx("button", { className: "absolute top-2 right-2 z-30 h-6 w-6 rounded-full flex items-center justify-center bg-destructive/80 hover:bg-destructive text-white shadow transition-colors", "data-no-drag": true, onPointerDown: (event) => event.stopPropagation(), onClick: (event) => {
                             event.stopPropagation();
                             onHide(id);
-                        }, title: `Hide ${label}`, "aria-label": `Hide ${label}`, children: _jsx(EyeOff, { className: "h-3 w-3", "aria-hidden": "true" }) })), _jsx("div", { className: "h-full w-full rounded-3xl transition-all flex flex-col bg-card shadow-sm", style: { contain: 'layout style' }, children: _jsx("div", { className: "flex-1 min-h-0 overflow-auto", children: content }) })] }), injectedChildren] }));
+                        }, title: `Hide ${label}`, "aria-label": `Hide ${label}`, children: _jsx(EyeOff, { className: "h-3 w-3", "aria-hidden": "true" }) })), _jsx("div", { className: "h-full w-full rounded-3xl transition-all flex flex-col bg-card border border-border shadow-sm dark:shadow-[var(--glow-card,none)]", style: { contain: 'layout style' }, children: _jsx("div", { className: cn('flex-1 min-h-0', autoHeight ? 'overflow-hidden' : 'overflow-auto'), children: autoHeight ? _jsx("div", { ref: measureRef, children: content }) : content }) })] }), injectedChildren] }));
 }));
 export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, 
 // Resize default flipped 2026-05-12: rgl v2 dropped auto-handle rendering
@@ -82,7 +154,7 @@ export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVer
 // the safe default is true so any consumer who forgets to set it still
 // gets a usable canvas. Opt out per-page with isResizable={false}.
 isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_NAMES, createEntityWidget, onRegisterEntityWidget, }) {
-    const { currentLayouts, layoutCols, isEditing, setIsEditing, activeCols, activeCompactor, onLayoutChange, handleColumnChange, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
+    const { currentLayouts, layoutCols, isEditing, setIsEditing, activeCols, activeCompactor, onLayoutChange, handleColumnChange, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
         pageKey,
         defaultLayouts,
         defaultCols,
@@ -91,6 +163,52 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
         editorEventNames,
         preferenceAdapter,
     });
+    // Auto-height dispatcher (blueprint amendment A1, hardened per quality
+    // review 2026-07-14). `GridItem`'s ResizeObserver calls this per-widget
+    // whenever its measured content height changes; we rAF-batch and flush ALL
+    // pending widgets in ONE `applyAutoHeightRows` call — a single functional
+    // state update, so two cards settling in the same frame (e.g. card2+card3
+    // on /people/:id mount) can never last-writer-wins each other. Measured
+    // rows are DERIVED, in-memory-only state: they merge into `activeLayouts`
+    // below for ALL viewers and are never persisted (see usePageGridLayout).
+    // Updates are suppressed entirely while the user is mid-drag/mid-resize so
+    // auto-height never fights a manual gesture. A suppressed update is
+    // queued, not dropped — the drag/resize *Stop handlers flush whatever's
+    // pending the moment the gesture ends.
+    const isInteractingRef = useRef(false);
+    const pendingAutoHeightRef = useRef(new Map());
+    const autoHeightFrameRef = useRef(null);
+    const scheduleFrame = useCallback((callback) => {
+        if (typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function') {
+            return window.requestAnimationFrame(callback);
+        }
+        return setTimeout(callback, 0);
+    }, []);
+    const flushAutoHeightUpdates = useCallback(() => {
+        autoHeightFrameRef.current = null;
+        if (isInteractingRef.current)
+            return;
+        const pending = pendingAutoHeightRef.current;
+        if (pending.size === 0)
+            return;
+        pendingAutoHeightRef.current = new Map();
+        applyAutoHeightRows(Object.fromEntries(pending));
+    }, [applyAutoHeightRows]);
+    const handleAutoHeightChange = useCallback((widgetKey, rows) => {
+        pendingAutoHeightRef.current.set(widgetKey, rows);
+        if (isInteractingRef.current || autoHeightFrameRef.current !== null)
+            return;
+        autoHeightFrameRef.current = scheduleFrame(flushAutoHeightUpdates);
+    }, [flushAutoHeightUpdates, scheduleFrame]);
+    const handleInteractionStart = useCallback(() => {
+        isInteractingRef.current = true;
+    }, []);
+    const handleInteractionStop = useCallback(() => {
+        isInteractingRef.current = false;
+        if (pendingAutoHeightRef.current.size > 0 && autoHeightFrameRef.current === null) {
+            autoHeightFrameRef.current = scheduleFrame(flushAutoHeightUpdates);
+        }
+    }, [flushAutoHeightUpdates, scheduleFrame]);
     const resizeEnabled = isEditing && isResizable;
     const resizeConstraints = useMemo(() => [
         // `gridBounds` caps width at the active column count, so we don't need
@@ -123,10 +241,32 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
     const activeLayouts = useMemo(() => {
         const filtered = { lg: [] };
         for (const bp in currentLayouts) {
-            filtered[bp] = (currentLayouts[bp] ?? []).filter((item) => renderableWidgetKeys.has(item.i) && !hiddenLayerIds[item.i]);
+            filtered[bp] = (currentLayouts[bp] ?? [])
+                .filter((item) => renderableWidgetKeys.has(item.i) && !hiddenLayerIds[item.i])
+                // autoHeight items are measured, not manually resized (blueprint
+                // amendment A1) — force isResizable: false centrally here so every
+                // call site that sets autoHeight: true gets this for free, rather
+                // than needing to remember to also set isResizable itself.
+                //
+                // Measured rows (quality-review design ruling, 2026-07-14) merge
+                // over the saved/base `h`/`minH` HERE — the render layer — so the
+                // grid renders full-height cards for every viewer while the saved
+                // layout (and thus the preference adapter) never sees a measured
+                // height. Until the first measurement lands, `autoHeightRows` has
+                // no entry and the item's seed `h` renders as-is.
+                .map((item) => {
+                if (!item.autoHeight)
+                    return item;
+                const measuredRows = autoHeightRows[item.i];
+                return {
+                    ...item,
+                    isResizable: false,
+                    ...(measuredRows !== undefined ? { h: measuredRows, minH: measuredRows } : {}),
+                };
+            });
         }
         return filtered;
-    }, [currentLayouts, hiddenLayerIds, renderableWidgetKeys]);
+    }, [autoHeightRows, currentLayouts, hiddenLayerIds, renderableWidgetKeys]);
     const hideLayer = (layerId) => {
         setHiddenLayerIds((previous) => ({ ...previous, [layerId]: true }));
     };
@@ -295,7 +435,7 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
                                         }) })] })), layerItems.length > 0 && (_jsxs("div", { className: "basis-full rounded-md border border-border bg-background/80 p-2", children: [_jsxs("div", { className: "mb-2 flex items-center gap-2 text-xs font-medium uppercase tracking-wide text-muted-foreground", children: [_jsx(Layers, { className: "h-3.5 w-3.5" }), "Layers"] }), _jsx("div", { className: "flex flex-col gap-1", children: layerItems.map((layer) => (_jsxs("div", { className: "flex items-center gap-1 rounded border border-border bg-card px-2 py-1", children: [_jsx("input", { type: "text", value: layer.label, onChange: (event) => handleLayerRename(layer.id, event.target.value), className: "min-w-0 flex-1 bg-transparent text-xs text-foreground outline-none", "aria-label": `Rename ${layer.label}` }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'up'), disabled: !layer.canMoveUp, "aria-label": `Move ${layer.label} up`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowUp, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => moveWidget(layer.id, 'down'), disabled: !layer.canMoveDown, "aria-label": `Move ${layer.label} down`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground disabled:opacity-40", children: _jsx(ArrowDown, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => setWidgetLocked(layer.id, !layer.locked), "aria-label": `${layer.locked ? 'Unlock' : 'Lock'} ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: layer.locked ? _jsx(Lock, { className: "h-3.5 w-3.5" }) : _jsx(Unlock, { className: "h-3.5 w-3.5" }) }), _jsx("button", { type: "button", onClick: () => hideLayer(layer.id), "aria-label": `Hide ${layer.label}`, className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", children: _jsx(EyeOff, { className: "h-3.5 w-3.5" }) })] }, layer.id))) })] })), _jsxs("button", { type: "button", onClick: handleCompact, className: cn('ml-auto inline-flex items-center rounded-md border border-border px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Layers, { className: "h-4 w-4 mr-1" }), "Compact Layout"] }), _jsxs("button", { type: "button", onClick: () => setResetConfirmOpen(true), className: cn('inline-flex items-center rounded-md border border-border px-2 py-1 text-sm transition-colors', 'text-muted-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(RotateCcw, { className: "h-4 w-4 mr-1" }), "Reset to Default"] })] })] })), resetConfirmOpen && (_jsx("div", { className: "fixed inset-0 z-50 flex items-center justify-center bg-black/40 p-4", role: "dialog", "aria-modal": "true", "aria-labelledby": "page-grid-reset-title", "aria-describedby": "page-grid-reset-description", children: _jsxs("div", { className: "max-w-md rounded-lg bg-card p-5 shadow-lg border border-border", children: [_jsx("h2", { id: "page-grid-reset-title", className: "text-lg font-semibold", children: "Reset page layout?" }), _jsx("p", { id: "page-grid-reset-description", className: "mt-2 text-sm text-muted-foreground", children: "This will discard your current layout and restore all widgets to their default positions." }), _jsxs("div", { className: "mt-4 flex justify-end gap-2", children: [_jsx("button", { type: "button", ref: resetCancelButtonRef, onClick: () => setResetConfirmOpen(false), className: cn('inline-flex items-center rounded-md border border-border px-3 py-2 text-sm transition-colors', 'bg-card text-foreground hover:bg-muted hover:text-foreground', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: "Cancel" }), _jsx("button", { type: "button", ref: resetConfirmButtonRef, onClick: () => {
                                         handleReset();
                                         setResetConfirmOpen(false);
-                                    }, className: cn('inline-flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors', 'bg-destructive text-white shadow hover:bg-destructive/90', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-destructive/40 focus-visible:ring-offset-1'), children: "Reset to Default" })] })] }) })), _jsx("div", { ref: containerRef, className: cn('relative z-0 overflow-visible', isEditing && 'min-h-[200px] bg-muted/30'), "data-page-grid-editing": isEditing || undefined, children: _jsx("div", { className: "relative z-0", style: { opacity: containerWidth > 0 ? 1 : 0 }, "aria-busy": containerWidth <= 0, children: _jsx(Responsive, { width: Math.max(containerWidth, 1), className: "layout page-grid-canvas", layouts: activeLayouts, breakpoints: { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }, rowHeight: 32, onLayoutChange: onLayoutChange, dragConfig: {
+                                    }, className: cn('inline-flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors', 'bg-destructive text-white shadow hover:bg-destructive/90', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-destructive/40 focus-visible:ring-offset-1'), children: "Reset to Default" })] })] }) })), _jsx("div", { ref: containerRef, className: cn('relative z-0 overflow-visible', isEditing && 'min-h-[200px] bg-muted/30'), "data-page-grid-editing": isEditing || undefined, children: _jsx("div", { className: "relative z-0", style: { opacity: containerWidth > 0 ? 1 : 0 }, "aria-busy": containerWidth <= 0, children: _jsx(Responsive, { width: Math.max(containerWidth, 1), className: "layout page-grid-canvas", layouts: activeLayouts, breakpoints: { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }, rowHeight: DEFAULT_ROW_HEIGHT, onLayoutChange: onLayoutChange, dragConfig: {
                             enabled: isEditing,
                             handle: '.drag-handle',
                             bounded: false,
@@ -305,10 +445,15 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
                             handles: resizeHandles,
                             // Required for v2 — see RGLResizeHandle comment above.
                             handleComponent: (axis, ref) => (_jsx(RGLResizeHandle, { axis: axis, ref: ref })),
-                        }, constraints: resizeEnabled ? resizeConstraints : undefined, compactor: activeCompactor, cols: activeCols, margin: [6, 6], children: activeLayouts.lg.map((layoutItem) => {
+                        }, constraints: resizeEnabled ? resizeConstraints : undefined, compactor: activeCompactor, cols: activeCols, margin: DEFAULT_MARGIN, 
+                        // Suppress auto-height writes mid-gesture (blueprint amendment
+                        // A1) — coexists with dragConfig/resizeConfig above; RGL v2's
+                        // grouped config props and top-level *Start/*Stop callbacks are
+                        // independent, not mutually exclusive.
+                        onDragStart: handleInteractionStart, onDragStop: handleInteractionStop, onResizeStart: handleInteractionStart, onResizeStop: handleInteractionStop, children: activeLayouts.lg.map((layoutItem) => {
                             const content = allWidgets[layoutItem.i];
                             if (content === undefined || content === null)
                                 return null;
-                            return (_jsx(GridItem, { id: layoutItem.i, content: content, isEditing: isEditing, label: layerNames[layoutItem.i] || widgetMeta?.[layoutItem.i]?.label || layoutItem.i, onHide: hideLayer }, layoutItem.i));
+                            return (_jsx(GridItem, { id: layoutItem.i, content: content, isEditing: isEditing, label: layerNames[layoutItem.i] || widgetMeta?.[layoutItem.i]?.label || layoutItem.i, onHide: hideLayer, autoHeight: layoutItem.autoHeight, onAutoHeightChange: handleAutoHeightChange }, layoutItem.i));
                         }) }) }) })] }));
 }

package/dist/autoHeight.d.ts

@@ -0,0 +1,49 @@
+export interface ComputeAutoHeightRowsOptions {
+    /**
+     * Measured intrinsic content height in pixels. Callers MUST measure an
+     * UNCONSTRAINED wrapper around the card content (see `GridItem`'s
+     * ResizeObserver in `PageGridLayout.tsx`) — `overflow: hidden` on an
+     * ancestor clips *painting* only, it does not shrink a descendant's own
+     * computed box height, so an unconstrained wrapper reports the content's
+     * true size regardless of the grid item's current allocated pixel height.
+     * That property is what makes this function converge to a fixed point
+     * (see the "idempotent" test below) instead of oscillating: the same
+     * content always measures the same, no matter how many rows the item
+     * currently occupies.
+     */
+    contentPx: number;
+    /**
+     * Fixed non-content chrome (e.g. the card's top+bottom border added by
+     * the unconditional `border border-border` — blueprint item 1) added
+     * before converting to rows, so rounding/border pixels never clip
+     * content by a sub-row amount.
+     */
+    cardChromePx: number;
+    /**
+     * Must match the `rowHeight` passed to `<Responsive>`. Single source of
+     * truth: `DEFAULT_ROW_HEIGHT` in `PageGridLayout.tsx`.
+     */
+    rowHeightPx: number;
+    /**
+     * Must match the vertical component of the `margin` tuple passed to
+     * `<Responsive>`. Single source of truth: `DEFAULT_MARGIN` in
+     * `PageGridLayout.tsx`.
+     */
+    marginYPx: number;
+    /**
+     * Row-count floor. Defaults to 1 — a widget can never auto-collapse to 0
+     * rows even if content momentarily measures 0px (e.g. before first paint).
+     */
+    minRows?: number;
+}
+/**
+ * Pure px→row conversion for auto-height grid items (blueprint amendment
+ * A1). Deliberately uses `Math.ceil`, NOT react-grid-layout's own internal
+ * `Math.round` convention (see `calcWH` in react-grid-layout's compiled
+ * source) — rounding down would silently clip content roughly half the
+ * 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.
+ */
+export declare function computeAutoHeightRows({ contentPx, cardChromePx, rowHeightPx, marginYPx, minRows, }: ComputeAutoHeightRowsOptions): number;
+//# sourceMappingURL=autoHeight.d.ts.map

package/dist/autoHeight.d.ts.map

@@ -0,0 +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"}

package/dist/autoHeight.js

@@ -0,0 +1,16 @@
+/**
+ * Pure px→row conversion for auto-height grid items (blueprint amendment
+ * A1). Deliberately uses `Math.ceil`, NOT react-grid-layout's own internal
+ * `Math.round` convention (see `calcWH` in react-grid-layout's compiled
+ * source) — rounding down would silently clip content roughly half the
+ * 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.
+ */
+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);
+    return Math.max(minRows, raw);
+}

package/dist/index.d.ts

@@ -2,6 +2,8 @@ export { PageGridLayout } from './PageGridLayout.js';
 export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
 export type { PageGridEditingEventDetail } from './usePageGridLayout.js';
 export { rescaleLayout } from './rescaleLayout.js';
+export { computeAutoHeightRows } from './autoHeight.js';
+export type { ComputeAutoHeightRowsOptions } from './autoHeight.js';
 export { WYSIWYG_REQUIRED_PRIMITIVES, WYSIWYG_SURFACE_CONTRACTS, assertWysiwygPrimitiveCoverage, getWysiwygSurfaceContract, } from './wysiwygContract.js';
 export type { WysiwygPrimitive, WysiwygSurfaceContract, WysiwygSurfaceId, } from './wysiwygContract.js';
 export { buildResponsiveLayouts, RESPONSIVE_BREAKPOINTS, } from './buildResponsiveLayouts.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,UAAU,GACX,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,iBAAiB,EACjB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACzE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,YAAY,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EACL,2BAA2B,EAC3B,yBAAyB,EACzB,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,6BAA6B,EAC7B,oBAAoB,GACrB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAChF,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export { PageGridLayout } from './PageGridLayout.js';
 export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
 export { rescaleLayout } from './rescaleLayout.js';
+export { computeAutoHeightRows } from './autoHeight.js';
 export { WYSIWYG_REQUIRED_PRIMITIVES, WYSIWYG_SURFACE_CONTRACTS, assertWysiwygPrimitiveCoverage, getWysiwygSurfaceContract, } from './wysiwygContract.js';
 export { buildResponsiveLayouts, RESPONSIVE_BREAKPOINTS, } from './buildResponsiveLayouts.js';
 export { useLocalPreference, defaultPreferenceAdapter } from './preferences.js';

package/dist/types.d.ts

@@ -1,6 +1,17 @@
 import type React from 'react';
 import type { Compactor, LayoutItem, ResizeHandleAxis } from 'react-grid-layout';
-export type GridLayoutItem = LayoutItem;
+export interface GridLayoutItem extends LayoutItem {
+    /**
+     * When true, this item's height is driven by its own measured content
+     * height rather than manual resize (blueprint amendment A1). `GridItem`
+     * mounts a `ResizeObserver` on an unconstrained content wrapper and
+     * reports the computed row count upward via `computeAutoHeightRows`;
+     * `PageGridLayout` force-sets `isResizable: false` for any item with
+     * `autoHeight: true` (see the `activeLayouts` memo) so callers don't need
+     * to remember to set both fields.
+     */
+    autoHeight?: boolean;
+}
 export interface GridLayouts {
     lg: GridLayoutItem[];
     [key: string]: GridLayoutItem[];
@@ -67,6 +78,21 @@ export interface UsePageGridLayoutResult {
     moveWidget: (widgetKey: string, direction: 'up' | 'down') => void;
     setWidgetLocked: (widgetKey: string, locked: boolean) => void;
     removeWidget: (widgetKey: string) => void;
+    /**
+     * Applies a batch of measured auto-height row counts (widgetKey -> rows)
+     * in a SINGLE functional state update. Measured heights are DERIVED,
+     * in-memory-only state: they are merged over the saved layout when
+     * producing the layouts handed to react-grid-layout (so every viewer
+     * renders full-height cards) and are NEVER written to the preference
+     * adapter — measurements re-derive on every mount, so persisting them
+     * would be redundant and would cause storage writes from mere viewing
+     * (e.g. switching tabs inside a card). Diff-guarded: returns the previous
+     * map identity when nothing changed, so no re-render occurs.
+     */
+    applyAutoHeightRows: (rowsByWidget: Record<string, number>) => void;
+    /** Current measured auto-height overrides (widgetKey -> rows). In-memory
+     * only; see `applyAutoHeightRows`. */
+    autoHeightRows: Record<string, number>;
     resetConfirmOpen: boolean;
     setResetConfirmOpen: React.Dispatch<React.SetStateAction<boolean>>;
     canEditPage: boolean;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/usePageGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAaA,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,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,GAC7C,EAAE,wBAAwB,GAAG,uBAAuB,CA8UpD"}
+{"version":3,"file":"usePageGridLayout.d.ts","sourceRoot":"","sources":["../src/usePageGridLayout.ts"],"names":[],"mappings":"AAaA,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,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,GAC7C,EAAE,wBAAwB,GAAG,uBAAuB,CA8ZpD"}

package/dist/usePageGridLayout.js

@@ -141,6 +141,40 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
      */
     const pendingLayoutRef = useRef(null);
     const layoutCommitFrameRef = useRef(null);
+    /**
+     * Strips DERIVED measured heights out of a layout before it reaches the
+     * preference adapter. react-grid-layout is rendered with `autoHeightRows`
+     * merged over the saved layout (see `applyAutoHeightRows`), so the layouts
+     * it echoes back through `onLayoutChange` carry the MEASURED `h` for
+     * autoHeight items — persisting that verbatim would smuggle measured
+     * heights into user_preferences through the drag/resize path and drop the
+     * `autoHeight` flag (react-grid-layout does not round-trip custom item
+     * props). Restore `h`/`minH`/`autoHeight` from the un-merged base layout;
+     * user-driven `x`/`y`/`w` (and `h` for non-autoHeight items) pass through
+     * untouched. Reads the base via a ref so the trailing-rAF commit below
+     * never closes over a stale snapshot.
+     */
+    const currentLayoutsForStripRef = useRef(null);
+    const stripAutoHeightRows = useCallback((layouts) => {
+        const base = currentLayoutsForStripRef.current;
+        if (!base)
+            return layouts;
+        const result = { lg: [] };
+        for (const bp of Object.keys(layouts)) {
+            const baseItems = base[bp] ?? base.lg ?? [];
+            const baseByKey = new Map(baseItems.map((item) => [item.i, item]));
+            result[bp] = (layouts[bp] ?? []).map((item) => {
+                const baseItem = baseByKey.get(item.i);
+                if (!baseItem?.autoHeight)
+                    return item;
+                return { ...item, autoHeight: true, h: baseItem.h, minH: baseItem.minH };
+            });
+        }
+        return result;
+    }, []);
+    useEffect(() => {
+        currentLayoutsForStripRef.current = currentLayouts;
+    }, [currentLayouts]);
     const onLayoutChange = useCallback((_layout, layouts) => {
         if (!isEditing)
             return;
@@ -148,7 +182,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         if (layoutCommitFrameRef.current !== null)
             return;
         if (typeof window === 'undefined' || typeof window.requestAnimationFrame !== 'function') {
-            setSavedLayout(layouts);
+            setSavedLayout(stripAutoHeightRows(layouts));
             return;
         }
         // Trailing rAF — lets a burst of resize ticks coalesce into one commit.
@@ -157,10 +191,10 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             const pending = pendingLayoutRef.current;
             if (pending) {
                 pendingLayoutRef.current = null;
-                setSavedLayout(pending);
+                setSavedLayout(stripAutoHeightRows(pending));
             }
         });
-    }, [isEditing, setSavedLayout]);
+    }, [isEditing, setSavedLayout, stripAutoHeightRows]);
     useEffect(() => {
         return () => {
             if (layoutCommitFrameRef.current !== null &&
@@ -267,6 +301,37 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         }
         startTransition(() => setSavedLayout(updated));
     }, [currentLayouts, setSavedLayout]);
+    /**
+     * Measured auto-height overrides (widgetKey -> rows). DERIVED, in-memory-
+     * only state (quality-review design ruling, 2026-07-14):
+     *
+     * - Applied for ALL viewers — the map is merged over the saved layout when
+     *   producing the layouts handed to react-grid-layout (see
+     *   `PageGridLayout`'s `activeLayouts` memo), so read-only users get
+     *   full-height cards too.
+     * - NEVER persisted — not even while editing. Measurements re-derive on
+     *   every mount; writing them to the preference adapter would be redundant
+     *   AND would turn mere viewing (e.g. Radix tab switches inside a card,
+     *   which unmount/remount panel content and fire the ResizeObserver) into
+     *   storage upserts for any authenticated viewer.
+     * - Updated FUNCTIONALLY in one combined state update per flush, so two
+     *   cards settling in the same animation frame can never last-writer-wins
+     *   each other through a stale closure.
+     */
+    const [autoHeightRows, setAutoHeightRows] = useState({});
+    const applyAutoHeightRows = useCallback((rowsByWidget) => {
+        setAutoHeightRows((previous) => {
+            let changed = false;
+            const next = { ...previous };
+            for (const [widgetKey, rows] of Object.entries(rowsByWidget)) {
+                if (next[widgetKey] !== rows) {
+                    next[widgetKey] = rows;
+                    changed = true;
+                }
+            }
+            return changed ? next : previous;
+        });
+    }, []);
     useEffect(() => {
         if (!canEditPage || typeof window === 'undefined')
             return;
@@ -274,7 +339,16 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
             const detail = event.detail;
             if (!detail?.page || detail.page === pageKey) {
                 detail?.ack?.();
-                setIsEditing(true);
+                // `detail.editing` defaults to `true` when omitted — every existing
+                // dispatcher across all 6 apps only ever sent `{ page, path }` to
+                // OPEN the editor, so this preserves 100% backward compatibility.
+                // An explicit `editing: false` lets a launcher force-close a grid
+                // instance that's still mounted after an in-route navigation (e.g.
+                // wouter's `/people/:id` not remounting between different ids) —
+                // see crm7's `PageEditorLauncher.tsx` navigation-close effect
+                // (blueprint amendment A3). Reuses this exact event channel rather
+                // than introducing a second one.
+                setIsEditing(detail?.editing ?? true);
             }
         };
         for (const eventName of editorEventNames) {
@@ -285,7 +359,7 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
                 window.removeEventListener(eventName, handler);
             }
         };
-    }, [canEditPage, editorEventNames, pageKey]);
+    }, [canEditPage, editorEventNames, pageKey, setIsEditing]);
     return {
         currentLayouts,
         layoutCols,
@@ -301,6 +375,8 @@ export function usePageGridLayout({ pageKey, defaultLayouts, defaultCols = 12, l
         moveWidget,
         setWidgetLocked,
         removeWidget,
+        applyAutoHeightRows,
+        autoHeightRows,
         resetConfirmOpen,
         setResetConfirmOpen,
         canEditPage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -32,6 +32,7 @@
     "prepublishOnly": "pnpm build"
   },
   "peerDependencies": {
+    "@bsuite/theme": ">=0.5.0",
     "@dnd-kit/core": "^6",
     "@dnd-kit/sortable": "^10",
     "@dnd-kit/utilities": "^3",
@@ -42,6 +43,9 @@
     "react-resizable": "^3 || ^4"
   },
   "peerDependenciesMeta": {
+    "@bsuite/theme": {
+      "optional": true
+    },
     "@dnd-kit/core": {
       "optional": true
     },