@genesislcap/foundation-react-utils 15.50.3 → 15.51.1

package/dist/foundation-react-utils.api.json

@@ -172,6 +172,87 @@
       "name": "",
       "preserveMemberOrder": false,
       "members": [
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-react-utils!AppErrorBoundary:var",
+          "docComment": "/**\n * Top-level error boundary. Wrap the whole app in one instance; use {@link TileErrorBoundary} inside it.\n *\n * @remarks\n *\n * Renders a fallback with a reference ID, copyable diagnostics and a Retry button that remounts the children. Each caught error is passed to `onError`. Without one, it's logged through the {@link ERROR_BOUNDARY_LOGGER_NAME} logger instead, which a global log reporter receives. Pair with {@link onCaughtError} on the root so React doesn't log the error a second time.\n *\n * @example\n * ```tsx\n * createRoot(el, { onCaughtError }).render(\n *   <AppErrorBoundary onError={({ error, ...extra }) => Sentry.captureException(error, { extra })}>\n *     <App />\n *   </AppErrorBoundary>,\n * );\n * ```\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "AppErrorBoundary: "
+            },
+            {
+              "kind": "Reference",
+              "text": "FC",
+              "canonicalReference": "@types/react!React.FC:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "AppErrorBoundaryProps",
+              "canonicalReference": "@genesislcap/foundation-react-utils!AppErrorBoundaryProps:type"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "AppErrorBoundary",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-react-utils!AppErrorBoundaryProps:type",
+          "docComment": "/**\n * Props for {@link AppErrorBoundary}.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type AppErrorBoundaryProps = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    onError?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ErrorBoundaryErrorHandler",
+              "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryErrorHandler:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    children: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ReactNode",
+              "canonicalReference": "@types/react!React.ReactNode:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "releaseTag": "Public",
+          "name": "AppErrorBoundaryProps",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/foundation-react-utils!createGridProCellPortals:function(1)",
@@ -416,6 +497,138 @@
           ],
           "name": "createReactRenderer"
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-react-utils!ERROR_BOUNDARY_LOGGER_NAME:var",
+          "docComment": "/**\n * Name of the logger the error boundaries log through. They log a caught error, with a message naming its scope, title, tile registration and reference ID and giving its component stack, only when no `onError` handler is set or when the handler throws. `setupErrorMonitoring` from foundation-utils reports these logs, so apps using it don't need an `onError`.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "ERROR_BOUNDARY_LOGGER_NAME = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"foundation-react-utils:error-boundary\""
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "ERROR_BOUNDARY_LOGGER_NAME",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryErrorHandler:type",
+          "docComment": "/**\n * Callback that receives every error a boundary catches, for example to send it to an error-monitoring service.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ErrorBoundaryErrorHandler = "
+            },
+            {
+              "kind": "Content",
+              "text": "(report: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ErrorBoundaryReport",
+              "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryReport:type"
+            },
+            {
+              "kind": "Content",
+              "text": ") => void"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "releaseTag": "Public",
+          "name": "ErrorBoundaryErrorHandler",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 4
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryReport:type",
+          "docComment": "/**\n * What an error boundary passes to `onError` when it catches an error.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ErrorBoundaryReport = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    error: "
+            },
+            {
+              "kind": "Reference",
+              "text": "Error",
+              "canonicalReference": "!Error:interface"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    componentStack: string;\n    referenceId: string;\n    scope: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ErrorBoundaryScope",
+              "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryScope:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    title: string;\n    tileRegistration?: string;\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "releaseTag": "Public",
+          "name": "ErrorBoundaryReport",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryScope:type",
+          "docComment": "/**\n * Where a boundary sits: around the whole app, or around a single tile.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ErrorBoundaryScope = "
+            },
+            {
+              "kind": "Content",
+              "text": "'application' | 'tile'"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "releaseTag": "Public",
+          "name": "ErrorBoundaryScope",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/foundation-react-utils!GridProCellPortals:interface",
@@ -1047,6 +1260,43 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-react-utils!onCaughtError:var",
+          "docComment": "/**\n * Root `onCaughtError` for `createRoot`.\n *\n * @remarks\n *\n * By default React 19 logs every error a boundary catches to `console.error`, before the boundary's `componentDidCatch` runs. Console-capturing monitoring tools then report that bare error first, and can drop or duplicate the boundary's own report. {@link AppErrorBoundary} and {@link TileErrorBoundary} report or log errors themselves, so this skips them. Errors caught by any other boundary are still logged to `console.error`, with their component stack.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "onCaughtError: "
+            },
+            {
+              "kind": "Reference",
+              "text": "NonNullable",
+              "canonicalReference": "!NonNullable:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "RootOptions",
+              "canonicalReference": "@types/react-dom!RootOptions:interface"
+            },
+            {
+              "kind": "Content",
+              "text": "['onCaughtError']>"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "onCaughtError",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/foundation-react-utils!reactFactory:function(1)",
@@ -1287,6 +1537,208 @@
             }
           ],
           "name": "reactFactoryWithProvider"
