@bsuite/page-builder 2.5.0 → 2.6.0

package/dist/CustomPageView.d.ts

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+/** The subset of a `custom_pages` row this component needs. Apps may pass more. */
+export interface CustomPageLike {
+    title: string;
+    description?: string | null;
+    layout?: unknown;
+}
+/**
+ * A stored layout. Deliberately structural and permissive: this package does not
+ * own the field vocabulary, and a layout carrying keys it does not recognise must
+ * render what it can rather than throw.
+ */
+export interface StoredLayoutSection {
+    id?: string;
+    title?: string;
+    description?: string | null;
+    columns?: number;
+    fields?: Array<{
+        fieldKey?: string;
+        label?: string;
+        [k: string]: unknown;
+    }>;
+}
+export interface StoredLayout {
+    sections?: StoredLayoutSection[];
+    tabs?: Array<{
+        id?: string;
+        title?: string;
+        sections?: StoredLayoutSection[];
+    }>;
+}
+export interface CustomPageViewProps {
+    /** The already-fetched row. `null` means resolved-and-absent; `undefined` means not yet known. */
+    page: CustomPageLike | null | undefined;
+    isLoading?: boolean;
+    error?: {
+        message: string;
+    } | null;
+    /**
+     * What to do when the page resolves to nothing.
+     *
+     * `silent` (the default) is for an EMBEDDED mount that sits beside a static
+     * layout: a miss must render nothing rather than an error card in the middle of
+     * a working page.
+     *
+     * `message` is for a route where the custom page IS the whole page. Silence
+     * there is a blank screen, which reads as broken.
+     */
+    onMissing?: 'silent' | 'message';
+    /** The per-app widget catalogue. Omit it and the structural default is used. */
+    renderLayout?: (layout: StoredLayout, page: CustomPageLike) => ReactNode;
+    renderLoading?: () => ReactNode;
+    renderError?: (message: string) => ReactNode;
+    renderEmpty?: () => ReactNode;
+    className?: string;
+}
+/** A layout with no sections and no tabs has nothing to draw. */
+export declare function layoutIsEmpty(layout: unknown): boolean;
+/** Every section in a layout, whether it sits at the top level or inside a tab. */
+export declare function flattenSections(layout: StoredLayout): StoredLayoutSection[];
+/**
+ * The readable default. NOT a widget catalogue and not pretending to be one — it
+ * renders the SHAPE a page was given, so an app without its own catalogue shows
+ * something a person can read instead of `JSON.stringify`.
+ */
+export declare function renderStructuredLayout(layout: StoredLayout): ReactNode;
+export declare function CustomPageView({ page, isLoading, error, onMissing, renderLayout, renderLoading, renderError, renderEmpty, className, }: CustomPageViewProps): import("react").JSX.Element | null;
+//# sourceMappingURL=CustomPageView.d.ts.map

package/dist/CustomPageView.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CustomPageView.d.ts","sourceRoot":"","sources":["../src/CustomPageView.tsx"],"names":[],"mappings":"AAyCA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAC;CAC7E;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACjC,IAAI,CAAC,EAAE,KAAK,CAAC;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,mBAAmB,EAAE,CAAA;KAAE,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,mBAAmB;IAClC,kGAAkG;IAClG,IAAI,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,CAAC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACnC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;IACjC,gFAAgF;IAChF,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,cAAc,KAAK,SAAS,CAAC;IACzE,aAAa,CAAC,EAAE,MAAM,SAAS,CAAC;IAChC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,CAAC;IAC7C,WAAW,CAAC,EAAE,MAAM,SAAS,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAOtD;AAED,mFAAmF;AACnF,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,mBAAmB,EAAE,CAM3E;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAwCtE;AAED,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,SAAiB,EACjB,KAAY,EACZ,SAAoB,EACpB,YAAY,EACZ,aAAa,EACb,WAAW,EACX,WAAW,EACX,SAAS,GACV,EAAE,mBAAmB,sCAyDrB"}

