@bsuite/page-builder 0.6.3 → 0.8.0

package/dist/PageGridLayout.d.ts

@@ -2,5 +2,5 @@ import React from 'react';
 import 'react-grid-layout/css/styles.css';
 import 'react-resizable/css/styles.css';
 import type { PageGridLayoutProps } from './types.js';
-export declare function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, isResizable, resizeHandles, addEntityWidgetEventNames, createEntityWidget, onRegisterEntityWidget, }: PageGridLayoutProps): React.JSX.Element;
+export declare function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, isResizable, resizeHandles, tenantId, defaultAutoHeight, addEntityWidgetEventNames, createEntityWidget, onRegisterEntityWidget, relationshipCatalog, addRelationshipWidgetEventNames, createRelationshipWidget, onRegisterRelationshipWidget, onRelationshipWidgetRejected, }: PageGridLayoutProps): React.JSX.Element;
 //# sourceMappingURL=PageGridLayout.d.ts.map

package/dist/PageGridLayout.d.ts.map

@@ -1 +1 @@
-{"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,qBAirBrB"}
+{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AACA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAMxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AA8U7F,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,QAAQ,EACR,iBAAiB,EACjB,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBA6xBrB"}

package/dist/PageGridLayout.js

@@ -1,12 +1,13 @@
 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, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import React, { startTransition, useCallback, useEffect, useLayoutEffect, 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 { isRelationshipWritable } from './relationshipCatalog.js';
 import { usePageGridLayout } from './usePageGridLayout.js';
 import { cn } from './utils.js';
 /**
@@ -48,6 +49,15 @@ const DEFAULT_CARD_CHROME_PX = 2;
 const DEFAULT_RESIZE_BOUNDS = { minW: 2, minH: 1 };
 const DEFAULT_RESIZE_HANDLES = ['se'];
 const DEFAULT_ADD_ENTITY_WIDGET_EVENT_NAMES = ['bsu-add-entity-widget', 'crm7-add-entity-widget'];
+/**
+ * Second widget kind (W4-1) — a relationship field, distinct from the
+ * entity-list events above. Named analogously so a consumer wiring both
+ * kinds recognises the pattern immediately.
+ */
+const DEFAULT_ADD_RELATIONSHIP_WIDGET_EVENT_NAMES = [
+    'bsu-add-relationship-widget',
+    'crm7-add-relationship-widget',
+];
 /**
  * Custom resize handle for react-grid-layout v2.
  *
@@ -87,6 +97,71 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     const measureRef = useRef(null);
     const lastReportedRowsRef = useRef(null);
     const measureRafRef = useRef(null);
+    /**
+     * Latest measured content height, updated on EVERY ResizeObserver entry.
+     *
+     * D-76 root cause ("cards render half cut off on page open"). The previous
+     * implementation captured `contentPx` in the rAF closure and then bailed
+     * out of any further entry that arrived before that frame ran:
+     *
+     *     if (measureRafRef.current !== null) return;   // <- measurement lost
+     *
+     * That is first-writer-wins inside a frame, and the first writer is
+     * routinely the WRONG one: a card mounts empty or skeletonised, the
+     * observer fires at (say) 90px and schedules the frame, the query resolves
+     * and the observer fires again at 760px — and that second entry returned
+     * early, discarding the real height. The frame then converged the card to
+     * ~3 rows. Because `computeAutoHeightRows` is a pure function of the height
+     * it is given, nothing re-triggered: the card stayed at the empty-state
+     * height with its content clipped by the `overflow-hidden` autoHeight
+     * wrapper until something else happened to resize it.
+     *
+     * Storing the height in a ref and READING IT INSIDE the frame makes it
+     * last-writer-wins, which is the only correct policy for "how tall is this
+     * content right now".
+     */
+    const latestContentPxRef = useRef(null);
+    const reportRows = useCallback((contentPx) => {
+        if (!onAutoHeightChange)
+            return;
+        const rows = computeAutoHeightRows({
+            contentPx,
+            cardChromePx: DEFAULT_CARD_CHROME_PX,
+            rowHeightPx: DEFAULT_ROW_HEIGHT,
+            marginYPx: DEFAULT_MARGIN[1],
+        });
+        if (rows === lastReportedRowsRef.current)
+            return;
+        lastReportedRowsRef.current = rows;
+        onAutoHeightChange(id, rows);
+    }, [id, onAutoHeightChange]);
+    /**
+     * First measurement BEFORE paint (second half of D-76).
+     *
+     * A ResizeObserver's initial observation is delivered asynchronously, and
+     * the rAF hop below adds another frame. Until it lands the card renders at
+     * its seed `h` — 6 rows / 192px for a `DraggableCardPage` card — with
+     * `overflow-hidden`, so the first painted frame of a taller card is
+     * literally cut in half. That is what the operator sees "on page open",
+     * every open, on every surface with content taller than its seed.
+     *
+     * Measuring in a layout effect and reporting synchronously puts the correct
+     * row count into state within the same commit, so the browser never paints
+     * the clipped frame. React batches these updates across all GridItems
+     * mounting together, and `applyAutoHeightRows` is a functional update, so N
+     * cards settling at once cost one re-render and cannot clobber each other.
+     */
+    useLayoutEffect(() => {
+        if (!autoHeight || !onAutoHeightChange)
+            return;
+        const el = measureRef.current;
+        if (!el)
+            return;
+        const contentPx = el.getBoundingClientRect().height;
+        latestContentPxRef.current = contentPx;
+        if (contentPx > 0)
+            reportRows(contentPx);
+    }, [autoHeight, onAutoHeightChange, reportRows]);
     useEffect(() => {
         if (!autoHeight || !onAutoHeightChange)
             return;
@@ -97,7 +172,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
             const entry = entries[0];
             if (!entry)
                 return;
-            const contentPx = entry.contentRect.height;
+            latestContentPxRef.current = entry.contentRect.height;
             if (measureRafRef.current !== null)
                 return;
             const schedule = typeof window !== 'undefined' && typeof window.requestAnimationFrame === 'function'
@@ -105,16 +180,10 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
                 : (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);
-                }
+                const contentPx = latestContentPxRef.current;
+                if (contentPx === null)
+                    return;
+                reportRows(contentPx);
             });
         });
         ro.observe(el);