+        },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-react-utils!TileErrorBoundary:var",
+          "docComment": "/**\n * Error boundary for a single tile, so a crash replaces only that tile with the fallback UI and the rest of the app keeps running.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "TileErrorBoundary: "
+            },
+            {
+              "kind": "Reference",
+              "text": "FC",
+              "canonicalReference": "@types/react!React.FC:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<"
+            },
+            {
+              "kind": "Reference",
+              "text": "TileErrorBoundaryProps",
+              "canonicalReference": "@genesislcap/foundation-react-utils!TileErrorBoundaryProps:type"
+            },
+            {
+              "kind": "Content",
+              "text": ">"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "isReadonly": true,
+          "releaseTag": "Public",
+          "name": "TileErrorBoundary",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 5
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-react-utils!TileErrorBoundaryProps:type",
+          "docComment": "/**\n * Props for {@link TileErrorBoundary}.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type TileErrorBoundaryProps = "
+            },
+            {
+              "kind": "Content",
+              "text": "{\n    title: string;\n    tileRegistration: string;\n    onError?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ErrorBoundaryErrorHandler",
+              "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryErrorHandler:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n    children: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ReactNode",
+              "canonicalReference": "@types/react!React.ReactNode:type"
+            },
+            {
+              "kind": "Content",
+              "text": ";\n}"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "releaseTag": "Public",
+          "name": "TileErrorBoundaryProps",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 6
+          }
+        },
+        {
+          "kind": "Function",
+          "canonicalReference": "@genesislcap/foundation-react-utils!withTileErrorBoundary:function(1)",
+          "docComment": "/**\n * Wraps a component in a {@link TileErrorBoundary}.\n *\n * @param WrappedComponent - The tile component.\n *\n * @param title - Human-readable tile name shown in the fallback UI.\n *\n * @param tileRegistration - The tile's key in the layout.\n *\n * @param onError - Optional callback for caught errors.\n *\n * @public\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "withTileErrorBoundary: <P extends "
+            },
+            {
+              "kind": "Content",
+              "text": "object"
+            },
+            {
+              "kind": "Content",
+              "text": ">(WrappedComponent: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ComponentType",
+              "canonicalReference": "@types/react!React.ComponentType:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<P>"
+            },
+            {
+              "kind": "Content",
+              "text": ", title: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ", tileRegistration: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            },
+            {
+              "kind": "Content",
+              "text": ", onError?: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ErrorBoundaryErrorHandler",
+              "canonicalReference": "@genesislcap/foundation-react-utils!ErrorBoundaryErrorHandler:type"
+            },
+            {
+              "kind": "Content",
+              "text": ") => "
+            },
+            {
+              "kind": "Reference",
+              "text": "FC",
+              "canonicalReference": "@types/react!React.FC:type"
+            },
+            {
+              "kind": "Content",
+              "text": "<P>"
+            }
+          ],
+          "fileUrlPath": "src/error-boundary/error-boundary.tsx",
+          "returnTypeTokenRange": {
+            "startIndex": 12,
+            "endIndex": 14
+          },
+          "releaseTag": "Public",
+          "overloadIndex": 1,
+          "parameters": [
+            {
+              "parameterName": "WrappedComponent",
+              "parameterTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 5
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "title",
+              "parameterTypeTokenRange": {
+                "startIndex": 6,
+                "endIndex": 7
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "tileRegistration",
+              "parameterTypeTokenRange": {
+                "startIndex": 8,
+                "endIndex": 9
+              },
+              "isOptional": false
+            },
+            {
+              "parameterName": "onError",
+              "parameterTypeTokenRange": {
+                "startIndex": 10,
+                "endIndex": 11
+              },
+              "isOptional": true
+            }
+          ],
+          "typeParameters": [
+            {
+              "typeParameterName": "P",
+              "constraintTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "defaultTypeTokenRange": {
+                "startIndex": 0,
+                "endIndex": 0
+              }
+            }
+          ],
+          "name": "withTileErrorBoundary"
         }
       ]
     }