package/dist/CustomPageView.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/** A layout with no sections and no tabs has nothing to draw. */
+export function layoutIsEmpty(layout) {
+    if (!layout || typeof layout !== 'object')
+        return true;
+    const l = layout;
+    const sections = Array.isArray(l.sections) ? l.sections : [];
+    const tabs = Array.isArray(l.tabs) ? l.tabs : [];
+    if (tabs.length > 0)
+        return false;
+    return sections.length === 0;
+}
+/** Every section in a layout, whether it sits at the top level or inside a tab. */
+export function flattenSections(layout) {
+    const out = Array.isArray(layout.sections) ? [...layout.sections] : [];
+    for (const tab of Array.isArray(layout.tabs) ? layout.tabs : []) {
+        for (const s of Array.isArray(tab.sections) ? tab.sections : [])
+            out.push(s);
+    }
+    return out;
+}
+/** Turn `given_name` into `Given name` when a field carries no explicit label. */
+function humanise(key) {
+    const spaced = key.replace(/[_-]+/g, ' ').trim();
+    if (spaced.length === 0)
+        return key;
+    return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+/**
+ * The readable default. NOT a widget catalogue and not pretending to be one — it
+ * renders the SHAPE a page was given, so an app without its own catalogue shows
+ * something a person can read instead of `JSON.stringify`.
+ */
+export function renderStructuredLayout(layout) {
+    const sections = flattenSections(layout);
+    return (_jsx("div", { className: "space-y-6", children: sections.map((section, si) => {
+            const fields = Array.isArray(section.fields) ? section.fields : [];
+            return (_jsxs("section", { className: "space-y-2", children: [section.title ? (_jsx("h2", { className: "text-sm font-semibold tracking-tight text-foreground", children: section.title })) : null, section.description ? (_jsx("p", { className: "text-sm text-muted-foreground", children: section.description })) : null, fields.length > 0 ? (_jsx("dl", { className: "grid gap-x-6 gap-y-2 sm:grid-cols-2", children: fields.map((field, fi) => {
+                            const key = typeof field.fieldKey === 'string' ? field.fieldKey : `field-${fi}`;
+                            const label = typeof field.label === 'string' && field.label.length > 0
+                                ? field.label
+                                : humanise(key);
+                            return (_jsxs("div", { className: "min-w-0", children: [_jsx("dt", { className: "truncate text-xs text-muted-foreground", children: label }), _jsx("dd", { className: "truncate text-sm text-foreground", children: "\u2014" })] }, key));
+                        }) })) : (_jsx("p", { className: "text-sm text-muted-foreground", children: "No fields in this section." }))] }, section.id ?? `section-${si}`));
+        }) }));
+}
+export function CustomPageView({ page, isLoading = false, error = null, onMissing = 'silent', renderLayout, renderLoading, renderError, renderEmpty, className, }) {
+    if (isLoading) {
+        if (renderLoading)
+            return _jsx(_Fragment, { children: renderLoading() });
+        // Silence while loading is right for an embedded mount: a spinner in the
+        // middle of a page that has already drawn reads as the page being broken.
+        return onMissing === 'message' ? (_jsx("div", { className: "flex items-center justify-center py-16 text-sm text-muted-foreground", children: "Loading\u2026" })) : null;
+    }
+    if (error) {
+        if (onMissing !== 'message')
+            return null;
+        if (renderError)
+            return _jsx(_Fragment, { children: renderError(error.message) });
+        return (_jsxs("div", { className: "mx-auto max-w-lg rounded-lg border border-destructive/40 p-4", children: [_jsx("p", { className: "text-sm font-medium text-destructive", children: "This page could not be loaded." }), _jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: error.message })] }));
+    }
+    if (!page) {
+        if (onMissing !== 'message')
+            return null;
+        return (_jsx("div", { className: "mx-auto max-w-lg rounded-lg border border-dashed p-6 text-center", children: _jsx("p", { className: "text-sm font-medium", children: "Page not found" }) }));
+    }
+    const layout = (page.layout ?? {});
+    const empty = layoutIsEmpty(layout);
+    return (_jsxs("section", { className: className ?? 'space-y-4', children: [_jsxs("header", { children: [_jsx("h1", { className: "text-2xl font-bold tracking-tight", children: page.title }), page.description ? (_jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: page.description })) : null] }), empty
+                ? renderEmpty
+                    ? renderEmpty()
+                    : (_jsx("div", { className: "rounded-lg border-2 border-dashed py-12 text-center text-muted-foreground", children: _jsx("p", { className: "text-sm", children: "This page has no layout configured yet." }) }))
+                : renderLayout
+                    ? renderLayout(layout, page)
+                    : renderStructuredLayout(layout)] }));
+}