@@ -127,7 +196,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
             }
             measureRafRef.current = null;
         };
-    }, [autoHeight, id, onAutoHeightChange]);
+    }, [autoHeight, onAutoHeightChange, reportRows]);
     // 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
@@ -153,8 +222,8 @@ export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVer
 // adapters then defaulted it back to true. With v2's handle gap fixed,
 // 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, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
+isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, defaultAutoHeight, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_NAMES, createEntityWidget, onRegisterEntityWidget, relationshipCatalog, addRelationshipWidgetEventNames = DEFAULT_ADD_RELATIONSHIP_WIDGET_EVENT_NAMES, createRelationshipWidget, onRegisterRelationshipWidget, onRelationshipWidgetRejected, }) {
+    const { currentLayouts, layoutCols, isEditing, setIsEditing, activeCols, activeCompactor, onLayoutChange, handleColumnChange, handleBreakpointChange, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
         pageKey,
         defaultLayouts,
         defaultCols,
@@ -162,6 +231,7 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
         canEditPage,
         editorEventNames,
         preferenceAdapter,
+        defaultAutoHeight,
     });
     // Auto-height dispatcher (blueprint amendment A1, hardened per quality
     // review 2026-07-14). `GridItem`'s ResizeObserver calls this per-widget
@@ -220,6 +290,7 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
         minSize(DEFAULT_RESIZE_BOUNDS.minW, DEFAULT_RESIZE_BOUNDS.minH),
     ], []);
     const [extraWidgetConfigs, setExtraWidgetConfigs] = useState({});