package/dist/foundation-react-utils.d.ts

@@ -1,13 +1,47 @@
 import type { ComponentFactory } from '@genesislcap/foundation-layout';
 import { ComponentType } from 'react';
+import type { FC } from 'react';
 import { JsonFormsState } from '@jsonforms/core';
 import { OwnPropsOfControl } from '@jsonforms/core';
 import { RankedTester } from '@jsonforms/core';
 import * as React_2 from 'react';
+import type { ReactNode } from 'react';
 import { RendererControlProps } from '@genesislcap/foundation-forms';
 import { RendererEntry } from '@genesislcap/foundation-forms';
+import type { RootOptions } from 'react-dom/client';
 import { StatePropsOfControl } from '@jsonforms/core';
 
+/**
+ * Top-level error boundary. Wrap the whole app in one instance; use {@link TileErrorBoundary}
+ * inside it.
+ *
+ * @remarks
+ * Renders a fallback with a reference ID, copyable diagnostics and a Retry button that remounts
+ * the children. Each caught error is passed to `onError`. Without one, it's logged through the
+ * {@link ERROR_BOUNDARY_LOGGER_NAME} logger instead, which a global log reporter receives. Pair with {@link onCaughtError} on the root so React doesn't log the
+ * error a second time.
+ *
+ * @example
+ * ```tsx
+ * createRoot(el, { onCaughtError }).render(
+ *   <AppErrorBoundary onError={({ error, ...extra }) => Sentry.captureException(error, { extra })}>
+ *     <App />
+ *   </AppErrorBoundary>,
+ * );
+ * ```
+ * @public
+ */
+export declare const AppErrorBoundary: FC<AppErrorBoundaryProps>;
+
+/**
+ * Props for {@link AppErrorBoundary}.
+ * @public
+ */
+export declare type AppErrorBoundaryProps = {
+    onError?: ErrorBoundaryErrorHandler;
+    children: ReactNode;
+};
+
 /**
  * Creates a {@link GridProCellPortals} manager: a single React root shared by every cell
  * renderer registered with it, with each cell rendered into its grid cell via a portal.
@@ -203,6 +237,42 @@ export declare function createReactRenderer(Component: ComponentType<RendererCon
     wrapWithControlWrapper?: boolean;
 }): RendererEntry;
 
+/**
+ * Name of the logger the error boundaries log through. They log a caught error, with a message
+ * naming its scope, title, tile registration and reference ID and giving its component stack, only
+ * when no `onError` handler is set or when the handler throws. `setupErrorMonitoring` from foundation-utils reports
+ * these logs, so apps using it don't need an `onError`.
+ * @public
+ */
+export declare const ERROR_BOUNDARY_LOGGER_NAME = "foundation-react-utils:error-boundary";
+
+/**
+ * Callback that receives every error a boundary catches, for example to send it to an
+ * error-monitoring service.
+ * @public
+ */
+export declare type ErrorBoundaryErrorHandler = (report: ErrorBoundaryReport) => void;
+
+/**
+ * What an error boundary passes to `onError` when it catches an error.
+ * @public
+ */
+export declare type ErrorBoundaryReport = {
+    error: Error;
+    componentStack: string;
+    /** Shown in the fallback UI, so support can match a user's screen to a reported event. */
+    referenceId: string;
+    scope: ErrorBoundaryScope;
+    title: string;
+    tileRegistration?: string;
+};
+
+/**
+ * Where a boundary sits: around the whole app, or around a single tile.
+ * @public
+ */
+export declare type ErrorBoundaryScope = 'application' | 'tile';
+
 /**
  * Shared portal manager for Grid Pro React cell renderers.
  *
@@ -321,6 +391,20 @@ export declare interface GridProReactCellRenderer {
     destroy(): void;
 }
 
+/**
+ * Root `onCaughtError` for `createRoot`.
+ *
+ * @remarks
+ * By default React 19 logs every error a boundary catches to `console.error`, before the
+ * boundary's `componentDidCatch` runs. Console-capturing monitoring tools then report that bare
+ * error first, and can drop or duplicate the boundary's own report. {@link AppErrorBoundary} and
+ * {@link TileErrorBoundary} report or log errors themselves, so this skips them. Errors caught by
+ * any other boundary are still logged to `console.error`, with their component stack.
+ *
+ * @public
+ */
+export declare const onCaughtError: NonNullable<RootOptions['onCaughtError']>;
+
 /**
  * Creates a factory function for rendering React components in layout items.
  *
@@ -371,4 +455,35 @@ export declare function reactFactoryWithProvider<CP = {}, WP = {}>(Component: Re
 
 export { RendererControlProps }
 
+/**
+ * Error boundary for a single tile, so a crash replaces only that tile with the fallback UI and
+ * the rest of the app keeps running.
+ * @public
+ */
+export declare const TileErrorBoundary: FC<TileErrorBoundaryProps>;
+
+/**
+ * Props for {@link TileErrorBoundary}.
+ * @public
+ */
+export declare type TileErrorBoundaryProps = {
+    /** Human-readable tile name shown in the fallback UI. */
+    title: string;
+    /** The tile's key in the layout. */
+    tileRegistration: string;
+    onError?: ErrorBoundaryErrorHandler;
+    children: ReactNode;
+};
+
+/**
+ * Wraps a component in a {@link TileErrorBoundary}.
+ *
+ * @param WrappedComponent - The tile component.
+ * @param title - Human-readable tile name shown in the fallback UI.
+ * @param tileRegistration - The tile's key in the layout.
+ * @param onError - Optional callback for caught errors.
+ * @public
+ */
+export declare const withTileErrorBoundary: <P extends object>(WrappedComponent: ComponentType<P>, title: string, tileRegistration: string, onError?: ErrorBoundaryErrorHandler) => FC<P>;
+
 export { }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-react-utils",
   "description": "Genesis Foundation React Utils",
