@djangocfg/layouts 2.1.380 → 2.1.382

package/README.md

@@ -126,6 +126,36 @@ When `routing` is set, `BaseApp` mounts a locale-aware `<Link>` adapter so every
 
 `baseApp.project` enables `window.monitor`. Debug panel: `Cmd+D` or `?debug=1`.
 
+### `MonitorBoundary`
+
+Error boundary that automatically reports caught errors to `@djangocfg/monitor`. Use at page/layout level so unexpected render errors land in your backend dashboard.
+
+```tsx
+import { MonitorBoundary } from '@djangocfg/layouts';
+
+export default function Layout({ children }) {
+  return (
+    <MonitorBoundary variant="fullscreen" name="root-layout">
+      {children}
+    </MonitorBoundary>
+  );
+}
+
+// Per-section, non-fatal:
+<MonitorBoundary variant="card" name="dashboard-stats" resetKeys={[pathname]}>
+  <StatsPanel />
+</MonitorBoundary>
+
+// Opt out of reporting (e.g. third-party iframe noise):
+<MonitorBoundary reportToMonitor={false} variant="silent">
+  <EmbeddedWidget />
+</MonitorBoundary>
+```
+
+Wraps `Boundary` from `@djangocfg/ui-core` — same `variant`/`fallback`/`resetKeys` API, plus auto `FrontendMonitor.capture(...)`.
+
+For local UI widgets that should not report to backend, use `Boundary` from `@djangocfg/ui-core` directly.
+
 ---
 
 ## Package exports

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.380",
+  "version": "2.1.382",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -84,13 +84,13 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.380",
-    "@djangocfg/centrifugo": "^2.1.380",
-    "@djangocfg/debuger": "^2.1.380",
-    "@djangocfg/i18n": "^2.1.380",
-    "@djangocfg/monitor": "^2.1.380",
-    "@djangocfg/ui-core": "^2.1.380",
-    "@djangocfg/ui-nextjs": "^2.1.380",
+    "@djangocfg/api": "^2.1.382",
+    "@djangocfg/centrifugo": "^2.1.382",
+    "@djangocfg/debuger": "^2.1.382",
+    "@djangocfg/i18n": "^2.1.382",
+    "@djangocfg/monitor": "^2.1.382",
+    "@djangocfg/ui-core": "^2.1.382",
+    "@djangocfg/ui-nextjs": "^2.1.382",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -121,15 +121,15 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.380",
-    "@djangocfg/centrifugo": "^2.1.380",
-    "@djangocfg/debuger": "^2.1.380",
-    "@djangocfg/i18n": "^2.1.380",
-    "@djangocfg/monitor": "^2.1.380",
-    "@djangocfg/typescript-config": "^2.1.380",
-    "@djangocfg/ui-core": "^2.1.380",
-    "@djangocfg/ui-nextjs": "^2.1.380",
-    "@djangocfg/ui-tools": "^2.1.380",
+    "@djangocfg/api": "^2.1.382",
+    "@djangocfg/centrifugo": "^2.1.382",
+    "@djangocfg/debuger": "^2.1.382",
+    "@djangocfg/i18n": "^2.1.382",
+    "@djangocfg/monitor": "^2.1.382",
+    "@djangocfg/typescript-config": "^2.1.382",
+    "@djangocfg/ui-core": "^2.1.382",
+    "@djangocfg/ui-nextjs": "^2.1.382",
+    "@djangocfg/ui-tools": "^2.1.382",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/errors/MonitorBoundary.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import { Boundary } from '@djangocfg/ui-core/components';
+import type {
+  BoundaryProps,
+  BoundaryResetDetails,
+} from '@djangocfg/ui-core/components';
+import { EventLevel, EventType, FrontendMonitor } from '@djangocfg/monitor/client';
+import { useCallback } from 'react';
+import type { ErrorInfo, ReactNode } from 'react';
+
+export interface MonitorBoundaryProps extends Omit<BoundaryProps, 'onError' | 'onReset'> {
+  /** Forwarded to FrontendMonitor as `extra.source` so you can filter events by boundary. */
+  name?: string;
+  /** Additional render-error handler called alongside the monitor capture. */
+  onError?: (error: Error, info: ErrorInfo) => void;
+  /** Additional reset handler called alongside the monitor breadcrumb. */
+  onReset?: (details: BoundaryResetDetails) => void;
+  /** Disable monitor reporting (still catches and renders fallback). */
+  reportToMonitor?: boolean;
+  children: ReactNode;
+}
+
+function currentUrl(): string | undefined {
+  return typeof window !== 'undefined' ? window.location.href : undefined;
+}
+
+function reportError(name: string | undefined, error: Error, info: ErrorInfo): void {
+  try {
+    FrontendMonitor.capture({
+      event_type: EventType.ERROR,
+      level: EventLevel.ERROR,
+      message: error.message || 'Unhandled React render error',
+      stack_trace: error.stack,
+      url: currentUrl(),
+      extra: {
+        source: name ?? 'boundary',
+        componentStack: info.componentStack,
+      },
+    });
+  } catch {
+    // Never let monitor failures crash the boundary itself.
+  }
+}
+
+function reportReset(name: string | undefined, details: BoundaryResetDetails): void {
+  try {
+    FrontendMonitor.capture({
+      event_type: EventType.ERROR,
+      level: EventLevel.INFO,
+      message: `Boundary recovered (${details.reason})`,
+      url: currentUrl(),
+      extra: {
+        source: name ?? 'boundary',
+        reason: details.reason,
+      },
+    });
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * `Boundary` + automatic reporting to `@djangocfg/monitor`.
+ *
+ * Use at page/layout level so unexpected render errors are captured in your backend.
+ * For widgets you don't want to report (chat, embeds), use `Boundary` from ui-core directly.
+ */
+export function MonitorBoundary({
+  name,
+  onError,
+  onReset,
+  reportToMonitor = true,
+  ...rest
+}: MonitorBoundaryProps) {
+  const handleError = useCallback(
+    (error: Error, info: ErrorInfo) => {
+      if (reportToMonitor) reportError(name, error, info);
+      onError?.(error, info);
+    },
+    [name, onError, reportToMonitor],
+  );
+
+  const handleReset = useCallback(
+    (details: BoundaryResetDetails) => {
+      if (reportToMonitor) reportReset(name, details);
+      onReset?.(details);
+    },
+    [name, onReset, reportToMonitor],
+  );
+
+  return <Boundary {...rest} name={name} onError={handleError} onReset={handleReset} />;
+}

package/src/components/errors/index.ts

@@ -3,6 +3,8 @@
  */
 
 export { ErrorBoundary } from './ErrorBoundary';
+export { MonitorBoundary } from './MonitorBoundary';
+export type { MonitorBoundaryProps } from './MonitorBoundary';
 export { ErrorLayout } from './ErrorLayout';
 export type { ErrorLayoutProps } from './ErrorLayout';
 export { getErrorContent, ERROR_CODES } from './errorConfig';