@bsuite/page-builder 0.6.2 → 0.7.0

package/dist/PageEditorLauncher.js

@@ -112,5 +112,5 @@ export function PageEditorLauncher({ pageId, tenantId, widgets, onAddWidget, onR
     // reference it here to avoid an unused-variable lint at the call site.
     void tenantId;
     const effectiveDefaultLayouts = defaultLayouts ?? { lg: [] };
-    return (_jsxs("div", { className: "relative isolate", children: [_jsx("div", { className: "sticky top-0 z-40 isolate flex flex-col gap-3 rounded-xl shadow-lg border-2 mb-4 p-4 bg-card/95 supports-[backdrop-filter]:bg-card/80 backdrop-blur border-primary", role: "region", "aria-label": "Page editor toolbar", children: _jsxs("div", { className: "flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("div", { className: "rounded-full flex items-center justify-center bg-primary/10 h-10 w-10 animate-pulse", children: _jsx(LayoutGrid, { className: "h-5 w-5 text-primary" }) }), _jsxs("div", { children: [_jsx("h3", { className: "font-semibold text-foreground text-lg", children: "Page Editor" }), _jsx("span", { className: "text-sm text-muted-foreground", children: "Drag cards to rearrange. Resize with the bottom-right handle." })] })] }), _jsxs("div", { className: "flex items-center gap-2 shrink-0", children: [_jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded-md border border-border px-3 py-2 text-sm font-medium transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", onClick: () => setPaletteOpen(true), children: [_jsx(Plus, { className: "h-4 w-4" }), "Add Widget"] }), _jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded-md border border-border px-3 py-2 text-sm font-medium transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", onClick: handleCancel, children: [_jsx(X, { className: "h-4 w-4" }), "Cancel"] }), _jsxs("button", { type: "button", className: "inline-flex items-center rounded-md px-3 py-2 text-sm font-medium bg-primary text-primary-foreground shadow transition-colors hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", onClick: handleSave, children: [_jsx(Save, { className: "h-4 w-4 mr-2" }), "Save"] })] })] }) }), _jsx(PageGridLayout, { pageKey: pageId, defaultLayouts: effectiveDefaultLayouts, canEditPage: true, preferenceAdapter: capturedAdapter, widgets: gridWidgets, widgetMeta: gridWidgetMeta }), paletteOpen && (_jsxs("div", { className: "fixed inset-0 z-50 flex", children: [_jsx("div", { className: "absolute inset-0 bg-black/40", onClick: () => setPaletteOpen(false), "aria-hidden": "true" }), _jsxs("div", { className: "relative ml-auto h-full w-80 max-w-[85vw] flex flex-col bg-card border-l border-border shadow-xl", children: [_jsxs("div", { className: "flex items-center justify-between px-4 pt-4 pb-3 border-b", children: [_jsx("h2", { className: "text-base font-semibold", children: "Add Widget" }), _jsx("button", { type: "button", className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", onClick: () => setPaletteOpen(false), "aria-label": "Close widget palette", children: _jsx(X, { className: "h-4 w-4" }) })] }), _jsxs("div", { className: "flex-1 overflow-y-auto px-4 py-4 space-y-4", children: [widgets.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground text-center py-8", children: "No widgets available. Add widgets via your app's widget catalogue." })) : (_jsxs("div", { className: "space-y-2", children: [_jsx("p", { className: "text-xs font-semibold uppercase tracking-wider text-muted-foreground px-1", children: "Available Widgets" }), widgets.map((w) => (_jsxs("div", { className: "flex items-center justify-between rounded-md border bg-card p-3 hover:bg-accent/50 transition-colors", children: [_jsx("span", { className: "text-sm font-medium truncate", children: w.meta?.label ?? w.key }), _jsx("button", { type: "button", className: "ml-2 shrink-0 inline-flex items-center rounded-md px-2 py-1 text-xs font-medium bg-secondary text-secondary-foreground transition-colors hover:bg-secondary/80", onClick: () => handlePaletteAdd(w.key), children: "Add" })] }, w.key)))] })), _jsxs("div", { className: "border-t border-border pt-4 space-y-2", children: [_jsx("p", { className: "text-xs font-semibold uppercase tracking-wider text-muted-foreground px-1", children: "Remove Widget" }), widgets.length === 0 ? (_jsx("p", { className: "text-xs text-muted-foreground px-1", children: "No widgets on the canvas to remove." })) : (widgets.map((w) => (_jsxs("div", { className: "flex items-center justify-between rounded-md border bg-card p-3", children: [_jsx("span", { className: "text-sm font-medium truncate", children: w.meta?.label ?? w.key }), _jsx("button", { type: "button", className: "ml-2 shrink-0 inline-flex items-center rounded-md px-2 py-1 text-xs font-medium bg-destructive/10 text-destructive transition-colors hover:bg-destructive/20", onClick: () => onRemoveWidget(w.key), children: "Remove" })] }, `remove-${w.key}`))))] })] })] })] }))] }));
+    return (_jsxs("div", { className: "relative isolate", children: [_jsx("div", { className: "sticky top-0 z-40 isolate flex flex-col gap-3 rounded-xl shadow-lg border-2 mb-4 p-4 bg-card/95 supports-[backdrop-filter]:bg-card/80 backdrop-blur border-primary", role: "region", "aria-label": "Page editor toolbar", children: _jsxs("div", { className: "flex flex-col sm:flex-row items-start sm:items-center justify-between gap-3", children: [_jsxs("div", { className: "flex items-center gap-3", children: [_jsx("div", { className: "rounded-full flex items-center justify-center bg-primary/10 h-10 w-10 animate-pulse", children: _jsx(LayoutGrid, { className: "h-5 w-5 text-primary" }) }), _jsxs("div", { children: [_jsx("h3", { className: "font-semibold text-foreground text-lg", children: "Page Editor" }), _jsx("span", { className: "text-sm text-muted-foreground", children: "Drag cards to rearrange. Resize with the bottom-right handle." })] })] }), _jsxs("div", { className: "flex items-center gap-2 shrink-0", children: [_jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded-md border border-border px-3 py-2 text-sm font-medium transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", onClick: () => setPaletteOpen(true), children: [_jsx(Plus, { className: "h-4 w-4" }), "Add Widget"] }), _jsxs("button", { type: "button", className: "inline-flex items-center gap-1 rounded-md border border-border px-3 py-2 text-sm font-medium transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", onClick: handleCancel, children: [_jsx(X, { className: "h-4 w-4" }), "Cancel"] }), _jsxs("button", { type: "button", className: "inline-flex items-center rounded-md px-3 py-2 text-sm font-medium bg-primary text-primary-foreground shadow transition-colors hover:bg-primary/90 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1", onClick: handleSave, children: [_jsx(Save, { className: "h-4 w-4 mr-2" }), "Save"] })] })] }) }), _jsx(PageGridLayout, { pageKey: pageId, defaultLayouts: effectiveDefaultLayouts, canEditPage: true, preferenceAdapter: capturedAdapter, widgets: gridWidgets, widgetMeta: gridWidgetMeta }), paletteOpen && (_jsxs("div", { className: "fixed inset-0 z-50 flex", children: [_jsx("div", { className: "absolute inset-0 bg-overlay/50", onClick: () => setPaletteOpen(false), "aria-hidden": "true" }), _jsxs("div", { className: "relative ml-auto h-full w-80 max-w-[85vw] flex flex-col bg-card border-l border-border shadow-xl", children: [_jsxs("div", { className: "flex items-center justify-between px-4 pt-4 pb-3 border-b", children: [_jsx("h2", { className: "text-base font-semibold", children: "Add Widget" }), _jsx("button", { type: "button", className: "rounded p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground", onClick: () => setPaletteOpen(false), "aria-label": "Close widget palette", children: _jsx(X, { className: "h-4 w-4" }) })] }), _jsxs("div", { className: "flex-1 overflow-y-auto px-4 py-4 space-y-4", children: [widgets.length === 0 ? (_jsx("p", { className: "text-sm text-muted-foreground text-center py-8", children: "No widgets available. Add widgets via your app's widget catalogue." })) : (_jsxs("div", { className: "space-y-2", children: [_jsx("p", { className: "text-xs font-semibold uppercase tracking-wider text-muted-foreground px-1", children: "Available Widgets" }), widgets.map((w) => (_jsxs("div", { className: "flex items-center justify-between rounded-md border bg-card p-3 hover:bg-accent/50 transition-colors", children: [_jsx("span", { className: "text-sm font-medium truncate", children: w.meta?.label ?? w.key }), _jsx("button", { type: "button", className: "ml-2 shrink-0 inline-flex items-center rounded-md px-2 py-1 text-xs font-medium bg-secondary text-secondary-foreground transition-colors hover:bg-secondary/80", onClick: () => handlePaletteAdd(w.key), children: "Add" })] }, w.key)))] })), _jsxs("div", { className: "border-t border-border pt-4 space-y-2", children: [_jsx("p", { className: "text-xs font-semibold uppercase tracking-wider text-muted-foreground px-1", children: "Remove Widget" }), widgets.length === 0 ? (_jsx("p", { className: "text-xs text-muted-foreground px-1", children: "No widgets on the canvas to remove." })) : (widgets.map((w) => (_jsxs("div", { className: "flex items-center justify-between rounded-md border bg-card p-3", children: [_jsx("span", { className: "text-sm font-medium truncate", children: w.meta?.label ?? w.key }), _jsx("button", { type: "button", className: "ml-2 shrink-0 inline-flex items-center rounded-md px-2 py-1 text-xs font-medium bg-destructive/10 text-destructive transition-colors hover:bg-destructive/20", onClick: () => onRemoveWidget(w.key), children: "Remove" })] }, `remove-${w.key}`))))] })] })] })] }))] }));
 }

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, 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,KAA6E,MAAM,OAAO,CAAC;AAGlG,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAMxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AAmR7F,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,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAowBrB"}

package/dist/PageGridLayout.js

@@ -7,6 +7,7 @@ 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.
  *
@@ -142,7 +152,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     // (buttons, inputs, textarea, select, links, [data-no-drag]) are still
     // protected via the `cancel` selector below in the <Responsive> render.
     const outerClass = cn('relative group overflow-visible', isEditing && 'drag-handle cursor-move', injectedClassName);
-    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) => {
+    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-primary/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-destructive-foreground 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 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] }));
@@ -153,7 +163,7 @@ 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, }) {
+isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, tenantId, 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, handleCompact, handleReset, addWidget, moveWidget, setWidgetLocked, applyAutoHeightRows, autoHeightRows, resetConfirmOpen, setResetConfirmOpen, containerRef, containerWidth, } = usePageGridLayout({
         pageKey,
         defaultLayouts,
@@ -220,6 +230,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 +243,35 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
                 entityType: config.entityType,
                 label: config.label,
                 isEditing,
+                tenantId,
+            });
+        }
+        return rendered;
+    }, [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;
-    }, [createEntityWidget, extraWidgetConfigs, isEditing]);
-    const allWidgets = useMemo(() => ({ ...widgets, ...extraWidgets }), [widgets, extraWidgets]);
+    }, [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: [] };
@@ -363,6 +398,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) => {
@@ -476,10 +562,10 @@ isResizable = true, resizeHandles = DEFAULT_RESIZE_HANDLES, addEntityWidgetEvent
                                             const meta = widgetMeta?.[key];
                                             const Icon = meta?.icon;
                                             return (_jsxs("button", { type: "button", onClick: () => showLayer(key, meta?.defaultSize), className: cn('flex items-center gap-1 px-2 py-0.5 rounded text-xs font-medium border transition-colors', 'bg-muted text-muted-foreground border-border', 'hover:bg-muted/80 hover:text-foreground hover:border-primary/60', 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1'), children: [_jsx(Plus, { className: "h-3 w-3" }), Icon && _jsx(Icon, { className: "h-3 w-3" }), layerNames[key] || meta?.label || key] }, key));
-                                        }) })] })), 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: () => {
+                                        }) })] })), 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-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: {
+                                    }, 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: {
                             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;

package/dist/index.d.ts

@@ -11,5 +11,8 @@ export type { WysiwygPrimitive, WysiwygSurfaceContract, WysiwygSurfaceId, } from
 export { buildResponsiveLayouts, RESPONSIVE_BREAKPOINTS, } from './buildResponsiveLayouts.js';
 export type { BuildResponsiveLayoutsOptions, ResponsiveBreakpoint, } from './buildResponsiveLayouts.js';
 export { useLocalPreference, defaultPreferenceAdapter } from './preferences.js';
-export type { EntityWidgetDetail, EntityWidgetFactoryOptions, GridLayoutItem, GridLayouts, PageGridLayoutProps, PageGridPreferenceAdapter, PageGridPreferenceFactory, UsePageGridLayoutOptions, UsePageGridLayoutResult, WidgetMeta, } from './types.js';
+export { RelationshipField } from './RelationshipField.js';
+export type { RelationshipFieldProps } from './RelationshipField.js';
+export { isRelationshipWritable } from './relationshipCatalog.js';
+export type { EntityWidgetDetail, EntityWidgetFactoryOptions, GridLayoutItem, GridLayouts, PageGridLayoutProps, PageGridPreferenceAdapter, PageGridPreferenceFactory, RelationshipCatalog, RelationshipCatalogEntry, RelationshipFieldOption, RelationshipWidgetDetail, RelationshipWidgetFactoryOptions, UsePageGridLayoutOptions, UsePageGridLayoutResult, WidgetMeta, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACrF,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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACrF,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,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,wBAAwB,EACxB,gCAAgC,EAChC,wBAAwB,EACxB,uBAAuB,EACvB,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -6,3 +6,5 @@ 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';
+export { RelationshipField } from './RelationshipField.js';
+export { isRelationshipWritable } from './relationshipCatalog.js';

package/dist/relationshipCatalog.d.ts

@@ -0,0 +1,22 @@
+import type { RelationshipCatalog, RelationshipWidgetDetail } from './types.js';
+/**
+ * True only when `detail` names a relationship literally present in
+ * `catalog` — the W4-2 gate ("a relationship field may only be offered
+ * where the host record genuinely has a foreign key to write").
+ *
+ * `catalog` is undefined/empty-safe by design: no catalogue means nothing
+ * has been proven writable, so every relationship is refused (fail closed)
+ * rather than silently offering a picker that cannot save. This is the only
+ * place that decision is made — `PageGridLayout`'s add-relationship-widget
+ * handler calls this before ever creating a widget, and it is exported so
+ * consumers (e.g. a canvas "add element" palette deciding what to list) can
+ * apply the identical rule ahead of dispatching the event.
+ *
+ * `@bsuite/page-builder` never infers writability itself — it has no notion
+ * of a database. Consumers build `catalog` from a live schema source (in
+ * crm7, `report_catalog_joins` filtered to `cardinality = 'many_to_one'`
+ * and `is_active = true`, cross-checked against `pg_constraint` — see the
+ * Wave 4 implementation PR for the verification query and evidence).
+ */
+export declare function isRelationshipWritable(catalog: RelationshipCatalog | undefined, detail: Pick<RelationshipWidgetDetail, 'hostEntityType' | 'fkColumn' | 'targetEntityType'>): boolean;
+//# sourceMappingURL=relationshipCatalog.d.ts.map

package/dist/relationshipCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationshipCatalog.d.ts","sourceRoot":"","sources":["../src/relationshipCatalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAEhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,mBAAmB,GAAG,SAAS,EACxC,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,gBAAgB,GAAG,UAAU,GAAG,kBAAkB,CAAC,GACzF,OAAO,CAQT"}

package/dist/relationshipCatalog.js

@@ -0,0 +1,26 @@
+/**
+ * True only when `detail` names a relationship literally present in
+ * `catalog` — the W4-2 gate ("a relationship field may only be offered
+ * where the host record genuinely has a foreign key to write").
+ *
+ * `catalog` is undefined/empty-safe by design: no catalogue means nothing
+ * has been proven writable, so every relationship is refused (fail closed)
+ * rather than silently offering a picker that cannot save. This is the only
+ * place that decision is made — `PageGridLayout`'s add-relationship-widget
+ * handler calls this before ever creating a widget, and it is exported so
+ * consumers (e.g. a canvas "add element" palette deciding what to list) can
+ * apply the identical rule ahead of dispatching the event.
+ *
+ * `@bsuite/page-builder` never infers writability itself — it has no notion
+ * of a database. Consumers build `catalog` from a live schema source (in
+ * crm7, `report_catalog_joins` filtered to `cardinality = 'many_to_one'`
+ * and `is_active = true`, cross-checked against `pg_constraint` — see the
+ * Wave 4 implementation PR for the verification query and evidence).
+ */
+export function isRelationshipWritable(catalog, detail) {
+    if (!catalog || catalog.length === 0)
+        return false;
+    return catalog.some((entry) => entry.hostEntityType === detail.hostEntityType &&
+        entry.fkColumn === detail.fkColumn &&
+        entry.targetEntityType === detail.targetEntityType);
+}

package/dist/types.d.ts

@@ -54,18 +54,104 @@ export interface EntityWidgetDetail {
 export interface EntityWidgetFactoryOptions extends EntityWidgetDetail {
     widgetId: string;
     isEditing: boolean;
+    /**
+     * The caller's tenant (Wave 4 / W4-3 — see {@link PageGridLayoutProps.tenantId}).
+     * Threaded through so the entity-list widget is scoped to the caller's
+     * tenant by default instead of each consumer inventing (or forgetting)
+     * its own plumbing — a platform developer and an ordinary tenant user
+     * previously saw identical `entityType`/`label` from this callback with
+     * no way to tell whose rows they were about to render.
+     */
+    tenantId?: string | null;
+}
+/**
+ * A single option a {@link RelationshipField} can offer — the row a user
+ * picks to write as the foreign key value. `id` is what gets written;
+ * `label` (and optional `secondaryLabel`) is what gets displayed.
+ */
+export interface RelationshipFieldOption {
+    id: string;
+    label: string;
+    secondaryLabel?: string;
+}
+/**
+ * Detail carried by the `crm7-add-relationship-widget` / `bsu-add-relationship-widget`
+ * events — mirrors {@link EntityWidgetDetail} for the entity-list kind.
+ * Unlike a list (which only needs an entity type to render a table), a
+ * relationship field writes a single foreign key, so it must name BOTH
+ * sides: the host record's entity type and FK column, and the entity type
+ * the FK targets.
+ */
+export interface RelationshipWidgetDetail {
+    /** Entity type of the record being edited — the host row the FK lives on. */
+    hostEntityType: string;
+    /** FK column on the host record this widget writes when a value is picked. */
+    fkColumn: string;
+    /** Entity type the FK points at — drives the typeahead's search. */
+    targetEntityType: string;
+    label?: string;
+}
+export interface RelationshipWidgetFactoryOptions extends RelationshipWidgetDetail {
+    widgetId: string;
+    isEditing: boolean;
+    /** The caller's tenant — see {@link PageGridLayoutProps.tenantId}. */
+    tenantId?: string | null;
 }
+/**
+ * One entry in the relationship catalogue: proof that a host entity's FK
+ * column genuinely points at a target entity, and is therefore safe to
+ * offer as a relationship field. Consumers build this array from a live
+ * schema source — in crm7, the `report_catalog_joins` table, filtered to
+ * `cardinality = 'many_to_one'` and `is_active = true` — never from
+ * inference. `@bsuite/page-builder` itself has no notion of a database and
+ * cannot verify writability on its own; see {@link isRelationshipWritable}.
+ */
+export interface RelationshipCatalogEntry {
+    hostEntityType: string;
+    fkColumn: string;
+    targetEntityType: string;
+}
+export type RelationshipCatalog = readonly RelationshipCatalogEntry[];
 export interface PageGridLayoutProps extends UsePageGridLayoutOptions {
     widgets: Record<string, React.ReactNode>;
     widgetMeta?: Record<string, WidgetMeta>;
     className?: string;
     isResizable?: boolean;
     resizeHandles?: readonly ResizeHandleAxis[];
+    /**
+     * The signed-in caller's tenant. Threaded into every widget-factory call
+     * (`createEntityWidget`, `createRelationshipWidget`) as `tenantId` so
+     * both widget kinds are scoped to the caller's tenant BY DEFAULT — the
+     * shared layer hands the scope down explicitly rather than leaving each
+     * consumer to invent (or omit) its own plumbing (W4-3).
+     */
+    tenantId?: string | null;
     addEntityWidgetEventNames?: readonly string[];
     createEntityWidget?: (options: EntityWidgetFactoryOptions) => React.ReactNode;
     onRegisterEntityWidget?: (options: EntityWidgetDetail & {
         widgetId: string;
     }) => void;
+    /**
+     * Schema facts describing which relationships are actually writable
+     * (W4-2). A relationship field is only ever added when its
+     * `{hostEntityType, fkColumn, targetEntityType}` triple appears here —
+     * consumers build this from a live catalogue, never from inference.
+     * Omitting this prop refuses every relationship field (fail closed): no
+     * catalogue means nothing has been proven writable.
+     */
+    relationshipCatalog?: RelationshipCatalog;
+    addRelationshipWidgetEventNames?: readonly string[];
+    createRelationshipWidget?: (options: RelationshipWidgetFactoryOptions) => React.ReactNode;
+    onRegisterRelationshipWidget?: (options: RelationshipWidgetDetail & {
+        widgetId: string;
+    }) => void;
+    /**
+     * Called when an `add-relationship-widget` event names a relationship
+     * that is not present in `relationshipCatalog` — the widget is refused;
+     * this is the hook for surfacing why (e.g. a toast) without
+     * `@bsuite/page-builder` owning any UI copy.
+     */
+    onRelationshipWidgetRejected?: (detail: RelationshipWidgetDetail) => void;
 }
 export interface UsePageGridLayoutResult {
     currentLayouts: GridLayouts;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -32,7 +32,7 @@
     "prepublishOnly": "pnpm build"
   },
   "peerDependencies": {
-    "@bsuite/theme": ">=0.5.0",
+    "@bsuite/theme": ">=0.7.1",
     "@dnd-kit/core": "^6",
     "@dnd-kit/sortable": "^10",
     "@dnd-kit/utilities": "^3",

package/src/styles/react-grid-layout-overrides.css

@@ -72,8 +72,14 @@
   bottom: 3px;
   width: 6px;
   height: 6px;
-  border-right: 2px solid var(--text-secondary, oklch(0 0 0 / 0.45));
-  border-bottom: 2px solid var(--text-secondary, oklch(0 0 0 / 0.45));
+  /* --text-secondary is NOT a token this design system defines — the name is
+     --role-text-secondary. So the fallback was not a fallback, it was the
+     value: every resize handle rendered at pure black 45%, which on a dark
+     surface is very nearly invisible. Named correctly, and the fallback
+     dropped rather than corrected — a fallback here can only ever mask the
+     same mistake again. */
+  border-right: 2px solid var(--role-text-secondary);
+  border-bottom: 2px solid var(--role-text-secondary);
 }
 
 /* Highlight the marker when hovering the handle itself. */