-  "version": "15.50.3",
+  "version": "15.51.1",
   "sideEffects": [
     "./dist/esm/flexlayout/index.js"
   ],
@@ -56,12 +56,12 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.50.3",
-    "@genesislcap/genx": "15.50.3",
-    "@genesislcap/ts-builder": "15.50.3",
-    "@genesislcap/uvu-playwright-builder": "15.50.3",
-    "@genesislcap/vite-builder": "15.50.3",
-    "@genesislcap/webpack-builder": "15.50.3",
+    "@genesislcap/foundation-testing": "15.51.1",
+    "@genesislcap/genx": "15.51.1",
+    "@genesislcap/ts-builder": "15.51.1",
+    "@genesislcap/uvu-playwright-builder": "15.51.1",
+    "@genesislcap/vite-builder": "15.51.1",
+    "@genesislcap/webpack-builder": "15.51.1",
     "react-router-dom": "^7.1.3"
   },
   "peerDependencies": {
@@ -75,11 +75,11 @@
     }
   },
   "dependencies": {
-    "@genesislcap/foundation-forms": "15.50.3",
-    "@genesislcap/foundation-layout": "15.50.3",
-    "@genesislcap/foundation-logger": "15.50.3",
-    "@genesislcap/rapid-design-system": "15.50.3",
-    "@genesislcap/web-core": "15.50.3",
+    "@genesislcap/foundation-forms": "15.51.1",
+    "@genesislcap/foundation-layout": "15.51.1",
+    "@genesislcap/foundation-logger": "15.51.1",
+    "@genesislcap/rapid-design-system": "15.51.1",
+    "@genesislcap/web-core": "15.51.1",
     "@jsonforms/core": "^3.2.1",
     "@r2wc/core": "1.3.1",
     "@r2wc/react-to-web-component": "^2.0.2",