package/dist/PageGridLayout.d.ts.map

@@ -1 +1 @@
-{"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;AAsBxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AA4kB7F,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,EAKjB,UAAkB,EAClB,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAq+BrB"}
+{"version":3,"file":"PageGridLayout.d.ts","sourceRoot":"","sources":["../src/PageGridLayout.tsx"],"names":[],"mappings":"AAEA,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf,OAAO,kCAAkC,CAAC;AAC1C,OAAO,gCAAgC,CAAC;AAsBxC,OAAO,KAAK,EAAe,mBAAmB,EAA4B,MAAM,YAAY,CAAC;AAmmB7F,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,EAKjB,UAAkB,EAClB,yBAAiE,EACjE,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,+BAA6E,EAC7E,wBAAwB,EACxB,4BAA4B,EAC5B,4BAA4B,GAC7B,EAAE,mBAAmB,qBAs+BrB"}

package/dist/PageGridLayout.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ElementScopeProvider } from './elementScope.js';
 import { ArrowDown, ArrowUp, ChevronDown, ChevronUp, Eye, EyeOff, Layers, LayoutGrid, Lock, Plus, RotateCcw, Save, Settings2, Unlock } from 'lucide-react';
 import React, { startTransition, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, } from 'react';
 import { Responsive } from 'react-grid-layout';
@@ -140,7 +141,7 @@ function warnOnceAboutCollapsedContent(el) {
         + '(an aspect ratio, a px/rem height, or min-height), or pass autoHeight={false} on '
         + 'this card so it renders into the constrained scrollable wrapper instead.');
 }
