@bsuite/page-builder 0.7.0 → 0.9.0

package/dist/buildResponsiveLayouts.js

@@ -1,4 +1,71 @@
 export const RESPONSIVE_BREAKPOINTS = ['lg', 'md', 'sm', 'xs', 'xxs'];
+/**
+ * Breakpoints whose layout MIRRORS `lg` verbatim.
+ *
+ * D-75 root cause (operator directive 2026-08-13: "columns available to move
+ * cards into do not respect the columns slider").
+ * ---------------------------------------------------------------------------
+ * react-grid-layout picks its breakpoint from the **container** width, not the
+ * viewport — `<Responsive width={containerWidth}>` in `PageGridLayout`. Inside
+ * an app shell with a sidebar and page padding, a 1280px laptop presents a
+ * container around 950px and a 1440px desktop around 1100px. Both land BELOW
+ * the `md: 996` / `lg: 1200` thresholds, so the great majority of real desktop
+ * sessions render at `sm` or `md`, not `lg`.
+ *
+ * `sm` used to be derived by `stackToSingleColumn`, which sets `w: cols` on
+ * every item — one card per row at full width, whatever the column count. So
+ * on an ordinary laptop the columns slider changed `activeCols` while every
+ * card stayed stretched across all of them: the control provably did nothing,
+ * and the SE resize handle could not widen a card that was already at the grid
+ * bound nor narrow one whose `minW` had been clamped up to `cols`.
+ *
+ * `md` and `sm` therefore mirror `lg`: at a container width of 768px and above
+ * there is room for the arrangement the user chose, and honouring their choice
+ * is the whole point of the control. Genuine phone widths (`xs` < 768px
+ * container, `xxs` < 480px) still stack, which is what that code was for.
+ */
+export const MIRRORED_BREAKPOINTS = ['md', 'sm'];
+/**
+ * Breakpoints derived as a single full-width stack — narrow enough that a
+ * multi-column arrangement cannot be read.
+ */
+export const STACKED_BREAKPOINTS = ['xs', 'xxs'];
+/**
+ * Every breakpoint this module DERIVES from `lg`.
+ *
+ * A derived breakpoint is a render-time projection, never a stored fact. It
+ * must not reach the preference adapter: react-grid-layout echoes ALL
+ * breakpoints back through `onLayoutChange` on every gesture, so persisting
+ * them verbatim froze the derivation — a layout derived once at 12 columns was
+ * then "consumer-supplied" forever and stopped tracking `lg`. See
+ * `canonicaliseLayoutForPersist` in `usePageGridLayout.ts`.
+ */
+export const DERIVED_BREAKPOINTS = [
+    ...MIRRORED_BREAKPOINTS,
+    ...STACKED_BREAKPOINTS,
+];
+export function isDerivedBreakpoint(breakpoint) {
+    return DERIVED_BREAKPOINTS.includes(breakpoint);
+}
+/**
+ * True when a gesture at `breakpoint` can be written straight back onto `lg`.
+ *
+ * `lg`, `md` and `sm` all render the same array against the same column count,
+ * so an edit made at any of them is expressible in `lg` with no loss. `xs` and
+ * `xxs` render a full-width stack, where an edit carries only a vertical order
+ * and would flatten a multi-column desktop arrangement if applied to `lg`.
+ */
+export function isCanonicalisableBreakpoint(breakpoint) {
+    return breakpoint === 'lg' || MIRRORED_BREAKPOINTS.includes(breakpoint);
+}
+/**
+ * Stack items into one full-width column, preserving reading order.
+ *
+ * `w: cols` is deliberate at the breakpoints this is used for (`xs`/`xxs`):
+ * the container is narrower than 768px, so a card occupies the whole grid
+ * whatever the column count. Do NOT reach for this at wider breakpoints — that
+ * was D-75.
+ */
 function stackToSingleColumn(items, cols) {
     const sorted = [...items].sort((a, b) => (a.y !== b.y ? a.y - b.y : a.x - b.x));
     let nextY = 0;
@@ -16,10 +83,15 @@ function stackToSingleColumn(items, cols) {
 }
 /**
  * Ensure a GridLayouts object has entries for all responsive breakpoints
- * (lg, md, sm, xs, xxs). Missing smaller breakpoints (sm/xs/xxs) are derived
- * from `lg` as a single-column vertical stack so that consumer-supplied
- * lg-only layouts no longer squash on phone viewports. Missing `md` is
- * mirrored from `lg`. Consumer-supplied breakpoints are preserved verbatim.
+ * (lg, md, sm, xs, xxs).
+ *
+ * - `md` and `sm` mirror `lg` so the user's chosen column arrangement survives
+ *   every desktop and tablet container width (see {@link MIRRORED_BREAKPOINTS}).
+ * - `xs` and `xxs` are derived as a single-column stack so a phone viewport
+ *   never squashes cards into unreadable slivers.
+ * - Consumer-supplied breakpoints are preserved verbatim. Supplying one opts
+ *   that breakpoint OUT of tracking `lg`, including out of the columns slider —
+ *   prefer not to.
  */
 export function buildResponsiveLayouts(layouts, { cols = 12 } = {}) {
     const lg = layouts.lg ?? [];
@@ -32,7 +104,7 @@ export function buildResponsiveLayouts(layouts, { cols = 12 } = {}) {
             result[bp] = supplied;
             continue;
         }
-        if (bp === 'md') {
+        if (MIRRORED_BREAKPOINTS.includes(bp)) {
             result[bp] = lg;
             continue;
         }

package/dist/canvasCardLayout.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The CanvasCard → grid-layout algorithm, extracted from the component so it
+ * can be unit-tested and reused without rendering anything.
+ *
+ * This is the half of `DraggableCardPage` that was copied verbatim into three
+ * apps (crm7, braden, throughput) and was absent from two more (BSU, conduit).
+ * It has no app dependencies, no permission model and no adapter — those are
+ * the parts that legitimately differ per app and stay there.
+ */
+import { type ReactElement, type ReactNode } from 'react';
+import type { CanvasCardProps } from './CanvasCard.js';
+import type { GridLayouts } from './types.js';
+/** The 12-column grid every BSuite page canvas is laid out against. */
+export declare const CANVAS_GRID_COLUMNS = 12;
+export declare function isCanvasCardElement(node: ReactNode): node is ReactElement<CanvasCardProps>;
+/**
+ * Best-effort display name for a node that is about to be discarded.
+ * "Something was dropped" is not actionable across hundreds of pages; the
+ * component's own name is what makes it findable.
+ */
+export declare function describeNode(node: ReactNode): string;
+/**
+ * Depth-first flatten: CanvasCards kept, Fragments expanded, everything else
+ * dropped — and RECORDED rather than vanishing.
+ *
+ * The dropping itself is correct and deliberate: this maps children onto grid
+ * slots, and a node with no `cardKey` has no slot to occupy. What was wrong is
+ * that it happened in total silence, so a page could render with a confirm
+ * dialog missing and look completely fine — the button appears, the click
+ * handler runs, state flips, and the element it toggles was never mounted.
+ *
+ * Fragments must be expanded explicitly because `Children.forEach` is shallow:
+ * it sees one Fragment node, not the CanvasCards inside it. A Fragment-wrapped
+ * conditional branch used to drop every nested card silently (the crm7 burn-7
+ * CI class, `leave/[id]`).
+ */
+export declare function flattenCanvasCards(nodes: ReactNode): {
+    cards: ReactElement<CanvasCardProps>[];
+    dropped: string[];
+};
+export declare function clampColumns(value: number, min?: number, max?: number): number;
+export interface CanvasCardLayoutResult {
+    /** Widget dict keyed by `cardKey`, ready for `PageGridLayout.widgets`. */
+    widgets: Record<string, ReactNode>;
+    /** `lg` breakpoint layout, ready for `PageGridLayout.defaultLayouts`. */
+    layouts: GridLayouts;
+    /** Display names of children that occupied no grid slot and were discarded. */
+    dropped: string[];
+}
+/**
+ * Build the `widgets` dict and `defaultLayouts.lg` array from CanvasCard
+ * children.
+ *
+ * Cards flow left-to-right and wrap to a new row when the next card would
+ * overflow the 12-column grid. Because the dict is built FROM THE CHILDREN AT
+ * RENDER TIME, a `.map()` producing N cards is fully supported and needs no
+ * registration mechanism — each mapped card becomes its own independent grid
+ * item. (This is the fact that disproves the "dynamic card lists cannot be
+ * split into static widget keys" objection recorded in several app ledgers.)
+ */
+export declare function buildCanvasCardLayout(children: ReactNode): CanvasCardLayoutResult;
+//# sourceMappingURL=canvasCardLayout.d.ts.map

package/dist/canvasCardLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvasCardLayout.d.ts","sourceRoot":"","sources":["../src/canvasCardLayout.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,GACd,IAAI,IAAI,YAAY,CAAC,eAAe,CAAC,CAKvC;AAQD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAQpD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,GAAG;IACpD,KAAK,EAAE,YAAY,CAAC,eAAe,CAAC,EAAE,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAqBA;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,SAAI,EAAE,GAAG,SAAsB,UAE7E;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACnC,yEAAyE;IACzE,OAAO,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,GAClB,sBAAsB,CA0CxB"}

package/dist/canvasCardLayout.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The CanvasCard → grid-layout algorithm, extracted from the component so it
+ * can be unit-tested and reused without rendering anything.
+ *
+ * This is the half of `DraggableCardPage` that was copied verbatim into three
+ * apps (crm7, braden, throughput) and was absent from two more (BSU, conduit).
+ * It has no app dependencies, no permission model and no adapter — those are
+ * the parts that legitimately differ per app and stay there.
+ */
+import { Children, Fragment, isValidElement, } from 'react';
+/** The 12-column grid every BSuite page canvas is laid out against. */
+export const CANVAS_GRID_COLUMNS = 12;
+export function isCanvasCardElement(node) {
+    return (isValidElement(node) &&
+        node.type.displayName === 'CanvasCard');
+}
+function isFragmentElement(node) {
+    return isValidElement(node) && node.type === Fragment;
+}
+/**
+ * Best-effort display name for a node that is about to be discarded.
+ * "Something was dropped" is not actionable across hundreds of pages; the
+ * component's own name is what makes it findable.
+ */
+export function describeNode(node) {
+    if (!isValidElement(node))
+        return typeof node === 'string'
+            ? `text ${JSON.stringify(node)}`
+            : String(node);
+    const t = node.type;
+    if (typeof t === 'string')
+        return `<${t}>`;
+    return `<${t?.displayName ?? t?.name ?? 'Unknown'}>`;
+}
+/**
+ * Depth-first flatten: CanvasCards kept, Fragments expanded, everything else
+ * dropped — and RECORDED rather than vanishing.
+ *
+ * The dropping itself is correct and deliberate: this maps children onto grid
+ * slots, and a node with no `cardKey` has no slot to occupy. What was wrong is
+ * that it happened in total silence, so a page could render with a confirm
+ * dialog missing and look completely fine — the button appears, the click
+ * handler runs, state flips, and the element it toggles was never mounted.
+ *
+ * Fragments must be expanded explicitly because `Children.forEach` is shallow:
+ * it sees one Fragment node, not the CanvasCards inside it. A Fragment-wrapped
+ * conditional branch used to drop every nested card silently (the crm7 burn-7
+ * CI class, `leave/[id]`).
+ */
+export function flattenCanvasCards(nodes) {
+    const cards = [];
+    const dropped = [];
+    Children.forEach(nodes, (child) => {
+        // Falsy entries are the documented conditional shape — `{cond && <CanvasCard/>}`
+        // collapses to `false`, which is intentional and must stay silent.
+        if (child == null || child === false || child === true || child === '')
+            return;
+        if (isCanvasCardElement(child)) {
+            cards.push(child);
+            return;
+        }
+        if (isFragmentElement(child)) {
+            const inner = flattenCanvasCards(child.props.children);
+            cards.push(...inner.cards);
+            dropped.push(...inner.dropped);
+            return;
+        }
+        dropped.push(describeNode(child));
+    });
+    return { cards, dropped };
+}
+export function clampColumns(value, min = 1, max = CANVAS_GRID_COLUMNS) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Build the `widgets` dict and `defaultLayouts.lg` array from CanvasCard
+ * children.
+ *
+ * Cards flow left-to-right and wrap to a new row when the next card would
+ * overflow the 12-column grid. Because the dict is built FROM THE CHILDREN AT
+ * RENDER TIME, a `.map()` producing N cards is fully supported and needs no
+ * registration mechanism — each mapped card becomes its own independent grid
+ * item. (This is the fact that disproves the "dynamic card lists cannot be
+ * split into static widget keys" objection recorded in several app ledgers.)
+ */
+export function buildCanvasCardLayout(children) {
+    const widgets = {};
+    const lg = [];
+    let x = 0;
+    let y = 0;
+    let rowHeight = 0;
+    const { cards, dropped } = flattenCanvasCards(children);
+    for (const child of cards) {
+        // autoHeight defaults to TRUE — cards track measured content height unless
+        // a card explicitly opts out for a virtualized list. See CanvasCardProps.
+        const { cardKey, h = 6, minH = 2, minW = 4, autoHeight = true, children: body, } = child.props;
+        const normalizedMinW = clampColumns(minW);
+        const width = clampColumns(child.props.w ?? CANVAS_GRID_COLUMNS, normalizedMinW);
+        if (x + width > CANVAS_GRID_COLUMNS) {
+            y += rowHeight;
+            x = 0;
+            rowHeight = 0;
+        }
+        widgets[cardKey] = (_jsx("div", { className: "relative h-full group/canvas-card", children: body }));
+        lg.push({
+            i: cardKey,
+            x,
+            y,
+            w: width,
+            h,
+            minW: normalizedMinW,
+            minH,
+            ...(autoHeight ? { autoHeight: true } : {}),
+        });
+        x += width;
+        rowHeight = Math.max(rowHeight, h);
+    }
+    return { widgets, layouts: { lg }, dropped };
+}

package/dist/index.d.ts

@@ -1,5 +1,11 @@
 export { PageGridLayout } from './PageGridLayout.js';
 export { PageEditorLauncher } from './PageEditorLauncher.js';
+export { CanvasCard } from './CanvasCard.js';
+export type { CanvasCardProps } from './CanvasCard.js';
+export { DraggableCardPage } from './DraggableCardPage.js';
+export type { DraggableCardPageProps } from './DraggableCardPage.js';
+export { buildCanvasCardLayout, flattenCanvasCards, isCanvasCardElement, describeNode, clampColumns, CANVAS_GRID_COLUMNS, } from './canvasCardLayout.js';
+export type { CanvasCardLayoutResult } from './canvasCardLayout.js';
 export type { WidgetConfig, PageEditorLauncherProps } from './PageEditorLauncher.js';
 export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
 export type { PageGridEditingEventDetail } from './usePageGridLayout.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,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"}
+{"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,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"}

package/dist/index.js

@@ -1,5 +1,8 @@
 export { PageGridLayout } from './PageGridLayout.js';
 export { PageEditorLauncher } from './PageEditorLauncher.js';
+export { CanvasCard } from './CanvasCard.js';
+export { DraggableCardPage } from './DraggableCardPage.js';
+export { buildCanvasCardLayout, flattenCanvasCards, isCanvasCardElement, describeNode, clampColumns, CANVAS_GRID_COLUMNS, } from './canvasCardLayout.js';
 export { usePageGridLayout, DEFAULT_EDITOR_EVENT_NAMES, PAGE_GRID_EDITING_EVENT, } from './usePageGridLayout.js';
 export { rescaleLayout } from './rescaleLayout.js';
 export { computeAutoHeightRows } from './autoHeight.js';

package/dist/scanner/cardSurfaceScanner.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The card-surface contract scanner — ONE implementation, shipped from the
+ * package, replacing five divergent hand-rolled copies.
+ *
+ * Why this exists
+ * ---------------
+ * crm7 wrote a card-unglue contract test. BSU, conduit, throughput and braden
+ * each PORTED it, and each silently dropped checks during the port. The
+ * divergence was not cosmetic:
+ *
+ *   - `findUngriddedMultiCard` — the check crm7's own comment calls "the actual
+ *     root cause of the operator's platform-wide complaint" — was ABSENT from
+ *     BSU, throughput and braden, and present only in a narrowed form in
+ *     conduit. In throughput and braden it was absent structurally: their glue
+ *     scan is gated on the file containing `CanvasCard` at all, so a page with
+ *     two cards and no grid primitive is invisible by construction.
+ *   - conduit's header documents THREE card idioms and its regexes detect TWO.
+ *     The third (`rounded-lg border p-4` section panels) has no detector, which
+ *     is how five known-glued conduit pages pass as an empty ledger.
+ *   - BSU's scan only walks files containing the literal string
+ *     `PageGridLayout`, so every BSU page that never adopted the grid is
+ *     structurally invisible to BSU's own gate.
+ *
+ * A gate that cannot tell "checked nothing" from "found nothing" is not a gate
+ * (D-92). This module therefore ASSERTS ITS INPUTS: it fails closed if a scan
+ * root is missing or matches zero files, and it reports how it reached its
+ * verdict rather than only the verdict.
+ *
+ * What stays per-app
+ * ------------------
+ * Scan roots, card vocabulary, class-based surface patterns, and the exclusion
+ * ledgers. Those are operational truth about a specific app. Everything else —
+ * the detection logic — lives here so it can only be fixed once.
+ *
+ * Node-only: this module touches the filesystem and is exported from
+ * `@bsuite/page-builder/scanner`, NOT from the package root, so it never
+ * reaches a browser bundle.
+ */
+export type CardSurfaceIdiom = 
+/** 2+ card-like components packed inside ONE grid slot. */
+'glued-widget'
+/** 2+ card-like components on a page that never reaches a grid primitive. */
+ | 'ungridded-multi-card'
+/** A retired single-widget primitive still present or still imported. */
+ | 'retired-primitive'
+/** autoHeight opt-out on a card that is not a virtualized list. */
+ | 'autoheight-optout'
+/** autoHeight={false} with a seed height so small the card must clip. */
+ | 'clipped-card';
+export interface CardSurfaceFinding {
+    file: string;
+    idiom: CardSurfaceIdiom;
+    detail: string;
+    /** Number of card-like components involved, where meaningful. */
+    cardCount?: number;
+}
+export interface CardSurfaceScannerConfig {
+    /** Absolute path to the repo root. */
+    projectRoot: string;
+    /**
+     * Directories to walk, repo-relative. Every one MUST exist and MUST contain
+     * at least one scannable file, or the scan fails closed.
+     */
+    scanRoots: string[];
+    /**
+     * Component names that count as a card. Apps differ materially here: crm7
+     * uses `Card`/`StatCard`/`SummaryCard`, BSU adds `ServiceCard`, conduit uses
+     * `SummaryCard`/`CounterCard`.
+     */
+    cardTags: string[];
+    /**
+     * Class-based card surfaces — a card that is a styled `div`, not a
+     * component. This is the idiom conduit documented and never implemented, and
+     * the one BSU's `glass-card` tiles use. Supply e.g.
+     * `[/glass-card/, /rounded-lg border p-4/]`.
+     */
+    classSurfaces?: RegExp[];
+    /** Identifiers that prove a file reached the grid. */
+    gridPrimitives?: string[];
+    /** Repo-relative path of a retired single-widget primitive that must not exist. */
+    retiredPrimitivePaths?: string[];
+    /** file -> reason. A glued widget listed here is allowed. */
+    gluedExclusions?: Record<string, string>;
+    /** file -> reason. An ungridded multi-card page listed here is allowed. */
+    ungriddedExclusions?: Record<string, string>;
+    /**
+     * Directories deliberately NOT scanned, each with a reason. Declaring a
+     * blind spot is required; having an undeclared one is the defect.
+     */
+    blindSpots?: Record<string, string>;
+    /**
+     * If a file matches this, an `autoHeight={false}` in it is permitted — the
+     * opt-out is reserved for genuinely virtualized/windowed lists.
+     */
+    autoHeightEscapeHatch?: RegExp;
+    /** File extensions to scan. Defaults to .tsx. */
+    extensions?: string[];
+}
+export interface CardSurfaceScanResult {
+    findings: CardSurfaceFinding[];
+    /** Files actually read. If this is 0 the scan proved nothing. */
+    filesScanned: number;
+    scanRootsResolved: string[];
+    /** Exclusion-ledger keys that no longer match any finding — stale entries. */
+    staleExclusions: string[];
+    /** Human-readable account of how the verdict was reached. */
+    summary: string;
+}
+/**
+ * Strip block comments, line comments and JSX comments before matching.
+ *
+ * Three of the five hand-rolled copies matched against raw file content, which
+ * produced two opposite errors at once: a commented-out `<Card/><Card/>`
+ * example false-POSITIVES as glue, and a file that merely MENTIONS
+ * `CanvasCard` in a TODO comment false-NEGATIVES as "already gridded" and is
+ * skipped entirely. Stripping first fixes both.
+ */
+export declare function stripComments(source: string): string;
+export declare function scanCardSurfaces(config: CardSurfaceScannerConfig): CardSurfaceScanResult;
+//# sourceMappingURL=cardSurfaceScanner.d.ts.map

package/dist/scanner/cardSurfaceScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cardSurfaceScanner.d.ts","sourceRoot":"","sources":["../../src/scanner/cardSurfaceScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,MAAM,MAAM,gBAAgB;AAC1B,2DAA2D;AACzD,cAAc;AAChB,6EAA6E;GAC3E,sBAAsB;AACxB,yEAAyE;GACvE,mBAAmB;AACrB,mEAAmE;GACjE,mBAAmB;AACrB,yEAAyE;GACvE,cAAc,CAAC;AAEnB,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,mFAAmF;IACnF,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,2EAA2E;IAC3E,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,iEAAiE;IACjE,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,8EAA8E;IAC9E,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB;AASD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKpD;AAwHD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,qBAAqB,CAwIvB"}