@genesislcap/foundation-react-utils 15.50.3 → 15.51.1

package/dist/esm/error-boundary/error-boundary.js

@@ -0,0 +1,217 @@
+var _a;
+import { __awaiter } from "tslib";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createLogger } from '@genesislcap/foundation-logger';
+import { Component, useState } from 'react';
+import { errorBoundaryStyles } from './error-boundary-styles';
+/**
+ * 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 const ERROR_BOUNDARY_LOGGER_NAME = 'foundation-react-utils:error-boundary';
+const logger = createLogger(ERROR_BOUNDARY_LOGGER_NAME);
+const initialBoundaryState = {
+    error: null,
+    componentStack: '',
+    capturedAt: '',
+    referenceId: '',
+};
+/**
+ * Marks instances of these boundaries. A brand rather than `instanceof`, so {@link onCaughtError}
+ * still recognises a boundary from another copy of this package, such as one in a federated remote.
+ */
+const BOUNDARY_BRAND = Symbol.for('@genesislcap/foundation-react-utils:error-boundary');
+const REPORTS_GLOBAL = '__GENESIS_ERROR_BOUNDARY_REPORTS__';
+const MAX_REPORTS = 20;
+const COPIED_RESET_MS = 2000;
+const REFERENCE_RANDOM_LENGTH = 6;
+const BASE36 = 36;
+const toError = (value) => {
+    if (value instanceof Error) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return new Error(value);
+    }
+    try {
+        return new Error(JSON.stringify(value));
+    }
+    catch (_b) {
+        return new Error('Unknown non-serializable error');
+    }
+};
+const createReferenceId = () => {
+    const timestamp = new Date().toISOString().split(':').join('-');
+    const random = Math.random()
+        .toString(BASE36)
+        .slice(2, 2 + REFERENCE_RANDOM_LENGTH)
+        .toUpperCase();
+    return `APP-${timestamp}-${random}`;
+};
+/**
+ * Keeps the most recent reports on `window` for dev tooling (the Genesis Create preview reads them).
+ */
+const recordReport = (error, componentStack) => {
+    var _b, _c;
+    const host = globalThis;
+    const reports = ((_b = host[REPORTS_GLOBAL]) !== null && _b !== void 0 ? _b : (host[REPORTS_GLOBAL] = []));
+    reports.push({
+        message: error.message,
+        stack: (_c = error.stack) !== null && _c !== void 0 ? _c : null,
+        componentStack: componentStack || null,
+        ts: Date.now(),
+    });
+    if (reports.length > MAX_REPORTS) {
+        reports.shift();
+    }
+};
+const ErrorBoundaryFallback = ({ scope, referenceId, title, subtitle, details, onRetry, }) => {
+    const [copied, setCopied] = useState(false);
+    const [copyHelpVisible, setCopyHelpVisible] = useState(false);
+    const handleCopy = () => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            yield navigator.clipboard.writeText(details);
+            setCopied(true);
+            setCopyHelpVisible(false);
+            window.setTimeout(() => setCopied(false), COPIED_RESET_MS);
+        }
+        catch (_b) {
+            setCopyHelpVisible(true);
+        }
+    });
+    return (_jsxs("section", { className: "error-boundary", role: "alert", "data-test-id": "error-boundary", children: [_jsx("style", { children: errorBoundaryStyles }), _jsxs("div", { className: "error-boundary__top", children: [_jsx("span", { className: "error-boundary__status", children: scope === 'application' ? 'Application incident' : 'Tile incident' }), _jsxs("span", { className: "error-boundary__reference", "data-test-id": "error-boundary-reference", children: ["Ref: ", referenceId] })] }), _jsx("h2", { className: "error-boundary__title", children: title }), _jsx("p", { className: "error-boundary__subtitle", children: subtitle }), _jsx("textarea", { className: "error-boundary__details", readOnly: true, value: details, "aria-label": "Error diagnostics details", "data-test-id": "error-boundary-details" }), _jsxs("div", { className: "error-boundary__actions", children: [_jsx("button", { type: "button", className: "error-boundary__button", onClick: onRetry, "data-test-id": "error-boundary-retry", children: "Retry" }), _jsx("button", { type: "button", className: "error-boundary__button error-boundary__button--secondary", onClick: handleCopy, "data-test-id": "error-boundary-copy", children: copied ? 'Copied' : 'Copy diagnostics' })] }), copyHelpVisible ? (_jsx("p", { className: "error-boundary__manual-copy-help", role: "status", children: "Clipboard access is blocked in this browser context. Select the diagnostics text and copy it manually." })) : null] }));
+};
+class BaseErrorBoundary extends Component {
+    constructor() {
+        super(...arguments);
+        this[_a] = true;
+        this.state = initialBoundaryState;
+        this.handleRetry = () => {
+            this.setState(initialBoundaryState);
+        };
+    }
+    static getDerivedStateFromError(error) {
+        return {
+            error: toError(error),
+            capturedAt: new Date().toISOString(),
+            referenceId: createReferenceId(),
+        };
+    }
+    componentDidCatch(error, errorInfo) {
+        var _b;
+        const { scope, title, tileRegistration, onError } = this.props;
+        const normalized = toError(error);
+        const componentStack = (_b = errorInfo.componentStack) !== null && _b !== void 0 ? _b : '';
+        const { referenceId } = this.state;
+        this.setState({ componentStack });
+        recordReport(normalized, componentStack);
+        const tile = tileRegistration ? ` (${tileRegistration})` : '';
+        const stack = componentStack ? `\n\nComponent stack:${componentStack}` : '';
+        const logCaughtError = () => logger.error(`[${scope}] error boundary captured an error in "${title}"${tile}, reference ${referenceId}${stack}`, normalized);
+        if (!onError) {
+            logCaughtError();
+            return;
+        }
+        try {
+            onError({ error: normalized, componentStack, referenceId, scope, title, tileRegistration });
+        }
+        catch (handlerError) {
+            logCaughtError();
+            logger.error(`[${scope}] error boundary onError handler threw`, handlerError);
+        }
+    }
+    render() {
+        var _b;
+        const { error, referenceId, capturedAt, componentStack } = this.state;
+        if (!error) {
+            return this.props.children;
+        }
+        const { scope, title, tileRegistration } = this.props;
+        const diagnostics = [
+            `Reference: ${referenceId}`,
+            `Scope: ${scope}`,
+            `Title: ${title}`,
+            `Tile registration: ${tileRegistration !== null && tileRegistration !== void 0 ? tileRegistration : 'N/A'}`,
+            `Captured at: ${capturedAt}`,
+            `URL: ${window.location.href}`,
+            `User agent: ${window.navigator.userAgent}`,
+            `Error name: ${error.name}`,
+            `Error message: ${error.message}`,
+            'Error stack:',
+            (_b = error.stack) !== null && _b !== void 0 ? _b : 'No stack available',
+            'Component stack:',
+            componentStack || 'No component stack available',
+        ].join('\n');
+        const isApp = scope === 'application';
+        return (_jsx(ErrorBoundaryFallback, { scope: scope, referenceId: referenceId, title: isApp ? 'Something went wrong' : `Something went wrong in "${title}"`, subtitle: isApp
+                ? 'The app hit an unexpected error. You can retry or copy the diagnostics.'
+                : 'This tile crashed, but the rest of the application keeps running. Retry or copy the diagnostics.', details: diagnostics, onRetry: this.handleRetry }));
+    }
+}
+_a = BOUNDARY_BRAND;
+/**
+ * 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 const AppErrorBoundary = ({ onError, children }) => (_jsx(BaseErrorBoundary, { scope: "application", title: "Application", onError: onError, children: children }));
+/**
+ * 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 const TileErrorBoundary = ({ title, tileRegistration, onError, children, }) => (_jsx(BaseErrorBoundary, { scope: "tile", title: title, tileRegistration: tileRegistration, onError: onError, children: children }));
+/**
+ * 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 const withTileErrorBoundary = (WrappedComponent, title, tileRegistration, onError) => {
+    const WithTileErrorBoundary = (props) => (_jsx(TileErrorBoundary, { title: title, tileRegistration: tileRegistration, onError: onError, children: _jsx(WrappedComponent, Object.assign({}, props)) }));
+    WithTileErrorBoundary.displayName = `WithTileErrorBoundary(${title}:${tileRegistration}:${WrappedComponent.displayName || WrappedComponent.name || 'TileComponent'})`;
+    return WithTileErrorBoundary;
+};
+const isFoundationBoundary = (boundary) => typeof boundary === 'object' &&
+    boundary !== null &&
+    boundary[BOUNDARY_BRAND] === true;
+/**
+ * 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 const onCaughtError = (error, errorInfo) => {
+    var _b;
+    if (isFoundationBoundary(errorInfo.errorBoundary)) {
+        return;
+    }
+    console.error(error, '\n\nThe above error was caught by an error boundary.', (_b = errorInfo.componentStack) !== null && _b !== void 0 ? _b : '');
+};

package/dist/esm/error-boundary/index.js

@@ -0,0 +1 @@
+export { AppErrorBoundary, ERROR_BOUNDARY_LOGGER_NAME, onCaughtError, TileErrorBoundary, withTileErrorBoundary, } from './error-boundary';

package/dist/esm/index.js

@@ -12,6 +12,8 @@
  *   grid's `gridComponents` property).
  * - `reactFactory` / `reactFactoryWithProvider` — mount React component trees into
  *   Genesis Foundation layout regions.
+ * - `AppErrorBoundary` / `TileErrorBoundary` / `withTileErrorBoundary` — error boundaries with a
+ *   fallback UI and an `onError` reporting hook; pair with `onCaughtError` on the React root.
  *
  * Subpath entry points:
  * - `./flexlayout` — `flexlayout-react` at the version this package pins, re-exported with the
@@ -23,3 +25,4 @@ export { reactFactory, reactFactoryWithProvider } from './react-layout-factory';
 export { createReactRenderer } from './create-react-renderer';
 export { createGridProCellRenderer } from './create-grid-pro-cell-renderer';
 export { createGridProCellPortals } from './create-grid-pro-cell-portals';
+export * from './error-boundary';