-const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, isEditing, label, onHide, autoHeight, onAutoHeightChange, chrome = false, cardStyleVars, children: injectedChildren, className: injectedClassName, style: injectedStyle, ...rest }, ref) {
+const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, isEditing, label, pageKey, onHide, autoHeight, onAutoHeightChange, chrome = false, cardStyleVars, children: injectedChildren, className: injectedClassName, style: injectedStyle, ...rest }, ref) {
     // Auto-height measurement (blueprint amendment A1). `measureRef` wraps
     // `content` with NO height constraint of its own — its parent has
     // `overflow-hidden` + `flex-1 min-h-0` (clips *painting* to the current
@@ -150,6 +151,16 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
     // intrinsic size, independent of however many rows the item currently
     // occupies — the property that makes the auto-height loop converge to
     // a fixed point instead of oscillating (see autoHeight.ts).
+    /*
+     * The card's identity, handed down so anything inside it can be addressed.
+     *
+     * A Context.Provider renders NO DOM NODE, so this cannot affect the
+     * ResizeObserver measurement below — which matters, because a trailing
+     * margin once collapsed THROUGH the autoHeight measure wrapper and cost 32px
+     * of card overflow across 70 sites. An extra element here would have been a
+     * real risk; a provider is not one.
+     */
+    const scopedContent = (_jsx(ElementScopeProvider, { scope: { pageKey, cardKey: id, cardLabel: label, isEditing }, children: content }));
     const measureRef = useRef(null);
     const lastReportedRowsRef = useRef(null);
     const measureRafRef = useRef(null);
@@ -335,7 +346,7 @@ const GridItem = React.memo(React.forwardRef(function GridItem({ id, content, is
                             ...(cardStyleVars && '--card-padding' in cardStyleVars
                                 ? { padding: cardStyleVars['--card-padding'] }
                                 : null),
-                        }, children: _jsx("div", { className: cn('min-h-0', autoHeight ? 'flex-none overflow-visible' : 'flex-1 overflow-auto'), children: autoHeight ? (_jsx("div", { ref: measureRef, className: "flow-root", children: content })) : (content) }) })] }), injectedChildren] }));
+                        }, children: _jsx("div", { className: cn('min-h-0', autoHeight ? 'flex-none overflow-visible' : 'flex-1 overflow-auto'), children: autoHeight ? (_jsx("div", { ref: measureRef, className: "flow-root", children: scopedContent })) : (scopedContent) }) })] }), injectedChildren] }));
 }));
 export function PageGridLayout({ pageKey, defaultLayouts, defaultCols, layoutVersion, canEditPage, editorEventNames, preferenceAdapter, widgets, widgetMeta, className, 
 // Resize default flipped 2026-05-12: rgl v2 dropped auto-handle rendering
@@ -832,6 +843,6 @@ itemChrome = false, addEntityWidgetEventNames = DEFAULT_ADD_ENTITY_WIDGET_EVENT_
                             const content = allWidgets[layoutItem.i];
                             if (content === undefined || content === null)
                                 return null;
-                            return (_jsx(GridItem, { id: layoutItem.i, content: content, isEditing: isEditing, label: layerNames[layoutItem.i] || widgetMeta?.[layoutItem.i]?.label || layoutItem.i, onHide: hideLayer, autoHeight: layoutItem.autoHeight, onAutoHeightChange: handleAutoHeightChange, chrome: layoutItem.chrome ?? itemChrome, cardStyleVars: cardStyleVars }, layoutItem.i));
+                            return (_jsx(GridItem, { id: layoutItem.i, content: content, isEditing: isEditing, label: layerNames[layoutItem.i] || widgetMeta?.[layoutItem.i]?.label || layoutItem.i, pageKey: pageKey, onHide: hideLayer, autoHeight: layoutItem.autoHeight, onAutoHeightChange: handleAutoHeightChange, chrome: layoutItem.chrome ?? itemChrome, cardStyleVars: cardStyleVars }, layoutItem.i));
                         }) }) }) })] }));
 }

package/dist/elementScope.d.ts