+    const [extraRelationshipWidgetConfigs, setExtraRelationshipWidgetConfigs] = useState({});
     const { value: layerNames, setValue: setLayerNames } = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_grid_layer_names`, {});
     const { value: hiddenLayerIds, setValue: setHiddenLayerIds } = (preferenceAdapter ?? defaultPreferenceAdapter)(`page:${pageKey}_grid_hidden_layers`, {});
     const extraWidgets = useMemo(() => {
@@ -232,11 +303,35 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
                 entityType: config.entityType,
                 label: config.label,
                 isEditing,
+                tenantId,
             });
         }
         return rendered;
-    }, [createEntityWidget, extraWidgetConfigs, isEditing]);
-    const allWidgets = useMemo(() => ({ ...widgets, ...extraWidgets }), [widgets, extraWidgets]);
+    }, [createEntityWidget, extraWidgetConfigs, isEditing, tenantId]);
+    // Relationship-field widgets (W4-1) — same shape as the entity-list path
+    // above (config registry -> render via a consumer-supplied factory), kept
+    // as a parallel structure rather than folded in because the two widget
+    // kinds are gated differently: an entity-list widget can always be added,
+    // a relationship widget only when `relationshipCatalog` proves the FK is
+    // real (see the add-relationship-widget listener below).
+    const extraRelationshipWidgets = useMemo(() => {
+        const rendered = {};
+        if (!createRelationshipWidget)
+            return rendered;
+        for (const [widgetId, detail] of Object.entries(extraRelationshipWidgetConfigs)) {
+            rendered[widgetId] = createRelationshipWidget({
+                widgetId,
+                hostEntityType: detail.hostEntityType,
+                fkColumn: detail.fkColumn,
+                targetEntityType: detail.targetEntityType,
+                label: detail.label,
+                isEditing,
+                tenantId,
+            });
+        }
+        return rendered;
+    }, [createRelationshipWidget, extraRelationshipWidgetConfigs, isEditing, tenantId]);
+    const allWidgets = useMemo(() => ({ ...widgets, ...extraWidgets, ...extraRelationshipWidgets }), [widgets, extraWidgets, extraRelationshipWidgets]);
     const renderableWidgetKeys = useMemo(() => new Set(Object.keys(allWidgets).filter((key) => allWidgets[key] !== null && allWidgets[key] !== undefined)), [allWidgets]);
     const activeLayouts = useMemo(() => {
         const filtered = { lg: [] };
@@ -274,9 +369,28 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
                 // 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;
-                // HEAL a persisted `isResizable: false`.
+                // HEAL a persisted `isResizable: false` on ANY item, not just an
+                // autoHeight one (D-75: "individual cards can no longer be resized").
+                //
+                // The 0.6.0 heal was scoped to `item.autoHeight`, which left the
+                // whole non-autoHeight population — every card that opted out, and
+                // every layout persisted before `autoHeight` existed as a concept —
+                // permanently unresizable with no way back: the flag is re-persisted
+                // on each load, so clearing it by hand does not survive a refresh.
+                //
+                // The one legitimate source of a per-item `isResizable: false` is the
+                // Layers "lock" control, which writes it together with `static: true`
+                // and `isDraggable: false`. Requiring that full signature separates a
+                // deliberate lock (kept) from the 0.5.2 leak (dropped), so the heal
+                // can be widened without silently unlocking anything a user locked.
+                const lockedDeliberately = item.static === true || item.isDraggable === false;
+                const needsResizeHeal = item.isResizable === false && !lockedDeliberately;
+                if (!item.autoHeight) {
+                    if (!needsResizeHeal)
+                        return item;
+                    const { isResizable: _dropped, ...unlocked } = item;
+                    return unlocked;
+                }
                 //
                 // 0.5.2 set this at the render layer, and it leaked out through
                 // `onLayoutChange` into the SAVED layout. Removing the override in
@@ -363,6 +477,57 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
         onRegisterEntityWidget,
         setIsEditing,
     ]);
+    // Relationship-field widget listener (W4-1/W4-2). Mirrors the
+    // add-entity-widget listener above, with one structural difference: every
+    // request is checked against `relationshipCatalog` via
+    // `isRelationshipWritable` BEFORE a widget is ever created. No catalogue
+    // match means the FK is not proven to exist, so the request is refused —
+    // `onRelationshipWidgetRejected` fires (for the consumer to surface why)
+    // and nothing is added to the layout. This is the only place that gate is
+    // enforced; there is no other path that creates a relationship widget.
+    useEffect(() => {
+        if (!createRelationshipWidget || typeof window === 'undefined')
+            return;
+        const handleAddRelationshipWidget = (event) => {
+            const detail = event.detail;
+            if (!detail?.hostEntityType || !detail.fkColumn || !detail.targetEntityType)
+                return;
+            if (!isRelationshipWritable(relationshipCatalog, detail)) {
+                onRelationshipWidgetRejected?.(detail);
+                return;
+            }
+            const widgetId = `relationship:${detail.hostEntityType}:${detail.fkColumn}`;
+            const alreadyInLayout = activeLayouts.lg?.some((item) => item.i === widgetId);
+            if (alreadyInLayout) {
+                startTransition(() => setIsEditing(true));
+                return;
+            }
+            onRegisterRelationshipWidget?.({ widgetId, ...detail });
+            setExtraRelationshipWidgetConfigs((previous) => ({
+                ...previous,
+                [widgetId]: detail,
+            }));
+            addWidget(widgetId, { w: 4, h: 3, minW: 3, minH: 2 });
+            startTransition(() => setIsEditing(true));
+        };
+        for (const eventName of addRelationshipWidgetEventNames) {
+            window.addEventListener(eventName, handleAddRelationshipWidget);
+        }
+        return () => {
+            for (const eventName of addRelationshipWidgetEventNames) {
+                window.removeEventListener(eventName, handleAddRelationshipWidget);
+            }
+        };
+    }, [
+        activeLayouts.lg,
+        addRelationshipWidgetEventNames,
+        addWidget,
+        createRelationshipWidget,
+        onRegisterRelationshipWidget,
+        onRelationshipWidgetRejected,
+        relationshipCatalog,
+        setIsEditing,
+    ]);
     const visibleKeys = useMemo(() => new Set((activeLayouts.lg ?? []).map((item) => item.i)), [activeLayouts.lg]);
     const hiddenWidgetKeys = useMemo(() => [...renderableWidgetKeys].filter((key) => !visibleKeys.has(key)), [renderableWidgetKeys, visibleKeys]);
     const layerItems = useMemo(() => (activeLayouts.lg ?? []).map((item, index, layers) => {
@@ -479,7 +644,11 @@ 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-overlay/50 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-destructive-foreground 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: {
+                                    }, className: cn('inline-flex items-center rounded-md px-3 py-2 text-sm font-medium transition-colors', 'bg-destructive text-destructive-foreground 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, 
+                        // Tells the hook which breakpoint a gesture belongs to, so the edit
+                        // is folded back onto `lg` instead of into a derived breakpoint
+                        // that is regenerated (and therefore discarded) on the next render.
+                        onBreakpointChange: handleBreakpointChange, dragConfig: {
                             enabled: isEditing,
                             handle: '.drag-handle',
                             bounded: false,

package/dist/RelationshipField.d.ts

@@ -0,0 +1,77 @@
+import React from 'react';
+import type { RelationshipFieldOption } from './types.js';
+/**
+ * RelationshipField — the app-agnostic relationship-field widget (W4-1).
+ *
+ * A typeahead over a single entity that writes ONE foreign key on the
+ * record being edited, distinct from the entity-list widget (a table of
+ * every row, writing nothing). `@bsuite/page-builder` cannot import from
+ * crm7 or talk to Supabase, so the data source is entirely caller-supplied
+ * — `search`/`resolveOption` are the ClientSelector-equivalent behaviour
+ * crm7 (or any consumer) wires in; this component owns only the picker
+ * interaction and its validation contract.
+ *
+ * The validation contract is deliberately the same shape as crm7's
+ * `EntitySelector`/`ClientSelector` (`crm7/src/components/entity/
+ * EntitySelector.tsx`, `.../selectors/ClientSelector.tsx`): the ONLY way to
+ * commit a value is to pick one of the options `search` returned — there is
+ * no code path that turns raw typed text into a committed value. Typed text
+ * that does not match the currently-committed option's label is refused on
+ * blur/Escape: the field reverts to the last committed value and
+ * `onInvalidEntry` fires instead of `onChange`. That refusal is exactly
+ * what stopped 7 contacts becoming free-text orphans in crm7 — a
+ * relationship field that skipped it would recreate the same problem this
+ * widget exists to fix.
+ *
+ * Controlled component: `value` is the FK currently persisted on the host
+ * record. `onChange` REQUESTS a write; the caller updates its own backing
+ * store and re-passes `value` once the write lands (optimistically or
+ * not) — this component never assumes its own write succeeded.
+ */
+export interface RelationshipFieldProps {
+    /** Currently selected FK value (the id written on the host record), or
+     * null/undefined when unset. */
+    value?: string | null;
+    /** The caller's tenant — forwarded to `search`/`resolveOption` on every
+     * call so the picker's data source is scoped to it by construction,
+     * never by convention (W4-1's tenant-scoping requirement). */
+    tenantId?: string | null;
+    label?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    /** Debounce, in ms, between the last keystroke and firing `search`. */
+    debounceMs?: number;
+    /**
+     * Search the target entity, scoped to `tenantId`. Consumers supply their
+     * own data source here (crm7's ClientSelector-equivalent query) — this
+     * package never talks to Supabase directly.
+     */
+    search: (query: string, tenantId: string | null | undefined) => Promise<RelationshipFieldOption[]>;
+    /**
+     * Resolve the option behind an already-set `value` (e.g. re-fetch by id)
+     * so the field can show its label without the caller pre-resolving it.
+     * Optional — omit if `initialOption` is supplied instead.
+     */
+    resolveOption?: (id: string, tenantId: string | null | undefined) => Promise<RelationshipFieldOption | null>;
+    /** Pre-resolved option for `value`, when the caller already has it. */
+    initialOption?: RelationshipFieldOption | null;
+    /**
+     * Called with the picked option — this is what writes the foreign key.
+     * Called with `null` only from the explicit clear action, never from an
+     * unresolved typed value.
+     */
+    onChange: (option: RelationshipFieldOption | null) => void | Promise<void>;
+    /**
+     * Called when the field is blurred/committed with typed text that does
+     * not match any resolved/committed option — the value is refused
+     * (reverted) and `onChange` is NOT called.
+     */
+    onInvalidEntry?: (query: string) => void;
+    emptyLabel?: string;
+    className?: string;
+    id?: string;
+    'aria-label'?: string;
+}
+export declare function RelationshipField({ value, tenantId, label, placeholder, disabled, debounceMs, search, resolveOption, initialOption, onChange, onInvalidEntry, emptyLabel, className, id, 'aria-label': ariaLabel, }: RelationshipFieldProps): React.JSX.Element;
+export default RelationshipField;
+//# sourceMappingURL=RelationshipField.d.ts.map

package/dist/RelationshipField.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RelationshipField.d.ts","sourceRoot":"","sources":["../src/RelationshipField.tsx"],"names":[],"mappings":"AACA,OAAO,KAA0D,MAAM,OAAO,CAAC;AAE/E,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,sBAAsB;IACrC;oCACgC;IAChC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;kEAE8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAAC;IACnG;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KAAK,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7G,uEAAuE;IACvE,aAAa,CAAC,EAAE,uBAAuB,GAAG,IAAI,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,uBAAuB,GAAG,IAAI,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3E;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,WAAuB,EACvB,QAAgB,EAChB,UAAgB,EAChB,MAAM,EACN,aAAa,EACb,aAAoB,EACpB,QAAQ,EACR,cAAc,EACd,UAAyB,EACzB,SAAS,EACT,EAAE,EACF,YAAY,EAAE,SAAS,GACxB,EAAE,sBAAsB,qBAwOxB;AAED,eAAe,iBAAiB,CAAC"}

package/dist/RelationshipField.js

@@ -0,0 +1,158 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { X } from 'lucide-react';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { cn } from './utils.js';
+export function RelationshipField({ value, tenantId, label, placeholder = 'Search…', disabled = false, debounceMs = 250, search, resolveOption, initialOption = null, onChange, onInvalidEntry, emptyLabel = 'No matches', className, id, 'aria-label': ariaLabel, }) {
+    const generatedId = useId();
+    const inputId = id ?? `relationship-field-${generatedId}`;
+    const listboxId = `${inputId}-listbox`;
+    const [selected, setSelected] = useState(initialOption);
+    const [query, setQuery] = useState(initialOption?.label ?? '');
+    const [options, setOptions] = useState([]);
+    const [isOpen, setIsOpen] = useState(false);
+    const [isLoading, setIsLoading] = useState(false);
+    const [highlightedIndex, setHighlightedIndex] = useState(-1);
+    const debounceRef = useRef(null);
+    const requestIdRef = useRef(0);
+    // Hydrate the label for an externally-set/changed `value` this instance
+    // has not resolved yet. Deliberately keyed on `value` alone — `selected`
+    // is set BY this same effect (and by `commitOption`/`clearSelection`), so
+    // including it would either no-op (already in sync) or fight the user's
+    // own selection; `resolveOption`/`tenantId` changing mid-session should
+    // not retrigger a resolve for a value that hasn't changed.
+    useEffect(() => {
+        if ((value ?? null) === (selected?.id ?? null))
+            return;
+        if (!value) {
+            setSelected(null);
+            setQuery('');
+            return;
+        }
+        if (!resolveOption)
+            return;
+        let cancelled = false;
+        resolveOption(value, tenantId)
+            .then((option) => {
+            if (cancelled || !option)
+                return;
+            setSelected(option);
+            setQuery(option.label);
+        })
+            .catch(() => {
+            /* leave the field as-is; caller's resolveOption owns error reporting */
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value]);
+    useEffect(() => () => {
+        if (debounceRef.current)
+            clearTimeout(debounceRef.current);
+    }, []);
+    const runSearch = useCallback((text) => {
+        const requestId = ++requestIdRef.current;
+        setIsLoading(true);
+        search(text, tenantId)
+            .then((results) => {
+            if (requestIdRef.current !== requestId)
+                return;
+            setOptions(results);
+        })
+            .catch(() => {
+            if (requestIdRef.current !== requestId)
+                return;
+            setOptions([]);
+        })
+            .finally(() => {
+            if (requestIdRef.current !== requestId)
+                return;
+            setIsLoading(false);
+        });
+    }, [search, tenantId]);
+    const handleInputChange = (event) => {
+        const text = event.target.value;
+        setQuery(text);
+        setIsOpen(true);
+        setHighlightedIndex(-1);
+        if (debounceRef.current)
+            clearTimeout(debounceRef.current);
+        debounceRef.current = setTimeout(() => runSearch(text), debounceMs);
+    };
+    const commitOption = (option) => {
+        setSelected(option);
+        setQuery(option.label);
+        setIsOpen(false);
+        setOptions([]);
+        setHighlightedIndex(-1);
+        void onChange(option);
+    };
+    const clearSelection = () => {
+        setSelected(null);
+        setQuery('');
+        setOptions([]);
+        setIsOpen(false);
+        void onChange(null);
+    };
+    // The refusal behaviour this component exists to provide (see the module
+    // doc): committing is ONLY ever done via `commitOption`, called from a
+    // listbox option pick. Reaching blur/Escape with typed text that does not
+    // exactly match the currently-committed option's label means the user
+    // typed something that never resolved to a real row — revert, and tell
+    // the caller via `onInvalidEntry` instead of writing anything.
+    const refuseUnresolvedTypedText = () => {
+        const trimmed = query.trim();
+        const matchesCommitted = selected ? trimmed === selected.label : trimmed.length === 0;
+        if (matchesCommitted)
+            return;
+        onInvalidEntry?.(trimmed);
+        setQuery(selected?.label ?? '');
+        setOptions([]);
+    };
+    const handleBlur = () => {
+        // A mousedown on a listbox option (see onMouseDown below) prevents the
+        // input from ever losing focus for that interaction, so `handleBlur`
+        // only ever runs for a genuine focus-away — commitOption has already
+        // run synchronously before this fires when the user picks an option.
+        setIsOpen(false);
+        refuseUnresolvedTypedText();
+    };
+    const handleKeyDown = (event) => {
+        if (event.key === 'ArrowDown') {
+            event.preventDefault();
+            if (!isOpen) {
+                setIsOpen(true);
+                if (options.length === 0)
+                    runSearch(query);
+                return;
+            }
+            setHighlightedIndex((index) => Math.min(index + 1, options.length - 1));
+        }
+        else if (event.key === 'ArrowUp') {
+            event.preventDefault();
+            setHighlightedIndex((index) => Math.max(index - 1, 0));
+        }
+        else if (event.key === 'Enter') {
+            if (isOpen && highlightedIndex >= 0 && options[highlightedIndex]) {
+                event.preventDefault();
+                commitOption(options[highlightedIndex]);
+            }
+        }
+        else if (event.key === 'Escape') {
+            if (isOpen) {
+                event.preventDefault();
+                setIsOpen(false);
+                setQuery(selected?.label ?? '');
+                setOptions([]);
+            }
+        }
+    };
+    return (_jsxs("div", { className: cn('relative w-full', className), children: [label && (_jsx("label", { htmlFor: inputId, className: "mb-1 block text-xs font-medium text-muted-foreground", children: label })), _jsxs("div", { className: "relative flex items-center gap-1", children: [_jsx("input", { id: inputId, role: "combobox", type: "text", "aria-expanded": isOpen, "aria-controls": listboxId, "aria-autocomplete": "list", "aria-activedescendant": isOpen && highlightedIndex >= 0 && options[highlightedIndex]
+                            ? `${listboxId}-option-${highlightedIndex}`
+                            : undefined, "aria-label": ariaLabel ?? label, className: "w-full rounded-md border border-border bg-background px-2 py-1.5 text-sm text-foreground disabled:opacity-60", value: query, placeholder: placeholder, disabled: disabled, autoComplete: "off", onChange: handleInputChange, onFocus: () => {
+                            setIsOpen(true);
+                            if (options.length === 0)
+                                runSearch(query);
+                        }, onBlur: handleBlur, onKeyDown: handleKeyDown }), selected && !disabled && (_jsx("button", { type: "button", "aria-label": "Clear selection", className: "shrink-0 rounded p-1 text-muted-foreground hover:bg-muted hover:text-foreground", onMouseDown: (event) => event.preventDefault(), onClick: clearSelection, children: _jsx(X, { className: "h-3.5 w-3.5", "aria-hidden": "true" }) }))] }), isOpen && (_jsx("ul", { id: listboxId, role: "listbox", className: "absolute z-50 mt-1 max-h-60 w-full overflow-auto rounded-md border border-border bg-popover shadow-md", children: isLoading ? (_jsx("li", { className: "px-3 py-2 text-sm text-muted-foreground", children: "Searching\u2026" })) : options.length === 0 ? (_jsx("li", { className: "px-3 py-2 text-sm text-muted-foreground", children: emptyLabel })) : (options.map((option, index) => (_jsxs("li", { id: `${listboxId}-option-${index}`, role: "option", "aria-selected": selected?.id === option.id, className: cn('cursor-pointer px-3 py-2 text-sm', index === highlightedIndex ? 'bg-accent text-accent-foreground' : 'text-foreground'), onMouseDown: (event) => event.preventDefault(), onClick: () => commitOption(option), onMouseEnter: () => setHighlightedIndex(index), children: [_jsx("div", { children: option.label }), option.secondaryLabel && (_jsx("div", { className: "text-xs text-muted-foreground", children: option.secondaryLabel }))] }, option.id)))) }))] }));
+}
+export default RelationshipField;