@@ -0,0 +1,83 @@
+import * as React from 'react';
+/**
+ * EVERY ELEMENT NEEDS A NAME BEFORE ANYTHING CAN STYLE IT.
+ *
+ * The operator's complaint: "I'm sick of seeing buttons that go the full width of
+ * cards and not being able to modify it visually." Measured 2026-09-02: 270
+ * full-width buttons, 236 of them on pages he can already rearrange — so the
+ * mouse obeys him on a card's outside edge and ignores him on its inside.
+ *
+ * The blocker is not styling. It is IDENTITY. Nothing in the estate has ever
+ * stored a per-element property (except `colSpan` on a form field), because
+ * there has been no way to say WHICH element a stored value belongs to. A card
+ * has a `cardKey`; the button inside it has nothing.
+ *
+ * This module is that identity, and nothing else. No stored styles, no visual
+ * change at rest — a deliberate first step, so the thing everything else hangs
+ * off can be reviewed on its own.
+ *
+ * THE HOT PATH IS THE DESIGN CONSTRAINT. `Button` renders 2,097 times in crm7,
+ * and on the 34 EnhancedDataTable pages that is once per row per action column.
+ * So:
+ *   - the context default is `null`, and a `useContext` returning null is about
+ *     the cheapest hook there is;
+ *   - NOTHING is computed unless `isEditing` is true. A consumer's whole cost
+ *     outside edit mode is one null check.
+ * Building the reference string on every render would have been a real
+ * regression on the tables, which is why `elementRef` is a function the consumer
+ * calls rather than a value this provider computes.
+ */
+export interface ElementScope {
+    /** The page this element lives on — `PageGridLayout`'s own `pageKey`. */
+    pageKey: string;
+    /** The card it lives in — `GridItem`'s `id`. */
+    cardKey: string;
+    /** What the card calls itself, for a sentence a person can read. */
+    cardLabel?: string;
+    /**
+     * Whether the page editor is open. Gates every cost above; a consumer that
+     * reads this and returns early pays one boolean.
+     */
+    isEditing: boolean;
+}
+/**
+ * Provided by `GridItem`, which is the only component that knows both the page
+ * and the card. Consumers never construct one.
+ */
+export declare function ElementScopeProvider({ scope, children, }: {
+    scope: ElementScope;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * The scope this element sits in, or `null` outside a grid page.
+ *
+ * `null` is a normal answer, not an error: most of the estate renders outside a
+ * `PageGridLayout`, and an element with no scope simply cannot be addressed yet.
+ */
+export declare function useElementScope(): ElementScope | null;
+/**
+ * A stable address for one element.
+ *
+ * SHAPE: `page:<pageKey>|card:<cardKey>|el:<name>`. Chosen so it is greppable,
+ * sorts by page then card, and survives being read by a human in a database row.
+ *
+ * `name` is the element's own stable identifier — NOT its visible label. A label
+ * is a moving target: rename "Add contact" to "New contact" and every stored
+ * override keyed on it orphans silently. Callers pass something that does not
+ * change when the copy does.
+ */
+export declare function elementRef(scope: ElementScope, name: string): string;
+/**
+ * The same address as a sentence, for a tooltip or a property panel.
+ *
+ * Uses the card's LABEL rather than its key, because "the Contacts card" is what
+ * a person sees and `card3` is not.
+ */
+export declare function describeElement(scope: ElementScope, name: string): string;
+/** Parses an address back into its parts, or `null` if it is not one. */
+export declare function parseElementRef(ref: string): {
+    pageKey: string;
+    cardKey: string;
+    name: string;
+} | null;
+//# sourceMappingURL=elementScope.d.ts.map

package/dist/elementScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elementScope.d.ts","sourceRoot":"","sources":["../src/elementScope.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAID;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,QAAQ,GACT,EAAE;IACD,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAapB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAGzE;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,GACV;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAU3D"}

package/dist/elementScope.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from 'react';
+const ElementScopeContext = React.createContext(null);
+/**
+ * Provided by `GridItem`, which is the only component that knows both the page
+ * and the card. Consumers never construct one.
+ */
+export function ElementScopeProvider({ scope, children, }) {
+    /* Destructured FIRST, then memoised on the primitives.
+       Memoising on `scope` itself would hand the subtree a new context value on
+       every GridItem render and re-render every button in the card for nothing;
+       memoising on `scope.pageKey` and friends would need an exhaustive-deps
+       suppression, and the estate ratchets those. Pulling the fields out gets the
+       correct behaviour with no suppression at all — the lint rule was right. */
+    const { pageKey, cardKey, cardLabel, isEditing } = scope;
+    const value = React.useMemo(() => ({ pageKey, cardKey, cardLabel, isEditing }), [pageKey, cardKey, cardLabel, isEditing]);
+    return _jsx(ElementScopeContext.Provider, { value: value, children: children });
+}
+/**
+ * The scope this element sits in, or `null` outside a grid page.
+ *
+ * `null` is a normal answer, not an error: most of the estate renders outside a
+ * `PageGridLayout`, and an element with no scope simply cannot be addressed yet.
+ */
+export function useElementScope() {
+    return React.useContext(ElementScopeContext);
+}
+/**
+ * A stable address for one element.
+ *
+ * SHAPE: `page:<pageKey>|card:<cardKey>|el:<name>`. Chosen so it is greppable,
+ * sorts by page then card, and survives being read by a human in a database row.
+ *
+ * `name` is the element's own stable identifier — NOT its visible label. A label
+ * is a moving target: rename "Add contact" to "New contact" and every stored
+ * override keyed on it orphans silently. Callers pass something that does not
+ * change when the copy does.
+ */
+export function elementRef(scope, name) {
+    return `page:${scope.pageKey}|card:${scope.cardKey}|el:${name}`;
+}
+/**
+ * The same address as a sentence, for a tooltip or a property panel.
+ *
+ * Uses the card's LABEL rather than its key, because "the Contacts card" is what
+ * a person sees and `card3` is not.
+ */
+export function describeElement(scope, name) {
+    const where = scope.cardLabel?.trim() ? `the ${scope.cardLabel.trim()} card` : 'this card';
+    return `${name}, in ${where}`;
+}
+/** Parses an address back into its parts, or `null` if it is not one. */
+export function parseElementRef(ref) {
+    const parts = ref.split('|');
+    if (parts.length !== 3)
+        return null;
+    const [p, c, e] = parts;
+    if (!p.startsWith('page:') || !c.startsWith('card:') || !e.startsWith('el:'))
+        return null;
+    const pageKey = p.slice('page:'.length);
+    const cardKey = c.slice('card:'.length);
+    const name = e.slice('el:'.length);
+    if (!pageKey || !cardKey || !name)
+        return null;
+    return { pageKey, cardKey, name };
+}

package/dist/index.d.ts

@@ -23,4 +23,6 @@ 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';
 export { BORDER_TONES, BORDER_STYLES, DEFAULT_CARD_STYLE, RADIUS_RANGE, BORDER_WIDTH_RANGE, PADDING_RANGE, normaliseCardStyle, isDefaultCardStyle, toCssVars as cardStyleToCssVars, describeCardStyle, } from './cardStyle.js';
 export type { CardStyle, BorderTone, BorderStyle, Elevation } from './cardStyle.js';
+export { ElementScopeProvider, useElementScope, elementRef, describeElement, parseElementRef, } from './elementScope.js';
+export type { ElementScope } from './elementScope.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,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,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;AACpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,IAAI,kBAAkB,EAC/B,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,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,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAwB7C,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,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;AACpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,SAAS,IAAI,kBAAkB,EAC/B,iBAAiB,GAClB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAQpF,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,UAAU,EACV,eAAe,EACf,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -12,3 +12,10 @@ export { useLocalPreference, defaultPreferenceAdapter } from './preferences.js';
 export { RelationshipField } from './RelationshipField.js';
 export { isRelationshipWritable } from './relationshipCatalog.js';
 export { BORDER_TONES, BORDER_STYLES, DEFAULT_CARD_STYLE, RADIUS_RANGE, BORDER_WIDTH_RANGE, PADDING_RANGE, normaliseCardStyle, isDefaultCardStyle, toCssVars as cardStyleToCssVars, describeCardStyle, } from './cardStyle.js';
+/*
+ * ELEMENT IDENTITY. Exported so a consumer can address one control inside a
+ * card — the prerequisite for storing any per-element property, and the reason
+ * none has ever been storable: a card has a key, the button inside it had
+ * nothing. No styling here, only the name.
+ */
+export { ElementScopeProvider, useElementScope, elementRef, describeElement, parseElementRef, } from './elementScope.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsuite/page-builder",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Shared BSuite responsive page-builder grid and layout persistence primitives",
   "type": "module",
   "license": "UNLICENSED",
@@ -63,21 +63,21 @@
   "devDependencies": {
     "@bsuite/nav-core": "workspace:^",
     "@bsuite/theme": "workspace:^",
-    "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.2",
-    "@types/node": "^25.9.2",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.2",
-    "jsdom": "^29.1.1",
-    "lucide-react": "^1.17.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
-    "react-grid-layout": "^2.2.3",
-    "react-resizable": "^4.0.1",
-    "typescript": "~6.0.3",
-    "vite": "^8.0.16",
-    "vitest": "^4.1.8"
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.4.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.5",
+    "@vitejs/plugin-react": "^6.1.1",
+    "jsdom": "^30.0.1",
+    "lucide-react": "^1.37.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-grid-layout": "^2.2.4",
+    "react-resizable": "^4.0.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
   },
   "packageManager": "pnpm@10.33.3"
 }